Our First Configuration File

We have Peano 4 and ExaHyPE 2 installed, but how do we use it? For this, let's take a look at our first configuration file, in tutorials/exahype2/acoustic/Acoustic.ipynb The configuration files are in Python, so it should surprise no one that they start with the following:

import peano4, exahype2

With our imports out of the way, we are free to define our problem, for this, let's start with a solver:

my_solver = exahype2.solvers.aderdg.GlobalAdaptiveTimeStep(
    name                  = "PlanarAcousticSolver",
    order                 = 5,
    min_cell_h            = cell_h,
    max_cell_h            = cell_h,
    time_step_relaxation  = 0.9,
    unknowns              = {"p": 1, "v": 2},
    auxiliary_variables   = {}
)

This creates an ADER-DG solver of discretization order 5 named PlanarAcousticSolver with adaptive time-stepping and two unknowns: p and v, with v having a multiplicity of two (i.e., we have two velocities). Unknowns and auxiliary variables can be either specified by indicating how many there are (unknowns = 3), in which case users must keep track of them manually, or they can be specified via a dictionary, which will allow us to access them by name. The parameter time_step_relaxation is related to the adaptive time-stepping, and serves as a safety factor to guarantee stable time step sizes.

Now that we have a solver, let's define the problem we want to solve, and while we're at it let's add a simple optimisation:

my_solver.set_implementation(
    flux = exahype2.solvers.PDETerms.User_Defined_Implementation
)

my_solver.add_kernel_optimisations(is_linear=True)

This is again relatively self-explanatory: The acoustic equations do not require sources or a non-conservative flux, so the only term that remains is the flux. exahype2.solvers.PDETerms.User_Defined_Implementation means we want to define this manually. With this out of the way, we need to create an environment for the solver to run in, this is a ExaHyPE 2 project:

exahype2_project = exahype2.Project(
    namespace     = ["tutorials", "exahype2", "acoustic"],
    directory     = ".",
    project_name  = "PlanarWaves",
    executable    = "PlanarWaves"
)

exahype2_project.add_solver(my_solver)

This handles things like the grid generation, traversal, data exchanges and such. Once again we need to populated it with some data, such as the number of dimensions our problem is in, the size of the domain, how long the simulation should run for and when to plot.

We can also specify here whether we want to use periodic boundary conditions:

exahype2_project.set_global_simulation_parameters(
  dimensions            = 2,
  size                  = [2., 2.],
  offset                = [0., 0.],
  min_end_time          = 1.414,  # sqrt(2)
  max_end_time          = 1.414,  # sqrt(2)
  first_plot_time_stamp = 0.0,
  time_in_between_plots = 0.1,
  periodic_BC           = [True, True],
)

Finally, we configure the load balancer for the project, we inform the project of where to look for the Peano libraries, and then we can generate all the glue code we need and compile it:

exahype2_project.set_load_balancer("new ::exahype2::LoadBalancingConfiguration")
exahype2_project.set_Peano4_installation("../../../", peano4.output.CompileMode.Release)
peano4_project = exahype2_project.generate_Peano4_project()
peano4_project.build()

Once this is finished compiling, let's run it:

./PlanarWaves

And, while this is running, let's go take a look at our implementation over at Our First Implementation File so we can actually figure out what we're simulating!