feat: periodic-equilibrium warm-start for nuts-on-ode (gh#396)

[vsbuffalo]

Periodic-equilibrium warm-start for nuts on ode (gh#396)

Skips the seasonal spin-up transient in gradient ODE fits by solving the limit
cycle directly, instead of re-integrating decades of burn-in on every gradient.
The measured motivation (garki mv_age, origin = 1910): one augmented-ODE
gradient ≈ 1 min, a single NUTS warm-up iteration > 7 min ⇒ a full fit = days,
zero samples. The cost is the ~63-year transient, re-integrated per eval.

Approach

The seasonal equilibrium at the data-window start T_eq is the fixed point of
the one-period stroboscopic map, X* = Φ_P(X*; θ). We solve it by Newton using
the monodromy M = ∂Φ_P/∂X₀, and seed the data-window integration with the
exact sensitivity the sampler needs, ∂X*/∂θ = (I − M)⁻¹ ∂Φ_P/∂θ (implicit
function theorem). The 63-year transient collapses to a handful of one-year
period-solves plus dense linear solves.

Reuses the gh#275 augmented forward-sensitivity RK4 verbatim — Ṡ = J_x·S is
already the monodromy variational equation; a forcing toggle on the sensitivity
seed turns off the ∂rate/∂θ term to integrate M.

Conservation (the load-bearing correction)

A closed model conserves a linear quantity (cᵀM = cᵀ), so (I − M) is singular
endemic-or-not — and garki is conserved (per-village population, k = 4). We
detect the conserved directions numerically via SVD: because any RK method
preserves linear invariants exactly, genuine conservation sits at machine-
precision singular values (~1e-12), ~10 orders below the slowest real mode, so
the threshold is robust. The fixed point is then solved on the conservation
manifold with a bordered/KKT system; the sensitivity reuses the factorization and
the ic_grad seed for the conserved directions. An endemic gate refuses a
non-hyperbolic transverse cycle.

Validity

• Periodicity gate: an interpolated/table forcing carries no declared
  period, so warm_start_period is required and the forcing is checked
  numerically — the vector field must repeat with period P over the burn-in
  window, else a hard error (a misconfigured anchor can't silently seed a spurious
  equilibrium).
• Endemic gate: non-hyperbolic ⇒ hard error naming the dominant multiplier.
• Scheduled effects, rk45, dt-in-rate, real compartments — already refused by
  the existing det_grad capability gate.

Surface (fit.toml, on the nuts stage)

[stages.posterior]
algorithm         = "nuts"
backend           = "ode"
warm_start        = "equilibrium"   # default "none"
warm_start_period = 365.25          # forcing period P (required)
warm_start_at     = 1970.0          # T_eq; default = earliest observation

Consistent with the sibling stage knobs (dense_mass, warmup, …), which are
TOML-only. warm_start_* are identity-defining and re-key the run. nuts-only
in v1 — mh does not expose the option (an honest absence, a named follow-up).

Tests

Five solver oracles (all green): fixed-point residual + conservation (k, N
preserved); monodromy vs central FD; ∂X*/∂θ vs FD of the equilibrium re-solve
(the partial-vs-total seed-trap catcher); X* vs a long burn-in (confirms it's
the attracting cycle); the periodicity gate accepts the true period and refuses a
wrong one. No regression in the existing ODE gradient suite (31 + 3 det_grad FD).

Fixture is a freshly-compiled closed seasonal SEIRS. Note: the committed
ir/golden/*.ir.json predate the gh#275 rate_state_grad emission (they carry an
empty rate_state_grad, skip_serializing_if_empty) — a separate staleness worth
a make update-golden, filed as a follow-up; real fits compile fresh and are
unaffected.

Rust-only (a fit-time runtime option) — no IR/schema/OCaml/golden change.

Follow-ups

• mh-on-ode warm-start (needs only X*, no sensitivity).
• Real-compartment forward sensitivity → warm-start for explicit dx/dt models.
• Multi-period / LCM P; block-sparse bordered solve for national scale.
• Newton warm-start across evals (couples evals; land stateless first).
• End-to-end posterior-parity validation on the real garki mv_age (garki agent).

Proposal: docs/dev/proposals/2026-07-07-ode-periodic-equilibrium-warmstart.md.

[vsbuffalo]

Converting to draft — this is a correct-but-not-yet-viable foundation, not for merge.

Status: correct math, validated on small models (5 oracle tests green), but does not scale to densely-coupled models.

Findings from real-model testing (garki mv_age, 196 comp) + two expert reviews:

• Cost: the full monodromy is O(n_int) column-integrations; at n=196 one monodromy ≈ the entire 63-yr transient (measured: >10 min for a single solve). garki's dense FOI coupling makes the state-Jacobian dense, so even a matrix-free (JFNK/GMRES) rework pays that cost on every monodromy–vector product.
• Correctness gap: the endemic gate (rcond of I−M) misses period-doubling / multi-year cycles (a Floquet multiplier near −1 leaves I−M nonsingular). Seasonally-forced epidemic systems can settle to biennial cycles; solving x=Φ_P(x) at P=1yr can return an unstable annual orbit. Needs a Φ_P-vs-Φ_2P + Floquet-magnitude check before this is trusted on any model.
• Modeling subtlety: for models that are not actually settled at T_eq (garki's 61-yr burn-in ≈ one 56-yr relaxation time), jumping onto the limit cycle is a model change, not a faithful speedup.

Where this method belongs: sparsely-coupled seasonal models that are genuinely at their annual cycle. If we invest, build it the reviewers' way: symbolic projection/elimination for conservation (not SVD/KKT-first), Anderson-accelerated period map, matrix-free Newton–Krylov fallback, stiff-solver option, period-2/-k diagnostics.

The immediate garki unlock is being pursued separately via calendar-aware coarse-dt burn-in (simpler, faithful, no dense-coupling penalty).