Skip to content

Installation

Because the GUERNICA repository is private, you must first be added as a collaborator before you can access the code.

Clone GUERNICA

GUERNICA depends on MFEM, which is included as a git submodule under external/mfem. Clone the repository together with the submodule:

git clone --recursive <guernica-repository-url>
cd GUERNICA

If the repository was cloned without --recursive, fetch MFEM afterwards with:

git submodule update --init

This should give a directory structure like:

GUERNICA/
├── external/
│   └── mfem/
├── src/
├── include/
├── configs/
├── mesh/
├── scripts/
├── tests/
└── Makefile

Requirements

  • A C++17 compiler and CMake (MFEM is configured with CMake)
  • For CUDA builds: the CUDA toolkit (nvcc, cuBLAS, cuSPARSE, cuFFT)
  • Python 3 with NumPy, SciPy, and Matplotlib, for the plotting scripts in scripts/ and the verification tests

Build GUERNICA

GUERNICA is built with make. If MFEM has not already been built, running make will build both MFEM and GUERNICA automatically.

The general build command is:

make [options]

The main command line options are:

  • DEVICE=<cpu|omp|cuda>: selects the build backend
  • CUDA_HOME=<path>: sets the CUDA installation path
  • CUDA_ARCH=<arch>: sets the CUDA architecture
  • PROFILE=<0|1>: enables or disables profiling-friendly build flags
  • NVTX=<auto|1|0>: controls NVTX marker support for profiling builds

make cpu, make omp, and make cuda are shortcuts for the corresponding DEVICE setting.

Make options

DEVICE

Selects the target backend.

make DEVICE=cpu
make DEVICE=omp
make DEVICE=cuda

Options are:

  • DEVICE=cpu: CPU-only build
  • DEVICE=omp: OpenMP build
  • DEVICE=cuda: CUDA build

Default:

DEVICE=cuda

The FFT charge-exchange model and the test suite require a CUDA build.

CUDA_HOME

Sets the location of the CUDA installation. This is only relevant for CUDA builds.

Example:

make DEVICE=cuda CUDA_HOME=/usr/local/cuda

Default:

CUDA_HOME=/usr/local/cuda

CUDA_ARCH

Sets the CUDA compute architecture used in the build. This is only relevant for CUDA builds.

Example:

make DEVICE=cuda CUDA_ARCH=80

Default:

CUDA_ARCH=75

PROFILE

Controls whether profiling-friendly flags are enabled.

  • PROFILE=0: normal optimized build
  • PROFILE=1: adds profiling/debug-friendly flags

Example:

make DEVICE=cuda PROFILE=1

Default:

PROFILE=0

CUDA builds always include line information (-lineinfo). When PROFILE=1 is used with DEVICE=cuda, register usage reporting, host debug symbols, and NVTX markers (if available) are also added. When PROFILE=1 is used with non-CUDA builds, host debug/profiling flags are added.

NVTX

Controls NVTX marker support in profiling builds.

  • NVTX=auto: enable NVTX if the NVTX3 header (or the legacy library) is found
  • NVTX=1: force NVTX on
  • NVTX=0: force NVTX off

Example:

make DEVICE=cuda PROFILE=1 NVTX=1

Default:

NVTX=auto

Note that NVTX is only used in profiling-oriented CUDA builds.

Inspect build settings

To print the active build configuration:

make print-config

This prints the selected backend, compiler, CUDA path, CUDA architecture, profiling settings, flags, and output locations.

Profiling targets

These targets rebuild a CUDA profiling binary and then run it under Nsight. Pass the GUERNICA arguments through ARGS:

make nsys ARGS="-i example.cfg -o profile_run --overwrite"

make nsys writes prof.nsys-rep and prof.txt. make ncu runs Nsight Compute, and make profile-cuda only builds the profiling binary. See Running Simulations for running the profilers by hand.

Testing

make test-fast builds and runs the quick test tier, and make test-verify runs the slow verification cases. See Testing.

Cleaning

Remove object files, the executable, and the saved git diff:

make clean

Remove all of the above and also remove the MFEM build directory:

make distclean

Remove test binaries and test outputs:

make clean-tests

Notes

  • The executable produced by the build is named guernica.
  • Each build records the git commit (with a -dirty suffix for uncommitted changes) and writes git_diff.patch. Both are copied into every run directory.
  • Header dependencies are tracked automatically, so editing a header rebuilds only the objects that include it.
  • MFEM is built once into external/mfem/build. After changing DEVICE, run make distclean first so that MFEM is rebuilt for the new backend.
  • For CUDA builds, MFEM is configured with CUDA enabled and OpenMP enabled.
  • For OpenMP builds, MFEM is configured with OpenMP enabled and CUDA disabled.
  • For CPU builds, MFEM is configured with both OpenMP and CUDA disabled.