https://github.com/maxisi/ringdown
Bayesian analysis of black hole ringdowns in gravitational-wave data.
https://github.com/maxisi/ringdown
Last synced: 5 months ago
JSON representation
Bayesian analysis of black hole ringdowns in gravitational-wave data.
- Host: GitHub
- URL: https://github.com/maxisi/ringdown
- Owner: maxisi
- License: mit
- Created: 2021-05-18T22:22:49.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-09-24T00:47:02.000Z (9 months ago)
- Last Synced: 2025-09-24T02:29:05.026Z (9 months ago)
- Language: Python
- Homepage: https://ringdown.readthedocs.io
- Size: 287 MB
- Stars: 36
- Watchers: 3
- Forks: 23
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ringdown
[](https://badge.fury.io/py/ringdown)
[](https://mybinder.org/v2/gh/maxisi/ringdown/HEAD)
[](https://zenodo.org/badge/latestdoi/368680640)
[](https://ringdown.readthedocs.io/en/latest/?badge=latest)
Bayesian analysis of black hole ringdowns. The original paper that inspired this code package is [Isi, et al. (2019)](https://arxiv.org/abs/1905.00869); a full description of the code and method can be found in [Isi & Farr (2021)](https://arxiv.org/abs/2107.05609).
## Installation
This package is pip installable:
```shell
pip install ringdown
```
For the latest and greatest version, you can install directly from the git repo:
```shell
pip install git+https://github.com/maxisi/ringdown.git
```
Additionally, you may follow the [JAX documentation](https://jax.readthedocs.io/en/latest/installation.html) to install JAX with GPU support.
### Complete Environments
A complete [conda](https://docs.conda.io/en/latest/) environment that includes all the prerequisites (and more!) to install `ringdown` can be found in `environment.yml` in the current directory:
```shell
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](https://mybinder.org/) by pointing MyBinder at this repository or clicking the button at the top of this README.
## Examples and tips
See the [example gallery](https://ringdown.readthedocs.io/en/latest/gallery.html) 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:
```python
# 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:
```python
# 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)](https://arxiv.org/abs/2107.05609):
```bibtex
@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"
}
```