NRHJSur3dq8 release notes

This release contains three files, and you need all three:

The merger-ringdown arm is not optional. Both models refer to it by name and resolve it when they load, so a copy of this release without it gives you two models that cannot produce a waveform. The loader refuses to serve a model whose arm is missing rather than quietly returning an inspiral, and it refuses to serve a model paired with an arm it was not validated against.

What the models cover

Aligned-spin, non-precessing binary black holes. Mass ratio up to 8, with dimensionless aligned spins on both bodies. Seven spin-weighted spherical harmonic modes: (2,2), (2,1), (3,3), (3,2), (4,4), (4,3), (5,5). Waveforms run from the start of the fitted inspiral through merger and ringdown, reaching about 124 M after the amplitude peak.

Both models describe the same physics through different internal parameterisations. The action-angle model is callable directly; the adiabatic-angle model is used through its modes method. Which one suits you depends on what you are doing, and docs/USAGE.md shows both.

Ask the model rather than assuming: the parameter range, the mode list and the time span are all recorded inside the artifact, and evaluating outside the fitted range raises a warning saying so.

Accuracy

Both models are compared against the numerical relativity waveforms they were built to reproduce, using a leave-one-out procedure, so the quoted figures are what to expect at parameters the model was not shown.

The adiabatic-angle model in this release improves on the previous generation by a factor of about 1.56 in all-mode error, and is better on every one of the seven modes. The largest single improvement is on the (2,2) mode.

Both models also satisfy the body-exchange symmetry exactly. Swapping the two bodies, together with their spins, returns the same waveform to machine precision. This matters most near equal mass and near equal spins, where the symmetry binds, and it matters for parameter derivatives as well as for the waveform itself. The previous generation violated it.

Where these models are WORSE

Read this section. A model is only useful if you know where not to trust it.

• The (2,1) mode of the action-angle model is a real regression against the previous generation, by about 5 percent. It is small, but it is statistically solid rather than noise. If your analysis is sensitive to (2,1), the previous generation is better on that mode.
• The merger-ringdown arm is worse than its predecessor on (3,2) and (4,4), by roughly 20 percent and 10 percent respectively. Both models in this release use that arm, so this applies to both. It is the price of extending the waveform further past the peak, and it is a deliberate trade rather than a defect.
• The spread across configurations is wide. Quoted accuracy figures are medians. Individual points in the parameter space vary by roughly a factor of three either way. Do not treat a median as a guarantee at your particular parameters.
• Higher modes are less accurate than (2,2), by roughly an order of magnitude, which is normal for this class of model but worth stating.
• Accuracy figures are computed without weighting by a detector noise curve. A detector-weighted comparison is harsher, roughly a factor of two overall and more on the higher modes.

Time inversion

Converting from the model's internal phase variable to time does not converge on a small set of points, of measure zero, at about 2.5e-4 of the peak amplitude. Anything computed by integrating over the waveform is unaffected. A calculation that reads the waveform at individual sample points could notice it.

Getting started

pip install nrhjsurrogate gives you the compiled Kokkos backend, OpenMP enabled, wherever a wheel is published: Python 3.12 and 3.13 on Linux x86-64 (manylinux_2_28), macOS arm64 and Windows x64. Nothing to build, no compiler, no flags; the macOS wheels carry their own libomp inside them. You do not need --no-binary, and using it where a wheel exists only discards a tested binary.

Everywhere else -- Python 3.14, Intel macOS, Linux aarch64 -- pip falls through to the SOURCE distribution and compiles it for you. That needs a C++17 compiler (GCC 10.4, Clang 14, Apple Clang or Visual Studio 2022 and later) and downloads and builds Kokkos 5.2.0 itself, or uses an installed Kokkos found through Kokkos_ROOT. Measured on an AMD EPYC with GCC 14 at eight parallel jobs, the compile takes about half a minute and the whole install about two, most of it dependency downloads. Without a usable compiler the install still succeeds with the NumPy backend and says so once; NRHJ_BUILD_KOKKOS=0 skips the attempt.

On macOS a source build needs an OpenMP runtime, because Apple's clang ships none: conda install -c conda-forge llvm-openmp, or brew install libomp (keg-only, so CMake may also want CMAKE_ARGS="-DOpenMP_ROOT=$(brew --prefix libomp)"). Without one the build succeeds Serial-only, which is a success to pip and single-threaded to you. No PyPI package can be declared as a dependency to fix this: llvm-openmp, libomp and openmp are not on PyPI at all, and intel-openmp ships no macOS files. INSTALL.md sections 1a and 2 have the details.

Choose a source build deliberately for -march=native (worth 8-17% end to end, and deliberately absent from the portable wheels) or for CUDA.

Which backend gets built is NRHJ_BACKEND: auto (default), numpy, serial, openmp (a missing OpenMP becomes a build error rather than a quietly single-threaded module) or cuda with NRHJ_CUDA_ARCH, e.g. NRHJ_BACKEND=cuda NRHJ_CUDA_ARCH=sm_75. INSTALL.md section 1b has the table. Whatever the outcome, the build record is written into the installed package: python -m nrhjsurrogate.compiled_backend prints it, the first import after an install reports it once, and a build that succeeded but got no OpenMP warns, because that is a success to pip and single-threaded to you.

Linux is verified, on two machines and for all four backend modes, CUDA included (GTX 1650 Ti, Turing sm_75, CUDA 13.0). macOS arm64 and Windows x64 are verified as of 2026-09-09: every published wheel is built on a hosted runner and must load its compiled backend, exit cleanly and pass nrhjsur-verify --strict 17 of 17 before it may be uploaded, and the macOS wheel was confirmed independently on a user's Apple Silicon machine (OpenMP on, exactly one libomp loaded, 4.2x faster at B=64 than the same build held to one thread). Intel macOS is still unbuilt -- GitHub retired that runner image -- so those users take the source route.

The model files download themselves the first time you name a released model and no copy is found: from the deposit into your per-user cache, SHA-256 checked against the registry, and kept only if it matches. Set NRHJ_AUTO_FETCH=0 to switch that off and place the files yourself.

One keyword is named backwards, and is left that way for this release. On the evaluation methods, safe=False selects the fast path rather than the one that reproduces bit for bit. It is not less accurate: over nine parameter points and seven modes the largest departure is 4.53e-10 relative on the waveform and 1.43e-09 on the derivatives, a millionth of the implementation divergence already present. What it costs is bit identity. It is also set for the whole process rather than for the calling thread, so a threaded likelihood can take the fast path everywhere without saying so. A later release renames it bitwise_reproducible and keeps safe= working.

docs/QUICKSTART.md gets you a waveform. docs/USAGE.md covers modes and polarizations, physical units, extending the inspiral to a lower starting frequency, parameter derivatives, the model's own error estimate, and the two evaluation backends. examples/usage/ has a runnable script for each.

Citing

See CITATION.cff.