Installation

This page details the installation procedure for SpECTRE on personal computers. For instructions on installing SpECTRE on clusters please refer to the Installation on clusters page.

Dependencies

Required:

Optional:

Using Docker to obtain a SpECTRE environment

A Docker image is available from DockerHub and can be used to build SpECTRE on a personal machine.

Note: The Docker image is the recommended way of using SpECTRE on a personal Linux machine. Because of the wide variety of operating systems available today it is not possible for us to support all configurations. However, using Spack as outlined below is a supported alternative to Docker images.

NOTE: If you have SELinux active on your system you must figure out how to enable sharing files with the host OS. If you receive errors that you do not have permission to access a shared directory it is likely that your system has SELinux enabled. One option is to disable SELinux at the expense of reducing the security of your system.

To build with the docker image:

  1. Clone SpECTRE into SPECTRE_ROOT, a directory of your choice.
  2. Retrieve the docker image (you may need sudo in front of this command)
    docker pull sxscollaboration/spectrebuildenv:latest
  3. Start the docker container (you may need sudo)
    docker run -v SPECTRE_ROOT:SPECTRE_ROOT --name CONTAINER_NAME -i -t sxscollaboration/spectrebuildenv:latest /bin/bash
    (The --name CONTAINER_NAME is optional, where CONTAINER_NAME is a name of your choice. If you don't name your container, docker will generate an arbitrary name.) You will end up in a shell in a docker container, as root (you need to be root). Within the container, SPECTRE_ROOT is available and CHARM_DIR is /work/charm. For the following steps, stay inside the docker container as root.
  4. Make a build directory somewhere inside the container, e.g. /work/spectre-build-gcc, and cd into it.
  5. Build SpECTRE with
    cmake -D CMAKE_Fortran_COMPILER=gfortran-8 \
    -D CHARM_ROOT=/work/charm/multicore-linux64-gcc SPECTRE_ROOT
    then make -jN to compile the code, make test-executables -jN to compile the test executables, and ctest to run the tests.

Notes:

Using Singularity to obtain a SpECTRE environment

Singularity is a container alternative to Docker with better security and nicer integration.

To use Singularity you must:

  1. Build Singularity and add it to your $PATH
  2. cd to the directory where you want to store the SpECTRE Singularity image, source, and build directories, let's call it WORKDIR. The WORKDIR must be somewhere in your home directory. If this does not work for you, follow the Singularity instructions on setting up additional bind points. Once inside the WORKDIR, clone SpECTRE into WORKDIR/SPECTRE_ROOT.
  3. Run singularity build spectre.img docker://sxscollaboration/spectrebuildenv:latest.
  4. To start the container run singularity shell spectre.img and you will be dropped into a bash shell. The first thing you will always need to do when entering the container is: . SPECTRE_HOME/containers/SingularityLoad.sh
  5. Run cd SPECTRE_HOME && mkdir build && cd build to set up a build directory.
  6. To build SpECTRE run
    cmake -D CMAKE_Fortran_COMPILER=gfortran-8 \
    -D CHARM_ROOT=/work/charm/multicore-linux64-gcc SPECTRE_ROOT
    followed by make -jN where N is the number of cores to build on in parallel.

Notes:

Using Spack to set up a SpECTRE environment

SpECTRE's dependencies can be installed with Spack, a package manager tailored for HPC use. Install Spack by cloning it into SPACK_DIR (a directory of your choice), then add SPACK_DIR/bin to your PATH.

For security, it is good practice to make Spack use the system's OpenSSL rather than allow it to install a new copy — see Spack's documentation for instructions. You may need to install the development version of OpenSSL:

Spack works well with a module environment. We recommend LMod, which is available on many systems:

To use modules with Spack, enable Spack's shell support by adding . SPACK_DIR/share/spack/setup-env.sh to your .bash_profile or .bashrc.

Once you have Spack installed and configured with OpenSSL and LMod, you can install the SpECTRE dependencies using

spack install blaze
spack install brigand@master
spack install libsharp -openmp -mpi
spack install catch
spack install gsl
spack install jemalloc # or from your package manager
spack install libxsmm
spack install yaml-cpp@develop

You can also install CMake, OpenBLAS, Boost, and HDF5 from Spack. To load the packages you've installed from Spack run spack load PACKAGE, or (equivalently) use the module load command.

Note: Spack allows very flexible configurations and it is recommended you read the documentation if you require features such as packages installed with different compilers.

Note: On a Mac, you may need to spack install yaml-cpp@develop~shared (note that is a tilde and not a dash in front of shared) in order to force the building of the static libraries in order to avoid dynamic linking errors.

Building SpECTRE

After the dependencies have been installed, Charm++ and SpECTRE can be compiled. Follow these steps:

  1. Clone SpECTRE into SPECTRE_ROOT, a directory of your choice.
  2. Install Charm++:
    • Clone Charm++ into CHARM_DIR, again a directory of your choice.
    • In CHARM_DIR, run git checkout v6.8.0 to switch to a supported, stable release of Charm++.
    • Charm++ is compiled by running ./build charm++ ARCH OPTIONS. To figure out the correct target architecture and options, you can simply run ./build; the script will then ask you questions to guide you towards the correct settings (see notes below for additional details). Then compile Charm++. The Charm++ build will be located in a new directory, CHARM_DIR/ARCH_OPTS, whose name may (or may not) have some of the options appended to the architecture.
    • The SpECTRE repo contains a patch that must be applied to Charm++ after Charm++ has been compiled. While still in CHARM_DIR, apply this patch by running git apply SPECTRE_ROOT/support/Charm/v6.8.patch.
    • On macOS 10.12 it is necessary to patch the STL implementation. Insert
      #ifndef _MACH_PORT_T
      #define _MACH_PORT_T
      #include <sys/_types.h> /* __darwin_mach_port_t */
      typedef __darwin_mach_port_t mach_port_t;
      #include <pthread.h>
      mach_port_t pthread_mach_thread_np(pthread_t);
      #endif /* _MACH_PORT_T */
      into the front of /Library/Developer/CommandLineTools/usr/include/c++/v1/__threading_support
  3. Return to SPECTRE_ROOT, and create a build dir by running mkdir build && cd build
  4. Build SpECTRE with cmake -D CHARM_ROOT=CHARM_DIR/ARCH_OPTS SPECTRE_ROOT then make -jN to compile the code.
  5. Run the tests with make test-executables && ctest.

Notes:

Code Coverage Analysis

For any coverage analysis you will need to have LCOV installed on the system. For documentation coverage analysis you will also need to install coverxygen and for test coverage analysis gcov.

If you have these installed (which is already done if you are using the docker container), you can look at code coverage as follows:

  1. On a gcc build, pass -D COVERAGE=ON to cmake
  2. make unit-test-coverage
  3. The output is in docs/html/unit-test-coverage.