Building and testing

Prerequisites

Docker or Podman
dvt for the devcontainer, or any editor with Dev Containers support

The devcontainer (.devcontainer/devcontainer.json) is built from base-ubuntu plus the cpp-devtools Homebrew feature, which provides the C++23 toolchain (Clang, CMake, Ninja, just). The libraries -- netcdf-cxx4 and Catch2 v3 -- come from the Brewfile via brew bundle, run automatically as the container's postCreateCommand.

Build

Everything is driven by the justfile:

just configure   # cmake -G Ninja -B build (Clang, RelWithDebInfo)
just build       # cmake --build build
just test        # ctest --test-dir build --output-on-failure

just build depends on just configure, and just test on just build, so just test alone does the lot from a clean checkout.

Running the tests

The suite is Catch2, discovered by CTest. Tags of interest:

Tag	Meaning
`[slow]`	manufactured-solution and convergence-rate tests; seconds each
`[mms]`	manufactured-solution order-of-accuracy checks
`[netcdf]`	round-trip through a real netCDF file
`[mosolov]`	the viscoplastic example reduced-form checks
`[snippet]`	the compiled documentation snippets

Run a subset directly through the test binary:

./build/tests/multigrid_tests "[mms]"          # just the order-of-accuracy tests
./build/tests/multigrid_tests "~[slow]"        # everything except the slow ones

The example programs

./build/examples/poisson/poisson 1 2 4   # solves for aspect ratios 1, 2, 4
./build/examples/mosolov/mosolov         # viscoplastic channel flow, B = 0.24, b = 2

Each writes a netCDF-4 file per case (poisson_A2.0.nc, A2.00000B0.24000.nc). Inspect one with ncdump -h.

Extra build options

CMake option	Default	Effect
`MULTIGRID_BUILD_EXAMPLES`	`ON`	build `examples/poisson` and `examples/mosolov`
`MULTIGRID_BUILD_TESTS`	`ON`	build the Catch2 suite and the doc snippets
`MULTIGRID_WERROR`	`OFF`	add `-Werror` to every target

Documentation

The docs are a separate, Python-only toolchain kept in pixi.toml:

just docs         # mkdocs build --strict  (API reference + this guide)
just docs-serve   # live-reload preview on http://localhost:8000

just docs regenerates the Doxygen/mkdoxy API reference from the /// comments in include/multigrid/ on every run.