ExaHyPE's main function

Table of Contents

• Realisation
  • The runner itself
  • The program phases
• The default runner
• Hand-written runners
• Tailored runners

As with any C++ code, every Peano 4 application needs exactly one file pair that hosts a main() function.

For a plain peano4.api.Project, this pair is produced by peano4.api.runner.DefaultSequence, but this default runner doesn't serve ExaHyPE as it is meant only to be a prototype. So an ExaHyPE project defines its own runner. This is again an ExaHyPE-specific runner, but you can overwrite it with your own bespoke runner. Bespoke runners come in handy, for example, if you want to have dedicated benchmark runs, or complex coupled solvers.

Here's the workflows:

• Every project holds a Project.Generator object. This is an interface, but we ship a default implementation.
• The generator object is called when we ask the project to lower its data into a Peano project through generate_Peano4_project().
• Most generators create a new instance of a header/C++ file pair and add it to the Peano project returned.

Realisation

The runner itself

exahype2.api.Project realises its runner through aggregation: it holds a mainfile_generator attribute, an instance of the nested abstract class Project.Generator, whose construct_output(peano_project) is what actually produces the main file pair. generate_Peano4_project() creates a fresh peano4.api.Project, has every solver contribute its part, and only right before it returns calls self.mainfile_generator.construct_output(peano_project) - so the runner is the very last thing wired into the generated project.

Solid hollow-triangle arrows are inheritance (DefaultSimulationMain extends Project.Generator); dashed hollow-triangle arrows are realisation of the duck-typed main-file protocol (by _ExaHyPEMainFileSequence and, by default, DefaultSequence); diamond-ended lines are aggregation (a Project holds exactly one such object); dashed open arrows are "creates"/"replaces" dependencies at runtime. Reading the diagram bottom-up: an ExaHyPE application never talks to DefaultSequence at all - by the time peano4.api.Project.generate() runs, its main slot has already been swapped out for the ExaHyPE-flavoured sequence.

The program phases

There are four distinct program phases:

1. Setting up the simulation
2. Time stepping
3. Plotting
4. Mesh adaptation and dynamic load balancing

The default runner, exahype2::runSimulation(), runs the setup once and then toggles between time stepping and plotting. Right after each time step, it runs the mesh adaptation if exahype2::isMeshAdaptationRequired() holds, i.e. if the time step has asked for a mesh refinement or erase, or if the load balancing has split recently. Solvers contribute to this fourth phase only if they have a mesh adaptation (exahype2.api.Solver.Solver.MeshAdaptation). The runner never runs the phase if no solver has contributed to it.

The default runner

Hand-written runners

Tailored runners