Home

Welcome to the Engrenage wiki!

Engrenage (the code formerly known as BabyGRChombo) is a spherically symmetric BSSN code designed for teaching Numerical Relativity (NR), which is the solution of the Einstein Equations of General Relativity (GR) using numerical methods. The code includes a scalar field (obeying the Klein Gordon equation for a minimally coupled spin 0 field) as the matter source of the metric curvature. It currently includes two physical examples - a black hole and a real scalar boson star (or oscillaton).

We have put together the following set of documentation which we hope will help you to get started using Engrenage. A contents bar should be shown on the right hand side of the wiki (or below if you are on a small screen) to help you navigate the documentation.

Here are some suggestions on where to start depending on what you want to know:

• I want to use Engrenage for my research project

Stop and think! Engrenage was not really designed for doing research projects although it can be if you have a specific problem in spherical symmetry. It is best for creating tests, or for masters level projects to learn NR. For larger problems you may want to go to Engrenage's parent GRChombo or another more developed NR code.

• I don't know anything about GR and want to learn NR

Engrenage is probably not the best place for you to start. Useful Resources provides some suggestions for texts you could start with, but you should as a minimum follow an undergraduate level course in GR before attempting to learn NR.

• I know GR and want to learn NR

This course is designed for you! However, you will probably need to do some background reading before you start working with the code. You should be able to start at Background on Numerical Relativity and work forward sequentially through the wiki.

Technical Note: This code uses the BSSN formulation of NR, which is not the only option, but is arguable one of the most common. Alternatives include General Harmonic Coordinates (GHC) and null coordinate methods. The code uses a dynamical gauge, which is not essential for spherically symmetric problems (one can use semi constrained methods to fix a gauge), but is more similar to the evolution methods used in larger 3+1D codes. Due to Birkhoff's theorem the code does not simulate situations with gravitational waves, which may make it seem rather pointless! However, I believe the code provides the best compromise, allowing you to learn the basics of NR for several non-trivial problems, whilst keeping the methods and coding aspects as simple as possible. A scalar field is included as the matter component, so one can calculate scalar waves, which provide a spin 0 equivalent of the spin 2 tensor waves.

Please note our License and Citation guidance.

• I know NR and want to learn/use BabyGRChombo

If you know NR you probably don't need to learn Engrenage :-) But maybe you want to use it to teach your own students about NR, which I strongly encourage!

There are some features of Engrenage that differ from standard 3+1D BSSN codes in order to get an acceptable runtime on a laptop - in particular the formulation uses the reference metric approach and spherical symmetry is assumed. There is also an option to use logarithmic radial coordinates. These features and their implementation are briefly described in Technical details specific to Engrenage.

Please note our License and Citation guidance.

• I have used Engrenage and I want to report a bug

Please file an issue in GitHub and provide sufficient detail for us to recreate the problem. You can also Contact us, but raising an issue is preferred if the problem is code related.

• I have used Engrenage and I want to contribute to the code

Great! Please see Contributing to Engrenage for more details.

DISCLAIMER: Whilst we have done our best to only include things which are well tested, we can't guarantee that everything works perfectly. Use of Engrenage is at your own risk!