KerrP2P (Kerr Point-to-Point)

KerrP2P is a software designed for forward ray tracing in Kerr spacetime. It is specifically tailored to efficiently calculate multiple null geodesics between designated "source" and "observer" points, locate apparent positions of the corresponding images, and quantify their shapes. Detailed information can be found in the paper Forward Ray Tracing and Hot Spots in Kerr Spacetime by Lihang Zhou, Zhen Zhong, Yifan Chen, and Vitor Cardoso.

Using Jacobi elliptic functions to express the solutions to the geodesic equations based on Gralla and Lupsasca 2019, this software consists of two tools:

1. A Python/C++ package that computes null geodesics and thoroughly explores the parameter space to identify multiple images. Tutorials for it are presented in the folder examples:

   • tutorial_float64_sweep.ipynb: geodesic calculation and parameter space sweep in double precision
   • tutorial_float128or256.ipynb: geodesic calculation in quad/oct precision
   • cpp_tutorial_basic.cpp: geodesic calculation
   • cpp_tutorial_sweep.cpp: parameter space sweep

2. A Mathematica code: examples/tutorial_geodesic_and_image.nb. It also includes functions for geodesic calculation and can be utilized to visualize geodesics, image positions, and image shapes.

Latest Update

Primary-Image Solver along a Trajectory (Sep 5, 2026)

We added a polished Python .ipynb notebook for computing the primary image of a point source moving along a continuous trajectory. The current notebook uses a circular orbit as the working example, while the same continuation-and-fallback strategy can be easily adapted to other source trajectories.

The notebook initializes the primary image with an all-branch (r_c, log10|d|) sweep over the eight (nu_r, nu_theta, sign(d)) branch choices, selecting the smallest-n_half image among the candidates found. It then moves the source point along the orbit and solves for the corresponding (lambda, q) image parameters at each orbital phase, using the previous phase's solution as the initial guess. If no acceptable root is found, or if the change in n_half is too large (indicating an unwanted jumping to higher-level images), the solver tries locally perturbed (lambda, q) seeds, flipped (nu_r, nu_theta) signs and, if necessary, falls back to an all-branch sweep. The selected sweep solution is then used to resume the continuation in the (lambda, q) plane.

Notebook in examples/primary_image_solver, with an .md document containing detailed technical notes for users and AI agents.

Features

• Forward ray tracing in Kerr spacetime: this involves calculating multiple null geodesics that connects a given source to an observer
• Support for arbitrary precision arithmetic
• Python bindings for easy-to-use interface
• Support for multiple platforms: Linux, macOS, and Windows

Installation

Prerequisites

Before installing KerrP2P, ensure that you have the following dependencies installed on your system:

• Boost (with filesystem components)
• Catch2 (optional, for testing)
• fmt
• GMP (optional)
• MPFR (optional)
• MPC (optional)
• Eigen
• Intel oneAPI TBB
• Python (optional)
• pybind11 (optional)

Linux

On Linux, you can use Spack to install the dependencies:

spack:
  specs:
    - boost+filesystem
    - catch2
    - fmt
    - gmp
    - mpfr
    - mpc
    - eigen
    - intel-oneapi-tbb
    - python
    - py-pybind11
  view: true
  concretizer:
    unify: true

macOS

On macOS, you can use Homebrew to install the dependencies:

brew install boost catch2 fmt gmp mpfr mpc eigen tbb python pybind11

Windows

On Windows, you can use vcpkg to install the dependencies:

vcpkg.exe install boost catch2 fmt eigen3 tbb python3 pybind11

Usage

To use KerrP2P, follow these steps:

1. Clone the repository:

git clone https://github.com/AuroraDysis/KerrP2P.git

2. Build the project using CMake:

cd KerrP2P
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

3. Remember to copy the generated .so file to your working directory to enable the package's usage in Python/C++, while the Mathematica code can be used without this.

Contributing

Contributions to KerrP2P are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the GitHub repository.

License

KerrP2P is released under the MIT License. See the LICENSE file for more details.

Citation

If you use KerrP2P in your research, please cite the following paper:

@article{Zhou:2024dbc,
    author = "Zhou, Lihang and Zhong, Zhen and Chen, Yifan and Cardoso, Vitor",
    title = "{Forward ray tracing and hot spots in Kerr spacetime}",
    eprint = "2408.16049",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    doi = "10.1103/PhysRevD.111.064075",
    journal = "Phys. Rev. D",
    volume = "111",
    number = "6",
    pages = "064075",
    year = "2025"
}