EMRISurrogate

Overview

EMRISurrogate is a Python package for evaluating EMRISur1dq1e4, a surrogate gravitational waveform model trained on waveform data generated by point-particle black hole perturbation theory (ppBHPT). The model covers non-spinning black hole binaries with mass ratios from 3 to $10^4$.

Model details

The “raw” surrogate model is defined by

where ${}^{-2}Y_{\ell m}$ are the spin-weight $-2$ spherical harmonics. The surrogate model provides fast evaluations of the modes $h_{\tt S}^{\ell,m}$. The available modes are

while the $m<0$ modes follow from $h^{\ell,-m} = (-1)^{\ell} \left(h^{\ell,m}\right)^*$.

By default, the package returns rescaled waveform modes,

where the total-mass rescaling parameter $\alpha(q)$ is tuned to NR simulations (Eq. 4 of Rifat et al.). $\alpha$ approaches unity in the extreme-mass-ratio limit. Most users will want the NR-tuned model. To generate pure point-particle perturbation theory waveforms without any tuning to NR ($\alpha = 1$), pass calibrated=False to generate_surrogate.

Installation

EMRISurrogate is not packaged for pip. Clone the repository and download the surrogate data file, which is hosted on Zenodo:

git clone https://github.com/BlackHolePerturbationToolkit/EMRISurrogate.git
cd EMRISurrogate
wget https://zenodo.org/record/3612600/files/EMRISur1dq1e4.h5

The code looks for EMRISur1dq1e4.h5 in the current working directory and tries to download it with wget if it is missing. Either move the file into the directory you work from, or create a symbolic link to it there.

The module emri_sur_load.py needs numpy, scipy, h5py, matplotlib and gwtools. Parts of the accompanying notebook also need gwsurrogate (pip install gwsurrogate), but you don’t need it to evaluate the EMRI surrogate model.

Usage

Run Python from the repository directory (or add it to your path) and import emri_sur_load. Its generate_surrogate function returns the time array and a dictionary of modes keyed by (l, m):

import emri_sur_load as emriSur

# NR-calibrated modes in geometric units (all available modes by default)
t, h = emriSur.generate_surrogate(100.0)
h22 = h[(2, 2)]

# raw (uncalibrated) ppBHPT waveform
t_raw, h_raw = emriSur.generate_surrogate(100.0, calibrated=False)

# physical units: total mass in solar masses, distance in Mpc
t_phys, h_phys = emriSur.generate_surrogate(100.0, M_tot=80.0, dist_mpc=500.0)

Pass modes=[(2,2), (3,3)] (for example) to return only a subset of the modes. You must give both M_tot and dist_mpc to get physical-unit waveforms.

Examples

The EMRISur1dq1e4.ipynb notebook in the repository shows how to evaluate the model in geometric and physical units, and compares calibrated and raw waveforms. The repository also contains the notebook BHPToolkit_Spring2020_Tutorial.ipynb from the Spring 2020 Toolkit workshop.

Known problems

Known bugs are recorded in the project issue tracker.

License

EMRISurrogate is distributed under the MIT License. See the LICENSE file for details.

Authors and contributors

Scott Field, Tousif Islam, Gaurav Khanna, Nur Rifat, Vijay Varma

Citing EMRISurrogate

If you use EMRISurrogate in your research, please acknowledge the Toolkit:

EMRISurrogate also requests the following citation:

• Surrogate model for gravitational wave signals from comparable and large-mass-ratio black hole binaries arXiv Inspire
  BibTeX

  @article{Rifat:2019ltp,
      author = "Rifat, Nur E. M. and Field, Scott E. and Khanna, Gaurav and Varma, Vijay",
      title = "{Surrogate model for gravitational wave signals from comparable and large-mass-ratio black hole binaries}",
      eprint = "1910.10473",
      archivePrefix = "arXiv",
      primaryClass = "gr-qc",
      doi = "10.1103/PhysRevD.101.081502",
      journal = "Phys. Rev. D",
      volume = "101",
      number = "8",
      pages = "081502",
      year = "2020"
  }

See how to cite for further guidance.