Skip to content
Numerical ray tracing code for photon rays emitted by a moving source in a Kerr spacetime
Fortran Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Light Ray Tracing in Kerr Spacetime

This code calculates the trajectory of light (ray - geometrical optics) on a background Kerr spacetime.

Whilst typical ray tracing typically integrates the ray backwards in time, for this code we instead integrate forwards.

The code solves a set of ODEs numerically. We use a Hamiltonian formulation as described in Pu et al. 2016. Going beyond the usual vacuum approach, we also consider the influence of plasma on the ray spacetime trajectory. See Kimpson et al. 2019.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.


This code is written in FORTRAN with a gfortran compiler. Other compilers have not been tested. The gfortran installation binaries can be found here, although typically gfortran comes pre-installed on most Linux/Unix systems. If you have Homebew installed on OSX, you can simply run

brew install gcc

Starting steps

After cloning the repo, the first thing to do is to set the path to the output files that the code will produce. This can be done by setting the environment variable as

echo 'export RayTracingDir="/Users/tomkimpson/Data/RayTracing/"' >> ~/.bash_profile
source ~/.bash_profile

Just change the path Users/tomkimpson/Data/RayTracing/ to some appropriate local path.

You can check the environemnt variable has been added to bash_profile by either env or vim ~/.bashprofile

The code should then run as is, out of the box. Try

to compile and run the code. Once you have checked that everything is running OK, you can then start playing. The code structure (modukes, subroutines etc.) is outlined below.

If making edits to the code, try to keep to the FORTRAN Style Guide



parameters.f defines all the system parameters. That is, anything that needs changing (e.g. BH mass, BH spin) can be modified in this module

constants.f is for calculations with those parameters for use later in the code. It can effectively be ignored - no changes should be necessary to this file

main.f is where the code program is run from. After setting up the initial conditions (initial_conditions.f) it then goes on to integrate the equations and save the output (`integration.f')

tensors.f contains some useful subroutines for calculating e.g. metric, vector magnitudes etc.

A python wrapper has been provided to compile and run the code, We use a -O3 optimization. See the docs for discussion on the optimization flags

tools does what is says on the tin. Can be switched between 3d and 2d by changing the opening `d' parameter

Numerical Method

We integrate the equations using a Runge-Kutta-Fehlberg algorithm with adaptive stepsize. See Press et al.

Accuracy tests

When integrating numerically, an important consideration is the accuracy of the method. We can assess this by independently evaluating the Carter Constant, Q


This project is licensed under the MIT License - see the file for details

You can’t perform that action at this time.