This repository provides simple Cadabra and Ada codes for 3+1 numerical evolutions of Kasner initial data.
There is no need for yet another elementary code that does nothing more than evolve Kasner initial data. That job can be adequately done using existing codes (such as the Einstein Toolkit or Cactus). But if you want to do something slightly less standard (off piste), e.g., evolve the initial data with respect to a modified evolution scheme, then you are faced with a serious question. Should you invest the time to understand the inner workings of the existing software so that you can be assured that your changes actually do what you want them to do? Or do you use that same time to write your own code from the ground up? The later case is certainly an example of reinventing the wheel but once you have your new wheel you are in complete control. The risk you take is that your code will contain bugs and that it will not have all the features of other codes.
The codes on which this project is based were written mainly because I did not have the time, the patience or the inclination to delve into the inner workings of Cactus. I did not need all of the features of Cactus. So I wrote a few codes that met my limited needs. I am sharing them here so that if anyone else feels inclined to write their own own (which I strongly encourage) you may find these codes to be a useful guide (or maybe not). The bulk of the Ada code is standard (simple uni-grid code, periodic boundaries and second order centred finite differences). The things that might be of interest are the multi-tasking (using native Ada constructs) and the modular structure of the code (using Ada packages for the various tasks, e.g., I/O, time stepping, constraints).
The code uses Cadabra to convert the tensor equations to bare C-code. Other tools are used to integrate these into larger programs written in Ada. The result is a bridge between the formal equations on one side (the ADM or BSSN equations) and the numerical or graphical results on the other side (the data generated by the codes).
Having an automated system that converts the tensor equations to code and then runs that code to produce numerical or graphical results does make experimentation very easy. Your time can be spent on the mathematics rather than on writing low level code. This also reduces the chances of (human) coding errors.
This philosophy (of having computers do all the work) is not new. See for example the NRPY+ software and the Einstein Toolkit.
Cadabra is a symbolic algebra system ideally suited to tensor computations in General Relativity. The core software is written in C++. Cadabra uses a subset of LaTeX for the tensor equations and Python to control the computations. Cadabra is mostly used to do abstract tensor computations (e.g., showing that the Levi-Civita connection is metric compatible) as well as component computations (e.g., computing the Riemann components for a Schwarzschild metric in isotropic coordinates).
Using familiar tools like LaTeX and Python means that the learning curve for Cadabra is very gentle (and that's a big plus).
A detailed tutorial on Cadabra can be found here.
Most codes in computational relativity are written either in C/C++ or Fortran or some combination thereof. So why does this project use Ada? The simple answer is that I like to do things outside the triangle. The better answer is that Ada is a superb language (IMHO) for any large scale computational project. Here are a few of its features.
- Strong typing. Ada forces you to declare the type of every object. You can create your own types or use predefined types. This information is used by the compiler to avoid the classic apples and oranges errors.
- Native multitasking. The Ada language contains explicit rules for multi-tasking and distributed computing.
- Exception handling. Easily catch and handle any exceptions (array bounds error, floating point errors, file and i/o errors).
- Platform agnostic. Ada codes can be ported from one platform to another without change. The usual #ifdef constructs in C/C++ have no counterparts in Ada. All platform dependencies are resolved in the compiler.
- Interface with C and Fortran. Ada has precisely defined rules for communicating with C and Fortran codes. This makes it easy to access external libraries.
To build everything from scratch just run
$ source SETUP.txt
$ makefrom the top directory. This will build, install and run the Ada, Cadabra and LaTeX codes. The end result will be a pdf file adm-bssn-plots.pdf showing the evolution of the Kasner initial data for both the ADM and BSSN equations.
The Cadabra source codes can be found here
adm/cadabra
adm/cadabra/templateswhile the Ada source codes can be found in
adm/code
adm/code/src
adm/code/templatesThe bssn directory contains the corresponding codes for the BSSN formalism.
Various scripts are provided to compile and run the codes.
All of the Ada codes are compiled using gprbuild. This is a standard tool for Ada programs. It makes intelligent decisions about which files are out of date and which files need to be recompiled. The nice thing about gprbuild is that it determines the dependencies by inspection of the Ada files (compare this with make where the dependencies must be explicitly encoded in the Makefile targets).
If you make changes to any of the Cadabra codes in the bssn directory (for example) you will need to recompile the Cadabra codes using
cd bssn/cadabra
build.sh
If you make changes only to the Ada codes in bssn/code/src then you need only run
cd bssn/code
build.sh
bssninitial.sh
bssnevolve.sh
Creating the initial data and running the evolution code for the BSSN equations can be done using
cd bssn/code
bssninitial.sh
bssnevolve.sh
Note that any changes to the ADM codes will have no effect on the BSSN codes and vice-versa. The single point of contact between the ADM and BSSN codes is the shared support library.
There are other files that might be of interest to those planning to tinker with the sources. The first is road-map.md describing which files are sources and which are products. The second is adm/cadabra-ada-map.txt describing the various symbol names of various objects (the metric tensor, the curvature tensor etc.) and how those names change from one source to another (e.g., a LaTeX name in Cadabra does not sit nicely in an Ada source). See bssn/cadabra-ada-map.txt for the corresponding map in the BSSN system.
Some people may want to see the final Ada code without the extra burden of installing Cadabra and friends. For that reason I've created a seprate repository that is just pure Ada code. You can look at the code as well as compile an excute it.
You will need an Ada compiler and the Cadabra/Python/SymPy software.
Ada is part of the GNU compiler collection and compilers are available for a wide variety of platforms (including macOS, Linux and Windows). The easiest way to install Ada and its friends is to first install alr (the command line tool for Alire, the Ada package manager). You can download a binary from ada-lang.io and then follow these installation instructions. This will install alr but not, at that point, the Ada toochain. That is done (behind the scences) when you first attempt to compile any of the Ada codes. There will be a short delay while Alire downloads the toolchain (just once). The Ada toolchain will be installed in the directory ~/.local/share/alire/.
Cadabra is easy to compile and install. Full details can be found on the Cadabra repository.
A popular distribution of Python3 can be found at the Anaconda website.
If you are not using the latest Anaconda distribution you may need to check that your version of SymPy is at least 1.7 (this is required only during the Ada code generation). You can install the latest version of SymPy in Anaconda using conda install sympy.
Surely not? But if so, then you can do a complete uninstall by simply deleting this directory.
All files in this collection are distributed under the MIT license. See the file LICENSE.txt for the full details.