Stable High-Order Cut-Cell Solver (shoccs)

SHOCCS is a Cartesian cut-cell solver for time-dependent PDEs (heat equation, scalar wave, Euler/hyperbolic systems), using high-order finite-difference operators on structured grids with embedded boundaries. It is the code counterpart to the numerical algorithm in the JCP cut-cell paper. The solver is written in C++20 and built on Kokkos for parallel execution (currently host-only).

Status

See docs/ONBOARDING.md to get started and docs/CAPABILITY_AUDIT.md for a current, code-verified picture of what works.

The build is green as of 2026-06-04 (a Kokkos 5.0→5.1.1 create_graph API break was fixed); ctest passes 47/48, with one known failure (t-laplacian); t-csr and t-E2_1 fixed, tracked in docs/CLEANUP_PLAN.md §0a. If a stale build/ tree errors with cmake: not found, regenerate it (see Building below).

Dependencies

• Lua and sol2
• fmt
• pugixml
• spdlog
• cxxopts
• Catch2 v3
• Boost (header-only mp11)
• lapackpp
• Kokkos
• google-benchmark (optional, for benchmarks)

These are provisioned by the project's devcontainer, which uses spack to build the toolchain (see .devcontainer/). The recommended workflow is to build and develop inside that container.

Building

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_TESTING=ON
cmake --build build

Add -DBUILD_BENCHMARKS=ON to also build the benchmark executables.

Note: the root Makefile is a wrapper for building the devcontainer Docker images, not the solver itself. Use the CMake + Ninja commands above to build the solver.

Running

./build/src/app/shoccs heat.lua          # run the solver on a config
./build/src/app/shoccs heat.lua --check  # validate the config and exit

Several example .lua configs are provided at the repository root (heat.lua, scalar_wave.lua, scalar_wave_1d.lua, eigenvalues.lua) and under lua-configs/.

Run the test suite with ctest:

ctest --test-dir build              # all tests
ctest --test-dir build -L systems   # by label
ctest --test-dir build -R t-heat    # single test by name

Documentation

• docs/ONBOARDING.md — start here
• docs/CAPABILITY_AUDIT.md — current capabilities
• docs/reference/ — per-subsystem reference
• docs/handoff/MASTER.md — entry point for the Python stencil-derivation / optimization framework (scripts/stencil_gen/)

Misc

Copyright assertion C20039