CMake Transition¶
We are currently transitioning to support CMake as our primary build system. Until we have transitioned our documentation and functionality completely, please read the following preview section for details.
Progress status: see on GitHub
Introduction to CMake¶
If you are new to CMake, this short tutorial from the HEP Software foundation is the perfect place to get started with it.
If you just want to use CMake to build the project, jump into sections 1. Introduction, 2. Building with CMake and 9. Finding Packages.
Dependencies¶
WarpX depends on the following popular third party software. Please see installation instructions below.
a mature C++14 compiler: e.g. GCC 5, Clang 3.6 or newer
AMReX (development): we automatically download and compile a copy of AMReX
Optional dependencies include:
MPI 3.0+: for multi-node and/or multi-GPU execution
CUDA Toolkit 9.0+: for Nvidia GPU support (see matching host-compilers)
OpenMP 3.1+: for threaded CPU execution (currently not fully accelerated)
FFTW3: for spectral solver (PSATD) support
Boost 1.66.0+: for QED support
openPMD-api 0.12.0+: we automatically download and compile a copy of openPMD-api for openPMD I/O support
CCache: to speed up rebuilds (needs 3.7.9+ for CUDA)
Install Dependencies¶
macOS/Linux:
spack env create warpx-dev
spack env activate warpx-dev
spack add adios2
spack add ccache
spack add cmake
spack add fftw
spack add hdf5
spack add mpi
spack add pkgconfig # for fftw
# optional:
# spack add cuda
spack install
(in new terminals, re-activate the environment with spack env activate warpx-dev again)
or macOS/Linux:
brew update
brew install adios2
brew install ccache
brew install cmake
brew install fftw
brew install hdf5-mpi
brew install libomp
brew install pkg-config # for fftw
brew install open-mpi
Now, cmake --version should be at version 3.14.0 or newer.
Configure your compiler¶
For example, using a GCC on macOS:
export CC=$(which gcc)
export CXX=$(which g++)
If you also want to select a CUDA compiler:
export CUDACXX=$(which nvcc)
export CUDAHOSTCXX=$(which g++)
Build & Test¶
From the base of the WarpX source directory, execute:
mkdir -p build
cd build
# find dependencies & configure
cmake ..
# build using up to four threads
make -j 4
# run tests (todo)
You can inspect and modify build options after running cmake .. with either
ccmake .
or by providing arguments to the CMake call: cmake .. -D<OPTION_A>=<VALUE_A> -D<OPTION_B>=<VALUE_B>
CMake Option |
Default & Values |
Description |
|---|---|---|
|
RelWithDebInfo/Release/Debug |
Type of build, symbols & optimizations |
|
ON/OFF |
Ascent in situ visualization |
|
NOACC/OMP/CUDA/DPCPP |
On-node, accelerated computing backend |
|
3/2/RZ |
Simulation dimensionality |
|
ON/OFF |
Multi-node support (message-passing) |
|
ON/OFF |
MPI thread-multiple support, i.e. for |
|
ON/OFF |
openPMD I/O (HDF5, ADIOS) |
|
24 |
Maximum parser depth for input file functions |
|
double/single |
Floating point precision (single/double) |
|
ON/OFF |
Spectral solver |
|
ON/OFF |
PICSAR QED (requires Boost and PICSAR) |
|
|
Repository URI to pull and build AMReX from |
|
|
Repository branch for |
|
ON/OFF |
Needs a pre-installed AMReX library if set to |
|
ON/OFF |
Needs a pre-installed openPMD library if set to |
For example, one can also build against a local AMReX git repo.
Assuming AMReX’ source is located in $HOME/src/amrex and changes are committed into a branch such as my-amrex-branch then pass to cmake the arguments: -DWarpX_amrex_repo=file://$HOME/src/amrex -DWarpX_amrex_branch=my-amrex-branch.
For developers, WarpX can be configured in further detail with options from AMReX, which are documented in the AMReX manual.
Run¶
An executable WarpX binary with the current compile-time options encoded in its file name will be created in bin/.
Additionally, a symbolic link named warpx can be found in that directory, which points to the last built WarpX executable.