Getting Started

This page covers everything needed to go from a fresh checkout to a running ExaGOOP simulation: system requirements, obtaining the source, building with CMake or GNUmake, and verifying the installation.

System Requirements

ExaGOOP runs on macOS and Linux. Windows is not officially supported; Windows users should use the Windows Subsystem for Linux (WSL).

Compiler. A C++17-capable compiler is required:

GCC 8 or newer
Clang 3.6 or newer

Microsoft Visual C++ (MSVC) is not offcially supported. However, the developers are not aware of any potential issues preventing Windows 11 builds on non-GPU architectures.

Build system. Either of:

CMake 3.20 or newer (recommended)
GNU Make 3.81 or newer

MPI. An MPI-2 implementation (e.g. OpenMPI, MPICH) is required for multi-process runs. Single-process CPU builds can be compiled without MPI by setting EXAGOOP_ENABLE_MPI=OFF (CMake) or USE_MPI=FALSE (GNUmake).

GPU (optional).

NVIDIA GPUs: CUDA 11 or newer
AMD GPUs: ROCm 5.2 or newer

The AMReX framework (bundled as a submodule) handles the low-level GPU portability layer.

Obtaining the Source

Clone the repository with its AMReX submodule in a single step:

git clone --recurse-submodules https://github.com/NatLabRockies/Exagoop.git

This creates an Exagoop/ directory. The AMReX sources reside under Exagoop/Submodules/amrex.

Next, set the two environment variables that the build system and test scripts rely on. Add these to your ~/.bashrc or ~/.zshrc to make them persistent:

export MPM_HOME=/path/to/Exagoop
export AMREX_HOME=${MPM_HOME}/Submodules/amrex

Building with CMake

The Build_Cmake/cmake.sh script contains a template cmake invocation; edit it to match your environment before running it.

cd $MPM_HOME/Build_Cmake
# Edit cmake.sh as described below, then:
sh cmake.sh

Key options in cmake.sh:

Option	Default	Description
`-DEXAGOOP_ENABLE_MPI`	`OFF`	Enable MPI parallelism
`-DEXAGOOP_ENABLE_CUDA`	`OFF`	Enable NVIDIA GPU support (requires CUDA ≥ 11)
`-DEXAGOOP_ENABLE_HIP`	`OFF`	Enable AMD GPU support (requires ROCm ≥ 5.2)
`-DAMReX_CUDA_ARCH`	`Auto`	CUDA compute capability, e.g. `80` for A100
`-DAMReX_AMD_ARCH`	`gfx90a`	ROCm target architecture
`-DEXAGOOP_USE_TEMP`	`OFF`	Compile in the heat-transfer module
`-DEXAGOOP_PRECISION`	`DOUBLE`	Floating-point precision: `SINGLE` or `DOUBLE`
`-DEXAGOOP_USE_HDF5`	`OFF`	Enable HDF5 output

EXAGOOP_DIM is fixed at 2 in the CMake build. Users should set these variables corresponding to the dimensionality: of the problem they intend to solve.

On a successful build the executable ExaGOOP<dim>d.*.exe is placed in $MPM_HOME/Build_Cmake. The executable name is determined by the dimensionality used as well other build variables.

Building with GNUmake

Open $MPM_HOME/Build_Gnumake/GNUmakefile and set the options near the top of the file:

Variable	Default	Description
`DIM`	`1`	Spatial dimension: `1`, `2`, or `3`
`COMP`	`gnu`	Compiler: `gnu` or `clang`
`USE_MPI`	`TRUE`	Enable MPI
`USE_OMP`	`FALSE`	Enable OpenMP threading
`USE_CUDA`	`FALSE`	Enable NVIDIA GPU (CUDA)
`USE_HIP`	`FALSE`	Enable AMD GPU (ROCm/HIP)
`USE_TEMP`	`FALSE`	Compile in the heat-transfer module
`USE_EB`	`FALSE`	Compile in embedded boundary support (requires `DIM` ≥ 2)
`DEBUG`	`FALSE`	Build in debug mode
`PRECISION`	`DOUBLE`	Floating-point precision: `SINGLE` or `DOUBLE`

Then build:

cd $MPM_HOME/Build_Gnumake
make -j$(nproc)

The executable is named ExaGOOP<dim>d.<comp>[.<parallel>].ex and is placed in the same directory.

Verifying the Build

The quickest verification is to run the 1-D axial bar vibration test, which has no physics-module dependencies and produces a known analytical solution:

cd $MPM_HOME/Tests/1D_Axial_Bar_Vibration
sh Generate_MPs_and_InputFiles.sh
# This creates an initial material point file (mpm_particles.dat or mpm_particles.h5) and an input file- Inputs_1DAxialBarVibration.inp
# Now copy the ExaGOOP executable from the build folder and run the solver
./ExaGOOP1d.*.ex Inputs_1DAxialBarVibration.ex

If the run completes without errors, the build is working correctly. For a richer check, the tutorials section walks through two multi-physics test cases end-to-end.

Visualizing Output

ExaGOOP writes output in the AMReX plotfile format. Two types of output files are produced:

plt* files — particle (material point) data
nplt* files — nodal grid data

Both can be loaded directly in ParaView using the built-in AMReX/BoxLib reader. Open the top-level plt*/ or nplt*/ directory as a dataset.

Getting Help

For questions and discussion: GitHub Discussions
To report a bug: GitHub Issues (include your compiler version, MPI implementation, and the build flags used)