ringdown

Bayesian analysis of black hole ringdowns. The original paper that inspired this code package is Isi, et al. (2019); a full description of the code and method can be found in Isi & Farr (2021).

Requires Python 3.12–3.14. Python 3.13 is recommended (qnm emits SyntaxWarnings on 3.14). Intel Macs are not supported (JAX no longer ships x86_64 macOS wheels).

This package is pip installable:

pip install ringdown

For the latest and greatest version, you can install directly from the git repo:

pip install git+https://github.com/maxisi/ringdown.git

The default install provides a CPU build of JAX. To run on NVIDIA GPUs, upgrade JAX after installing ringdown:

pip install --upgrade "jax[cuda12]==0.11.1"

See the JAX documentation for CUDA version details and other accelerators.

The recommended way to set up a complete environment (including Jupyter and development tools) is with uv from a clone of this repository:

uv sync

You can also easily install all optional dependencies:

uv sync --all-extras

Alternatively, you can use conda with environment.yml:

conda env create -f environment.yml
conda activate ringdown

The environment.yml file enables running ringdown in JupyterHub services like MyBinder by pointing MyBinder at this repository or clicking the button at the top of this README.

See the example gallery in the docs for several examples. You can download the Jupyter notebooks featured in the docs from the docs/examples.

In order to run Jax on a CPU with four cores and use double precision, you can do the following at the top of your script:

# disable numpy multithreading to avoid conflicts
# with jax multiprocessing in numpyro
import os
os.environ["OMP_NUM_THREADS"] = "1"

# set jax up to use double precision
from jax import config
config.update("jax_enable_x64", True)

# import numpyro and set it up to use 4 CPU devices
import numpyro
numpyro.set_host_device_count(4)
numpyro.set_platform('cpu')

To run on a GPU with single precision you can instead do:

# set jax to use single precision (this is the default so no need to run the lines below)
# from jax import config
# config.update("jax_enable_x64", False)

# import numpyro and set it up to use the GPU
import numpyro
numpyro.set_platform('gpu')

You will see significant performance enhancements when running on a GPU with 32-bit precision. If you have multiple GPUs, numpyro can use them in parallel to run different chains, just as with CPUs. Sampling one chain for a GW150914-like system takes O(s) on an Nvidia A100 GPU.

⚠️ Caveat emptor: depending on the autocovariance function (ACF), using float32 can cause numerical problems when computing the likelihood; ringdown will automatically rescale the strain in an attempt to prevent this, but you should use this feature at your own risk.

We ask that scientific users of this code cite the corresponding Zenodo entry (see blue DOI badge above), as well as Isi & Farr (2021):

@article{Isi:2021iql,
    author = "Isi, Maximiliano and Farr, Will M.",
    title = "{Analyzing black-hole ringdowns}",
    eprint = "2107.05609",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    reportNumber = "LIGO-P2100227",
    month = "7",
    year = "2021"
}