Build parameter reference

Build parameter reference#

For Developers: if you add a CMake parameter, make sure to document it here.

For a good overview and easy, we recommend the use of ccmake. To do so, simply replace the use of cmake by ccmake. (i.e. add a “c” in front of the command) Alternatively, you may also modify the CMakeCache.txt in your build directory directly (for it to exist, cmake needs to be run first).

Simulation- and optimization-specific parameters#

The following parameters will alter the name of the SeisSol executable. You may explicitly compile and install multiple of these configurations at the same time—however, you will have to re-do the CMake and build process for each configuration.

  • CMAKE_BUILD_TYPE: Either Release, RelWithDebInfo, or Debug

    • Release: default value; usually optimizes with -O3.

    • RelWithDebInfo: optimizes a bit less than Release (usually -O2), but offers more debug information.

    • Debug: Also enables assertions. Note that more bugs can appear here than when running with the release options.

  • EQUATIONS: the equation system to compile for

    • elastic: isotropic elastic

    • viscoelastic: obsolete, use viscoelastic2 instead

    • viscoelastic2: isotropic viscoelastic. Requires a positive number of relaxation mechanisms (NUMBER_OF_MECHANISMS).

    • anisotropic: anisotropic elastic; essentially uses the same kernels as the elastic mode, but with more general matrices

    • poroelastic: isotropic poroelastic

  • NUMBER_OF_MECHANISMS: the number of mechanisms for viscoelastic simulations. For all other equations, this parameter is required to be 0.

  • ORDER: the expected convergence order. It corresponds to the polynomial degree plus 1. The order is used for both space and time integration. For example, if you specify order 4, you will be using polynomials of degree 3 in space and time. Note that a higher order can impact the performance greatly.

  • PRECISION:

    • single: use single precision. Recommended in general for faster simulations. But especially for consumer GPUs (i.e. Nvidia GeForce, AMD Radeon, Intel ARC etc.), since these have usually a high performance difference between single and double precision.

    • double: use double precision. Recommended, if your simulation fails with Inf/NaN errors in single precision builds. See also SeisSol/SeisSol#200 .

  • NUMBER_OF_FUSED_SIMULATIONS: the number of simulations run simultaneously.

  • NEW_BINARY_NAMING: use an updated binary naming scheme which uses lower-case letters and a shorter notation

Besides these, the host or, if enabled, the device architecture and backend are also encoded in the name of the executable.

Generic parameters#

  • LOG_LEVEL_MASTER: determines the minimum relevance level of log messages that are printed. Possible values are error, warning, info, and debug.

  • ASAGI: enable or disable ASAGI as input for fault and material information. Note that easi will need to be built with ASAGI support if you select this option.

  • COVERAGE: determine the code coverage (currently only relevant for the CI).

  • DR_QUAD_RULE: the quadrature rule used for the Dynamic Rupture. Currently permits either dunavant or stroud, referring to the respective quadrature scheme names.

  • PLASTICITY_METHOD: changes the plasticity matrices to be used. Options are

    • nb: nodal basis

    • ib: interpolating basis

  • PROXY_PYBINDING: compile Python bindings for the SeisSol proxy

  • TESTING: compile unit tests for SeisSol

  • TESTING_GENERATED: compile unit tests

  • LTO: enable link-time optimization

  • GRAPH_PARTITIONING_LIBS: compile for the given graph partitioning libraries. Allowed options are:

  • BUILD_DOCS: build the (sphinx) documentation as HTML

  • BUILD_DOXYGEN: build the doxygen docs for the SeisSol code

CPU-specific parameters#

  • HOST_ARCH: the parameter to tune the architecture for. See build-archs for an overview. Applies both compiler options and GEMM generation. If you get an illegal instruction error, check this variable first. Since there are many options, we have an own page for them. In short, use hsw when using a Linux/Windows PC or an older Mac. Use apple-m1 or apple-m2 on the latest Mac computers.

  • MEMKIND: enables HBM support.

  • NUMA_AWARE_PINNING: pin the free CPUs (those used for the communication and IO threads) according to the given NUMA domains.

  • MEMORY_LAYOUT: the sparsity patterns to apply. If set to auto, code generation chooses a layout from the target-specific config folder (codegen/config/cpu or codegen/config/gpu). Passing a filename such as dense.xml or ms32.xml resolves it from that same target-specific folder automatically.

  • GEMM_TOOLS_LIST: the list for CPU GEMM generators that are used. Note that SeisSol benefits from code generation specifically for small matrices. Currently supports combinations of the following:

    • auto: automatically selects the installed and usable GEMM generators out of LIBXSMM_JIT, LIBXSMM and PSpaMM (in this order).

    • LIBXSMM_JIT: libxsmm, in JIT mode

    • LIBXSMM: libxsmm, in code generation mode

    • PSpaMM: PSpaMM (may support more matrix types and offers higher-performance sparsity compared to libxsmm, slightly slower for dense matrices at the time being).

    • MKL: Intel MKL

    • OpenBlas: OpenBLAS

GPU-specific parameters#

  • DEVICE_BACKEND: enables or disables the GPU backend. The following backends are available at the moment:

    • none: compile for the CPU

    • cuda: Nvidia CUDA

    • hip: AMD HIP, using ROCm (or CUDA)

    • acpp: SYCL, more specifically AdaptiveCpp, formerly known as Open SYCL and hipSYCL. Provides support for Intel, AMD, and Nvidia GPUs. Repository: AdaptiveCpp/AdaptiveCpp

    • oneapi: SYCL, more specifically Intel Data Parallel C++ (DPC++). Provides support for Intel, AMD, and Nvidia GPUs. The open source variant is located under intel/llvm

  • DEVICE_ARCH: the parameter to tune and compile the kernels for. See build-archs for an overview.

  • DEVICE_CODEGEN: the GPU code generator to use. Unlike the CPU code generator list, you may only choose a single code generator here.

    • gemmforge-chainforge: Gemmforge and chainforge (auto-enabled if the latter is found)

    • tensorforge: TensorForge

    • tinytc: Tiny Tensor Compiler (for Intel)

  • DEVICE_KERNEL_INFOPRINT: print register/resource usage info for each compiled kernel while compiling SeisSol.

  • DEVICE_KERNEL_SAVETEMPS: store the temporary output (e.g. PTX, AMDGCN ISA) of the GPU compilers. Useful e.g. for kernel debugging.

  • SYCL_USE_NVHPC: if AdaptiveCpp is compiled with NVHPC support, and we use NVHPC

  • USE_GRAPH_CAPTURING: if a compute graph feature is available, then use it. This is currently the case for CUDA (since 11.0), HIP (requires ROCm 6.1 or higher), or oneAPI.

  • ENABLE_PROFILING_MARKERS: Currently available for CUDA and HIP

  • DEVICE_EXPERIMENTAL_EXPLICIT_KERNELS: enable some faster, handwritten accumulation kernels (default for NVIDIA and AMD)

Contents