Key parts of the code

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 Kerr Schild 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).

There is also a file that shows how the finite derivative stencils are calculated and tested for the logarithmic grid, using sympy functions.

Source folder

The code that supports the examples and the tests lives in the source folder.

It aims to be self explanatory with plenty of comments and a (hopefully) clear naming system. The key files of interest are:

1. The uservariables file lists all the evolved variables, which are the (rescaled) BSSN variables in spherical symmetry, and specifies their parity under r -> -r and their asymptotic fall off.

2. The bhinitialconditions and oscillatoninitial conditions files provide the initial conditions for these variables for the two Examples above, and mytests gives the same for the Tests. The oscillaton initial conditions have been numerically solved for using a shooting algorithm, and the profiles for the metric and field are stored in the initial_data folder from which they are interpolated onto the numerical grid used.

3. The Grid class controls the grid setup, with derivative calculations in Derivatives. These are all pre-calculated and given to the evolution code so they don't need to be recalculated at each step. 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. 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 mymatter to calculate the matter evolution and sources, and bssnrhs to calculate the evolution of the BSSN variables. The tensoralgebra file provides many geometric functions such as the calculation of the 3D Ricci tensor.

5. Finally, hamdiagnostic 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.