Skip to content
General Relativistic Pulsar Timing
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.

Iliad - General Relativistic Pulsar Timing in Kerr Spacetime

This code calculates the time-frequency signal from a pulsar orbiting a massive black hole (BH), account for all relativistic and astrophysical effects.

This repo has two main ingredients. The first part determines the orbital trajectory of a spinning body. It is based on the Spin Curvature Dynamics code. The second part calculates the trajectory of light from the pulsar, based on the ForwardRayTracing code. This repo then combines these two tools so that the user can specify some BH-PSR system and consistently generate the frequency-dependent photon ToAs. Some work using these methods has been published in Kimpson 2019a,b.

The public release of this code via this repo is still in development. Whilst the bare-bones base code is available for constructing the signal, modules relating to the signal analysis and computational optimization are still due to be released, subject to internal checks and development.

Getting Started

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


The main part of the code (w.r.t orbital dynamcis, ray tracing) 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

First 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 IliadDir="/Users/tomkimpson/Data/Iliad/"' >> ~/.bash_profile
source ~/.bash_profile

Just change the path Users/tomkimpson/Data/Iliad/ 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. This is effectively the config file for specifying the system parameters

  • main.f. This is the root program which runs all the necessary subroutines. It first determines the PSR spin orbital dynamics (OrbitalDynamics.f) and then uses the output as initial conditions for the ray tracing (RayTracing.f)

  • OrbitalDynamics.f. Computes the PSR spin dynamics, assuming a Kerr background spacetime. Standard position initial conditions are (t0, r0, theta0, phi0) = 0,sma,PI/2,PI ), though naturally these can be changed. The intial oreintation of the spin axis is set in parameters.f. The integration can be set to have constant stepsize, or adaptive in parameters.f. The output is a single file of size NSTEPS x 13 i.e. number of integration steps and 3 x 4 vectors (positions, spin ,momentum) plus the proper time (related to the stepsize). If plot_MPD is set to 1 in parameters.f, then the output file will also be written as a readable text file (useful for e.g. plotting).

  • RayTracing.f. Photon trajectory emiited from the PSR described by OrbitalDynamics.


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

You can’t perform that action at this time.