Useful Resources - GRTLCollaboration/engrenage GitHub Wiki

Some useful resources for those starting out with Engrenage are:

General Relativity (GR) background

If you are completely new to GR I personally like the books by Schutz and Carroll, but there are many other options available and a quick google search will identify them for you.

For more advanced reading it is usually hard to find a topic not covered by MTW.

Numerical Relativity (NR) background

There are many useful introductions to NR, but I would recommend in particular the introductory book by Baumgarte and Shapiro as a companion to this course.

There are also the following open source resources:

In the longer term, the NR textbooks of Alcubierre, Baumgarte & Shapiro, and Shibata are useful for filling in the (important but more advanced) details.

Command line

You should only need the command line to install python and open the jupyter notebook, but if you are now asking yourself "what is a command line?" or "where do I find this thing called a terminal?", see the instructions here and a list of the main commands here. Google is going to be your friend here.

Usually you can just search for "terminal" in the applications menu and click on it.

If you have a Windows machine I strongly suggest that you first install Linux on Windows with WSL, so that you can use the linux terminal as nature intended.

The following are the key commands: mkdir (make a new directory) ls (or dir) (list the directories) cd (change directory, note cd .. takes you up a level) rm (or rd) (remove file - be careful with this one! Add -r to remove a folder and all its contents), mv (to move a file). If all else fails the nuclear option is to hold Control and press c to kill the process running in a terminal.

Python, Anaconda and virtual environments

There are many introductory online courses for python, for example here. You should always use python 3 and not python 2 which is now defunct (mostly).

Jupyter notebook documentation is here .

In order to get the coding environment that we want, with packages like git, numpy and scipy, we need to use a virtual environment. This allows us to make a container for all the things we need that we can then activate, without installing them more widely in your home directory, or the network.

Here we will describe how to use Anaconda to conda install packages. A common alternative is to use the python environment commands and pip install to install the packages as detailed here. There are many, many ways to install packages (see below), so knowing the conda method will be a useful introduction but just be aware that it is not a universal standard.

Anaconda provides an installation including Python 3 and Jupyter Notebooks (and many other things) that runs on Windows, Linux, and MacOS, so you can install Anaconda on most systems. Please make sure you use the latest Python 3 version available.

To set up a virtual environment we will need to use the command line, which is accessed via the terminal (see instructions above).

Create an environment called myenv

In the terminal, type the following to set up the environment with all the dependencies we need:

conda create -n myenv jupyterlab notebook matplotlib numpy scipy tqdm sympy

There may be a lot of output and it may take a while to complete, and complain about conflicts that it needs to check - just leave it and be patient. If it asks if you want to install some supporting packages, it is usually ok to type y for yes.

You can check it worked by doing

conda info --envs

and seeing that myenv is now listed.

Activate your environment

Activating environments is essential to making the software in the environments work. Activation entails two primary functions: adding entries to your PATH (where the computer looks for libraries and code) for the environment and running any activation scripts that the environment may contain.

To activate your environment simply type:

conda activate myenv

The terminal prompt will now look something like (myenv) G:/>. You will need to activate the environment every time you log in and start work.

To deactivate just type

conda deactivate

You should now be able to use all of the packages that were installed, so try opening the Jupyter notebook interface by typing jupyter notebook.

Remove the environment and start again

If all goes horribly wrong and you want to start again, you can simply remove the environment completely by typing:

conda remove --name myenv --all

and check it worked by doing

conda info --envs

which should not return the myenv any more.

Git guide

A complete but far too comprehensive guide to git is here (labelled a "git quick guide", without a hint of irony).

Unofficial Git guide

Here is a simpler but more inaccurate git guide to get you going. Apologies to git purists.

The basic purpose of git is to allow you to save all your changes to a code so you can go back and see where you screwed up when things don't work.

In the spirit of xkcd , after getting setup and forking the repository I want to work on the commands I have memorised are:

Clone repository:

git clone <https path copied from the git webpage using the green code button>

Make a new branch to develop a feature or fix some bug without messing up the main branch:

git branch <newbranchname>

But you are not yet in the new branch, so now check it out:

git checkout <newbranchname>

Having made changes, add them all (or just specific files) so they are ready to be committed:

git add --all

git add <specificfilenameorfolder>

Now you actually need to commit them too, adding isn't enough, and it is good to label them with a useful message for future you (e.g. "Code currently broken, was trying to fix integration but it did not work"):

git commit -m "<Some useful commit message>"

Push to the origin so you can see it using the internet browser and it is saved forever:

git push origin <newbranchname>

I usually use the web interface to do merging between branches or other more complicated things, because it shows you the changes in a nice readable interface.

Some more detailed instructions I wrote for a Masters course on numerical methods can be found here.

PRO TIP: Do not wait until code is working to push it to the origin, otherwise you will probably push once a month and end up losing stuff that could have been useful. I push at the end of every session in which I code and I then go and check the comparison of the commit to the old code in the web browser so that I see if I accidentally deleted anything (see for example this commit). Somehow seeing it in the web browser makes it obvious. This takes about 5 minutes each time but probably saves me an hour of debugging or more at a later date. Always be kind to future you.