BuildSystems

These are standalone projects that show how to build your own code against AMReX. Each one is a small program meant to be copied as the start of a new project. They are not part of the tutorials’ CMake build; build them from their own directories. See Getting Started for building the tutorials themselves.

CMakeSuperbuild

Source:: BuildSystems/CMakeSuperbuild
Key APIs:: FetchContent_Declare, FetchContent_MakeAvailable, AMReX::amrex, setup_target_for_cuda_compilation

AMReX is downloaded with FetchContent and built together with the application. Most AMReX applications are built this way. AMReX options are ordinary CMake cache variables; the project sets defaults before AMReX is added, and they can be overridden on the command line.

cmake_minimum_required(VERSION 3.25)
project(MyApp LANGUAGES C CXX)

# AMReX options must be set before AMReX is added. Users can still
# override them on the command line, e.g., -DAMReX_SPACEDIM=2.
set(AMReX_SPACEDIM    3    CACHE STRING "Dimension(s) of AMReX")
set(AMReX_MPI         ON   CACHE BOOL   "Enable MPI")
set(AMReX_OMP         OFF  CACHE BOOL   "Enable OpenMP")
set(AMReX_GPU_BACKEND NONE CACHE STRING "GPU backend: NONE, CUDA, HIP or SYCL")
set(AMReX_INSTALL     OFF  CACHE BOOL   "Generate AMReX install targets")

# The GPU language must be enabled before AMReX is added.
if(AMReX_GPU_BACKEND STREQUAL "CUDA")
    enable_language(CUDA)
elseif(AMReX_GPU_BACKEND STREQUAL "HIP")
    enable_language(HIP)
endif()

include(FetchContent)
FetchContent_Declare(amrex
    GIT_REPOSITORY https://github.com/AMReX-Codes/amrex.git
    GIT_TAG        development   # or a release tag such as 26.10
    GIT_SHALLOW    ON)
FetchContent_MakeAvailable(amrex)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE AMReX::amrex)

# With CUDA, the .cpp files must be compiled as CUDA sources.
if(AMReX_GPU_BACKEND STREQUAL "CUDA")
    setup_target_for_cuda_compilation(MyApp)
endif()

Build and run:

cd BuildSystems/CMakeSuperbuild
cmake -S . -B build
cmake --build build -j 8
mpiexec -n 2 ./build/MyApp

AMReX options, e.g., -DAMReX_SPACEDIM=2 -DAMReX_OMP=ON -DAMReX_EB=ON.
GPU: -DAMReX_GPU_BACKEND=CUDA -DCMAKE_CUDA_ARCHITECTURES=native, or HIP with -DAMReX_AMD_ARCH=gfx90a, or SYCL with Intel’s icpx compiler.
A local AMReX source tree instead of a download: -DFETCHCONTENT_SOURCE_DIR_AMREX=/path/to/amrex.
A fixed AMReX version: set GIT_TAG to a release such as 26.10.

CMakeInstalledAMReX

Source:: BuildSystems/CMakeInstalledAMReX
Key APIs:: find_package(AMReX), AMReX::amrex_3d, setup_target_for_cuda_compilation

The project links to an AMReX installed with CMake. find_package(AMReX REQUIRED 3D EB ...) fails if the installed AMReX lacks a requested component. AMReX provides the targets AMReX::amrex_1d, AMReX::amrex_2d and AMReX::amrex_3d for each dimension it was built for. The project inherits AMReX’s compiler, MPI, OpenMP and GPU settings.

cmake_minimum_required(VERSION 3.25)
project(MyApp LANGUAGES C CXX)

# Request the dimension and any optional components the code needs, e.g.,
# find_package(AMReX REQUIRED 3D EB PARTICLES).
find_package(AMReX REQUIRED 3D)

# An AMReX built with a GPU backend needs that language enabled here.
if(AMReX_GPU_BACKEND STREQUAL "CUDA")
    enable_language(CUDA)
    include(AMReXTargetHelpers)
elseif(AMReX_GPU_BACKEND STREQUAL "HIP")
    enable_language(HIP)
endif()

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE AMReX::amrex_3d)

if(AMReX_GPU_BACKEND STREQUAL "CUDA")
    setup_target_for_cuda_compilation(MyApp)
endif()

Install AMReX once, then build the project:

cmake -S /path/to/amrex -B amrex-build -DAMReX_SPACEDIM=3 -DCMAKE_INSTALL_PREFIX=$HOME/amrex-install
cmake --build amrex-build -j 8 --target install

cd BuildSystems/CMakeInstalledAMReX
cmake -S . -B build -DAMReX_ROOT=$HOME/amrex-install
cmake --build build -j 8
mpiexec -n 2 ./build/MyApp

GNUMake

Source:: BuildSystems/GNUMake
Key APIs:: AMREX_HOME, Make.defs, Make.package, Make.rules

A project built with AMReX’s GNU Make system. The application sources are in Source/ and the build happens in Exec/, a layout that scales to codes with several problem setups (Exec/ProblemA, …). Source/Make.package lists the application sources, and AMREX_DIRS lists the AMReX source directories to compile.

# Path to the AMReX source tree. Override with `make AMREX_HOME=/path/to/amrex`.
AMREX_HOME ?= ../../../../amrex

# Build options. Each can be overridden on the command line, e.g., `make USE_CUDA=TRUE`.
DEBUG        ?= FALSE
DIM          ?= 3
COMP         ?= gnu
USE_MPI      ?= TRUE
USE_OMP      ?= FALSE
USE_CUDA     ?= FALSE
USE_HIP      ?= FALSE
USE_SYCL     ?= FALSE
TINY_PROFILE ?= FALSE
BL_NO_FORT   ?= TRUE

include $(AMREX_HOME)/Tools/GNUMake/Make.defs

# Application sources
include ../Source/Make.package
VPATH_LOCATIONS   += ../Source
INCLUDE_LOCATIONS += ../Source

# AMReX sources. Add more directories as needed, e.g., Boundary AmrCore
# LinearSolvers/MLMG EB Particle FFT.
AMREX_DIRS = Base
include $(foreach dir, $(AMREX_DIRS), $(AMREX_HOME)/Src/$(dir)/Make.package)

include $(AMREX_HOME)/Tools/GNUMake/Make.rules

CEXE_sources += main.cpp MyKernels.cpp
CEXE_headers += MyKernels.H

Build and run:

cd BuildSystems/GNUMake/Exec
make -j8 AMREX_HOME=/path/to/amrex
mpiexec -n 2 ./main3d.gnu.MPI.ex

Options are set in Exec/GNUmakefile or on the command line:

Variable	Values
`DIM`	1, 2, 3
`COMP`	gnu, llvm, intel-llvm
`DEBUG`	TRUE, FALSE
`USE_MPI`, `USE_OMP`	TRUE, FALSE
`USE_CUDA`, `USE_HIP`, `USE_SYCL`	TRUE, FALSE (e.g., `USE_CUDA=TRUE CUDA_ARCH=80`)

The name of the executable records the build options, e.g., main3d.gnu.MPI.ex for a 3D GCC build with MPI.