gwBOB

The Backwards-One-Body Gravitational Waveform Package

Getting Started

Please see more detailed documentation here!

What is the Backwards One Body Model?

The Backwards One Body (BOB) model is an analytical and physically motivated approach to modeling gravitational waveforms from black hole binary mergers, as described in arXiv:1810.00040. The BOB model is based on the physical insight that, during the late stages of binary evolution, the spacetime dynamics of the binary system closely resemble a linear perturbation of the final, stationary black hole remnant.

Features

• Analytical accuracy: Closed form expressions for the amplitude and frequency evolution.
• Minimally Calibrated: Requires minimal calibration to numerical relativity (NR)
• Test all BOB flavors Easily generate and switch between different "flavors" of BOB depending on your research problem.
• Easy initialization Easy initialization using SXS, CCE, or raw NR data.
• Beyond Kerr waveforms Compare NR data to BOB waveforms generated with custom QNMs.
• Easy comparisons: Easy comparisons to waveforms from the public SXS and CCE catalog, as well as raw NR data.
• Well Documented and Actively Developed

Generate plots like these with just a few lines of code!

Requirements

• (Windows users should use WSL)
• kuibit
• sxs
• qnmfits
• scri
• jax (install the GPU compatible version if possible)
• sympy
• numpy
• scipy
• matplotlib

Install via pip

pip install gwBOB

Running the Tests

If you've cloned the repo and want to run the test suite:

cd BackwardsOneBody/
pip install -e ".[tests]"

# Unit tests are fast and need no external data:
pytest tests/unit/

# Integration tests need ~90 MB of waveform data from the SXS catalog and
# the Zenodo CCE record. Fetch it once:
python tests/fetch_data.py
pytest tests/

Citing this Code

If you use this code please cite

@article{mcwilliams2019analytical,
  title={Analytical black-hole binary merger waveforms},
  author={McWilliams, Sean T},
  journal={Physical review letters},
  volume={122},
  number={19},
  pages={191102},
  year={2019},
  publisher={APS}
}

@misc{kankani2025bobwaveformbuilderoptimizing,
      title={BOB the (Waveform) Builder: Optimizing Analytical Black-Hole Binary Merger Waveforms}, 
      author={Anuj Kankani and Sean T. McWilliams},
      year={2025},
      eprint={2510.25012},
      archivePrefix={arXiv},
      primaryClass={gr-qc},
      url={https://arxiv.org/abs/2510.25012}, 
}

JOSS paper to be added. If you have any issues with this code, want any new features, or use this code for your own research, please let me know!

AI Usage

While the original code was written largely manually, this code is now mostly developed through the use of Claude Code. AI usage follows the JOSS policy on AI usage. All design decisions are made by humans. All LLM generated code is verified manually by humans. Throughout the code you will likely see comments starting with "Claude Code:" that refer to specific MD files. These files are not part of the git but Anuj will share them on request.

Contributing

Contributions are always welcome! If you find an issue, or have any questions on how to use the code, please raise an issue on this repo. If you want to contribute directly to the code, please fork the code and create a pull request!