Modelling the PDE solver

Table of Contents

• Unknowns and auxiliary variables
• PDE terms

This page discusses how a user describes what their solver should compute, i.e.

the mathematical model, as opposed to how it is eventually computed (discussed on the adding a numerical scheme page). Modelling is entirely done through exahype2.api.Solver and stays purely descriptive, in line with the design philosophy that keeps the what free of any how.

ExaHyPE 2 solves partial differential equations of the form

\( \frac{\partial Q}{\partial t} + \nabla . F(Q, \nabla Q) + B(Q) . \nabla Q= S(Q) + \sum_{i = 1}^{n_{ps}} \delta_i \)

and users model an instance of this equation by creating an exahype2.api.Solver (or a concrete subclass thereof, such as a Finite Volume or ADER-DG solver) and configuring two things on it: the unknowns and the individual PDE terms.

Unknowns and auxiliary variables

Every solver is constructed with an unknowns and an auxiliary_variables specification. Both can be given either as a plain integer (just the multiplicity) or as a dictionary mapping a variable name onto its multiplicity, e.g.

solver = exahype2.api.fv.SomeFiniteVolumeSolver(
  name                 = "MyEulerSolver",
  unknowns             = {"rho": 1, "j": 3, "E": 1},
  auxiliary_variables  = 0,
)

Both groups end up merged into one data vector Q per mesh entry (Finite Volume voxel, DG degree of freedom, ...), but only the unknowns are subject to the actual PDE formulation above - auxiliary variables may vary in space but are not evolved by the PDE terms. If a dictionary is used, the code generator additionally emits a VariableShortcuts file so user code can address Q's entries by name instead of by raw offset.

PDE terms

Q, F, B, S and the point sources \( \delta_i \) from the equation above each correspond to one exahype2.api.PDETerm registered with the solver via Solver.add_pde_term(). Well-known terms - the flux (exahype2.api.Flux), eigenvalues, the non-conservative product, algebraic/point sources, boundary conditions, ... - ship as their own PDETerm subclasses that pin down the C++ method name and signature; solver-specific terms can be added with the plain PDETerm constructor.

A term's implementation is one of

• PDETerm.USER_DEFINED: the generated C++ method is left pure virtual for the user to implement by hand,
• PDETerm.NONE (the default): the term is switched off, i.e. this contribution is absent from the PDE, or
• PDETerm.EMPTY: the method is generated but does nothing,

or an actual C++ code snippet that becomes the method body verbatim, e.g. for small, closed-form terms that do not warrant a hand-written implementation.

A term is thus itself a small, purely descriptive object (name, signature, implementation), and it is only the corresponding generator (term.generator,

See also

PDETerm.Generator) that later lowers it into an actual generated C++ method - the same descriptive-class-plus-generator pattern used throughout ExaHyPE 2 (

Design philosophy and principles).