Skip to content

Getting Started

This page describes how to build and run GUERNICA from a fresh checkout. GUERNICA vendors MFEM under external/mfem, so in the common case you can clone the repository and run make without installing MFEM separately.

Quick start

1) Clone (with submodules)

If you have access to the private repository:

git clone --recurse-submodules <GUERNICA_REPO_URL>
cd GUERNICA

If you already cloned without submodules:

git submodule update --init --recursive

2) Build

From the repository root:

make

This builds:

  • MFEM into external/mfem/build/
  • the GUERNICA executable ./guernica

Note

The Makefile automatically configures and builds MFEM for the selected backend. On a fresh clone, the first build may take several minutes.

3) Run

./guernica

Most outputs are written to the gf_out/ directory.

Build backends

The build backend is selected at build time using the DEVICE variable.

Supported options are:

  • CPU (serial)
make DEVICE=cpu
  • CPU with OpenMP
make DEVICE=omp
  • CUDA (GPU acceleration)
make DEVICE=cuda

Convenience targets are also provided:

make cpu
make omp
make cuda

Note

If no backend is specified, DEVICE=cuda is used by default.

CUDA options (Linux)

When building with DEVICE=cuda, the Makefile uses:

  • CUDA_HOME (default: /usr/local/cuda)
  • CUDA_ARCH (default: 75)

You can override these at build time, for example:

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

GUERNICA links against CUDA libraries including cuFFT, which is used by the FFT-based charge exchange operator.

Useful build helpers

make print-config

This prints the selected compiler, flags, backend, CUDA settings, and MFEM build paths.

Profiling-friendly build (optional)

make DEVICE=cuda PROFILE=1

This enables additional debug and profiling flags suitable for GPU profiling workflows.

If libnvToolsExt is available, NVTX markers may be enabled automatically. You can explicitly control this with:

make DEVICE=cuda NVTX=1

or

make DEVICE=cuda NVTX=0

Outputs

Running GUERNICA typically produces:

  • ex9.mesh
    A copy of the mesh written for reference.

  • gf_out/
    A directory containing MFEM GridFunction output files and diagnostics.

See Overview → Inputs & Outputs for a detailed description of available outputs and file naming conventions.

macOS notes

  • The Makefile includes small macOS-specific linking differences automatically.
  • CUDA builds are generally not supported on macOS.
  • On macOS, use one of:
make DEVICE=cpu

or

make DEVICE=omp

Cleaning

To remove object files, the executable, and common output artifacts:

make clean

To also remove the MFEM build directory:

make distclean

Common issues

MFEM submodule missing

Symptoms include a missing external/mfem directory or CMake configuration errors during the build.

Fix:

git submodule update --init --recursive

CMake not found

MFEM is configured using CMake. Ensure CMake is installed and available in your PATH.

CUDA not found (Linux)

If you see errors related to nvcc or missing CUDA libraries:

  • Verify that CUDA is installed
  • Set CUDA_HOME to the correct location

Example:

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

Incorrect GPU architecture

If the build targets the wrong GPU architecture, you may see runtime launch failures or poor performance. Set CUDA_ARCH to match your GPU.