https://github.com/vijayvarma392/surfinbh
Surrogate Final BH properties
https://github.com/vijayvarma392/surfinbh
blackholes gaussian-process-regression gravitational-waves physics
Last synced: 4 months ago
JSON representation
Surrogate Final BH properties
- Host: GitHub
- URL: https://github.com/vijayvarma392/surfinbh
- Owner: vijayvarma392
- License: mit
- Created: 2018-08-18T01:10:51.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-07-21T14:25:15.000Z (11 months ago)
- Last Synced: 2025-10-21T19:49:34.195Z (8 months ago)
- Topics: blackholes, gaussian-process-regression, gravitational-waves, physics
- Language: Python
- Size: 3.11 MB
- Stars: 23
- Watchers: 9
- Forks: 13
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/vijayvarma392/surfinBH)
[](https://pypi.org/project/surfinBH/)
[](https://anaconda.org/conda-forge/surfinbh)
[](https://zenodo.org/badge/latestdoi/145179417)
[](https://github.com/vijayvarma392/surfinBH/blob/master/LICENSE)
[](https://github.com/vijayvarma392/surfinBH/actions/workflows/test.yml)
# Welcome to surfinBH!
_**surfinBH**_ provides _**sur**rogate **fin**al **B**lack_ _**H**ole_
properties for mergers of binary black holes (BBH).
These fits are described in the following papers:
[1] V. Varma, D. Gerosa, L. C. Stein, F. Hébert and H. Zhang,
[arxiv:1809.09125](https://arxiv.org/abs/1809.09125).
[2] V. Varma, S. E. Field, M. A. Scheel, J. Blackman, D. Gerosa, L. C.
Stein, L. E. Kidder, H. P. Pfeiffer,
[arxiv:1905.09300](https://arxiv.org/abs/1905.09300).
[3] M. Boschini, D. Gerosa, V. Varma, et al.,
[arXiv:2307.03435](https://arxiv.org/abs/2307.03435)
[4] L. Magaña Zertuche, L. C. Stein, et al.,
[arXiv:2408.05300](https://arxiv.org/abs/2408.05300)
[5] G. Da Re, K. Mitman, L. C. Stein, et al.,
[arXiv:2503.09569](https://arxiv.org/abs/2503.09569)
If you find this package useful in your work, please cite reference [1] and,
if available, the relevant paper describing the particular model. Please also
cite this package, see the DOI badge at the top of this page for BibTeX keys.
This package lives on [GitHub](https://github.com/vijayvarma392/surfinBH), is
compatible with `python3`, and is tested every week. You can see the current
build status of the master branch at the top of this page.
## Installation
### PyPI
_**surfinBH**_ is available through [PyPI](https://pypi.org/project/surfinBH/):
```shell
pip install surfinBH
```
### Conda
_**surfinBH**_ is available on [conda-forge](https://anaconda.org/conda-forge/surfinbh):
```shell
conda install -c conda-forge surfinbh
```
### From source
```shell
git clone git@github.com:vijayvarma392/surfinBH.git
cd surfinBH
git submodule init
git submodule update
python setup.py install
```
If you do not have root permissions, replace the last step with
`python setup.py install --user`
## Dependencies
All of these can be installed through pip or conda.
* [numpy](https://docs.scipy.org/doc/numpy/user/install.html)
* [scipy](https://www.scipy.org/install.html)
* [h5py](http://docs.h5py.org/en/latest/build.html)
* [scikit-learn](http://scikit-learn.org/stable/install.html) (at least 0.19.1)
* [lalsuite](https://pypi.org/project/lalsuite) (at least 6.70)
* [gwsurrogate](https://pypi.org/project/gwsurrogate)
## Usage
```python
import surfinBH
```
### See list of available fits
```python
print(list(surfinBH.fits_collection.keys()))
>>> ['NRSur3dq8Remnant', 'surfinBH7dq2', 'NRSur7dq4Remnant', 'NRSur7dq4EmriRemnant', 'NRSur3dq8_RD', 'NRSur3dq8BMSRemnant']
```
Pick your favorite fit and get some basic information about it.
```python
fit_name = 'NRSur7dq4Remnant'
surfinBH.fits_collection[fit_name].desc
>>> 'Fits for remnant mass, spin and kick veclocity for generically precessing BBH systems up to mass ratio 4.'
surfinBH.fits_collection[fit_name].refs
>>> 'arxiv:1905.09300'
```
### Load the fit
This only needs to be done **once** at the start of your script.
If the fit data is not already downloaded, this will also download the data.
```python
fit = surfinBH.LoadFits(fit_name)
>>> Loaded NRSur7dq4Remnant fit.
```
### Evaluation
The evaluation of each fit is different, so be sure to read the documentation.
This also describes the frames in which different quantities are defined.
```python
help(fit)
```
We also provide ipython examples for usage of different fits:
##### Current fits
* [NRSur7dq4Remnant](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_7dq4.ipynb) (Ref. [2])
* [NRSur7dq4EmriRemnant](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_7dq4Emri.ipynb) (Ref. [3])
* [NRSur3dq8Remnant](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_3dq8.ipynb) (called surfinBH3dq8 in Ref. [1])
* [NRSur3dq8_RD](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_3dq8_RD.ipynb) (Ref. [4])
* [NRSur3dq8BMSRemnant](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_3dq8BMS.ipynb) (Ref. [5])
##### Deprecated fits
* [surfinBH7dq2](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_7dq2.ipynb) (Ref. [1]. Superseded by NRSur7dq4Remnant)
## Animations
We also provide a tool to visualize the binary black hole scattering process,
see
[binary black hole explorer](https://vijayvarma392.github.io/binaryBHexp/).
Here's an example:
## Making contributions
See this
[README](https://github.com/vijayvarma392/surfinBH/blob/master/README_developers.md)
for instructions on how to make contributions to this package.
## Credits
The code is maintained by [Vijay Varma](https://vijayvarma.com).
You can find the list of contributors
[here](https://github.com/vijayvarma392/surfinBH/graphs/contributors).
Please report bugs by raising an
issue on our [GitHub](https://github.com/vijayvarma392/surfinBH) repository.