Chemical Transport with AMReX and SUNDIALS

This repository contains a small 2D passive-scalar transport solver for the linear advection-diffusion equation. AMReX manages the structured mesh, MPI decomposition, ghost-cell exchange, and plotfile output. SUNDIALS ARKODE advances the semi-discrete system in time with an adaptive explicit Runge-Kutta integrator.

The default problem is a periodic unit square with a Gaussian concentration pulse, constant advection velocity, and isotropic diffusion.

Build with Spack

spack env activate .
spack concretize
spack install

That installs AMReX and SUNDIALS and builds this code through the local chem-transport Spack package defined in spack-repo/packages/chem-transport/package.py. The package requests amrex +sundials so the executable can use AMReX's shipped MultiFab-backed N_Vector, and src/main.cpp hard-enforces AMREX_SPACEDIM == 2, so the executable is strictly 2D.

The repository also carries a generated spack.lock from a successful install to pin the validated dependency graph.

Run

mpiexec -n 1 "$(spack location -i chem-transport)"/bin/chem_transport \
  "$(spack location -i chem-transport)"/share/chem-transport/inputs/chem_transport.inputs

You can override any AMReX input parameter on the command line, for example:

mpiexec -n 2 "$(spack location -i chem-transport)"/bin/chem_transport \
  inputs/chem_transport.inputs transport.final_time=0.25 plot.prefix=run_transport

The run writes 2D AMReX plotfiles named plt00000, plt00001, and so on.

Model and Numerics

The code solves

$$ \frac{\partial c}{\partial t} + \nabla \cdot (\mathbf{u} c) = D \nabla^2 c $$

for a scalar concentration field $c(x, y, t)$ on a uniform Cartesian mesh. In the current implementation:

• the code is strictly 2D (AMREX_SPACEDIM == 2)
• the domain is rectangular and periodic in both directions
• the velocity $\mathbf{u} = (u_x, u_y)$ is spatially constant
• the diffusion coefficient $D$ is a single constant scalar
• the initial condition is a Gaussian pulse plus a uniform background level

The default initial state is

$$ c(x, y, 0) = c_{\mathrm{background}} + A \exp\left(-\frac{1}{2}\left[\left(\frac{x - x_0}{w_x}\right)^2 + \left(\frac{y - y_0}{w_y}\right)^2\right]\right) $$

where $A$ is transport.pulse_amplitude, $(x_0, y_0)$ is transport.pulse_center, and $(w_x, w_y)$ is transport.pulse_width.

The spatial operator is assembled in TransportSystem::rhs(...):

• advection uses first-order upwind fluxes based on the sign of each velocity component
• diffusion uses the standard 5-point second-order central Laplacian
• AMReX fills one layer of ghost cells using periodicity before each RHS evaluation

Time integration is handled by SUNDIALS ERKStep, which treats the semi-discrete method-of-lines system as an explicit ODE:

• solution data are wrapped directly as an AMReX MultiFab N_Vector
• ARKODE uses scalar relative and absolute tolerances from the input file
• the initial and maximum internal time step are user-configurable
• the driver always writes a plotfile at t = 0, then advances to each requested output time until transport.final_time

This setup is intended as a compact example of coupling AMReX data structures to a SUNDIALS explicit time integrator, rather than as a high-order or stiff chemistry transport formulation.

Input Options

These are the application-specific ParmParse options currently read by the executable. Array-valued entries take two numbers because the code is 2D.

Option	Default	Description
transport.n_cell	128 128	Number of cells in x and y.
transport.max_grid_size	32	Maximum AMReX box size used when chopping the domain for parallel distribution.
transport.prob_lo	0.0 0.0	Physical lower corner of the rectangular domain.
transport.prob_hi	1.0 1.0	Physical upper corner of the rectangular domain.
transport.velocity	1.0 0.35	Constant advection velocity (u_x, u_y).
transport.diffusion	2.5e-4	Constant isotropic diffusion coefficient D.
transport.background	1.0e-8	Uniform concentration offset added everywhere at initialization.
transport.pulse_amplitude	1.0	Peak amplitude of the Gaussian pulse above the background.
transport.pulse_center	0.2 0.5	Center of the Gaussian pulse in physical coordinates.
transport.pulse_width	0.08 0.08	Gaussian width parameters in each direction.
transport.final_time	0.5	Final simulation time passed to ARKODE.
transport.output_interval	0.1	Time between plotfiles. If this is <= 0, only the initial and final states are written.
transport.rtol	1.0e-6	Relative tolerance used by ARKodeSStolerances.
transport.atol	1.0e-10	Absolute tolerance used by ARKodeSStolerances.
transport.init_step	1.0e-4	Initial internal time step suggested to ARKODE.
transport.max_step	5.0e-3	Upper bound on the internal time step size.
plot.prefix	plt	Prefix for AMReX plotfiles, producing names like plt00000.

Any of these can be overridden on the command line:

mpiexec -n 2 "$(spack location -i chem-transport)"/bin/chem_transport \
  inputs/chem_transport.inputs \
  transport.n_cell="256 256" \
  transport.velocity="0.5 0.0" \
  transport.final_time=1.0 \
  plot.prefix=advect_x

The main implementation lives in src/main.cpp.

Visualization

After spack env activate ., locate the installed Amrvis binaries with:

spack find -p amrvis

Typical launch patterns are:

/path/from/spack-find/bin/amrvis2d.gnu.MPI.ex plt00000

If needed, export DISPLAY first:

export DISPLAY=:1