osmose.calibration.larva_recal

SP1b — mean-neutral recalibration of cod larval mortality for the SP1 spatial term.

Pure 1-D root finder: coarse grid scan over [0, d0] -> sign-change feasibility gate -> bisection. Engine-free (the caller injects run_mean_on); see the SP1b design spec.

Per-stock (cod_west + cod_east, since the 2026-07-25 disaggregation): each SP1-enabled stock gets its own rate, solved against its own SP1-off mean by a Gauss-Seidel sweep over the 1-D solver (solve_per_stock). Every solved rate is frozen TOGETHER WITH the resolved baseline rate d0 it was solved against (StockRecal.d0); sp1_on_config refuses to apply a rate whose d0 no longer matches the live config, because a mean-neutral offset is only meaningful relative to the baseline it offsets (the 2026-07 trap: d0 moved 15 -> 10.16 under a frozen 14.66 and the overlay silently became a larval-mortality INCREASE).

Functions

e_clip_first_guess(field_path, spawn_path, d0)

Analytical first-guess rate d1 = clip(d0 + ln E[clip], 0, d0), and E[clip].

mean_cod(cfg, *[, seed])

Mean total-cod biomass over years index [3:15] (finite & >0), matching the SP1 diagnostic.

mean_cod_from_biomass(bio)

Total cod = cod_west + cod_east (aggregate 'cod' fallback for undisaggregated configs).

resolved_d0(cfg, name)

The live resolved per-cohort larva rate of name (the baseline d0 a solve offsets).

solve_larva_rate(baseline, run_mean_on, *, ...)

Find the larva rate whose SP1-on mean cod biomass matches baseline within tol.

solve_per_stock(baselines, run_means_on, *, ...)

Gauss-Seidel sweep of solve_larva_rate over coupled stocks.

sp1_on_config(base_cfg, field_path, *[, ...])

SP1-on config: SP1 flags (every declared stock in stocks) + determinism keys + per-stock recalibrated larva rates.

species_index(cfg, name)

sp index of the species named name (species.name.sp{i}), or None if absent.

stock_means(cfg, *[, seed])

One engine run -> years-[3:15] mean biomass per focal species.

stock_means_from_biomass(bio)

Mean biomass per species column over years [3, 15) (finite & >0).

stock_overshoot_from_biomass(bio)

max/mean per species column over years [3, 15) — the boom/bust index the SP1b diagnostic records (measured, never gated).

with_determinism(cfg)

Return a copy of cfg with the two fixed-seed keys set (required for a reproducible solve; the runtime numba single-thread pin is set separately by the caller).

Classes

PerStockResult(rates, means, rel_errs, ...)

RecalResult(rate, baseline, mean_on, ...)

StockRecal(rate, d0[, baseline, mean_on, ...])

A solved per-stock rate frozen together with the baseline it was solved against.