System Setup using CMake

The first step is to clone and configure the FELTOR repository from GitHub.

You may need to install the external dependencieslibnetcdf-dev,liblapack-dev andlibboost-dev (andlibglfw3-dev for OpenGL output andlibopenmpi-dev for MPI support) from your system package manager.

On Windows you can use the built-in git client and cmake integration of Visual Studio. It is easiest to use the built-in vcpkg manager to install thenetcdf-c,glfw3,lapack andboost-headers dependencies.

There are 6 presets targeting 6 different hardware architectures. All require the C++-17 standard. Each presetX creates its binary directorybuild/X.

Our GPU backend uses theNvidia-CUDA programmingenvironment and in order to compile and run a program for a GPU a userneeds the nvcc compiler and a NVidiaGPU. However, we explicitly note here that due to the modular design ofour software a user does not have to possess a GPU nor the nvcccompiler. The CPU version of the backend is equally valid and providesthe same functionality. Analogously, an MPI installation is only required if the user targetsa distributed memory system.

Available targets

The Feltor projects defines a host of CMake targets that can bebuilt after configuration. To build everything run

The Feltor CMake targets are organised into three categories: tests, benchmarks and production projects. Thesecan be targeted individually using

The tests and benchmarks will be built inbuild/X/inc and the projects inbuild/X/src, whereX is the preset in use. The location of the executables inbuild/X exactly mirror the folder structure of the original C++ files infeltor, for examplefeltor/inc/dg/blas_b.cpp compiles tobuild/X/inc/dg/blas_b.The tests can be run using

Lastly, one can also target individual programs. All programs in the dg library start with the prefixdg_ followed by the component namebackend,topology,geometries,file ormatrix followed by the program name without suffix. The feltor project targets follow the naming schemeproject_target whereproject is the name of the folder in thesrc directory andtarget is the program name without suffix. Again, the output name in the binary directory follows the original folder structure and program name. For example:

Again, remember to replacecpu with the preset of your choice and mind the various options when running parallel programs, e.g.

Using FELTOR’s dg library in CMake

FELTOR contains a library called thedg-library (from discontinuous Galerkin). To integrate FELTOR’s dg library in your own project via cmake currently the only option is to add it as a submodule i.e. either (i) useFetchContent directly or (ii) use the cmake package managerCPM (our recommendation) or (iii) add feltor as a git submodule and useadd_subdirectory in yourCMakeLists.txt. We here show the CPM version. To get started follow the CPM quick start guide to setup the filecmake/CPM.cmake. It is also highly recommended to set theCPM_SOURCE_CACHE environment variable.

CMake’s install rules andfind_package currently does not work well with targets that can be compiled for various languages (seethis issue)

The available library targets in cmake are of the formatfeltor::dg::component, wherecomponent is one of the following:

As noted before you may need to install the external dependencieslibnetcdf-dev,liblapack-dev andlibboost-dev from your system package manager (or use e.g. the vcpkg manager to installnetcdf-c,lapack andboost-headers). Note that you can set the optionsFELTOR_DG_WITH_MATRIX OFF andFELTOR_FILE_WITH_NETCDF OFF to avoid having to install netcdf, lapack or boost.

Furthermore, since feltor’s dg library depends on cccl, we inherit their optionCCCL_THRUST_DEVICE_SYSTEM, which can be eitherCPP,OMP orCUDA. Since with CUDA a new language must be enabled (which can only be done once in a cmake project) we must add this to the cmake file:

Notethat the dg library isheader-only, which means that you just have toinclude the relevant header(s) and you’re good to go. For example in thefollowing program we compute the square L2 norm of afunction:

To compile and run this code for a GPU use

Or if you want to use OpenMP and gcc instead of CUDA for the devicefunctions you can also use

If you do not want any parallelization, you can use a single thread version

If you want to use mpi, just include the MPI header before any otherFELTOR header and use our convenient typedefs like so:

The CMake file needs to be modified like

Compile e.g. for a hybrid MPI + OpenMP hardware platform with

This will run 4 MPI threads with 2 OpenMP threads each.

Note the striking similarity to the previous program. Especially theline calling the dot function did not change at all. The compilerchooses the correct implementation for you! This is a first example ofplatform independent code.

Using Makefiles (Deprecated)

Open a terminal and clone the repository into any folder you like

You also need to clonecccl distributed under theApache-2.0 license. Also, we need Agner Fog’svcl library (Apache 2.0). So again in a folder of your choice

Our code only depends on external libraries that are themselves openlyavailable.If version2 of the vectorclass library does not work for you, you can also try version1.