Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : ## Installing SpECTRE on Apple Silicon {#installation_on_apple_silicon}
       6             : 
       7             : \tableofcontents
       8             : 
       9             : The following instructions show how to install SpECTRE and its dependencies
      10             : on Apple Silicon Macs. Apple Silicon is an arm64 architecture, in contrast
      11             : to the x86-64 architecture that SpECTRE usually targets. These instructions
      12             : will result in an Apple Silicon native build of SpECTRE.
      13             : 
      14             : \note Floating-point exception trapping is not currently
      15             : supported on Apple Silicon.
      16             : 
      17             : ### 0. Install the xcode command-line tools.
      18             : 
      19             : Install the xcode command-line tools, which include the clang compiler, etc.
      20             : Run the following command in the terminal:
      21             : 
      22             : ```
      23             : xcode-select --install
      24             : ```
      25             : 
      26             : ### 1. Clone spectre
      27             : 
      28             : Clone the SpECTRE repository in a directory of your choice:
      29             : 
      30             : ```sh
      31             : git clone git@github.com:sxs-collaboration/spectre.git
      32             : export SPECTRE_HOME=$PWD/spectre
      33             : ```
      34             : 
      35             : ### 2. Install python dependencies
      36             : 
      37             : Spectre depends on python and some python packages. There are different ways to
      38             : install an arm64-native python stack. The following instructions show how
      39             : to do this using the Python 3 interpreter bundled with macOS.
      40             : 
      41             : ```sh
      42             : cd $SPECTRE_HOME
      43             : 
      44             : # Create a Python environment
      45             : python3 -m venv ./env --upgrade-deps
      46             : 
      47             : # Activate the Python environment
      48             : . ./env/bin/activate
      49             : 
      50             : # Install Python packages
      51             : pip install -r support/Python/requirements.txt \
      52             :   -r support/Python/dev_requirements.txt
      53             : 
      54             : # Optionally install additional packages you might want, like Jupyter
      55             : pip install jupyterlab
      56             : ```
      57             : 
      58             : ### 3. Install dependencies with Homebrew
      59             : 
      60             : Most of spectre's dependencies can be installed using the
      61             : [Homebrew](https://brew.sh) package manager. First, if you haven't already,
      62             : install Homebrew by following the instructions on the
      63             : [Homebrew](https://brew.sh) homepage. Then, run the following to install a
      64             : Fortran compiler and other dependencies:
      65             : 
      66             : ```
      67             : brew install gcc autoconf automake ccache cmake
      68             : brew install boost catch2 doxygen gsl hdf5 openblas yaml-cpp
      69             : ```
      70             : 
      71             : \note We use OpenBLAS instead of Apple's Accelerate framework here because
      72             : Accelerate fails to reach the same floating point accuracy as OpenBLAS in some
      73             : of our tests (specifically partial derivatives).
      74             : 
      75             : ### 4. Install remaining dependencies
      76             : 
      77             : Here, install the remaining dependencies that cannot be installed with Homebrew.
      78             : You can install them from source manually, or use the
      79             : [Spack](https://github.com/spack/spack) package manager (see below).
      80             : 
      81             : #### Install manually
      82             : 
      83             : ```sh
      84             : export SPECTRE_DEPS_ROOT=$HOME/apps
      85             : mkdir -p $SPECTRE_DEPS_ROOT
      86             : cd $SPECTRE_DEPS_ROOT
      87             : 
      88             : # Install Charm++
      89             : git clone https://github.com/UIUC-PPL/charm
      90             : pushd charm
      91             : git checkout v7.0.0
      92             : git apply $SPECTRE_HOME/support/Charm/v7.0.0.patch
      93             : ./build charm++ multicore-darwin-arm8 --with-production -g3 -j --build-shared
      94             : popd
      95             : 
      96             : # The following dependencies are optional! They will be installed in the build
      97             : # directory automatically if needed in the next step. You can install them
      98             : # manually like this if you want control over where or how they are installed.
      99             : # If you don't care, you can skip ahead.
     100             : 
     101             : # Install Blaze
     102             : mkdir blaze
     103             : pushd blaze
     104             : curl -L https://bitbucket.org/blaze-lib/blaze/downloads/blaze-3.8.tar.gz \
     105             : > blaze-3.8.tar.gz
     106             : tar -xf blaze-3.8.tar.gz
     107             : mv blaze-3.8 include
     108             : popd
     109             : 
     110             : # Install libxsmm
     111             : # Need master branch of libxsmm to support Apple Silicon
     112             : git clone https://github.com/hfp/libxsmm.git
     113             : pushd libxsmm
     114             : make
     115             : popd
     116             : ```
     117             : 
     118             : #### Install with Spack
     119             : 
     120             : ```sh
     121             : # Download spack
     122             : cd ~
     123             : git clone -c feature.manyFiles=true https://github.com/spack/spack.git
     124             : cd spack
     125             : # Switch to latest release
     126             : git checkout releases/latest
     127             : # Load shell support
     128             : . ./share/spack/setup-env.sh
     129             : # Find some system packages so we don't have to install them all from source
     130             : spack external find
     131             : # Install dependencies
     132             : spack install \
     133             :   charmpp@7.0.0: +shared backend=multicore build-target=charm++ \
     134             :   blaze@3.8.2 ~blas ~lapack smp=none \
     135             :   libxsmm@1.16.1: \
     136             : ```
     137             : 
     138             : ### 5. Configure and build SpECTRE
     139             : 
     140             : Create a build directory in a location of your choice, e.g.
     141             : 
     142             : ```sh
     143             : cd $SPECTRE_HOME
     144             : mkdir build
     145             : cd build
     146             : ```
     147             : 
     148             : Next, configure SpECTRE using the following CMake command. If you installed
     149             : dependencies with Spack, you can use `spack find -p` to retrieve the root
     150             : directories of the packages and replace them in the command below.
     151             : You only need to specify `LIBXSMM_ROOT` and `BLAZE_ROOT` if you installed
     152             : those packages yourself above. The option `SPECTRE_FETCH_MISSING_DEPS` will
     153             : take care of downloading these if you haven't installed them above.
     154             : 
     155             : ```sh
     156             : cmake \
     157             : -D CMAKE_C_COMPILER=clang \
     158             : -D CMAKE_CXX_COMPILER=clang++ \
     159             : -D CMAKE_Fortran_COMPILER=gfortran \
     160             : -D CMAKE_BUILD_TYPE=Debug \
     161             : -D BUILD_SHARED_LIBS=ON \
     162             : -D MEMORY_ALLOCATOR=SYSTEM \
     163             : -D CHARM_ROOT=${SPECTRE_DEPS_ROOT}/charm/multicore-darwin-arm8 \
     164             : -D SPECTRE_FETCH_MISSING_DEPS=ON \
     165             : -D SPECTRE_TEST_TIMEOUT_FACTOR=5 \
     166             : -D BLAS_ROOT=$(brew --prefix openblas) \
     167             : -D LAPACK_ROOT=$(brew --prefix openblas) \
     168             : -D LIBXSMM_ROOT=${SPECTRE_DEPS_ROOT}/libxsmm/ \
     169             : -D BLAZE_ROOT=${SPECTRE_DEPS_ROOT}/blaze/ \
     170             : ..
     171             : ```
     172             : 
     173             : Finally, build and test SpECTRE. E.g., on a Mac with 10 cores,
     174             : 
     175             : ```sh
     176             : make -j10 unit-tests
     177             : make -j10 test-executables
     178             : ctest --output-on-failure -j10
     179             : ```
     180             : 
     181             : Optionally, to install the python bindings in your python environment,
     182             : 
     183             : ```sh
     184             : make -j10 all-pybindings
     185             : pip install -e ${SPECTRE_HOME}/build/bin/python
     186             : ```