Additions to Source code

This page describes the addition of Source files relating to the ScalarField example. You should have read Structure of the code and A new Example folder before what follows.

If you are writing something that you or others are likely to reuse, it may be appropriate to write a new library file and put it into one of the Source folders.

You should never modify existing Source files unless you have a very good reason to - they are likely to be used by other examples and you may break the code. However, you should also not just copy and paste classes wholesale to make a small modification - consider whether you can inherit from them instead.

This step of thinking about what to add and what to reuse is very important. The idea is that any update to one class should flow through naturally to the classes that use it. If you copy a class so you can make a small modification to it, then you won't benefit from any updates made to the original at a later date, whereas if you inherit from it you will. Basically, the same code should never exist in two places - copy and paste is your enemy!

Here we give some details on the Source files that were added for use in the ScalarField Example, and how they were designed to inherit from the existing KerrBH and other Source files.

The ScalarField Example Source files

In this case, we wanted to update the bare CCZ4 equations for the vacuum case (with cosmological constant) to include a matter field. Many different types of matter are possible, but they result in the same update to the gravity field variables given the relevant Energy-Momentum (EM) tensor. In order to make the code reusable it was therefore sensible to split the update into two levels:

• A class which, given a specific matter type matter_t (over which the class is templated), would calculate the relevant update (rhs) from the field equations. We called this MatterCCZ4RHS. Clearly this needed to reuse a lot of the CCZ4RHS code, so it inherits from it.

• A class for the matter type matter_t which would generate the EM tensor for the relevant matter type (in this case a scalar field), and also perform the correct evolution for the matter fields (in this case the evolution equations for phi and Pi which result from the Klein Gordon equation on a curved background).

Thus if another user wishes to evolve a scalar field, but just with different initial conditions, both classes can be reused without modification. If they wish to use another matter type such as a fluid, then the first could be used, but another matter_t class, based on ScalarField, would need to be written. Such a matter class would be an example of something appropriate to include in the libraries rather than the example files, as it could potentially be reused by others.

In addition, since one motivation for the work was to consider different self interaction potentials V(\phi) for the scalar field, the ScalarField class was itself templated over a Potential class.

You should look over the files and try to understand how they work. Some key points are noted below to guide you on the thought process, but the files themselves are heavily commented.

MatterCCZ4RHS

This class inherits from the CCZ4RHS class, which enables it to access the RHS update already implemented in the vacuum case. The benefit of inheriting, rather than rewriting the CCZ4RHS class, is clearly readability and modularity - should we wish to make a small amendment to the CCZ4RHS class (we spot a bug in one of the equations, for example), we only need to change the code in one place.

In order to make this code reusable for different matter types it was templated over a matter class, matter_t. This matter class must be able to compute the 3+1 components of the energy momentum (EM) tensor, and update the evolution of the matter fields, but these functions are specific to the matter class and thus not specified explicitly in MatterCCZ4RHS.

The practical effect of this templating is that the class will not exist unless a matter type is specified in the angular brackets, for example, MatterCCZ4RHS would be specified so the compiler knows to build the class with matter_t = ScalarField.

However, as we will see, ScalarField is itself templated over a Potential class (which is included in the Example folder as it is problem specific), thus you will actually see

MatterCCZ4RHS<ScalarField<> > //Default potential which sets V(\phi) = 0

or

MatterCCZ4RHS<ScalarField<Potential> > // User specified Potential class

or

MatterCCZ4RHS // Uses the alias defined in ScalarFieldLevel.hpp

The compute function (which is what is called on each cell in the box by BoxLoops) computes the rhs from CCZ4 for the CCZ4 variables, and then adds the changes to these resulting from the presence of the matter components, for any given energy momentum tensor. It then requests that the matter_t class adds in the rhs for the matter components (whatever they are).

ScalarField

This is an example of a matter_t, which computes the energy momentum tensor for use in other classes. It also calculates the updates for the matter field variables phi and Pi, using the Klein Gordon equation in curved space, and specifies the struct for the matter variables.

Again it is advisable to read through this class and try and understand the effect of each line. Most of the physics should be readily recognisable from the Baumgarte & Shapiro Chapter 5 section on Scalar Fields.

It is templated over a potential which is defaulted to the DefaultPotential class. In this the self interaction potential of the field V(phi) is set to zero.

MatterConstraints

This class inherits from the CCZ4 constraints file, and simply adds in the contributions from the EM Tensor (for a given matter_t object) to the Hamiltonian and Momentum constraints.

It is thus also templated over a matter type matter_t, which in this case is ScalarField.

Note that it allows the user to set the value of Newton's constant, which can be useful if one wishes to remove the backreaction of the field onto the metric, whilst still evolving the scalar field on a curved background, or evolve the scalar field with order 1 values, but adjust the physical density via the value of G.