Building `riot`

riot builds on Linux with CMake. Windows users should build it in Windows Subsystem for Linux (WSL); after WSL is installed, the Linux build steps are the same as on Ubuntu.

Prerequisites

riot requires CMake 3.26 or newer, a C++17-capable compiler, MPI, and a parallel HDF5 installation. For Ubuntu, install the base dependencies with:

sudo apt update
sudo apt install -y build-essential libhdf5-mpich-dev git cmake curl \
  python3 python3-dev python3-venv

Clone riot and all required submodules:

git clone --recursive git@github.com:lanl/riot.git
cd riot

If the repository was cloned without submodules, initialize them before configuring:

git submodule update --init --recursive

Python environment

riot’s Python interface requires Python development files and NumPy. A virtual environment keeps Python packages isolated from the system installation:

python3 -m venv riot_venv
. riot_venv/bin/activate
python -m pip install --upgrade pip
python -m pip install numpy
python -m pip install "pybind11[global]"

Additional Python packages, such as scipy and h5py, may be installed in this virtual environment when needed by an input deck. Do not install them into a Conda or Micromamba environment that CMake will use to locate parallel HDF5 unless that environment provides a compatible MPI-enabled HDF5 package.

Configure, build, and install

Create a separate build directory. The following configuration uses the active virtual environment for Python and installs riot’s runtime files into it:

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DPython_ROOT_DIR="$VIRTUAL_ENV" \
  -DCMAKE_INSTALL_PREFIX="$VIRTUAL_ENV"
cmake --build build --parallel 6
cmake --install build

The executable is built at build/src/riot. To run a Cartesian example:

cd build/src
cp ../../inputs/triple/triple.py .
./riot -i "$(python triple.py)"
mpirun -np 4 ./riot -i "$(python triple.py)"

The final command runs the example with four MPI ranks.

Optional plugin physics

The optional CMake parameter PLUGINS_DIR enables additional plugin physics from a downstream source directory. Add it to the configuration command above:

cmake -S . -B build -DPLUGINS_DIR=/absolute/path/to/plugins
cmake --build build --parallel 6

The directory must contain a CMakeLists.txt.

Plugins are compiled into riot. When PLUGINS_DIR is empty (the default), the build uses the no-op implementations in src/plugin_stubs. Set -DPLUGINS_DIR= to restore that behavior in an existing build directory.

See Implementing the plugin interface in the programmer’s guide for the required interface functions and plugin CMake setup.

Building in WSL

Install WSL and Ubuntu from an elevated Windows PowerShell prompt:

wsl --list --online
wsl --install Ubuntu-24.04

Restart Windows if prompted, launch Ubuntu, and create a Linux username and password. Then follow the Ubuntu instructions above inside the Ubuntu terminal. Windows drives are available under /mnt; for example, the C: drive is mounted at /mnt/c.

Micromamba alternative

Micromamba can be used instead of a Python virtual environment. After creating and activating an environment with MPI-enabled HDF5, configure riot with its prefix:

"${SHELL}" <(curl -L micro.mamba.pm/install.sh)
source ~/.bashrc
micromamba create -n riot python=3.12 numpy matplotlib scipy h5py \
  'hdf5=*=mpi*' zlib cmake cxx-compiler c-compiler pkg-config
micromamba activate riot

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$CONDA_PREFIX" \
  -DHDF5_ROOT="$CONDA_PREFIX" \
  -DHDF5_IS_PARALLEL=ON \
  -DHDF5_PREFER_PARALLEL=ON \
  -DPython_ROOT_DIR="$CONDA_PREFIX" \
  -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX"

Build options

Pass options to CMake as -DOPTION=VALUE. The options below are defined by riot; additional Parthenon and Kokkos options are available from their documentation.

Option	Default	Description
`CMAKE_BUILD_TYPE`	`RelWithDebInfo`	Build configuration. Common alternatives are `Debug` and `Release`.
`PLUGINS_DIR`	empty	Optional source directory containing a `CMakeLists.txt` to enable additional plugin physics. See Optional plugin physics for the build setup and a link to the implementation guide.
`RIOT_ENABLE_UNIT_TESTS`	`OFF`	Build `riot` unit tests.
`RIOT_ENABLE_REGRESSION_TESTS`	`OFF`	Build `riot` regression tests.
`RIOT_REGRESSION_GOLD_VER`	`20260830`	Version of the regression-gold GitHub Release asset to use.
`RIOT_REGRESSION_GOLD_HASH`	SHA-512 for the default gold archive	Expected SHA-512 of the selected regression-gold archive. Set this with `RIOT_REGRESSION_GOLD_VER` when selecting a different version.
`RIOT_REGRESSION_GOLD_SYNC`	`ON`	Download and extract the selected regression-gold archive during CMake configuration when regression tests are enabled.
`RIOT_REGRESSION_GOLD_LOCAL`	unset	Path to a pre-downloaded regression-gold archive. When set, CMake uses this file instead of downloading from GitHub, after verifying it against `RIOT_REGRESSION_GOLD_HASH`. Useful on systems where the build node has no internet access: fetch the archive ahead of time (for example on a login node) and point this option at it.
`RIOT_ENABLE_CUDA`	`OFF`	Enable CUDA support in `riot` and its in-tree dependencies.
`RIOT_ENABLE_HDF5`	`ON`	Enable HDF5 support. MPI builds require a parallel HDF5 installation.
`RIOT_ENABLE_MPI`	`ON`	Enable MPI support.
`RIOT_ENABLE_OPENMP`	`OFF`	Enable OpenMP support in `riot` and Parthenon.
`RIOT_ENABLE_WARNINGS`	`OFF`	Enable compiler warnings.
`RIOT_ENABLE_SANITIZE`	`OFF`	Enable the address sanitizer.
`RIOT_ENABLE_NDI`	`OFF`	Enable NDI support for the `ndi2spiner` tool.
`RIOT_BUILD_NDI`	`ON` when NDI is enabled	Build the bundled NDI dependency. This option is available only when `RIOT_ENABLE_NDI=ON`.
`RIOT_BUILD_CATCH2`	`ON`	Build the bundled Catch2. Set to `OFF` to use a system Catch2 package.
`RIOT_BUILD_PARTHENON`	`ON`	Build the bundled Parthenon. Set to `OFF` to use an installed package.
`RIOT_BUILD_SINGULARITY`	`ON`	Build the bundled singularity-eos. Set to `OFF` to use an installed package.
`RIOT_BUILD_PYTHON`	`ON`	Build `riot`’s Python interface.
`RIOT_BUILD_CAD`	`OFF`	Enable CAD-file support through OpenCASCADE.
`RIOT_MAX_MATERIALS`	`16`	Maximum number of materials stored per mesh block.
`RIOT_MAX_STRONG`	`16`	Maximum number of strong materials.
`RIOT_MAX_ADV`	`32`	Maximum number of advected quantities.
`RIOT_MAX_GROUPS`	`64`	Maximum number of radiation energy groups.
`PARTHENON_COORDINATES`	`UniformCartesian`	Coordinate system: `UniformCartesian`, `UniformCylindrical`, or `UniformSpherical`. Use a separate build directory for each choice.
`MACHINE_CFG`	unset	Path to a Parthenon machine-configuration file for compiler and platform defaults.

Building riot