Matter types

The public version of the solver currently only implements a real-valued scalar field. However, it is templated over the type of matter, and so it should be straightforward to switch to another type. The steps below can be followed to achieve this.

We start with the source code that needs to be added outside of the Examples folder. Note that as a basic principle, one should mainly add new classes and avoid modifying the existing source code except where absolutely necessary.

Matter class

The scalar field description is located at ScalarField.hpp, ScalarField.cpp, and ScalarFieldUserVariables.hpp in Source/Matter. We start by copy-and-pasting these three files. Rename them to describe the new matter type, and don't forget to change the header guards.

Let's first take a look at the contents of ScalarFieldUserVariables.hpp. Edit the matter variables in the enum curly brackets. You can add as many as needed to describe the matter. Make sure to leave the = NUM_METHOD_VARS intact in the first line. This defines the grid variable names. Make sure that those used in the stress-energy tensor calculations are included here. Then, under the namespace MultigridUserVariables, add the strings that define how these variables are called in the hdf5 output files. Under vars_parity, define the parity of these new variables according to whether they are scalars or tensor components. This is necessary especially if you take advantage of the symmetry of your problem to simulate only parts of the domain.

Next, let's modify the definitions in ScalarField.hpp. Replace the class name and other mention of "ScalarField" with the name of the new matter type. The functions my_potential_function, my_phi_function, and my_Pi_function are functions used to set initial conditions that can be later specified in the Example folder. You can rename, add, or remove these functions for the initial condition specification of the new matter type. This added flexibility to the new matter type helps it to support different initial condition functions.

Finally, we modify ScalarField.cpp. there are two functions inside ScalarField.cpp, initialise_matter_vars, and compute_emtensor. Change initialise_matter_vars to utilize the initial condition functions declared in the header file ScalarField.hpp. The compute_emtensor function is the place to calculate the 3+1 decomposed stress-energy tensor rho and Si based on variables of your new matter type. Note that if you need the metric variables to calculate these stree-energy tensor components, the psi_0 calculation in ScalarField.cpp can be used to get the conformal factor of the metric. If derivatives are needed, you can use get_d1 in DerivativeOperators to take derivatives of grid variables. See the original ScalarField.cpp for examples. Here you will be using the matter-specific variables defined in ScalarFieldUserVariables.hpp in the first step.

GRChombo outputs

Variables for the final output data for GRChombo need to be defined. You can do this in Source/Variables/GRChomboVariables.hpp. If you want the final output hdf5 file to be used as a GRChombo checkpoint file without further processing, you need to define the variable names the same way you define them in your time evolution code. These variables will probably describe the same matter variables as those defined in Source/Matter/ScalarFieldVariables.hpp (replace "ScalarField" with the name of the new matter type here). You can give them the same names since they live in different namespaces.

To populate these output variables, go to Source/Tools/WriteOutput.H, and modify the set_output_data function to transfer the values to the GRChombo variables.

Example Construction

We are ready to copy-and-paste one of the folders under Examples.

The class instantiations in the main file located inside the examples are templated over the matter class. Replace all mentions of "ScalarField" with the name of your new matter in this file. The MatterParams.hpp is the place to define some constants that can be read off from the parameter files. Inside MultigridVariables.hpp, you only need to replace the name of the "ScalarFieldVariables.hpp" with the corresponding file name of the new matter type. In MyMatterFunctions.hpp you define the actual functions used to construct the initial matter variables. See all mentioned files in ScalarFieldCosmo as an example.

If everything is written correctly, your new matter type is fully implemented and ready to run.

Additional modifications

You might need to solve additional constraint equations related to your new matter variables. Depending on your need, you might wish to solve it algebraically or numerically. Both can be achieved by modifying the CTTK method in Source/Methods/CTTK.impl.hpp. New diagnostic variables can be defined in Source/Variables/DiagnosticVariables.hpp. Implementation of these variables can be done in Source/Core/Diagnostics.hpp and Source/Core/Diagnostics.impl.hpp.