AMReX: a block-structured AMR framework, and the build contract behind it

What block-structured AMR means for your code

AMReX is a software framework for massively parallel block-structured adaptive mesh refinement applications, and the README describes its purpose as accelerating scientific discovery for applications solving partial differential equations on block-structured meshes. The AMR algorithms focus computational resources and allow scalable performance on heterogeneous architectures so that scientists can resolve details in large simulations.

The commitment hidden in that description is the data model. Block-structured means the computational domain is decomposed into rectangular boxes, and the adaptive part means those boxes are refined and coarsened as the solution evolves, so that a shock front or a burning front gets fine cells while the quiet regions do not pay for them. The hierarchy of boxes, and the machinery to keep data consistent across levels, is the framework's core contribution.

A solver written on top of AMReX therefore inherits a specific philosophy about where the physics stops and the infrastructure starts. The data lives in a MultiFab, the array of boxes that holds the solution at one level, and the guided tutorials are described as introducing MultiFab data, parallel iteration and the AMR hierarchy one step at a time. That is the vocabulary you are learning when you start with this framework.

The audience is therefore computational science groups rather than application developers: teams working on combustion, astrophysics, plasma physics and similar multi-physics problems on leadership-class machines.

The feature list is the contract you are signing

The README's feature list is short enough to read as a specification of what the framework will handle for you, and it is worth reading that way.

There are C++ and Fortran interfaces, so a Fortran code can use it directly. Data can be cell-centered, face-centered, edge-centered or nodal, which is a physics-level choice rather than a formatting one. Solves can be hyperbolic, parabolic or elliptic on the hierarchical adaptive grid structure, and there is optional subcycling in time for time-dependent PDEs, which is what lets you advance fine levels with a different timestep than the coarse ones. Particles are supported, and embedded boundary description of irregular geometry is provided so that a non-rectangular domain can be represented.

The parallel and acceleration options are the ones that shape a build. Parallelization is available via flat MPI, OpenMP, hybrid MPI and OpenMP, or MPI with MPI, and GPU acceleration is offered with CUDA for NVidia, HIP for AMD or SYCL for Intel backends. There is parallel I/O, built-in profiling tools, and a plotfile format supported by Amrvis, VisIt, ParaView and yt.

That last point is a practical one. Being able to hand a result to a general purpose visualiser, or to yt, means the framework is not asking you to build a separate post-processing stack, which for a long simulation campaign is often the difference between usable output and a pile of unreadable files.

Building needs CMake 3.25, a C++20 compiler and a small set of switches

AMReX runs on Linux, macOS and Windows, and the README says it is deployed on DOE HPC systems including Perlmutter, Frontier and Aurora. Building it requires a C++20 compiler and CMake 3.25 or newer. MPI is enabled by default and can be turned off with -DAMReX_MPI=OFF, while OpenMP and a GPU toolchain of CUDA, HIP or SYCL are optional.

The build itself is three commands:

git clone https://github.com/AMReX-Codes/amrex.git
cd amrex
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/path/to/installdir
cmake --build build -j8 --target install

Options are set with the -D<var>=<value> form, and the README gives three examples: -DAMReX_MPI=OFF, -DAMReX_SPACEDIM=2 and -DAMReX_GPU_BACKEND=CUDA. AMReX can also be built with GNU Make, and it is packaged for Spack, which is what you want on a cluster where the module system is Spack rather than CMake.

The dimensional switch deserves a note, because it is the one that quietly changes the shape of your code. AMReX_SPACEDIM is the number of spatial dimensions, and a 2D build is a different program from a 3D build in a way that is not visible in the physics. The full set of options and the GNU Make workflow are in the Building AMReX chapter of the User's Guide.

The Dockerfile hands you a toolchain you do not have to assemble

The repository ships a Dockerfile whose purpose is stated in its own header comment: a build environment with AMReX compiled and installed, for reproducing user reports and for working through the tutorials without setting up a toolchain.

The two commands in the comment are the whole interface:

docker build -t amrex .
docker run --rm -it -v "$PWD":/work amrex

