Structure of the code (aka where is everything?)

Yes, we know, GRChombo is a big code. At first the many files will seem overwhelming, but with time you will start to learn where to find things and the structure will make (some) sense.

On this page we provide some hints on how to find your way around the code, but in the end you just have to dive in and learn as you go. Unless you are extremely proficient at coding and NR already, we strongly recommend working with a member of the collaboration who can guide you. See our website for details of members of the collaboration.

Hierarchy of GRChombo

The code is designed to have 3 main levels in its hierarchy, as follows:

1. Specific Example, e.g. BinaryBH - specific actions relevant to the Binary BH example - key classes: BHAMR, BinaryBHLevel, SimulationParameters

This inherits from: 2. GRChombo - specific physics actions common to most 
 GR problems - key classes: GRAMR, GRAMRLevel, SimulationParametersBase
 Inherits from:

This inherits from: 3. Chombo - overall program flow relevant to any initial value problem - key classes: AMR, AMRLevel, ChomboParameters


A useful pdf guide on this topic from the latest GRChombo training day can be found in Useful resources.

---

Thinking about what files are needed, and where to put them

We started by copying the entire contents of the Example/BinaryBH folder into a new folder called Examples/ScalarField. This folder is where the files specific to your physics problem live. By default, all your new files and tools should be created here first.

One can subsequently move new files to the Source libraries if it is felt they would be of use for other examples (we will see in the sections on matter classes and initial conditions what new library files were added for the Scalar Field (SF) example).

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!