Heron¶

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.