Artifacts and resolution

The released files, how a name becomes a path, and how an inspiral model is bound to its merger-ringdown arm. Written 2026-09-02, the day the deposit became six files and the digests were checked.

The six released files

Zenodo record 22262339, https://doi.org/10.5281/zenodo.22262339, base URL https://zenodo.org/records/22262339/files/. The v3 family is the default; v2 is deposited so that published v2 numbers stay reproducible (nrhjsurrogate/models.py, the registry, which is the only place the names and checksums live).

Read the names from nrhjsurrogate.RELEASE_AA and RELEASE_ADA rather than typing them. The full digests are in models.MODELS and were reproduced byte for byte on a second scrub run. The wheel ships code only; the files come from the deposit or from models.fetch_model(name), which downloads into the per-user cache and verifies the SHA-256 and size BEFORE the file is moved into place, so a truncated download can never be found by a loader (models.py:fetch_model). An unregistered name is refused with the released names listed, measured: fetch_model("nrhjsur_production_v4_swsph") raises unknown model ...; released models: NRHJSur3dq8_AA_v3, NRHJSur3dq8_AdA_v3.

A model cannot be evaluated without its merger-ringdown arm. Each inspiral file records the arm's NAME (mr_name) and the content digest it was validated against (mr_content_md5); both v3 inspirals record NRHJSur3dq8_MR_v3 and 912502ce1e193e81a91269693508f31c (read off the files' root attributes). Loading resolves that name on every load and refuses to continue without it, rather than returning an inspiral-only model, because a model degraded by accident is indistinguishable from one degraded on purpose (nrhjsurrogate/serialize.py:1206, resolve_mr_arm). The waveform, the remnant and the error estimate all need the arm.

How a name becomes a path

models.resolve_model(name_or_path), models.py:569. First hit wins:

1. an explicit path that exists, used verbatim;
2. $NRHJ_MODEL_DIR, colon separated like $PATH;
3. $LAL_DATA_PATH, the LALSuite convention, so an artifact dropped beside NRSur7dq4 and NRHybSur3dq8 resolves by name with nothing to learn; below the project variable so a project choice beats a shared install, above the cache so a file placed on purpose beats one the package downloaded, and never written to;
4. the per-user cache, $NRHJ_MODEL_CACHE_DIR, else platformdirs if it happens to be installed, else $XDG_CACHE_HOME/nrhjsurrogate, else ~/.cache/nrhjsurrogate;
5. model_release/ beside a source checkout, deliberately last.

models.search_path() prints the list: the directory named by NRHJ_MODEL_DIR, then the directories on LAL_DATA_PATH, then ~/.cache/nrhjsurrogate/models. A path with directory components is a specific request and is not searched for elsewhere. A miss raises FileNotFoundError naming the file, its size and digest, every directory searched and the two ways to fix it; measured for an unknown name.

Earlier spellings of these variables still work and warn once, naming the variable to use instead.

Verification is opt-in on load and the internal copies fail it, on purpose. The registry pins the PUBLIC checksums, the scrubbed files in dist_models/ that the deposit holds. The checkout's model_release/ copies carry the construction provenance (build script, cache paths, training ids) that the release strips, so they hash differently: model_release/NRHJSur3dq8_AA_v3.h5 measures 9cac9f97... against the registry's b6d2d300..., and models.verify_model refuses it with checksum mismatch. Evaluation is bitwise identical between the two copies, 192 of 192 arrays over four inspirals and six parameter points. resolve_model(..., verify=True) is how a consumer asks for the check.

The arm binding and its digest

serialize.compose_mr_arm (serialize.py:1352) decides, in order: an explicit merger_ringdown_path wins; else an embedded arm (pre-de-embedding files, none of the six); else mr_representation == "none" is a deliberately arm-less model; else the recorded name is resolved and checked.

The check compares digests, and the digest is computed in an unusual way that has consequences. mr_content_digest_of_arm (serialize.py:965) RE-SERIALISES the in-memory arm through the ordinary writer into an in-memory HDF5 image and hashes the resulting group. The alternative, hashing the dataclass fields, would have been a second definition of "the same arm", free to drift from the on-disk one. Two things follow:

