https://github.com/transientlunatic/heron
Heron is a surrogate modelling toolkit for python, using Gaussian process regression.
https://github.com/transientlunatic/heron
gaussian-processes gravitational-waves numerical-relativity surrogate-modelling surrogate-models
Last synced: 8 days ago
JSON representation
Heron is a surrogate modelling toolkit for python, using Gaussian process regression.
- Host: GitHub
- URL: https://github.com/transientlunatic/heron
- Owner: transientlunatic
- License: isc
- Created: 2016-02-15T10:46:17.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-10-29T17:59:36.000Z (7 months ago)
- Last Synced: 2024-10-29T19:16:19.286Z (7 months ago)
- Topics: gaussian-processes, gravitational-waves, numerical-relativity, surrogate-modelling, surrogate-models
- Language: Jupyter Notebook
- Homepage: http://www.code.daniel-williams.co.uk/heron/
- Size: 49.7 MB
- Stars: 3
- Watchers: 5
- Forks: 1
- Open Issues: 23
-
Metadata Files:
- Readme: README.rst
- Changelog: HISTORY.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
- Authors: AUTHORS.rst
Awesome Lists containing this project
README
Heron
=====
.. image:: https://badge.fury.io/py/heron-model.svg
:target: https://badge.fury.io/py/heron-model
.. image:: https://travis-ci.org/transientlunatic/heron.svg?branch=master
:target: https://travis-ci.org/transientlunatic/heron
.. image:: https://zenodo.org/badge/51749075.svg
:target: https://zenodo.org/badge/latestdoi/51749075
The ``heron`` project is an effort to create a new model for gravitational waveforms which uses Gaussian Process Regression (GPR), a form of machine learning, to produce waveforms for arbitrary compact binary systems.
The approach taken in the ``heron`` project is unique, using waveforms generated by numerical relativity simulations as training data to learn the behaviour of waveforms from these systems, and providing a probability distribution of potential waveforms for each location in the parameter space.
This means that the confidence of the model's prediction can be easily assessed, and can be incorporated in any parameter estimation process which uses the model.
The proof-of-principle model for ``heron`` is described in `Physical Review D `_ (also available free on the `arXiv `_), which also discusses some of the difficulties in using this type of model.
Additional information can be found in `this thesis `_.
-------------
Documentation
-------------
Full documentation, including code-level documentation and tutorials, can be found `here `_.
-------------
Prerequisites
-------------
Heron requires ``python`` version ``3.6`` or above to work.
It is not guaranteed to work on older versions of Python, and will very likely not run on Python 2.
In order to install ``heron`` you'll need to install its dependecies.
If you intend to use ``pip`` to install the package (see `Installing`_ for more details) then this should be done for you.
We strongly recommend that you install ``heron`` in a virtual environment to avoid dependency problems.
If you're installing ``heron`` from source (or aren't using ``pip``) you can install the pre-requisites by running
::
pip install -r requirements.txt
Should you also want to build the documentation for the package you'll need to run
::
pip install -r requirements_dev.txt
----------
Installing
----------
We recommend installing the latest version of ``heron`` from pypi using ``pip``.
::
pip install heron-model
This will also take care of installing any dependencies the package needs.
We recommend installing in a virtual environment.
If you wish to install from source you can run either
::
pip install .
in the top-level of this repository, or
::
python setup.py install
in the top level directory.
We strongly recommend using the ``pip`` approach to install the package; you can find out why `here `_.
------
Models
------
This section has a brief overview of the models which are implemented in the package, but for more information you should check the documentation for the package.
``HeronHODLR``
--------------
+------------------+-----------------------+------------+----------+--------------+
| Training data | GPR Technique | Model type | Spinning | Higher modes |
+==================+=======================+============+==========+==============+
| NR: Georgia Tech | HODLR, Approximate | BBH | Fully | No |
+------------------+-----------------------+------------+----------+--------------+
The HODLR model was the first fully-functioning binary black hole waveform model to be produced by the ``heron`` project, and it remains the recommended one to be used in further investigations at present.
The model is trained on `numerical relativity waveforms `_ produced by the Centre for Relativistic Astrophysics at Georgia Tech, and uses a `HODLR inversion technique `_ to make the Gaussian Process tractable for a large amount of data. The underlying package generating the GPR is `george `_.
``HeronCUDA``
--------------
+------------------+-----------------------+------------+----------+--------------+
| Training data | GPR Technique | Model type | Spinning | Higher modes |
+==================+=======================+============+==========+==============+
| NR: Georgia Tech | Exact, LOVE, CUDA | BBH | Fully | No |
+------------------+-----------------------+------------+----------+--------------+
The original ``heron`` model was capable only of running on CPU resources, and could only make use of a single thread.
The ``HeronCUDA`` model is an attempt to expand the abilities of ``heron`` to run on CUDA-enabled GPUs.
The model is trained on `numerical relativity waveforms `_ produced by the Centre for Relativistic Astrophysics at Georgia Tech, and uses exact scalable GPR techniques implemented by `GPyTorch `_.
-------------------
Citing this package
-------------------
If you use this package in any academic work please cite its paper and this repository's DOI:
::
@ARTICLE{2020PhRvD.101f3011W,
author = {{Williams}, D. and {Heng}, I.~S. and {Gair}, J. and {Clark}, J.~A. and
{Khamesra}, B.},
title = "{Precessing numerical relativity waveform surrogate model for binary black holes: A Gaussian process regression approach}",
journal = {\prd},
keywords = {General Relativity and Quantum Cosmology, Physics - Data Analysis, Statistics and Probability},
year = 2020,
month = mar,
volume = {101},
number = {6},
eid = {063011},
pages = {063011},
doi = {10.1103/PhysRevD.101.063011},
archivePrefix = {arXiv},
eprint = {1903.09204},
primaryClass = {gr-qc},
adsurl = {https://ui.adsabs.harvard.edu/abs/2020PhRvD.101f3011W},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
@software{daniel_williams_2019_3378679,
author = {Daniel Williams},
title = {transientlunatic/heron: Castle Semple},
month = aug,
year = 2019,
publisher = {Zenodo},
version = {v0.2.5},
doi = {10.5281/zenodo.3378679},
url = {https://doi.org/10.5281/zenodo.3378679}
}
----------
Versioning
----------
``Heron`` uses `semantic versioning `_ to label releases.
Significant releases may also be named after bodies of freshwater in Scotland.
-------
License
-------
``Heron`` is made available under the terms of the `ISC License `_.
----------------
Acknowledgements
----------------
The development of ``heron`` was conducted mainly in the `Institute for Gravitational Research `_ at the `University of Glasgow `_.
Funding was provided through a number of grants by the UK `Science and Technology Facilities Council `_.