Modifying the examples

The code has been designed so that the following aspects of the existing examples can be very straightforwardly modified within the Example folder:

• Change of parameters for the domain size, resolution, grid hierarchy etc
• Change in the matter profile for the scalar field and its conjugate momentum
• Change in the boundary conditions (periodic or asymptotically flat)
• Change in the scalar field potential, including its shape and mass/self interaction parameters
• Change in the black hole parameters (including up to two BHs)
• Switching the solver method between the existing CTTK and CTTKHybrid

For more advanced modifications, like adding a matter type or a new method, you will need to review the section Structure of GRTresna.

Here we will describe how we modify ScalarFieldBH, as an example.

Creating a new example

Go to the Examples folder and copy the whole folder of the example that most closely matches the one you want to create and rename it. In this case, to copy ScalarFieldBH, you can simply use the following command,

cp -r ScalarFieldBH myCoolerScalarFieldBH

Before diving into your creativity, you might want to change the main file name Main_ScalarFieldBH.cpp to Main_myCoolerScalarFieldBH.cpp and ebase = Main_myCoolerScalarFieldBH in GNUmakefile.

Now, you are ready to make the example your own.

Parameters

In the params.txt, you can change most of setup of the solver, filesystem, grid and boundary conditions for the example, and also specify the black hole parameters. Please have a look at Guide to parameters for a more detailed description of these parameters.

For example, you can add a second black hole simply by modifiying the parameters for the second black hole (i.e. setting the mass to 1.0 and the spin to 0.5), and giving it a location separate from the first one.

Matter profile and scalar potential

The default scalar field profiles are set as Gaussian functions, both for the field profile and the momentum, with a quadratic potential. These can be changed within the MyMatterFunctions.cpp to whatever profiles and scalar potential you are interested in.

This file also gives you the ability to add new parameters that you can read in from the params.txt file to support your new profiles or potential, e.g. adding a self interaction strength as well as a scalar mass.

Switching the solver method between the existing CTTK and CTTKHybrid methods

The current version of the solver supports the use of two different methods for solving the constraint equations: CTTK and Hybrid CTTK. See this article for full details of each approach.

The basic difference between the two methods is that in the Hybrid approach the conformal factor $\psi$ varies in response to the $A_{ij}$ sources in the Hamiltonian constraint, whereas in the CTTK method it is simply set to a constant (i.e. 1), and the variation in K absorbs the $A_{ij}$ sources. CTTK Hybrid is usually the default for black hole spacetimes, whereas the CTTK method is mainly used in periodic/cosmological spacetimes, or when it is important to maintain a fixed ratio between the gradient and kinetic/potential densities of the scalar field. In principle, both can be used in either case, but often one provides better convergence in certain cases.

The desired method is chosen in the GNUMakefile, by leaving the line with the desired method uncommented and commenting out the other options. For example, for using the Hybrid CTTK method, this line should be used:

cxxcppflags = -DUSE_CTTKHybrid

Then, the command make realclean should be used on the terminal after which the whole solver should be recompiled so that the desired method is implemented in the compilation.

Next steps

The executable can then be compiled and run as described in Running the examples

It is essential to do a convergence test to see if the resulting initial condition data is correct. Getting a "small" constraint violation tells you nothing

• it should converge at the appropriate rate (second order, subject to caveats) when the resolution is increased, otherwise it is likely that you have a bug.
• it should be "small" when compared to the dominant source in the constraint equations. For example, Ham/(16pi*rho) ~ 0.01 would correspond to a 1% error.

Further instructions are given in Convergence testing.