• A stored field's KEY is part of the arm's identity even when nothing reads its value. Fields the evaluator never reads still round trip through the reader and the writer, so they enter the content digest. Preparing the public copy therefore changed the digest of the arm: 912502ce... internal became 419923f3... public for v3, and 136981ad... became 9509f809... for v2. Both digests of each arm are registered in models.MR_CONTENT_MD5_TO_NAME, so an internal pair resolves, a public pair resolves, and a crossed pair is still refused (8 of 8 crossed pairs refused). The provenance attributes mr_content_md5, mr_name, mr_recipe, mr_source are excluded (_MR_PROVENANCE_ATTRS, serialize.py:790), which is why correcting the group's mr_name on the public copy was digest-inert.
• A write-side helper runs on the load path. Measured, 86 ms per load to recompute the digest from the resolved arm, against 180 ms for the whole load_h5.

Raise versus warn, all three measured:

The representation is checked too: a swsph model composes only with a swsph arm. And the two families are not interchangeable between classes: NRHJSurAdA.load on an AA file, and NRHJSurAA.load_h5 on an AdA file, each raise unsupported format_version naming the tag they found. Those tags are literal strings stored inside the files and one of them still carries a retired spelling of the project name; they identify the on-disk format, not the model.

What the files say about themselves

Root attributes worth reading with h5py before trusting a number:

• extrapolation = "N2", the strain extrapolation order the model was built on, which the names do not encode. The public copies carry it; the INTERNAL model_release/NRHJSur3dq8_AA_v3.h5 does not, which is why tests/test_model_resolver.py::test_released_h5_records_its_extrapolation_order fails on a checkout until that artifact is restamped.
• known_weakness_odd_m_21 on AA_v3: the (2, 1) in-sample mismatch is 0.950x the v2 model's, better on only 66 of 242 folds. The shared MR_v3 arm also reads 0.807 on (3, 2) and 0.906 on (4, 4) against its predecessor with the inspiral held fixed (models.py, the RELEASE_ADA comment). Both are properties of the released composition.
• mr_arm, mr_name, mr_content_md5, mr_representation: the binding described above. The internal MR_v3 group still names itself with the candidate spelling NRHJSur3dq8_MR_v3_cand_tailed_selfsel; the public copy is corrected to the release name.
• domain_end_M = 124.5 on the arm: the reach after the peak.

Limits, next to the capability

• The mass ratio in the name is 1.51e-5 outside the hull. The stored log-q training bound is 2.0794264247 against log(8) = 2.0794415417, so the largest trained mass ratio is 7.999879; in_hull(8, 0, 0) is False and every error estimate taken there warns that it is an extrapolation. Owner decision 2026-09-02: left as is and documented, here and in model-error-estimate.md. The parity gate keeps (8, -0.5, 0.6) as a point precisely because it exercises the clamped path (scripts/release_eval_parity.py).
• $LAL_DATA_PATH can satisfy a missing artifact from outside your deposit. That is the point of it, and it is also how the self-sufficiency gate once passed on a wheel that could not load AdA; the gate now strips it. When you need to know which file served, ask models.resolve_model(name).
• The checkout's model_release/README.md and RELEASE_CHECKSUMS.txt are stale: last regenerated 2026-08-23, they still describe v2 as the release and carry no v3 rows, while the deposit metadata says v3 plus MR_v3. The registry in models.py is the authority.
• dist_models/ must be regenerated after ANY change to an internal artifact by scripts/make_public_artifacts.py; the six checksums in models.py, the deposit README and the metadata move together.
• Nothing on the deposit is a pickle. The default load route is HDF5 and no released file is a pickle.
• AA_v1, AdA_v1, MR_v0_9, MR_v1 are registered as SUPERSEDED so the version numbers keep meaning something. Several other names in the registry are construction-side files that ship nowhere.

Where the code is