The image is Ubuntu 24.04 pinned by digest, and the comment explains the pin: the image provides CMake 3.28 and GCC 13, meeting AMReX's CMake 3.25 and C++20 requirements, and the digest keeps the image reproducible. The build configuration is passed through build arguments, for example a 2D build without MPI:

docker build -t amrex --build-arg AMREX_SPACEDIM=2 --build-arg AMREX_MPI=OFF .

with defaults of AMREX_SPACEDIM=3, AMReX_MPI=ON, AMReX_OMP=OFF, AMReX_PRECISION=DOUBLE and BUILD_JOBS=4, plus AMREX_UID and AMREX_GID set to 1000 so that files written to the mounted directory stay owned by a typical Linux user.

AMReX is installed into /usr/local inside the image, and the compilers and CMake are kept there too, so an application can be built against it inside the same container. That is the detail that makes the image useful for the tutorials rather than only for reproducing a bug: you are not just running a prebuilt library, you have the toolchain to compile your own code against it.

Consuming it from your own project is a find_package and a link

The usage section is deliberately minimal, and the reason is that the framework is a CMake package. The quickest way to start is to build one of the guided tutorials, which introduce MultiFab data, parallel iteration and the AMR hierarchy one step at a time. To use an installed AMReX from your own CMake project, it is two lines:

find_package(AMReX REQUIRED)
target_link_libraries(my_app PUBLIC AMReX::amrex)

The imported target AMReX::amrex carries the include directories, the libraries and the compile definitions, so a dependent project does not repeat the configuration.

Runnable example codes are kept in a separate amrex-tutorials repository and published as Example Codes, covering basic usage, linear solvers, particles, embedded boundaries and GPU offloading. The separation between examples and guided tutorials is a teaching choice: an example shows you a complete program that does one thing, while a guided tutorial walks you through one concept with code you build up. The documentation set follows the same logic with the User's Guide for features and functions, the Technical Reference generated by Doxygen for searching the code, and slides and video recordings from a tutorial session organised by NERSC, OLCF and ALCF on 2024-03-14.

Support comes through GitHub Discussions and issues, and contributions are pull requests against the development branch.

Monthly releases, open governance, and the cases it does not fit

The release numbering is a calendar: AMReX 26.08 on 2026-08-02, 26.09 on 2026-09-01 and 26.10 on 2026-10-01, with the last push to the repository on 2026-10-22 and the default branch named development. A monthly train with a development branch is a project that expects users to track upstream rather than vendor a copy, which is normal for a framework in the HPC world and unusual for a library.

The governance is open, with a steering committee, a technical committee and contributor roles described in GOVERNANCE.md. The project is also cited through CITATION.cff, a paper/ directory and a Zenodo DOI, which is the academic convention for software that appears in publications.

The licence is BSD 3-Clause according to the badge, with LICENSE and NOTICE files in the repository, although the repository is classified with a custom licence category that GitHub cannot name. Read those files for the terms, and this is not legal advice.

Where AMReX is the wrong tool is fairly clear. If you need a grid and a solver for a modest problem, the AMR hierarchy and the parallel infrastructure are overhead you do not need. If your problem is not a partial differential equation on a mesh, most of the framework is irrelevant. And if your group cannot absorb a monthly upstream release into a long simulation campaign, a fixed-mesh code you own end to end is the safer choice. The honest summary is that AMReX pays for itself when the resolution requirement varies across space, which is exactly the case the Exascale Computing Project applications in its gallery, ExaSky, WarpX, Pele, Astro and MFiX-Exa, are built for.

Editorial conclusion

AMReX fits a research group writing a partial differential equation solver that needs adaptive refinement and multi-node scaling, and that is prepared to adopt another group's mesh and linear algebra conventions. It does not fit a small application that only needs a grid, and it does not fit a team unwilling to track a monthly release branch. Before adopting it, build the guided tutorials rather than the examples, and confirm that the AMR overhead is worth it against the fixed-mesh alternative for your own problem.

Frequently asked questions

Official sources

1. AMReX-Codes/amrex on GitHub
2. Issues
3. Project website
4. README
5. Releases