Adding an example

Having run the limited set of example which we have made public, it is anticipated that new users will wish to make new examples in order to create their own simulations.

This may just mean updating initial conditions, or writing a new matter class or tool, but it is a very good way of learning your way around the code.

General points:

1. You will need to work in your own fork of the code, since we have locked the code to prevent accidental changes that could introduce bugs. Just like in Fight Club, what happens in your fork, stays in your fork. In cases where you add features to the code, we will most likely ask you to create a clean branch from master and add new code there. However, the reverse is not true - we do expect you to pull changes from the public master branch into your fork at regular intervals, so as to obtain the latest bug fixes and enhancements. Please check you have the latest updates before you report a bug. The latest key updates are listed in Updating your branches.

2. When updating to the latest GRChombo version, update consciously and with care. We try our best not to break existing code with updates, but depending on how much you amend your code it may result in conflicts that you need to resolve at this point. If you are using GRChombo for academic purposes, our advice is to update the code at the start of any new article/project, but once you have a working/tested code, do not update further during the project unless you are 100% confident you understand the changes. Most of the GRChombo developers work on this basis.

3. You should make a new Example folder in "Examples" for any case where the compiled code will differ from an existing Example. Normally you would start by duplicating the Example folder which is most similar to what you plan to do. In this way you can always compare back to a working example, and track which changes broke it.

4. In Examples where you just wish to change the parameters, and not the compiled code, the best setup is to create sub folders within the Example folder for each parameter set. Each folder will then contain a params file and a jobscript - note that you can run an executable in the folder above by prefixing it with "../" or alternatively provide the full path to its location.

5. Even though you work in your own fork, please follow our conventions for coding. Not only is this good practise, but it means that it will be much easier to merge your code into the main one should you wish to do so in the future.

6. The code is designed to be readable, so that you can create new features just by copying the existing physics classes and making a few changes to formulae. However, it will help you a lot if you know at least a bit about classes and templating in C++. References to good first sources are in Useful resources.

7. When creating new Source code, the rule is: don't duplicate code and don't amend existing classes. If you are using copy and paste for more than 4 lines of code, you should consider whether you can instead reuse the existing source code. However, this does not mean hacking the existing classes! Consider whether you can write a new class which inherits from an existing class and add the features you need to that.

8. Running the command

    make all
   

   in the GRChombo directory will make and run all the tests and compile the examples. This is a good check that any coding you have done has not broken other features of the code, and you should do it whenever you add a new feature.

9. If your code could be useful to others (likely), and once it has been extensively tested (as a rule of thumb, used in a publication accepted by a journal), you should make your code available to others by making Pull requests to the public code.

As a comprehensive introduction to adding components to the code, in this section of the wiki we will describe the overall structure, and then use the example of how the KerrBH example was copied and extended to create the ScalarField example. This is intended to give new users an idea of the key elements they need to consider updating. It is not an exhaustive description, but should enable the user to get a feel for how the different elements of the code interact.

Some additional examples that show how to amend the ScalarField code for initial conditions and different parameters are given in Hands on example with domain walls and Hands on example with Brill waves.