Quickstart: Clone-Build-Run¶

Copy-paste commands for common build scenarios. If you are on a supported HPC system, start with the HPC section below — it is the fastest path to a working build. If you are on a workstation or an unlisted system, start with Build with CMake or Build with GNU Make.

Quickstart on HPC Systems¶

Each tab covers only the machine-specific setup and build command. Shared guidance for directory layout and batch vs interactive runs is listed once below the tabs.

Perlmutter (NERSC)

git clone --recursive https://github.com/erf-model/ERF.git
cd ERF
source Build/machines/perlmutter_erf.profile

ERF_HOME=$(pwd) ./Build/cmake_with_kokkos_many_cuda.sh
cd install/bin
# Next: choose a run mode in "Run After Build" below

Download build+run snippet Download Perlmutter sbatch example Full guide: Perlmutter (NERSC)

Kestrel (NREL)

git clone --recursive https://github.com/erf-model/ERF.git
cd ERF
source Build/machines/kestrel_erf.profile

ERF_HOME=$(pwd) ./Build/cmake_with_kokkos_many_cuda.sh
cd install/bin
# Next: choose a run mode in "Run After Build" below

Download Kestrel custom build script Download Kestrel sbatch example Full guide: Kestrel (NREL)

Frontier (OLCF)

git clone --recursive https://github.com/erf-model/ERF.git
cd ERF
source Build/machines/frontier_erf.profile

ERF_HOME=$(pwd) ./Build/cmake_with_kokkos_many_hip.sh
cd install/bin
# Next: choose a run mode in "Run After Build" below

Download build+run snippet Download Frontier sbatch example More machine context: Machine Profiles, Cray Detection, Build Scripts, and Workstation Builds

Aurora (ALCF)

git clone --recursive https://github.com/erf-model/ERF.git
cd ERF
source Build/machines/aurora_erf.profile
export NETCDF_DIR=<path-to-netcdf>

ERF_HOME=$(pwd) ./Build/cmake_with_kokkos_many_sycl.sh
cd install/bin
# Next: choose a run mode in "Run After Build" below

Download build+run snippet Download Aurora PBS example Full guide: Aurora (ALCF): Build and Run with SYCL

Not on a listed machine? See Machine Profiles, Cray Detection, Build Scripts, and Workstation Builds for machine profile customization, or continue below for generic build workflows.

Run After Build: interactive smoke test or batch job

Use interactive mode for a quick check (2-10 steps). Use batch mode for normal production runs and longer jobs. Use interactive allocations primarily for debugging. Use batch jobs for normal testing and production runs.

Interactive Smoke Test (Fast)

Slurm (Perlmutter/Kestrel/Frontier):

# Account/project is usually required on shared systems
salloc -A <account_or_project> -N 1 -t 00:30:00
srun -n 4 ./erf_exec ../../Exec/CanonicalTests/ABL/inputs_most \
  amr.max_step=10

PBS (Aurora):

qsub -I -A <PROJECT> -q debug -l select=1 -l walltime=1:00:00
mpiexec -n 4 ./erf_exec ../../Exec/CanonicalTests/ABL/inputs_most \
  amr.max_step=10

Batch Scripts Provided

System	Scheduler	Provided script	Launch command
Perlmutter	Slurm	`run_perlmutter_erf.sbatch`	`sbatch ../../Docs/sphinx_doc/scripts/quickstart/run_perlmutter_erf.sbatch`
Kestrel	Slurm	`run.erf.aw.job_arena`	`sbatch ../../Docs/sphinx_doc/scripts/quickstart/run.erf.aw.job_arena`
Frontier	Slurm	`run_frontier_erf.sbatch`	`sbatch ../../Docs/sphinx_doc/scripts/quickstart/run_frontier_erf.sbatch`
Aurora	PBS	`submit_erf_aurora.pbs`	`qsub ../../Docs/sphinx_doc/scripts/quickstart/submit_erf_aurora.pbs`

Build with GNU Make¶

For workstations or systems where CMake is not preferred:

CPU Build

git clone --recursive git@github.com:erf-model/ERF.git
cd ERF/Exec
make COMP=gnu USE_MPI=TRUE
mpiexec -n 4 ./ERF3d.gnu.TPROF.MPI.ex CanonicalTests/ABL/inputs_most

GPU Build

git clone --recursive git@github.com:erf-model/ERF.git
cd ERF/Exec
make COMP=gnu USE_MPI=TRUE USE_CUDA=TRUE
mpiexec -n 4 ./ERF3d.gnu.TPROF.MPI.CUDA.ex CanonicalTests/ABL/inputs_most

Default GNU Make builds are done in ERF/Exec. Use ERF/.Exec_dev/<test_name> only when working on development tests.

Build with CMake¶

Suggested path for most users not on a listed HPC system. Choose other workflows only when you need tighter control (see Build Systems and Options for details).

Automated Script (Suggested)

git clone --recursive git@github.com:erf-model/ERF.git
cd ERF
# Customize (optional): export ERF_BUILD_DIR=... ERF_SOURCE_DIR=... ERF_INSTALL_DIR=... or ERF_HOME=...
ERF_HOME=$(pwd) ./Build/cmake_with_kokkos_many.sh

# Run from install directory
cd install/bin
mpiexec -n 4 ./erf_exec ../../Exec/CanonicalTests/ABL/inputs_most

Out-of-Source Build

git clone --recursive git@github.com:erf-model/ERF.git
cd ERF
mkdir build && cd build
../Build/cmake.sh
make -j

# Run from build tree
cd Exec
mpiexec -n 4 ./erf_exec ../../Exec/CanonicalTests/ABL/inputs_most

In Build/ Directory

git clone --recursive git@github.com:erf-model/ERF.git
cd ERF/Build
./cmake.sh
make -j

# Run from Exec subdirectory
cd Exec
mpiexec -n 4 ./erf_exec ../../Exec/CanonicalTests/ABL/inputs_most

Cleanup¶

For a quick rebuild after source changes, make clean and rebuilding in place works for most cases. If you have changed CMake configuration options or are hitting strange errors, removing the build directory entirely and starting fresh is more reliable — see Build Troubleshooting.

GNU Make

# From ERF/Exec (or ERF/.Exec_dev/<test_name> for dev-test builds)
make clean           # Remove build artifacts
make realclean       # Same as clean
make cleanconfig     # Remove configuration only

In Build/ Directory

# From ERF/Build
make distclean       # Clean all CMake artifacts
make uninstall       # Uninstall based on install-manifest.txt

# If configuration failed, manually remove
rm -rf CMakeFiles/ CMakeCache.txt

Out-of-Source / Automated Script

# From ERF root
cmake --build build --target distclean
cmake --build build --target uninstall

# Or remove directories entirely
rm -rf build/ install/

For detailed build options and troubleshooting, see Build Systems and Options.