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 carried in hp-adaptive spectral elements and evaluated either in NumPy or through a compiled Kokkos kernel.

Documentation: https://psu-edu.github.io/nrhjsurrogate/

Range of validity. Non-eccentric orbits, mass ratio 1 to 8, aligned spin components 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. Installing the source distribution also builds the compiled evaluator, fetching Kokkos if it is not already on the system; if that compile cannot run, the install still succeeds and the model falls back to NumPy and says so. NRHJ_BUILD_KOKKOS=0 skips the compile, =1 requires it.

NRHJ_BACKEND chooses what gets compiled, independently of whether:

NRHJ_BACKEND=openmp pip install --no-binary nrhjsurrogate nrhjsurrogate
NRHJ_BACKEND=cuda NRHJ_CUDA_ARCH=sm_75 \
  pip install --no-binary nrhjsurrogate nrhjsurrogate

auto (default) takes OpenMP when the compiler has it; numpy skips the compile; serial forces a single-threaded build; openmp makes a missing OpenMP a build error instead of a silent Serial build; cuda adds the device backend and needs NRHJ_CUDA_ARCH. After any install, python -m nrhjsurrogate.compiled_backend says what you actually got, and the first import after installing says it once by itself. See INSTALL.md sections 1b, 3 and 5 for the detail.

The model files are not in the package. They are distributed separately and located at run time, in order: an explicit path, then $NRHJ_MODEL_DIR, then the directories on $LAL_DATA_PATH, then a per-user cache. A miss raises FileNotFoundError naming the file, its SHA-256 and how to get it. Nothing degrades silently. If nothing on that list has a released model you named, the package downloads it into the per-user cache and checks its SHA-256 before using it; NRHJ_AUTO_FETCH=0 turns that off, and nrhjsurrogate.fetch_model does the same thing explicitly.

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 check the installation against shipped reference values:

nrhjsur-verify

Beyond waveforms the model serves analytic parameter derivatives, its own predictive uncertainty, post-Newtonian extension below the stored inspiral, the orbital dynamics and the remnant mass and spin. The runnable examples in examples/usage/ take one capability each, and 00_walkthrough.ipynb is a guided tour of the main ones.

The public import surface

Everything you are meant to use is importable straight from the package: from nrhjsurrogate import NRHJSurAA (and NRHJSurAdA, AABatch, AAHMCLikelihood, InnerProduct, fetch_model, and more; dir(nrhjsurrogate) lists them). The submodule layout underneath, driver/, physics/, execution/, numerical_methods/, is internal and may be rearranged in any release. Import from the top level and a reorganisation cannot reach you; import nrhjsurrogate.driver.something and it can.

Importing the package also sets OMP_PROC_BIND=close and OMP_PLACES=cores unless you have chosen otherwise; INSTALL.md gives the measured basis, the caveats and the off switch.

What is released

Two model flavours, both 3dq8, meaning aligned-spin (q, chi1z, chi2z) with q up to 8, matching the NRHybSur3dq8 convention. Both are built on the N2 numerical-relativity extrapolation, which the names do not encode and each file records as the root attribute extrapolation = "N2".

file what it is
NRHJSur3dq8_AA_v3 action-angle inspiral. The default.
NRHJSur3dq8_AdA_v3 adiabatic-angle inspiral, 14 elements
NRHJSur3dq8_MR_v3 the merger-ringdown arm both v3 inspirals name
NRHJSur3dq8_AA_v2 previous generation
NRHJSur3dq8_AdA_v2 previous generation
NRHJSur3dq8_MR_v2 previous generation

The inspiral files are de-embedded: each composes at load with the shared merger-ringdown arm it names, resolved by name and checked by content digest, so a crossed pair is refused rather than served. The version digit is the generation, not a patch level. Both generations are deposited; v3 is the default and v2 still loads by name.

The two flavours agree closely, and not by coincidence: the coordinates that give the adiabatic-angle model its structure were identified from the action-angle model's post-Newtonian normalizer.

How it works

  1. Slow variables. Each waveform is decomposed into a fast angle variable (the orbital phase) and slowly evolving action-like variables (a frequency parameter, co-orbital-frame amplitudes). The orbital phase, not time, is the independent coordinate.
  2. Frames and conventions. SXS extrapolated strain, centre-of-mass corrected, output in LAL conventions, round-trip validated against NRHybSur3dq8 through LALSimulation.
  3. Domain decomposition. Spectral elements both across the parameter space and along the phase coordinate, with a dedicated merger-ringdown element where adiabaticity breaks.
  4. Spectral representation. Chebyshev elements in phase, with regression onto spectral bases over the scattered simulation parameters. Accuracy is controlled by h- and p-refinement.
  5. Compiled evaluator. The evaluator is a Kokkos C++ kernel batched over parameter points and exposed through pybind11.
  6. Variable lengths. Handled natively by the phase coordinate and the element decomposition: elements exist only where data exists.

Scope of the distribution

The distribution ships 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, https://doi.org/10.5281/zenodo.22262339.

Licence

