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).

Installation

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

Additionally, you may follow the JAX documentation to install JAX with GPU support.

Complete Environments

A complete conda environment that includes all the prerequisites (and more!) to install ringdown can be found in environment.yml in the current directory:

conda env create -f environment.yml
conda activate ringdown
pip install ringdown

will leave the shell in an environment that includes jupyterlab ready to explore the ringdown package.

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.

Examples and tips

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

Performance notes

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 4 CPU devices
import numpyro
numpyro.set_platform('gpu')

You will see significant performance enhancements when running ona 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.

Citations

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"
}