ExaGRyPE library

ExaGRyPE is Peano's extension for numerical relativity.

It sits on top of ExaHyPE 2 and hosts the C++ code that all ExaGRyPE applications share. The applications themselves (such as applications/exahype2/ccz4, see applications_exahype2_ExaGRyPE) generate their solvers through the Python API and link against this library.

Configuration

ExaGRyPE is enabled like any other Peano extension or toolbox:

./configure --enable-exahype --enable-blockstructured --enable-loadbalancing --enable-exagrype ...

or, with CMake,

cmake .. -DENABLE_EXAHYPE=ON -DENABLE_BLOCKSTRUCTURED=ON -DENABLE_LOADBALANCING=ON -DENABLE_EXAGRYPE=ON

ExaGRyPE requires ExaHyPE 2. As the Einstein equations are three-dimensional, the library is built for 3d only, i.e. there is a libExaGRyPECore3d.a plus its _debug, _asserts, _trace and _stats variants, but no 2d counterpart. If enabled, configure adds the library to the 3d link line of all generated Makefiles. Its unit tests run as part of UnitTests3d.

Content

• exagrype::ccz4 holds the CCZ4 compute kernels (non-conservative product, source, eigenvalues, constraint enforcement and diagnostics) plus the reconstruction of the auxiliary variables for the fourth-order finite differences.
• exagrype::initialvalues holds analytical initial conditions such as the gauge wave or flat spacetime, plus exagrype::initialvalues::ApplyTwoPunctures() for black holes.
• src/exagrype/twopunctures hosts the TwoPunctures code from the EinsteinToolkit (namespaces TP and TP_bindding), which computes initial data for single and binary black holes.

Python API

The package exagrype.api (in src/exagrype/api) layers on top of exahype2.api. Its exagrype.api.CCZ4Solver is an exahype2.api.Solver with the 59 CCZ4 unknowns, the CCZ4 parameters and all PDE terms of CCZ4 pre-registered, i.e. the terms call the kernels from exagrype::ccz4. The module exagrype.api.initialvalues provides the analytical initial conditions. You pick a numerical scheme, a grid construction and a plotter for the solver as for any other exahype2.api.Solver, and add it to an exahype2.api.Project:

solver = exagrype.api.CCZ4Solver("CCZ4", initial_condition=exagrype.api.initialvalues.gauge_wave())
solver.numerical_scheme = exahype2.api.fv.RusanovWithOptimisticExplicitEuler(solver, patch_size)

For the fourth-order Finite Differences of the production runs, use the numerical scheme, grid construction and plotter of exahype2.api.rkfd4 instead:

solver.numerical_scheme  = exahype2.api.rkfd4.CentralDifferencesWithRungeKutta(solver, patch_size, rk_order=4)
solver.grid_construction = exahype2.api.rkfd4.SetupSimulationOverRegularGrid(solver, volume_size=0.04)

These Finite Differences have no artificial dissipation. To add a Kreiss-Oliger dissipation, replace the numerical scheme by exagrype.api.FD4WithKODissipation, which runs the plain fourth-order kernel first and then adds the dissipation per Runge-Kutta stage. By default, the dissipation applies to all unknowns. You can restrict it to some of them:

solver.numerical_scheme  = exagrype.api.FD4WithKODissipation(solver, patch_size, rk_order=4, kreiss_oliger_sigma=8.0)
solver.numerical_scheme  = exagrype.api.FD4WithKODissipation(solver, patch_size, rk_order=4, kreiss_oliger_sigma=8.0, quantities=["lapse", "shift"])

Gauge wave is a complete example. Please note the current limitations: exahype2.api.rkfd4 supports regular grids only, and tracers and the second-order formulation are not available through the new API yet.

Black holes and GSL

TwoPunctures requires the GNU Scientific Library (GSL). It hence is only compiled into the library if you configure Peano with --with-gsl (-DWITH_GSL=ON for CMake). This defines UseGSL and adds GSL to the link line of all generated Makefiles.

Applications switch black hole initial data on per build through -DIncludeTwoPunctures. If an application sets this flag but Peano has been configured without GSL, the build stops with an error message that tells you to reconfigure.