Caveats

Read these before interpreting any number. They are physics/design facts, not bugs.

Frozen-seed large-scale offset

All 64 design models share five initial-condition seeds, so the ensemble-mean ξ (and ξ_hh) amplitudes at r ≳ 30 Mpc/h carry a frozen ~+2–3 % offset vs truth. Confirmed at two independent-seed fiducials (F5n1 and F6n1: signed ξ_hh bands +1.7–2.6 % over [2.5, 60] at both) — so it is the design offset, not an emulator defect.

• pk_mm is CLOSED — the low-k anchor to linear theory removes it.
• xi_mm / xi_hh remain OPEN — an r-space anchor and a Hankel-of-anchored-P(k) hybrid were both tested and rejected (they degrade the BAO).
• Design-internal comparisons are unaffected (the offset is common-mode).

Details: DOCUMENTATION.md §12; mitigation campaign in fRn1_new_runs_plan.md.

ξ near the BAO zero crossing

ξ fractional errors are meaningless where |ξ| < 0.01. The suite masks there and quotes χ vs the across-box SEM instead. Don't divide by ξ in that band.

xi_hh default route and its window

Since 2026-08-20 a bare predict("xi_hh", ...) serves the density-threshold chain in mass coordinates (route="nbar"): 0.1-dex bins over [12.8, 14.2] on the native 0.051-dex radial bin centres (r ∈ [0.556, 113.4]). The values are measured-bin estimates on that binning — do not compare them to point evaluations at arithmetic bin centres. Requests outside the contract (edges below 12.8, interpolated or sub-0.5 radii, r_edges, mass-extrapolation policies) fall back to route="exact" — check validity["route_selection"] when the output grid is not what you expected. The auto window is frozen so the route never flips within a cosmology scan; explicit route="nbar" reaches each cosmology's full served mass span and raises outside it rather than extrapolating.

xi_hh small-r validity radii

In route="exact", each mass-bin pair carries a validity radius res["validity"]["r_valid_bin"][i, j]: the floor of trained data support, not the physical exclusion radius. Mass bins aligned to the 0.05-dex grid (edges on 12.55…14.0) are served by the bin-level route down to each pair's own data floor — 0.56–1.6 Mpc/h for ΛCDM, ≳0.97 for f(R) (its stored radial grid starts at 0.9); off-grid edges keep the threshold-corner floors (r_valid_bin_threshold, 2.0–2.4 ΛCDM typical); bin_smallr_served marks which pairs got the deep route.

Below r_valid_bin pairs still exist in abundance — the floors are mostly the 5-box noise edges of the design suite, and the fiducial suite measures a large, smooth pair density well below them, down to a sharp total-exclusion cliff near half the summed halo radii. Never treat sub-floor radii as "physically excluded": the 2026-07 central-only HOD comparison lost 80 % of ξ_gg at 1 Mpc/h to exactly that reading. Since 2026-07-24 the served values below r_valid_bin are the labelled halo-exclusion reconstruction (xi_hh_excl templates): the boundary prediction continued along the emulated matter shape times a suppression factor calibrated on fiducial boxes 1–30 in the scaled radius x = r/R_excl — with R_excl = α·max(R)+β·min(R) (ΛCDM 1.29/0.63: the heavier halo's boundary sets the exclusion scale) — reaching zero pair density (ξ = −1) below validity["r_zero_bin"][i, j]. validity["xi_mode"] labels every value (0 trained, 1 exclusion model, 2 zero-pair). Held out on boxes 31–100, the model region carries 5.5–8.6 % median error on 1+ξ over 0.6–3 Mpc/h (χ ≈ 1.1–2.1; the cosmology transfer of the templates is good to |ΔS| ≈ 0.03–0.07 median across the design); the f(R) model region is rougher — 18–24 % median at [0.9, 1.3) against its fiducials, the limit of the 0.9-floor f(R) cubes — quote all of it as a model, never as trained-emulator accuracy. Routes have validity windows: exact [0.5, 100] for trained support with the model continuation below, bbar [20, 70] Mpc/h. Requested r above the xi_mm support (124.8) raises.

Velocity moments

• Accuracy is χ = residual / SEM, never fractional (the moments cross zero).
• f(R) high even moments (c40, c04, c22, c02) sit well above χ = 1 at design interior — a design-sampling limit; use with care and consult return_var (per-emulator χ in the manifest).
• Native mass range: 14 bins span log₁₀M ∈ [12.5, 15.5], ending in one deliberately broad [14.2, 15.5) cell. A separate [14.7, 15.5) cell was rejected because the weakest design realization has only 16 halos and 3 in-range pairs (54/57 empty radial bins); merging it into the broad tail gives trainable support while retaining the highest measured HMF edge.
• The terminal-cell validation passes comfortably: new-pair interior-LOO χ is 1.04–1.33 (ΛCDM) / 1.14–1.61 (f(R)) and the five-box high-mass aggregate is 0.82–1.19 / 0.97–1.40. Fresh-seed terminal-cell aggregates are absent below 1.25 Mpc/h because halo exclusion leaves no complete pair sample.
• vel_binned has a narrower range than the native vel_<moment> surfaces: its halo-abundance/ξ weight chain is served only through log₁₀M=14.2 for ΛCDM and 14.0 for f(R). Requested edges must lie on the native grid and use whole cells; res["validity"] reports both limits.
• Radial grid (since 2026-07-24): 57 bins over [0.352, 150] Mpc/h — 26 logarithmic 0.05-dex bins below 7 Mpc/h (the re-measured small-r product) + the wide bins above. Each mass pair's radial support ends at its own data floor (pair starvation near the exclusion boundary, ~0.4–1.1 Mpc/h for m10/c20/c02; higher for c12 and the heaviest pairs): below it the surfaces are NaN — hole-free per pair by construction, so hold-flat-inward consumers keep working. The floors are where pairs run out, not a request limit.

Redshift coverage

Only z = 0.25 (all properties) and z = 0.00 (matter sector: hmf, pk_mm, xi_mm) are registered. Other redshifts raise — the registry snaps only within Z_TOL = 0.005.

Parameter conventions

• θ order is fixed: [Omega_m, h, n_s, S_8(, logf_R0)].
• Pass S_8, not σ_8. S_8 = sigma_8 * sqrt(Omega_m / 0.3).
• Outside the design ranges the GP extrapolates and is unvalidated.

Provenance

When in doubt, the manifest is the source of truth: reg.entry(prop, gravity, z) gives the accuracy block, dependency pins, and the code version that produced the trained emulator.