Code configuration with Cmake

Introduction to Cmake

Cmake is a tool to control code generation on diverse platforms. It is the default tool used to configure Idefix. Idefix (and Kokkos) requires cmake version >= 3.16. It is also recommended to use the graphical frontend ccmake to configure Idefix, as it allows one to have a rapid overview of all of the configuration options and switch them according to the target architecture.

To configure Idefix with Cmake, simply launch cmake $IDEFIX_DIR with the desired options in a problem directory (that is a directory containing at least definitions.hpp and setup.cpp). Alternatively, you can replace cmake by ccmake to get a more user-friendly graphical interface).

Warning

The old configuration script configure.py is not supported in this version of Idefix and will likely break compilation.

Main configuration options

Several options can be enabled from the command line (or are accessible with ccmake GUI):

-LH

List all of the available configure options and exit

-D Idefix_MHD=ON

Enable MHD. If your setup is MHD-only, making this option mandatory, it is recommended to use a local CMakeLists.txt file instead, as described in Setup-specific options

-D Idefix_MPI=ON

Enable MPI parallelisation. Requires an MPI library. When used in conjonction with CUDA (Nvidia GPUs), a CUDA-aware MPI library is required by Idefix.

-D Idefix_DEFS=foo.hpp

Specify a particular filename to be used in place of the default problem file definitions.hpp

-D Idefix_DEBUG=ON

Enable debug options in Idefix. This triggers a lot of outputs, and automatic bound checks of array accesses. As a result, this option makes the code very slow.

-D Idefix_RECONSTRUCTION=x
Specify the type of reconstruction scheme (replaces the old “ORDER” parameter in definitions.hpp). Accepted values for x are:

  • Constant: first order, donor cell reconstruction,

  • Linear: second order, piecewise linear reconstruction (PLM) using Van-leer slope limiter.

  • LimO3: third order, Cada & Torrilhon 2009

  • Parabolic: fourth order piecewise parabolic reconstruction (PPM, Colella & Woodward 1984)

Note

The number of ghost cells is automatically adjusted as a function of the order of the reconstruction scheme. Idefix uses 2 ghost cells when ORDER < 4 and 3 ghost cells when ORDER = 4

-D Kokkos_ENABLE_OPENMP=ON

Enable OpenMP parallelisation on supported compilers. Note that this can be enabled simultaneously with MPI, resulting in a hybrid MPI+OpenMP compilation.

-D Kokkos_ENABLE_CUDA=ON

Enable Nvidia Cuda (for GPU targets). When enabled, cmake will attempt to auto-detect the target GPU architecture. If this fails, one needs to specify the target architecture adding -DKokkos_ARCH_{..}=ON (see below).

-D Kokkos_ARCH_{...}=ON

Enable architecture-specific optimisation. A complete list can be obtained with the -LH option. Note that several host and target architecture can be enabled simulatenously (e.g for a CPU and a GPU). For instance:

  • Intel CPUs: BDW (Broadwell), HSW (Haswell), KNL (Knights Landing Xeon phi), SKX (Skylake Xeon with AVX512), SNB (Sandy/Ivy bridge), WSM (Westmere) …

  • NVIDIA GPUs: PASCAL60, PASCAL61, VOLTA70, VOLTA72, AMPERE80, AMPERE86, …

  • IBM CPUs: POWER7, POWER8, POWER9, BOOL (Blue gene Q)

  • ARM CPUs: ARMV80, ARMV81, ARMV8_THUNDERX, ARMV8_THUNDERX2, A64FX…

  • AMD CPUs: AMDAVX, ZEN, ZEN2, ZEN3…

  • AMD GPUs: VEGA906, VEGA908…

-D CMAKE_CXX_COMPILER=foo

Request a specific foo compiler for the compilation and link. Alternatively, it is also possible to export the CXX environement variable with a valid compiler name before calling cmake.

Tip

Note that cmake keeps a cache of the previous configuration performed in a particular problem directory. To reset the configuration and start from scratch, delete the file CMakeCache.txt.

Warning

Idefix cmake configuration expects the build directory to be a problem directory (that is a directory containing at least definitions.hpp and setup.cpp). Launching cmake from a problem directory ensures that cmake will use that directory as its build directory. Note that it is also possible to use the -B option to explictely tell cmake a path to a build=*Idefix* problem directory.

Setup-specific options

Some physical setup might require some cmake options to be set to specific value (e.g. an MHD setup will surely require MHD to be enabled). To avoid mistakes, it is then recommended to enforce this choice by creating a custom CMakeLists.txt in your setup directory, and setting explicitely the options as they are required, using the functions set_idefix_property (for string properties) and enable_idefix_propery/ disable_idefix_propery (for boolean properties), as in the example below:

CMakeLists.txt
set_idefix_property(Idefix_RECONSTRUCTION LimO3)
enable_idefix_property(Idefix_MHD)

Add/replace custom source files

It is possible to add custom source files to be compiled and linked against Idefix. This can be useful if your setup requires complex functions and analysis in separate source files. To do so, add a CMakeLists.txt in your problem directory, which adds to the idefix target all the additional source files (i.e cpp and hpp headers). For instance, say you want to add source files for an analysis, your CMakeLists.txt should look like:

CMakeLists.txt
add_idefix_source(analysis.cpp)
add_idefix_source(analysis.hpp)

Idefix also allows one to replace a source file in $IDEFIX_DIR by your own implementation. This is useful when developping new functionnalities without touching the main directory of your Idefix repository. For instance, say one wants to replace the implementation of viscosity in $IDEFIX_SRC/src/hydro/viscosity.cpp, with a customised myviscosity.cpp in the problem directory, one should add a CMakeLists.txt in the problem directory reading

CMakeLists.txt
replace_idefix_source(hydro/viscosity.cpp myviscosity.cpp)

Note that the first parameter of replace_idefix_source is used as a search pattern in $IDEFIX_DIR. Hence it is possible to ommit the parent directory of the file being replaced if there is only one file with that name in the Idefix source directory, which is not guaranteed (some classes may implement methods with the same name). It is therefore recommended to add the parent directory in the first argument of replace_idefix_source.

Tip

Don’t forget to delete CMakeCache.txt before attempting to reconfigure the code when adding a problem-specific CmakeLists.txt.