Make source-to-site distance a configurable registry, and specify the magnitude calculation

[sgjholt]

Follows PR #24. One piece of working code — the distance registry — and the magnitude roadmap it serves, sourced from the thesis rather than guessed.

The bug this started from

staged.InverseDistance, added in #24, hardcoded rhyp. Meanwhile [windows] distance_metric said repi and was read by nothing. So the project declared epicentral and computed hypocentral — the same defect class this refactor has now found seven times.

It is not bookkeeping at microseismic range. The nearest PNR station is 0.89 km epicentral against 2.30 km hypocentral, a factor of 2.57, while the farthest agree to 1.00. Since the weighting is by inverse distance, the two measures disagree hardest exactly where the weight is largest. Every number PR #24 quoted moves:

	was (rhyp)	now (repi)
event fc	12.751 Hz	11.585 Hz
weight carried by nearest 2 channels	22.8%	41.4%
dropping the nearest station	+16%, 1.56× stress drop	+34.7%, 2.44×

Epicentral is the right default beyond the config having said so. rhyp is built from the source depth and the station elevation, so it assumes every sensor sits at the surface; for a borehole deployment that is wrong by the burial depth and nothing announces it. The PNR inventory records channel depth as 123456.0 — a placeholder — so on that dataset rhyp is an assumption wearing a measurement's name.

specmod.distance

A registry, in the same shape as ESTIMATORS, NOISE_MODELS and WEIGHT_MODELS. It lives outside staged because geometric spreading needs distance too, and a second consumer restating the choice is how two things drift apart.

repi and rhyp are implemented. rrup and rjb are registered and raise, deliberately rather than being omitted:

rrup is not implemented. It needs a rupture surface — strike, dip, length
and width, and SpecMod carries a point source... For a point source rrup
degenerates to hypocentral; name that instead if it is what you mean,
rather than getting it by accident.

That degeneracy is the reason a silent fallback would be dangerous — plausible numbers, wrong for precisely the events large enough to warrant asking. A name that resolves to a clear failure is a better extension point than a name that does not resolve.

InverseDistance(measure=None) follows the configuration; explicit inverse_hypocentral_distance and inverse_epicentral_distance spellings remain for a study that wants to record which it used regardless.

[geometry] distance_measure

The setting moves out of [windows], which was the wrong home even when nothing read it — cutting a window does not depend on how distance is measured. Renamed as well as moved, since these are measures rather than metrics and the name now matches the registry.

studies/magna_2020_paper.toml carries the value across unchanged. The published run used hypocentral, and that is preserved as the record of what was done rather than edited toward the new default. Magna is a transcript, not a recommendation.

Caught while moving it: deleting the old field took p_velocity and s_velocity with it, since the three shared a comment block. Five test_config.py failures named the missing keys immediately — the value of a test that asserts the whole resolved configuration rather than the fields someone remembered to check.

Roadmap, sourced rather than guessed

Read from Holt (2019) — the Edwards et al. (2010) method this package implements. Chapters 1 and 2 have now been read in full. Two earlier claims in the plan were wrong and are corrected:

• ΘλΦ = 0.55 is not a different average of the same quantity, it is a different quantity — the average radiation pattern of SH propagation, pairing with F = 2 for vertically incident SH. The textbook 0.63 is the RMS over total S. So it was never a departure from the standard value, and it couples directly to the rotation question: a formulation using the SH radiation pattern wants the transverse component.
• R₀ = 1000 m is a reference source distance, not a kilometre-to-metre bridge as an earlier draft guessed.

And that resolves the disagreement about the unit of R: there are two. R₀ in the moment expression is in metres alongside ρ in kg/m³ and β in m/s, giving M₀ in N·m. The geometric spreading model S(R) is a separate term and its R is in kilometres. Both answers were right about different terms.

Also recorded, each with the measurement behind it:

