[](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!
<img src="https://raw.githubusercontent.com/vijayvarma392/surfinBH/master/images/interaction.jpeg" alt="BHScattering" width="600px"/>
<br/>
_**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: <br/>
[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)
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)
* [NRSur7dq2](https://pypi.org/project/NRSur7dq2) (only for surfinBH7dq2)
## Usage
```python
import surfinBH
```
### See list of available fits
```python
print(list(surfinBH.fits_collection.keys()))
>>> ['NRSur3dq8Remnant', 'surfinBH7dq2', 'NRSur7dq4Remnant', 'NRSur7dq4EmriRemnant', 'NRSur3dq8_RD']
```
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])
##### Older 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:
<img src="https://raw.githubusercontent.com/vijayvarma392/binaryBHexp/master/animations/video.gif" width="500"/>
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/vijayvarma392/surfinBH",
"name": "surfinBH",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "black-holes gravitational-waves Gaussian-process-regression",
"author": "Vijay Varma",
"author_email": "vvarma@caltech.edu",
"download_url": "https://files.pythonhosted.org/packages/82/27/a1f93bf7afb2ddb43548eec3297301145d0a15a8f4858632773033dbec81/surfinBH-1.2.5.tar.gz",
"platform": null,
"description": "[](https://github.com/vijayvarma392/surfinBH)\n[](https://pypi.org/project/surfinBH/)\n[](https://anaconda.org/conda-forge/surfinbh)\n[](https://zenodo.org/badge/latestdoi/145179417)\n[](https://github.com/vijayvarma392/surfinBH/blob/master/LICENSE)\n[](https://github.com/vijayvarma392/surfinBH/actions/workflows/test.yml)\n\n\n# Welcome to surfinBH!\n\n<img src=\"https://raw.githubusercontent.com/vijayvarma392/surfinBH/master/images/interaction.jpeg\" alt=\"BHScattering\" width=\"600px\"/>\n\n<br/>\n\n_**surfinBH**_ provides _**sur**rogate **fin**al **B**lack_ _**H**ole_\nproperties for mergers of binary black holes (BBH).\n\nThese fits are described in the following papers: <br/>\n[1] V. Varma, D. Gerosa, L. C. Stein, F. He\u0301bert and H. Zhang,\n[arxiv:1809.09125](https://arxiv.org/abs/1809.09125).\n\n[2] V. Varma, S. E. Field, M. A. Scheel, J. Blackman, D. Gerosa, L. C.\nStein, L. E. Kidder, H. P. Pfeiffer,\n[arxiv:1905.09300](https://arxiv.org/abs/1905.09300).\n\n[3] M. Boschini, D. Gerosa, V. Varma, et al.,\n[arXiv:2307.03435](https://arxiv.org/abs/2307.03435)\n\n[4] L. Maga\u00f1a Zertuche, L. C. Stein, et al.,\n[arXiv:2408.05300](https://arxiv.org/abs/2408.05300)\n\nIf you find this package useful in your work, please cite reference [1] and,\nif available, the relevant paper describing the particular model. Please also\ncite this package, see the DOI badge at the top of this page for BibTeX keys.\n\nThis package lives on [GitHub](https://github.com/vijayvarma392/surfinBH), is\ncompatible with `python3`, and is tested every week. You can see the current\nbuild status of the master branch at the top of this page.\n\n## Installation\n\n### PyPI\n_**surfinBH**_ is available through [PyPI](https://pypi.org/project/surfinBH/):\n\n```shell\npip install surfinBH\n```\n\n### Conda\n_**surfinBH**_ is available on [conda-forge](https://anaconda.org/conda-forge/surfinbh):\n\n```shell\nconda install -c conda-forge surfinbh\n```\n\n\n### From source\n\n```shell\ngit clone git@github.com:vijayvarma392/surfinBH.git\ncd surfinBH\ngit submodule init\ngit submodule update\npython setup.py install\n```\n\nIf you do not have root permissions, replace the last step with\n`python setup.py install --user`\n\n\n## Dependencies\nAll of these can be installed through pip or conda.\n* [numpy](https://docs.scipy.org/doc/numpy/user/install.html)\n* [scipy](https://www.scipy.org/install.html)\n* [h5py](http://docs.h5py.org/en/latest/build.html)\n* [scikit-learn](http://scikit-learn.org/stable/install.html) (at least 0.19.1)\n* [lalsuite](https://pypi.org/project/lalsuite) (at least 6.70)\n* [gwsurrogate](https://pypi.org/project/gwsurrogate)\n* [NRSur7dq2](https://pypi.org/project/NRSur7dq2) (only for surfinBH7dq2)\n\n## Usage\n\n```python\nimport surfinBH\n```\n\n### See list of available fits\n```python\nprint(list(surfinBH.fits_collection.keys()))\n>>> ['NRSur3dq8Remnant', 'surfinBH7dq2', 'NRSur7dq4Remnant', 'NRSur7dq4EmriRemnant', 'NRSur3dq8_RD']\n```\n\nPick your favorite fit and get some basic information about it.\n```python\nfit_name = 'NRSur7dq4Remnant'\n\nsurfinBH.fits_collection[fit_name].desc\n>>> 'Fits for remnant mass, spin and kick veclocity for generically precessing BBH systems up to mass ratio 4.'\n\nsurfinBH.fits_collection[fit_name].refs\n>>> 'arxiv:1905.09300'\n```\n\n### Load the fit\nThis only needs to be done **once** at the start of your script.\nIf the fit data is not already downloaded, this will also download the data.\n```python\nfit = surfinBH.LoadFits(fit_name)\n>>> Loaded NRSur7dq4Remnant fit.\n```\n### Evaluation\nThe evaluation of each fit is different, so be sure to read the documentation.\nThis also describes the frames in which different quantities are defined.\n```python\nhelp(fit)\n```\n\nWe also provide ipython examples for usage of different fits:\n\n##### Current fits\n\n* [NRSur7dq4Remnant](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_7dq4.ipynb) (Ref. [2])\n\n* [NRSur7dq4EmriRemnant](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_7dq4Emri.ipynb) (Ref. [3])\n\n* [NRSur3dq8Remnant](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_3dq8.ipynb) (called surfinBH3dq8 in Ref. [1])\n\n* [NRSur3dq8_RD](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_3dq8_RD.ipynb) (Ref. [4])\n\n##### Older fits\n\n* [surfinBH7dq2](https://github.com/vijayvarma392/surfinBH/blob/master/examples/example_7dq2.ipynb) (Ref. [1]. Superseded by NRSur7dq4Remnant)\n\n## Animations\n\nWe also provide a tool to visualize the binary black hole scattering process,\nsee\n[binary black hole explorer](https://vijayvarma392.github.io/binaryBHexp/).\nHere's an example:\n\n<img src=\"https://raw.githubusercontent.com/vijayvarma392/binaryBHexp/master/animations/video.gif\" width=\"500\"/>\n\n\n## Making contributions\nSee this\n[README](https://github.com/vijayvarma392/surfinBH/blob/master/README_developers.md)\nfor instructions on how to make contributions to this package.\n\n\n\n## Credits\nThe code is maintained by [Vijay Varma](https://vijayvarma.com).\nYou can find the list of contributors\n[here](https://github.com/vijayvarma392/surfinBH/graphs/contributors).\nPlease report bugs by raising an\nissue on our [GitHub](https://github.com/vijayvarma392/surfinBH) repository.\n",
"bugtrack_url": null,
"license": null,
"summary": "Surrogate Final BH properties.",
"version": "1.2.5",
"project_urls": {
"Homepage": "https://github.com/vijayvarma392/surfinBH"
},
"split_keywords": [
"black-holes",
"gravitational-waves",
"gaussian-process-regression"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca91f4b877e7a08b85743bb28f85bec9fe6b81c10972bef58b58e6fcb48ea7de",
"md5": "cab128c78599f0a34f3c5da267f84050",
"sha256": "5f44e6e71d17d9b7b6d620fa8ca45c581316c1bb091176652de2485ddc568b47"
},
"downloads": -1,
"filename": "surfinBH-1.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cab128c78599f0a34f3c5da267f84050",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 36069,
"upload_time": "2024-08-13T03:32:17",
"upload_time_iso_8601": "2024-08-13T03:32:17.018453Z",
"url": "https://files.pythonhosted.org/packages/ca/91/f4b877e7a08b85743bb28f85bec9fe6b81c10972bef58b58e6fcb48ea7de/surfinBH-1.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8227a1f93bf7afb2ddb43548eec3297301145d0a15a8f4858632773033dbec81",
"md5": "7b0dabdc455a977062aeb4fb4731911b",
"sha256": "c1dff91a1d59e04aef5de1d8872cd0c25ae4fbc1a8f36b1b1bc26c8ad79a1028"
},
"downloads": -1,
"filename": "surfinBH-1.2.5.tar.gz",
"has_sig": false,
"md5_digest": "7b0dabdc455a977062aeb4fb4731911b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 30161,
"upload_time": "2024-08-13T03:32:18",
"upload_time_iso_8601": "2024-08-13T03:32:18.447737Z",
"url": "https://files.pythonhosted.org/packages/82/27/a1f93bf7afb2ddb43548eec3297301145d0a15a8f4858632773033dbec81/surfinBH-1.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-13 03:32:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vijayvarma392",
"github_project": "surfinBH",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "surfinbh"
}
JSON
