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 10, 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:
Latest release

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.3.tar.gz (2.4 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.3-cp313-cp313-win_amd64.whl (2.6 MB view details)

Uploaded CPython 3.13Windows x86-64

nrhjsurrogate-1.3-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.3-cp313-cp313-macosx_14_0_arm64.whl (2.4 MB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

nrhjsurrogate-1.3-cp312-cp312-win_amd64.whl (2.6 MB view details)

Uploaded CPython 3.12Windows x86-64

nrhjsurrogate-1.3-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.3-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.3.tar.gz.

File metadata

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

File hashes

Hashes for nrhjsurrogate-1.3.tar.gz
Algorithm Hash digest
SHA256 5c2132ed4d5fadd1d01d2d1d084740bcf073cbb06090a139551b8fd5bec5a834
MD5 8772414a5d899756fd7d95169fa3e78f
BLAKE2b-256 cb3f946e3e3833c836fef86071550fdfa9d99a89ec8da6e06236eed0db049a41

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.3.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.3-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.3-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 9e2fb97e44e600e54ef5d6dfe53a63ab2d88271682137d5dc83fbae1651885db
MD5 e5226727676b83bd670f91903ab74dc4
BLAKE2b-256 2b43b5d9b06db404cb2c9a391f7fdc67e970b3117b73797dbdcc652a595f1c40

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.3-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.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0bb6a164d58e16385ee67fec709e29771e6ce22da510b534b0ef34f446b014bf
MD5 c72c379963944b90a8167fe2d9cd552f
BLAKE2b-256 ef419a102499c6fa95c41aa5bd1d43c9c73bd36647a0ba0fa7f091de4bd47a86

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.3-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.3-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.3-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 6acffbf896a72d5b70762cd299297dfd1c165f064582b779394cb229940c1152
MD5 bc71468ba37a56de59c01be5f8f79293
BLAKE2b-256 ba3e02d35f1906757c3e045ea4668490c691fa701bc022612d70b923cfacf817

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.3-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.3-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 467c0132d9de9ee5bf91a532a1a8c6a8f8e30098f23a8e6cf5fb6c76641bb5d1
MD5 8b0fa121f604622176ad7de4074f2366
BLAKE2b-256 aabe1c02f969d3466cd317c5dc180bf84f24d6d0c712e7a0af81253aedfefd72

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.3-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.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5156050811cc1a6f2e4f0308213c71317c0882210133d6567ecf3049df87fc87
MD5 f8ec5f91d163c67dcd9b64b43f648199
BLAKE2b-256 d864a910923e411d68e9d6a1afc096f16f64ba8dd9a7d615daf19b3e044e1f05

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.3-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.3-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for nrhjsurrogate-1.3-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 70a20bfc407f54b5819c5729036a5c73d8c5010ff95de2f6c59b421c78eca728
MD5 8cc502edc3fc661be9d5750617d6bc12
BLAKE2b-256 724161782bce1f060947a5edbbe2b163ecb6668e18d23870ccb21ce3d8bb1f01

See more details on using hashes here.

Provenance

The following attestation bundles were made for nrhjsurrogate-1.3-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

This release

1.3 This release

7 files

1.1

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