From version 1.1 this software is dual-licensed:

  • Noncommercial use — research, teaching, personal projects — is free and needs no permission, under the PolyForm Noncommercial License 1.0.0 with an additional term on machine-learning training. See LICENSE.
  • Commercial use requires a separate licence, available from the author on request. See NOTICE.

Using the source or documentation as training data for general-purpose code or language models is not permitted. Building an emulator or reduced-order model of the waveforms this software produces is ordinary research use and is fine — see NOTICE for the distinction.

Citation metadata is in CITATION.cff; please cite the paper.

Project links

Data verified by PyPI on Sep 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for vaishakprasad from gravatar.com vaishakprasad

Credits

Author: Vaishak Prasad

License expression

LicenseRef-PolyForm-Noncommercial-1.0.0-with-ML-term
View SPDX License List

Requires

Python >=3.12

Provides Extra

build plot train pe test

Tags

gravitational-waves numerical-relativity surrogate-model waveform action-angle

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nrhjsurrogate-1.1.tar.gz (2.3 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

nrhjsurrogate-1.1-cp313-cp313-win_amd64.whl (2.5 MB view details)

Uploaded CPython 3.13Windows x86-64

nrhjsurrogate-1.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.4 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

nrhjsurrogate-1.1-cp313-cp313-macosx_14_0_arm64.whl (2.4 MB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

nrhjsurrogate-1.1-cp312-cp312-win_amd64.whl (2.5 MB view details)

Uploaded CPython 3.12Windows x86-64

nrhjsurrogate-1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.4 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

nrhjsurrogate-1.1-cp312-cp312-macosx_14_0_arm64.whl (2.4 MB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

File details

Details for the file nrhjsurrogate-1.1.tar.gz.

File metadata

  • Download URL: nrhjsurrogate-1.1.tar.gz
  • Upload date:
  • Size: 2.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nrhjsurrogate-1.1.tar.gz
Algorithm Hash digest
SHA256 97e431a83faf0b2a08e9042e5ac531bd4098ee0fb03523d3ddff5331c6eea790
MD5 e9129db7d848119f65053a91cda684fa
BLAKE2b-256 abfbddfac1a1beab34e87d2d2c3933ce8908b61a826153b67c87463d68fff229

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.1.tar.gz:

Publisher: release.yml on psu-edu/nrhjsurrogate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nrhjsurrogate-1.1-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 4695522c9aa6efd08e86340f2c77cbb5fb593c06a5f04aecca5c6a39de3ec752
MD5 9d92908c5319a4b6d6212557b68c9660
BLAKE2b-256 6a0ea80b974f1ec7c696a231edea563a8b001f1a5386436300c9e1d196655a91

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.1-cp313-cp313-win_amd64.whl:

Publisher: release.yml on psu-edu/nrhjsurrogate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nrhjsurrogate-1.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bfd59c2d8acf339ee0138e5e5b2858d5e8f34ff737262187d959b82d6f07ea74
MD5 3bacc2249928f22fafd9fad28996532c
BLAKE2b-256 53d9548e7e75c8e0f590da163b725670940f623471bf9f2013135e1a34f4477e

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on psu-edu/nrhjsurrogate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nrhjsurrogate-1.1-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.1-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a907c9901713dcde2af56d3be641eebaca680902dcc6d1346bcf03a4c929c132
MD5 7523f9de065d4f6f8c04aa85c70bb42d
BLAKE2b-256 e58044be2d0b3b595673860c90ec7250891318e60a8054c390f2207d23bde239

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.1-cp313-cp313-macosx_14_0_arm64.whl:

Publisher: release.yml on psu-edu/nrhjsurrogate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nrhjsurrogate-1.1-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 d7cb8429e7607f6fdddfb1c34b7ff10a40863ecf0f535f3ab504bd9e7c53d56d
MD5 f457064e50f97467b819bdfb8a9d2949
BLAKE2b-256 de5e6b2d6af2b0138451202cbd626364a9f6fbc49af5c402562400a4f5727b8a

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.1-cp312-cp312-win_amd64.whl:

Publisher: release.yml on psu-edu/nrhjsurrogate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nrhjsurrogate-1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 76d3d5d87b1618f51416a5ca93b776c7ccb964fe82bf1889186287a9de408fb7
MD5 1beecaa73311dbc47e9d3bcea1b4da89
BLAKE2b-256 c83e0a9da8a602b1fd9e7ffecf55dba55f949d0205975fc70c8646dd314e67f0

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on psu-edu/nrhjsurrogate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nrhjsurrogate-1.1-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.1-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 950d7c0b684c635648d94f22dcfa6bb69be7c3253a9d7383394feef8a0b539f1
MD5 e50b374c8a2f15dea0171604313cb083
BLAKE2b-256 724c2e194794ccfe355d866f66fa1baff1ed1a50a10fda1f50d3e5662b402af1

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.1-cp312-cp312-macosx_14_0_arm64.whl:

Publisher: release.yml on psu-edu/nrhjsurrogate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.3

7 files

This release

1.1 This release

7 files

Yanked

1.0.0

1 file

Yanked reason: change of licence

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page