block-adaptive, performance portable multi-material radiation hydrodynamics

RIOT is a block adaptive mesh refinement (AMR) multi-material hydrodynamics code built atop the Parthenon performance-portability framework. Parthenon supplies the block-AMR infrastructure, load balancing, and communication machinery but contains no physics; RIOT supplies the hydrodynamics algorithm and the physics packages documented in this manual.

Organization of the Documentation

Each physics package in RIOT is documented in its own chapter. Every chapter follows the same structure:

1. the governing equations solved by the package, and

2. the user-tunable input parameters that control it.

Input parameters are organized into blocks. The recommended way to write inputs is a Python script that calls riot.input(block, …) for each block (Chapter The Python Interface); each call corresponds to one block of the underlying text input deck (a .rin file). The parameter tables in this manual list parameters by their block and name (e.g. cfl in the <hydro> block); in a Python script these are supplied as keyword arguments:

riot.input("hydro", recon="plm",   # reconstruction method
                    riemann="hllc",  # Riemann solver
                    cfl=0.8)         # CFL number

The same block in the equivalent text input deck reads:

<hydro>
recon   = plm      # reconstruction method
riemann = hllc     # Riemann solver
cfl     = 0.8      # CFL number

Each package chapter also includes a Registered Fields table listing the Parthenon fields that package creates, the symbol each maps to in the governing equations, its component count, and its metadata.

Note

For readability, the metadata column of every Registered Fields table lists the salient flags (e.g. Independent, Conserved, WithFluxes, Sparse, Derived) rather than the complete flag set passed in the source.

Running RIOT

After building RIOT, run the executable from build/src. Supply an input deck with -i and, optionally, select an output directory with -d:

cd build/src
./riot -i input.rin -d /path/to/output/
mpiexec -n 4 ./riot -i input.rin -d /path/to/output/

The second command runs the same problem using four MPI ranks. See Building riot for prerequisites, configuration, and installation details.

Enabling Physics: the <physics> Block

Which packages are active in a run is controlled by boolean toggles in the <physics> block. Hydrodynamics is on by default; the remaining packages are off by default and are enabled here. Each package’s own parameters live in its own block, documented in the corresponding chapter.

Package toggles in the <physics> block.

Parameter	Type	Default	Description
hydro	bool	true	Enable hydrodynamics.
strength	bool	false	Enable material strength.
ionization	bool	false	Enable partial ionization.
levelsets	bool	false	Enable level-set interface tracking.
scalars	bool	false	Enable passive scalars.
mix	bool	false	Enable the BHR RANS subgrid mixing model.
tn	bool	false	Enable thermonuclear burn.
radiation_transport	bool	false	Enable radiation transport.
multigroup_diffusion	bool	false	Enable P1 radiation diffusion.
gravity	bool	false	Enable a constant gravitational acceleration.
prescribed_sources	bool	false	Enable prescribed energy sources.
lasers	bool	false	Enable laser ray tracing and energy deposition.
tracers	bool	false	Enable Lagrangian tracer particles.
fixed_fluid	bool	false	Hold the fluid fixed (no hydro update).

Sparsity

Many of RIOT’s per-material fields (cell-volume-averaged densities, volume fractions, and the derived material state of Chapter Materials and Equations of State) are registered as Parthenon sparse fields. A sparse field is allocated only on the mesh blocks where it is actually needed — for a material, only on blocks where that material is present — rather than everywhere in the domain. In a multi-material simulation where each material occupies a limited region, this saves substantial memory, since a block that contains none of a given material carries no storage for it. As materials move through the mesh, Parthenon allocates a material’s fields on blocks it enters and deallocates them on blocks it has left.

The deallocation step is controlled by sparse_dealloc in the <materials> block. When true (the default), the fields of a material that is no longer present on a block are freed, reclaiming memory; when false, once-allocated fields persist for the rest of the run.

Sparsity parameter in the <materials> block.

Parameter	Type	Default	Description
sparse_dealloc	bool	true	Free a material’s fields on blocks it has left.

Submodules

RIOT consumes several external libraries as submodules:

• Parthenon — block-AMR framework (mesh, communication, load balancing).

• singularity-eos — equation-of-state library.

• singularity-opac — opacity library.

These are summarized briefly in their own chapter. It also relies on Catch2 for unit tests and kokkos-kernels for device-side linear solvers.

Contents:

• Building riot
• Materials and Equations of State
• Hydrodynamics
• Material Strength
• Ionization
• Laser Ray Tracing
• Level Sets
• Passive Scalars
• Gravity
• Prescribed Sources
• Tracer Particles
• Turbulent Mixing (BHR)
• Radiation Transport
• Radiation Diffusion (P1)
• Thermonuclear Burn
• Sparse Physics
• Regions
• The Python Interface
• Diagnostics
• Developer’s guide
• Contributing

Indices and tables

• Index

• Module Index

• Search Page

Acknowledgements

The first draft of this documentation was prepared with the assistance of Claude Opus, Anthropic’s large language model. The model was used to survey the RIOT source tree and its submodules, to draft the governing equations, parameter tables, and prose of the preceding chapters, and to produce the figures and example input decks. OpenAI ChatGPT via Codex was also used to assist in additional revisions.