• The spreading exponent is ~1, not 2. 1/r² gives median Mw +5.39 against a catalogue 1.6 — the distance term applied twice. The thesis's own Utah inversion gives 0.88 ± 0.02 over 1–40 km, independently.
• Bilinear belongs in the design but one event cannot fit it. Regressing log10(Ω) on log10(R) over the 28 channels buys 5% of rms for two extra parameters across one decade of distance — a hinge finding scatter. The 0.265 log10 residual is site response and radiation pattern, inseparable from spreading when every station contributes one distance. Which is the argument for the non-parametric inversion.
• Magna stays the calibration anchor, because its S(R) is non-parametric where Utah's is piecewise parametric — and S(R) is the term least checkable by other means. Consequence recorded: it must arrive as tabulated data, so the spreading registry has to accept a table and not only a functional form.
• Components, phases and station/channel identity types (§4.7), including that back_azimuth is computed and read by nothing, that horizontals are fitted as independent measurements so each station is counted twice, and the N/E vs 1/2 trap.
• Documentation equations do not render — MyST dollarmath syntax with no MyST build.

The equations cannot be verified from the PDFs, and that route is now closed

An earlier draft of the plan recorded the constants as unverified and suggested a PDF export of Chapters 1–2 under 10 MB would settle them. Those exports were obtained. They do not, and the reason rules out trying again.

It is not an extraction failure. The pages carrying Eq. 1.12, 1.13, 1.14, 2.6, 2.7 and 2.8 declare only Times New Roman fonts and no image, and rendering them produces the equation numbers against blank space. The Word-to-PDF export dropped the embedded equation objects, taking inline maths with it — which is why the prose reads "where, is the long period spectral displacement plateau at the source". Settling the algebra needs the original document, or Edwards et al. (2010).

The prose survived, and settles every constant in the table, each now read from the section that defines it. Two things follow:

• The partition factor should not be folded in by default. Ch. 1 lists one in the generic C; Ch. 2, defining the Utah calculation this package follows, enumerates Eq. 2.7's constants without one. A study that wants it can set it.
• Table 2.1 carries a preferred model the plan was missing — Holt et al. [R]: 0.90 / 2.57 / 0.44 / 1.54, breaking at 43/76/136 km. §2.7 recommends it over [O] on lower uncertainty across every slope and more events resolved. If a Utah spreading table ever ships as study data, [R] is the one.

Mw is a near miss: Ch. 1 confirms the SI (N·m) convention around it, but the numeric constant sits inside a dropped equation, so the 9.1 is still unverified from this source.

Four transform defaults now have a published source

The equations did not survive the export, but Ch. 2 §2.2's description of the processing did, and it is the more useful half here — four steps land on defaults §4.4 and §4.5 previously justified on internal measurement alone.

• MultitaperEstimator defaults time_bandwidth=3.0, n_tapers=5 — exactly "five 3-π prolate tapers", NW=3 giving 2NW-1=5. §4.4 could only describe the 3 as the literal argument passed positionally to mtspec, with no way to configure it. It is now a considered choice with a citation.
• "Multiply by the sampling period" is one_sided_fas's |spec| * dt, reached there from the requirement that padding change only the frequency sampling. Same normalisation, opposite direction.
• Excluding zero-padding from the signal/noise length ratio is the same rule as that function's refusal to rescale for padding.
• SNR ≥ 3 matches SnrConfig.tolerance, but applied to a different job: the thesis gates the fit band per spectrum where the Magna paper gates spectrum selection in fixed bands. That is already the distinction between bandwidth selection and assert_bandwidths, so both are expressible — said explicitly so the shared number is not misread.

One knowing divergence recorded: the recipe pads to 2^N where resolve_n_fft defaults to a 5-smooth length, safe for the same reason the recipe itself relies on, with pow2 available for exact reproduction. The remaining steps — the 20 s window at 80% of the Pg–Sg interval, the noise window at 75%, 2.5σ station rejection, 3-station minimum — are event-level aggregation this package does not do yet, written down so the magnitude module has a specification to build to instead of inventing thresholds.

Checks

• 592 passed, 1 skipped
• ruff check, ruff format --check, mypy clean
• Tutorial notebook re-executed end to end; its numbers re-measured on epicentral distance

The last two commits are documentation only — no code changed since the checks above were run.