Key parts of the code - GRTLCollaboration/engrenage GitHub Wiki

Examples folder

The place to start is in the Examples folder, where there are currently two jupyter notebooks, one for each physical example. These are:

  1. An oscillaton - this is a solitonic object where gravity balances the tendency of the (real) scalar field to disperse, giving a (time varying) and quasi stable, localised configuration of the scalar field that gradually disperses over a timescale much longer than the simulation. By running the sections of the code (shift->enter as in Mathematica), you should generate the initial conditions for the example, perform the time integration and plot some of the results.

  2. A black hole - the initial data is a black hole of mass $M=1$ in isotropic Schwarzschild coordinates. Since this is a stationary solution of the Einstein equations, any evolution you see must be gauge evolution only. By running the code you should observe the transition from isotropic coordinates to the so-called "puncture gauge" that gives a stable numerical evolution around singularities. The gauge terminates the numerical grid outside the singularity (but within the horizon).

Test folder

Several tests are included here that were used to debug the code.

One checks that all the geometric quantities are being correctly calculated, using example functions for which the solutions are known. A second checks that the time evolution for a black hole in ingoing Eddington Finkelstein coordinates is zero at the first timestep (thanks to Uli Sperhake for suggesting this test as better than Schwarzschild - many components of the latter are trivially zero).

Source folder

The code that supports the examples and the tests lives in the source folder. It is separated into folders and aims to be self explanatory with plenty of comments and a (hopefully) clear naming system.

The key files of interest are:

  1. The state vector file builds the list of the evolved variables from the (rescaled) BSSN state variables in spherical symmetry and a given matter class that is passed as an input, e.g. scalar matter. It is also necessary to specify the parity under r -> -r and asymptotic fall off of each variable.

  2. The bh initial conditions and oscillaton initial conditions files provide the initial conditions for the state variables for the two Examples above. Note that the oscillaton initial conditions have been numerically solved for using a shooting algorithm, and the profiles for the metric and field are stored in a subfolder from which they are interpolated onto the numerical grid used.

  3. The Grid class controls the grid setup - e.g. the radial coordinate spacing and extent, with the appropriate finite difference derivative matrices being defined in the derivatives file. These are all pre-calculated and given to the evolution code so they don't need to be recalculated at each step (they only depend on the grid setup, not the variable values). Note the use of classes means we can package up all the required attributes and methods into one object (this is an example of object oriented programming, which is common in python and C++).

  4. The rhsevolution is the main file for calculating the time evolution of the quantities (the so called "rhs" or "right hand side", referring to the evolution equations when cast in the form $\partial_t \phi = ...$). This relies on the matter class provided to calculate the matter evolution and sources, and the bssn rhs file to calculate the evolution of the BSSN variables. The tensor algebra file provides many geometric functions such as the calculation of the 3D Ricci tensor.

  5. It is in principle possible to change the background reference metric, currently only flat space in spherical polar coordinates is provided here. This feature isn't very well tested so develop your own background at your own risk!

  6. Finally, ham diagnostic provides a (post processing) diagnostic for the Hamiltonian constraint, which is demonstrated in both examples.

That's it! All these files are relatively short and should be fairly self explanatory - I recommend that you scan through them and try to parse what is happening at each point. The tips in Useful code background may help with some of the more obscure parts of the code.