Welcome to surfinBH!
surfinBH provides surrogate final Black Hole 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.
[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.
[3] M. Boschini, D. Gerosa, V. Varma, et al., arXiv:2307.03435
[4] L. Magaña Zertuche, L. C. Stein, et al., arXiv:2408.05300
[5] G. Da Re, K. Mitman, L. C. Stein, et al., arXiv: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, 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:
pip install surfinBH
Conda
surfinBH is available on conda-forge:
conda install -c conda-forge surfinbh
From source
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
- scipy
- h5py
- scikit-learn (at least 0.19.1)
- lalsuite (at least 6.70)
- gwsurrogate
Usage
import surfinBH
See list of available fits
print(list(surfinBH.fits_collection.keys()))
>>> ['NRSur3dq8Remnant', 'surfinBH7dq2', 'NRSur7dq4Remnant', 'NRSur7dq4EmriRemnant', 'NRSur3dq8_RD', 'NRSur3dq8BMSRemnant']
Pick your favorite fit and get some basic information about it.
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.
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.
help(fit)
We also provide ipython examples for usage of different fits:
Current fits
-
NRSur7dq4Remnant (Ref. [2])
-
NRSur7dq4EmriRemnant (Ref. [3])
-
NRSur3dq8Remnant (called surfinBH3dq8 in Ref. [1])
-
NRSur3dq8_RD (Ref. [4])
-
NRSur3dq8BMSRemnant (Ref. [5])
Deprecated fits
- surfinBH7dq2 (Ref. [1]. Superseded by NRSur7dq4Remnant)
Animations
We also provide a tool to visualize the binary black hole scattering process, see binary black hole explorer. Here's an example:
Making contributions
See this README for instructions on how to make contributions to this package.
Credits
The code is maintained by Vijay Varma. You can find the list of contributors here. Please report bugs by raising an issue on our GitHub repository.
2 maintainers
Release files for surfinBH 1.2.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| surfinbh-1.2.7.tar.gz | 2.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| surfinbh-1.2.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.0 MB
Release files / surfinbh-1.2.7.tar.gz
| Download URL | surfinbh-1.2.7.tar.gz |
|---|---|
| Size | 2.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e584218c464844d50597062288e0f9f0c90d6995911941e070a1543d004e3b7
|
|
BLAKE2b-256 checksum How to use checksums |
9ee42de4a6d4855a67057ee0f5e2f6afa81a14d11cb7cfcfe930e15f3d3f1d1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.18
|
Release files / surfinbh-1.2.7-py3-none-any.whl
| Download URL | surfinbh-1.2.7-py3-none-any.whl |
|---|---|
| Size | 39.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
04f81c8a61c90566ebeae6744619fc6de4bedb309476441bac84cb7c3b19268b
|
|
BLAKE2b-256 checksum How to use checksums |
31eb1ab0e102f15d1c38723d269e7ef0c4143bb8a5c9108dfe29e71c92da2947
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.18
|
