NRHJSur3dq8

A surrogate model for gravitational waves from non-eccentric, aligned-spin binary black hole mergers, trained on numerical relativity.

It is built on a Hamilton-Jacobi (action-angle) representation of the binary dynamics: the orbital phase rather than time is the independent coordinate, so simulations of different lengths simply occupy different phase ranges. The waveform is represented in hp-adaptive spectral elements and evaluated either in NumPy or through a compiled Kokkos kernel.

Parameter range. Non-eccentric orbits. Mass ratio 1 to 8, aligned spins within 0.8 in magnitude. Seven modes: (2,2), (2,1), (3,3), (3,2), (4,4), (4,3), (5,5).

Install

pip install nrhjsurrogate

Every dependency resolves from PyPI. The compiled backend is built during the install of the source distribution, fetching Kokkos if it is not already present; if that compile cannot run, the install still succeeds and the model falls back to NumPy. See Installation for the detail.

The model files are distributed separately from the code and are located at run time. Point NRHJ_MODEL_DIR at the directory holding them, or let nrhjsurrogate.fetch_model download and checksum them.

A first waveform

from nrhjsurrogate import NRHJSurAA

model = NRHJSurAA.load_h5("NRHJSur3dq8_AA_v3")

# geometric units: time in M, modes as r h_lm / M
times, modes = model.get_td_waveform_modes_geometric(4.0, 0.3, -0.2)

# physical units, LAL spelling: the two polarizations
h_plus, h_cross = model.get_td_waveform(
    mass1=40.0, mass2=10.0, spin1z=0.3, spin2z=-0.2,
    delta_t=1.0 / 4096.0, f_min=30.0, inclination=0.7, distance=400.0)

Then verify the install against shipped reference values:

nrhjsur-verify

Where to go next

Quickstart is the five-minute version.
Walkthrough notebook runs waveforms, derivatives and hybridisation end to end, with figures.
Usage guide is the complete argument-by-argument reference.
Measured accuracy states what the model is worth, and The model's error estimate explains the uncertainty it reports about itself.

What is released

Two model flavours, both aligned-spin 3dq8, sharing one merger-ringdown arm:

model	what it is
`NRHJSur3dq8_AA_v3`	action-angle. The default.
`NRHJSur3dq8_AdA_v3`	adiabatic-angle, 14 elements.

The previous generation, _v2, is also deposited and still loads by name. The version digit is the generation, not a patch level.

The distribution contains EVALUATION CODE ONLY: what turns a frozen model file into a waveform, and nothing that builds one. There is no public source repository; the code is distributed through PyPI and the model files through Zenodo.

Licensed MIT.