The KerrGeodesics package for Mathematica provides functions for computing bound timelike geodesics and their properties in Kerr spacetime.

Example usage

As a quick example, the figure at the top of this page is made using the simple commands:

orbit = KerrGeoOrbit[0.998, 3, 0.6, Cos[π/4]];
{t, r, θ, φ} = orbit["Trajectory"];

Followed by the plot command:

 ParametricPlot3D[{r[λ] Sin[θ[λ]] Cos[φ[λ]], r[λ] Sin[θ[λ]] Sin[φ[λ]], r[λ] Cos[θ[λ]]}, {λ, 0, 20}, 
  ImageSize -> 700, Boxed -> False, Axes -> False, PlotStyle -> Red, PlotRange -> All],
 Graphics3D[{Black, Sphere[{0, 0, 0}, 1 + Sqrt[1 - 0.998^2]]}]

Orbital parametrization

The orbits are parameterized by the following

$a$ - the black hole spin
$p$ - the semi-latus rectum
$e$ - the eccentricity
$x_\text{inc} = \cos\theta_\text{inc}$ - the orbital inclination.

The parametrization $\{a,p,e,\theta_\text{inc}\}$ is described in, e.g., Sec. II of arXiv:gr-qc/0509101

Getting the package

The latest development version will always be available from the project git repository:

git clone


The KerrGeodesics package requires a recent version of Mathematica. It is typically tested with only the latest available version.


Clone the repository and place it somewhere on Mathematica’s $Path. Typical locations are inside ${HOME}/.Mathematica/Applications/ for Linux or inside ${HOME}/Library/Mathematica/Applications/ for Mac OSX.


The package may be loaded into Mathematica using the command:

<< KerrGeodesics`

Documentation and examples

Examples are included in the documentation. See the KerrGeodesics page in Documentation Center. The package includes functions to calculate, e.g.,


22 November 2018: Merged the development branch into the master branch. Thanks to Zach, Tommy and Chuck for contributing code. This update is a major change with a lot of improvements. A key difference is the defintion of the inclination angle which is now x_inc = Cos[\theta_inc]. Bumped version number up to 0.5.
7 August 2018: Added generic orbit calculation (thanks for M. van de Meent for contributing code). Currently the code is separated in KerrGeoOrbit2[..] but will soon replace the earlier code.
7 September 2017: Initial version publicly released.
10 June 2017: Initial version created.

Known problems

Known bugs are recorded in the project bug tracker.


This code is distributed under the University of Illinois/NCSA Open Source License. Details can be found in the LICENSE file.


Niels Warburton, Maarten van de Meent, Zach Nasipak, Thomas Osburn, Charles Evans