Exasim is a C++ library for solving partial differential equations (PDEs) with high-order discontinuous Galerkin (DG) methods. It combines a templated solver core (HDG / LDG, GMRES, Newton, DIRK time stepping) with optional symbolic code generation and Kokkos- based backend portability, so the same model definition runs on CPU, GPU, MPI, and MPI+GPU without changing the math.
- Spatial discretizations — local DG and hybridized DG; hex / tet / quad / tri elements; arbitrary polynomial order.
- Time stepping — diagonally implicit Runge–Kutta (DIRK) with configurable stage count.
- Solvers — Newton outer + GMRES inner, multiple preconditioners (block ILU, additive Schwarz, RB acceleration).
- Multi-physics — monolithic HDG with multi-domain coupling.
- Backend portability — Kokkos picks CPU / NVIDIA GPU (CUDA) / AMD GPU (HIP) at compile time.
- Distributed-memory — MPI partitioning via ParMETIS.
To run a PDE through Exasim the user must specify three things:
the PDE math, the solver setup, and the mesh. For each of the
three, the user picks one of two forms — an external artifact
(text file or binary blob) or a value constructed in C++. The
two-way combinations are walked through end-to-end in
tutorial/, which is the recommended starting
point.
Quick reference for the three axes:
| Axis | "built" form (external artifact) | "C++" form (in your program) |
|---|---|---|
| PDE math | pdemodel.txt (SymEngine DSL; text2code emits the C++ header) |
my_model.hpp (a struct against <exasim/model.hpp>) |
| Solver setup | pdeapp.txt (key-value text file) |
ExasimSolver<M> API calls |
| Mesh | grid.bin (binary blob, generated by a small script) |
flat C arrays passed to set_mesh / set_mesh_distributed |
The Model contract — full method signatures, defaults, and
indexing layouts — is documented in
02-model-contract.md. It is the
reference both the handwritten path and the text2code-generated
path target.
Compile-time choice driven by CMake flags:
| Variant | Kokkos build | EXASIM flags |
|---|---|---|
| CPU | kokkos/buildserial |
EXASIM_NOMPI=ON |
| GPU | kokkos/buildcuda (or buildhip) |
EXASIM_NOMPI=ON, EXASIM_CUDA=ON |
| MPI | kokkos/buildserial |
EXASIM_MPI=ON |
| MPI+GPU | kokkos/buildcuda |
EXASIM_MPI=ON, EXASIM_CUDA=ON |
The same source code produces all four binaries — only the build configuration differs.
Exasim/
├── apps/ # in-tree example PDEs
│ ├── poisson/ # poisson2d, poisson3d, periodic, ...
│ ├── navierstokes/ # naca0012steady, cone, sharpb2, ...
│ └── library_example/ # codegen + facade test apps + harness
├── backend/ # implementation: Common, Discretization,
│ ├── Common/ # Preprocessing, Solution, Postprocessing,
│ ├── Discretization/ # Model
│ ├── Preprocessing/
│ ├── Solution/
│ └── Postprocessing/
├── include/exasim/ # public API (headers consumed by users)
├── kokkos/ # vendored Kokkos
├── metis/ # vendored METIS + ParMETIS + GKlib
├── text2code/ # vendored SymEngine + text2code generator
├── baseline/ # recorded reference outputs for tests
├── tutorial/ # walkthrough through every supported path
├── docs/ # this documentation tree
└── doc/ # legacy docs (some still authoritative)
- Set up your environment → 01-installation.md
- Walk through the supported paths end to end →
../tutorial/ - Look up a method on the
Modelcontract → 02-model-contract.md - Read about the test harness, baseline format, or preprocessing internals → 03-internals/