methods_page_detail

.claude/skills/leaderboard-manager/references/populate-metadata.md

@@ -57,7 +57,7 @@ method_meta = {
     "TEKI": {
         "citation": "Chada et al., SIAM/ASA J. UQ, 2020",
         "url": "https://doi.org/10.1137/17M114402X",
-        "summary": "EKI variant with Tikhonov regularization for stability.",
+        "config": "`opt_experiments/ensemble_kalman_processes` — EnsembleKalmanProcesses.jl `Inversion(prior)` process. Fixed-step `DefaultScheduler()`, `NoLocalization()`, up to `N_iter=20` iterations.",
     },
     ...
 }
@@ -69,10 +69,20 @@ method_meta = {
 The three fields:
 - `citation` — free-form string; typically "Author et al., Journal, Year" or a short title.
 - `url` — a full `https://...` URL. Displayed as an "Open reference" button.
-- `summary` — one or two sentences. Keep it short enough to fit in a narrow column.
+- `config` — a short **technical configuration** summary (not a conceptual description):
+  the solver/process type, scheduler, key hyperparameters, and the source file path in
+  `CalibrationLeaderboard.jl` (`opt_experiments/...` or `uq_experiments/...`). This is what
+  renders in the "Technical Configuration" box at the top of the Methods page.
 
 If you don't have a value yet, use `"(citation pending)"` / `"https://example.com"` /
-`"(summary pending)"` as placeholders so the app renders gracefully.
+`"(configuration details pending)"` as placeholders so the app renders gracefully.
+
+Note: the Methods page (`src/pages/MethodDetails.py`) no longer reads `metric_store` or
+renders any benchmark tables/charts — it is a pure documentation page driven by
+`KNOWN_METHODS` (for the abbreviation/full-name list) and `method_meta` (for the
+citation/link/config box). Locating the config details for a method means reading its
+script(s) under `opt_experiments/` or `uq_experiments/` in
+`~/Dropbox/Caltech/CESjl/CalibrationLeaderboard.jl`, not the NetCDF data in this repo.
 
 ---
 

CLAUDE.md

@@ -57,7 +57,12 @@ calibration_benchmark/
 │   │   └── method_registry.py   KNOWN_METHODS registry + name canonicalization
 │   └── pages/
 │       ├── UQLeaderboard.py     🎯 UQ Leaderboard — calls render_leaderboard(load_uq_store())
-│       ├── MethodDetails.py     📘 Methods — per-method charts + metadata
+│       ├── MethodDetails.py     📘 Method configurations — per-method (selection-driven) technical
+│       │                        detail: update equation, guardrails, a small
+│       │                        parameter table, and convergence/speed notes,
+│       │                        plus citation/link, sourced from KNOWN_METHODS +
+│       │                        method_meta (no metric_store/NetCDF dependency,
+│       │                        no data-driven tables/charts)
 │       └── RawData.py           🧾 Get Data — raw table + CSV export
 ├── data/                        NetCDF result files (git-LFS — run `git lfs pull`)
 │   ├── *.nc                     Kalman results (TEKI, ETKI, IEKF)
@@ -231,6 +236,22 @@ the `budget_store` parameter of `render_leaderboard()` in `src/common/leaderboar
   (`streamlit_app.py`, `UQLeaderboard.py`, `MethodDetails.py`, `RawData.py`).
 - **Method metadata is split** — `method_registry.py` (scoring) and `pages/MethodDetails.py`
   `method_meta` dict (display copy) must both be updated when adding a new method.
+- **`method_meta` fields (per abbreviation)**: `citation`, `url`, `source` (short file-path
+  reference into `CalibrationLeaderboard.jl`), `math` (prose update description) + optional
+  `math_eq` (a single-line raw LaTeX string rendered via `st.latex()`), `guardrails` (prose:
+  regularization/localization/adaptive-scheduling/early-stopping machinery), `params` (a
+  list of `{"Parameter", "Value"}` dicts — deliberately **excludes ensemble size and max
+  iterations**, which are covered by the leaderboard charts), and `notes` (prose:
+  convergence/speed behavior, including known empirical issues). All of it is display copy
+  only; the Method configurations page renders `KNOWN_METHODS` (for
+  the abbreviation/full-name list) + `method_meta` (for everything else), scoped to
+  whichever method is currently selected.
+- **`method_meta` content is manually transcribed, not derived** — the math/guardrails/
+  params/notes text was written by reading `CalibrationLeaderboard.jl`'s
+  `experiment_config.jl`/`run_*.jl`/`*_core.jl` files (and, for the Kalman-family methods,
+  `EnsembleKalmanProcesses.jl`'s own update-equation source) directly. There is no
+  automated sync — update it by hand when a method's experiment settings or algorithm
+  change upstream.
 - **`build_leaderboard()` in `data_store.py` is dead code** — both leaderboards are rendered
   via `render_leaderboard()` in `src/common/leaderboard.py`.
 - **No CI / no formal test suite** — `test_parse.py` and `test_failures.py` are manual scripts.

src/pages/MethodDetails.py

@@ -1,136 +1,434 @@
 from pathlib import Path
 import sys
 
-import altair as alt
+import pandas as pd
 import streamlit as st
 
 try:
-    from data_store import load_metric_store
+    from common.method_registry import KNOWN_METHODS
 except ModuleNotFoundError:
     sys.path.append(str(Path(__file__).resolve().parents[1]))
-    from data_store import load_metric_store
+    from common.method_registry import KNOWN_METHODS
 
-st.set_page_config(page_title="Method Details", page_icon="📘", layout="wide")
+st.set_page_config(page_title="Method Configurations", page_icon="📘", layout="wide")
 
 # Sidebar navigation
 st.sidebar.title("Navigation")
 st.sidebar.page_link("streamlit_app.py", label="Home", icon="🏠")
 st.sidebar.page_link("pages/OptimizationLeaderboard.py", label="Optimization Leaderboard", icon="📊")
 st.sidebar.page_link("pages/UQLeaderboard.py", label="UQ Leaderboard", icon="🎯")
-st.sidebar.page_link("pages/MethodDetails.py", label="Methods", icon="📘")
+st.sidebar.page_link("pages/MethodDetails.py", label="Method configurations", icon="📘")
 st.sidebar.page_link("pages/RawData.py", label="Get Data", icon="🧾")
 
-st.title("Method Details")
-st.caption("Method-level view from NetCDF forward-model-run metrics averaged over random seeds")
+st.title("Method Configurations")
+st.caption("Technical configuration of each calibration / UQ method, as implemented for this benchmark")
+st.info(
+    "We are always seeking new algorithm families to be applied to this benchmark series. "
+    "If your favorite method is missing, or incorrectly configured, or if any algorithm is "
+    "lacking appropriate citation - please create an issue on `CalibrationLeaderboard.jl`, "
+    "and we can investigate this! Just note - we are interested in general behavior of "
+    "algorithm families, not hyper-optimizing any individual configuration to an individual "
+    "experiment."
+)
 st.markdown(
     "For the exact implementation of each algorithm, see "
-    "[CalibrationLeaderboard.jl](https://github.com/odunbar/CalibrationLeaderboard.jl)."
+    "[CalibrationLeaderboard.jl](https://github.com/odunbar/CalibrationLeaderboard.jl) "
+    "(`opt_experiments/` and `uq_experiments/`)."
 )
 
-# Read selected method from query params
-abbr = st.query_params.get("method")
-if not isinstance(abbr, str):
-    abbr = None
-
-metric_store = load_metric_store()
-if metric_store.empty:
-    st.warning("No metric data found. Expected NetCDF files in `data/` with a `metric` variable.")
-    st.stop()
-
-methods_df = metric_store[["Method", "abbreviation"]].drop_duplicates().sort_values("abbreviation")
-
-abbrs = methods_df["abbreviation"].tolist()
-
-# Metadata dictionary (can be moved to a JSON/YAML later)
+# Per-method metadata (can be moved to a JSON/YAML later). Every entry below was read
+# directly out of CalibrationLeaderboard.jl (opt_experiments/, uq_experiments/) and, for the
+# EKP-based processes, out of EnsembleKalmanProcesses.jl itself. `params` intentionally
+# excludes ensemble size and max-iteration count (covered by the leaderboard charts) and
+# instead lists the update-specific hyperparameters.
 method_meta = {
     "TEKI": {
         "citation": "Chada et al., SIAM/ASA J. UQ, 2020",
         "url": "https://doi.org/10.1137/17M114402X",
-        "summary": "EKI variant with Tikhonov regularization that adds a penalty term to prevent ensemble collapse and improve stability on nonlinear problems.",
+        "source": "`opt_experiments/ensemble_kalman_processes` — EnsembleKalmanProcesses.jl `Inversion(prior)`.",
+        "math": (
+            "Ensemble Kalman Inversion (Schillings & Stuart, 2017, eqns. 4-5): each iteration moves every "
+            "ensemble member by the same linear, empirical-covariance-based correction toward the data,"
+        ),
+        "math_eq": r"u_{n+1} = u_n + C^{ug}\left(C^{gg}+\Gamma\right)^{-1}\left(y - g(u_n)\right)",
+        "guardrails": (
+            "Tikhonov-style regularization is obtained by extending the state: the forward map is "
+            "augmented as `g ↦ [g; u]` and the data as `y ↦ [y; prior_mean]` with observation covariance "
+            "`blockdiag(Γ, prior_cov)`, so every step also pulls the ensemble back toward the prior "
+            "(`impose_prior=true`). A small `default_multiplicative_inflation` (1e-3) regularizes the "
+            "empirical covariance before it is inverted; `NoLocalization()` applies no covariance tapering; "
+            "`DefaultScheduler()` takes a fixed unit pseudo-time step each iteration."
+        ),
+        "params": [
+            {"Parameter": "impose_prior", "Value": "true (Tikhonov-style state extension)"},
+            {"Parameter": "default_multiplicative_inflation", "Value": "1e-3"},
+            {"Parameter": "localization", "Value": "NoLocalization()"},
+            {"Parameter": "scheduler", "Value": "DefaultScheduler() — fixed unit step"},
+        ],
+        "notes": "Runs until the whitened RMSE falls below the target or `N_iter` is exhausted; no reported pathology on this benchmark beyond the usual small-ensemble sampling error of stochastic EKI.",
     },
     "ETKI": {
         "citation": "Schillings & Stuart, Numer. Math., 2017",
         "url": "https://clima.github.io/EnsembleKalmanProcesses.jl/dev/",
-        "summary": "Ensemble Transform Kalman Inversion — applies an ensemble-space transform update that preserves the ensemble mean while reducing variance inflation.",
+        "source": "`opt_experiments/ensemble_kalman_processes` — EnsembleKalmanProcesses.jl `TransformInversion(prior)`.",
+        "math": (
+            "Ensemble Transform Kalman Inversion applies the update in ensemble-anomaly space instead of "
+            "perturbing observations: normalized anomalies `X=(u-ū)/√(m-1)` and `Y=(g_ext-ḡ_ext)/√(m-1)` are "
+            "formed (with the same prior extension as TEKI), and a transform matrix built from `Y'Γ⁻¹Y` maps "
+            "the prior ensemble anomalies onto posterior anomalies, `u ← ū + X·T`."
+        ),
+        "guardrails": (
+            "Same Tikhonov-style prior extension and `impose_prior=true` as TEKI; diagonal regularization "
+            "stabilizes the anomaly Gram matrix before it is inverted; `NoLocalization()`; the transform "
+            "update removes the perturbed-observation sampling noise present in stochastic EKI, which "
+            "generally lowers ensemble-collapse risk at small ensemble sizes."
+        ),
+        "params": [
+            {"Parameter": "impose_prior", "Value": "true (Tikhonov-style state extension)"},
+            {"Parameter": "localization", "Value": "NoLocalization()"},
+            {"Parameter": "scheduler", "Value": "DefaultScheduler() — fixed unit step"},
+        ],
+        "notes": "Same run-until-RMSE-target harness as TEKI; the transform (square-root) update trades stochastic sampling noise for a deterministic ensemble-anomaly map.",
     },
     "IEKF": {
         "citation": "Iglesias, Inverse Problems, 2016",
         "url": "https://doi.org/10.1088/0266-5611/32/2/025002",
-        "summary": "Regularizing iterative ensemble Kalman method; repeatedly refines the ensemble around a regularized Gauss-Newton step for nonlinear inverse problems.",
+        "source": "`uq_experiments/GaussNewtonKalmanInversion` — EnsembleKalmanProcesses.jl `GaussNewtonInversion(prior)` (alias GNKI); Chada, Chen & Sanz-Alonso, 2021, Algorithm 4.1.",
+        "math": (
+            "Iterated Ensemble Kalman Filter with statistical linearization: each pseudo-time step `Δt` "
+            "relaxes the ensemble between its current position and a linearized Gauss-Newton solve of the "
+            "joint parameter/output covariance, evaluated against a fresh perturbed draw around the prior "
+            "mean rather than the ensemble's own mean — a Gauss-Newton normal-equation solve carried out "
+            "entirely in empirical-covariance space, without ever forming the model Jacobian explicitly."
+        ),
+        "guardrails": (
+            "`perturbation_scale = 2/Δt - 1` rescales the prior-draw noise so the relaxation step's "
+            "stationary covariance equals the true posterior for every `Δt ∈ (0,1]`, not just `Δt=1`; "
+            "diagonal regularization + `NoLocalization()` stabilize the joint covariance solve; the pseudo-"
+            "step is fixed rather than adaptive (`DefaultScheduler(0.1)`, i.e. `Δt=0.1`)."
+        ),
+        "params": [
+            {"Parameter": "pseudo-step Δt", "Value": "0.1 (DefaultScheduler(0.1))"},
+            {"Parameter": "perturbation_scale", "Value": "2/Δt - 1 = 19"},
+            {"Parameter": "localization", "Value": "NoLocalization()"},
+        ],
+        "notes": "An iterative Gauss-Newton procedure, so — like other Newton-type ensemble methods — it can be sensitive to ensemble size at small N_ens; only the first `max_iter` (10 on L63, 15 on L96) of the `N_iter=20` allowed steps are scored.",
     },
     "UKI": {
         "citation": "Huang, Huang & Stuart, Physica D, 2022",
         "url": "https://clima.github.io/EnsembleKalmanProcesses.jl/dev/",
-        "summary": "Unscented Kalman Inversion — propagates a deterministic set of sigma points through the forward model to estimate mean and covariance without linearization.",
+        "source": "`opt_experiments/ensemble_kalman_processes` — EnsembleKalmanProcesses.jl `Unscented(prior; impose_prior=true)`.",
+        "math": (
+            "Unscented Kalman Inversion propagates `2·N_par + 1` deterministic sigma points (the symmetric "
+            "unscented transform) through the forward model instead of a random ensemble, forms their "
+            "weighted mean/covariance, and performs the same Kalman-style analysis step as TEKI on this "
+            "reduced sigma-point set."
+        ),
+        "guardrails": (
+            "`α_reg ∈ (0,1]` shrinks the analysis mean toward the prior mean each step, guarding against "
+            "covariance collapse; `impose_prior=true` adds the same TEKI-style `y_ext`/`Γ_ext` extension; "
+            "the symmetric sigma-point scheme (`2·N_par+1` points) is used by default rather than the "
+            "cheaper simplex scheme."
+        ),
+        "params": [
+            {"Parameter": "α_reg", "Value": "1.0 (regularization toward prior mean disabled by default)"},
+            {"Parameter": "sigma_points", "Value": '"symmetric" (2·N_par+1 points)'},
+            {"Parameter": "impose_prior", "Value": "true"},
+        ],
+        "notes": "Sigma-point count is fixed by the parameter dimension, not swept as an ensemble size — UKI's per-iteration cost is dimension-driven rather than N_ens-driven.",
     },
     "ABC": {
-        "citation": "Approximate Bayesian Calibration",
-        "url": "https://example.com/abc",
-        "summary": "Sample without exact likelihoods until error falls below a target convergence.",
+        "citation": "Csilléry et al., Trends in Ecology & Evolution, 2010",
+        "url": "https://doi.org/10.1016/j.tree.2010.04.001",
+        "source": "`uq_experiments/approximate_bayesian_computation` — simulation-based rejection sampling (no EKP, no surrogate).",
+        "math": (
+            "Each round draws `N_ens` i.i.d. prior candidates `θ ~ π(θ)`, evaluates the true forward model "
+            "`G(θ)`, and accepts a candidate iff its whitened misfit falls inside a chi-squared acceptance "
+            "region; accepted candidates across all rounds approximate draws from the ABC posterior."
+        ),
+        "math_eq": r"\left(G(\theta)-y\right)^{\top}(2R)^{-1}\left(G(\theta)-y\right) \le \chi^2_{n_y}(1-\alpha_{\text{reject}})",
+        "guardrails": (
+            "The acceptance threshold is set exactly to the `(1-alpha_reject)` quantile of `χ²(n_y)` rather "
+            "than hand-tuned; the final pushforward resamples `n_pushforward_samples=1000` draws from a "
+            "Gaussian fit to the accepted pool, smoothing a possibly sparse accepted set into a usable "
+            "posterior approximation; batch sizes are deliberately matched to IEKF's `N_ens_sizes`/`max_iter` "
+            "so the N_ens×k budget axis is directly comparable across methods on the leaderboard."
+        ),
+        "params": [
+            {"Parameter": "alpha_reject", "Value": "0.05"},
+            {"Parameter": "n_pushforward_samples", "Value": "1000"},
+        ],
+        "notes": "Acceptance rate collapses quickly in higher dimensions (the same \"curse of dimensionality\" documented for HM below); there is no adaptive tightening of the acceptance region as rounds proceed, so all cost-efficiency comes from the batch-size choice.",
     },
     "HM": {
         "citation": "Williamson et al. 2013; King et al. 2025",
         "url": "https://example.com/hm",
-        "summary": "Iterative constraint of parameter space using wave reductions.",
+        "source": "`uq_experiments/HistoryMatching` — custom (non-EKP) wave/rejection scheme.",
+        "math": (
+            "History Matching runs a series of waves. At wave k, an independent GP emulator is fit per "
+            "whitened output mode on every parameter evaluated so far; a candidate survives the wave iff "
+            "its implausibility (whitened, GP-predicted misfit) is below a chi-squared threshold, and the "
+            "surviving (\"Not Ruled Out Yet\", NROY) region is intersected across all waves run so far."
+        ),
+        "math_eq": r"I^2(\theta) = \sum_j \frac{\left(\mu_j(\theta)-y_j\right)^2}{1+\sigma_j^2(\theta)} < \chi^2_{k_R}(0.95)",
+        "guardrails": (
+            "GP emulators use an automatic-relevance-determination squared-exponential kernel (`SEArd`), "
+            "refit every wave via `GaussianProcesses.optimize!`; NROY testing exploits monotonicity — a "
+            "candidate ruled out by an earlier wave is never re-tested by later waves — cutting GP-predict "
+            "cost from O(waves×batch) to O(surviving candidates); a Poisson/Garwood upper-confidence-bound "
+            "rule (`poisson_rate_upper_bound`, `early_stop_alpha=1e-6`) aborts a rejection-sampling sweep "
+            "early once even its best-case acceptance rate can no longer plausibly reach the wanted sample "
+            "count within the remaining budget, rather than burning the full `max_samples` budget on a "
+            "doomed sweep; inputs/outputs are PCA-whitened (`retain_var_input`/`retain_var`) before fitting."
+        ),
+        "params": [
+            {"Parameter": "confidence (implausibility threshold)", "Value": "0.95 → quantile(Chisq(k_R), 0.95)"},
+            {"Parameter": "n_candidate_batch", "Value": "2000 per wave"},
+            {"Parameter": "retain_var (output PCA)", "Value": "0.99"},
+            {"Parameter": "retain_var_input (input PCA)", "Value": "0.9"},
+            {"Parameter": "early_stop_alpha", "Value": "1e-6"},
+        ],
+        "notes": "Acceptance rate collapses toward zero after a couple of waves on higher-dimensional problems (the repo's own documented \"curse of dimensionality\"); the early-stop rule only changes how quickly a doomed sweep gives up, not the eventual pass/fail outcome.",
     },
     "CES-EKI-DMC": {
         "citation": "Cleary et al., J. Comput. Phys., 2021",
         "url": "https://doi.org/10.1016/j.jcp.2020.109716",
-        "summary": "Calibrate-Emulate-Sample: uses EKI with a DataMisfitController to select training points, builds a GP emulator of the forward model, then samples the posterior via MCMC.",
+        "source": "`uq_experiments/calibrate_emulate_sample` — Calibrate-Emulate-Sample, calibrate stage: `Inversion()` + `DataMisfitController`.",
+        "math": (
+            "Three-stage Calibrate-Emulate-Sample. Calibrate: run EKI to generate an ensemble of "
+            "`(θ, G(θ))` training pairs. Emulate: fit a random-feature surrogate `Ĝ(θ)` on those pairs. "
+            "Sample: draw from `π(θ|y) ∝ exp(-½‖y-Ĝ(θ)‖²_Γ)·π(θ)` against the cheap surrogate using "
+            "preconditioned Crank-Nicolson Metropolis-Hastings (pCN-MH), rather than the true forward model."
+        ),
+        "guardrails": (
+            "Calibrate stage uses an adaptive `DataMisfitController(terminate_at=2.0)` schedule so the EKI "
+            "pseudo-time step grows automatically and training points concentrate near the posterior, "
+            "rather than requiring a hand-tuned fixed schedule (`terminate_at=2.0` approximates the "
+            "finite-time posterior); emulate stage keeps 99% of variance in a likelihood-informed PCA "
+            "encoding before fitting the `ScalarRandomFeatureInterface`; sample stage auto-tunes the pCN "
+            "step size (`optimize_stepsize`, 2,000-sample dry run from `init_stepsize=0.2`) before the full "
+            "100,000-sample chain with a 2,000-sample burn-in."
+        ),
+        "params": [
+            {"Parameter": "scheduler (calibrate)", "Value": "DataMisfitController(terminate_at=2.0)"},
+            {"Parameter": "retain_var (emulate PCA)", "Value": "0.99"},
+            {"Parameter": "n_features / n_features_opt", "Value": "100/60 (L63), 200/160 (L96 variants)"},
+            {"Parameter": "MCMC samples / burn-in", "Value": "100,000 / 2,000 (pCN-MH)"},
+            {"Parameter": "init_stepsize", "Value": "0.2 (auto-tuned before the full chain)"},
+        ],
+        "notes": "The emulator is fit only once, after calibration finishes (\"after-optimize\"), so sampled-posterior quality depends entirely on how well the calibrate-stage ensemble has already covered the posterior region.",
     },
     "CES-EKI-CONST": {
         "citation": "Cleary et al., J. Comput. Phys., 2021",
         "url": "https://doi.org/10.1016/j.jcp.2020.109716",
-        "summary": "Calibrate-Emulate-Sample: uses EKI with a constant (fixed) timestep scheduler to select training points, builds a GP emulator of the forward model, then samples the posterior via MCMC.",
+        "source": "`uq_experiments/calibrate_emulate_sample` — Calibrate-Emulate-Sample, calibrate stage: `Inversion()` + fixed-step scheduler.",
+        "math": "Identical Calibrate-Emulate-Sample pipeline to CES-EKI-DMC (see that entry for the emulate/sample math).",
+        "guardrails": (
+            "Calibrate stage uses a fixed-step `DefaultScheduler(0.1)` instead of the adaptive "
+            "`DataMisfitController`, trading adaptivity for a simpler, more predictable schedule; emulate "
+            "and sample stages are unchanged from CES-EKI-DMC (same PCA retention, feature counts, and "
+            "MCMC step-size tuning)."
+        ),
+        "params": [
+            {"Parameter": "scheduler (calibrate)", "Value": "DefaultScheduler(0.1) — fixed step"},
+            {"Parameter": "retain_var (emulate PCA)", "Value": "0.99"},
+            {"Parameter": "n_features / n_features_opt", "Value": "100/60 (L63), 200/160 (L96 variants)"},
+            {"Parameter": "MCMC samples / burn-in", "Value": "100,000 / 2,000 (pCN-MH)"},
+        ],
+        "notes": "Same after-optimize emulator caveat as CES-EKI-DMC; the fixed step trades the DMC variant's adaptive posterior-concentration for predictability.",
     },
     "CES-IEKF-CONST": {
         "citation": "Cleary et al., J. Comput. Phys., 2021; Iglesias, Inverse Problems, 2016",
         "url": "https://doi.org/10.1016/j.jcp.2020.109716",
-        "summary": "Calibrate-Emulate-Sample: uses IEKF with a constant (fixed) timestep scheduler to select training points, builds a GP emulator of the forward model, then samples the posterior via MCMC.",
+        "source": "`uq_experiments/calibrate_emulate_sample` — Calibrate-Emulate-Sample, calibrate stage: `GaussNewtonInversion(prior)` + fixed-step scheduler.",
+        "math": "Identical Calibrate-Emulate-Sample pipeline to CES-EKI-DMC, but the calibrate stage runs the IEKF/GNKI Gauss-Newton update (see the IEKF entry) instead of plain EKI.",
+        "guardrails": (
+            "Calibrate stage uses `GaussNewtonInversion(prior)` with a fixed pseudo-step `DefaultScheduler(0.1)`; "
+            "emulate and sample stages are unchanged from CES-EKI-DMC (same PCA retention, feature counts, "
+            "and MCMC step-size tuning)."
+        ),
+        "params": [
+            {"Parameter": "scheduler (calibrate)", "Value": "DefaultScheduler(0.1) — fixed pseudo-step"},
+            {"Parameter": "retain_var (emulate PCA)", "Value": "0.99"},
+            {"Parameter": "n_features / n_features_opt", "Value": "100/60 (L63), 200/160 (L96 variants)"},
+            {"Parameter": "MCMC samples / burn-in", "Value": "100,000 / 2,000 (pCN-MH)"},
+        ],
+        "notes": "Same after-optimize emulator caveat as CES-EKI-DMC, with the Gauss-Newton calibrate step's usual small-ensemble sensitivity (see IEKF).",
     },
     "ADAM": {
         "citation": "Kingma & Ba, ICLR, 2015",
         "url": "https://doi.org/10.48550/arXiv.1412.6980",
-        "summary": "Adaptive Moment Estimation — gradient-based optimizer that adapts per-parameter learning rates using first and second moment estimates of the gradient.",
+        "source": "`opt_experiments/adam` — custom (non-Flux) Adam implementation.",
+        "math": (
+            "Adam gradient descent on the whitened least-squares loss `L(θ)=½‖R^{-1/2}(y-G(θ))‖²`: "
+            "first/second raw-gradient moments `m_t=β₁m_{t-1}+(1-β₁)g_t`, `v_t=β₂v_{t-1}+(1-β₂)g_t²` are "
+            "bias-corrected to `m̂_t, v̂_t` and applied as `θ_{t+1}=θ_t - α·m̂_t/(√v̂_t+ε)`. The gradient "
+            "`g_t` comes from a whitened Jacobian obtained via `ForwardDiff.jl` forward-mode automatic "
+            "differentiation through the Lorenz solver itself — not a surrogate."
+        ),
+        "guardrails": (
+            "`N_ens` initial-condition perturbations are drawn and averaged into the gradient at every step "
+            "to reduce gradient noise from the chaotic forward model (`N_ens=1` here, i.e. a single-sample "
+            "stochastic gradient); beyond Adam's own adaptive per-parameter step scaling there is no line "
+            "search, trust region, or restart mechanism."
+        ),
+        "params": [
+            {"Parameter": "α (step size)", "Value": "0.001"},
+            {"Parameter": "β₁, β₂", "Value": "0.9, 0.999"},
+            {"Parameter": "ε", "Value": "1e-8"},
+            {"Parameter": "N_ens (IC perturbations)", "Value": "1"},
+        ],
+        "notes": "**Empirically gets stuck in local minima close to the initial parameter draw, regardless of step size** — observed running this benchmark. Consistent with Adam having no mechanism (trust region, restart, ensemble diversity) to escape a bad basin once its gradient estimate vanishes there.",
     },
     "LM": {
         "citation": "Levenberg, 1944; Marquardt, 1963; Fletcher, 1971",
         "url": "https://doi.org/10.1090/qam/10666",
-        "summary": "Levenberg-Marquardt — damped least-squares algorithm that interpolates between gradient descent and Gauss-Newton steps for efficient nonlinear least-squares minimization.",
+        "source": "`opt_experiments/levenberg_marquardt` — custom Levenberg-Marquardt implementation.",
+        "math": (
+            "Damped Gauss-Newton: each step solves the damped normal equations for the parameter update "
+            "`Δθ`, using a whitened Jacobian/residual `(J̃, r̃)` obtained via `ForwardDiff.jl`, then accepts "
+            "the step only if the reduction ratio `ρ` (actual vs. predicted misfit decrease) is favorable."
+        ),
+        "math_eq": r"\left(\tilde J^{\top}\tilde J + \lambda\,\mathrm{diag}(d)\right)\Delta\theta = \tilde J^{\top}\tilde r",
+        "guardrails": (
+            "Damping `λ` adapts every step: ×4 (capped at `λ_max`) on a rejected or non-finite step "
+            "(`ρ<0.25` or NaN), ÷3 (floored at `λ_min`) on an accepted step (`ρ>0.75`), interpolating between "
+            "gradient descent (large λ) and Gauss-Newton (small λ); a non-finite `Δθ` is handled gracefully "
+            "(`ρ=NaN → !isfinite(ρ) → λ↑`) rather than crashing the run."
+        ),
+        "params": [
+            {"Parameter": "λ₀ (initial damping)", "Value": "1.0"},
+            {"Parameter": "λ growth / shrink factor", "Value": "×4 (reject) / ÷3 (accept)"},
+            {"Parameter": "λ bounds", "Value": "[1e-10, 1e8]"},
+            {"Parameter": "N_ens (IC perturbations)", "Value": "1"},
+        ],
+        "notes": "**Empirically also gets stuck in local minima near the initial condition, regardless of the damping schedule** — the same failure mode as ADAM, unsurprising for any single-trajectory local optimizer on this multimodal, chaotic-dynamics calibration surface.",
     },
     "GBOED": {
         "citation": "Holthuijzen et al. 2026",
         "url": "https://arxiv.org/abs/2508.13071",
-        "summary": "Goal-oriented Bayesian Optimal Experimental Design — selects each batch of forward-model evaluations by maximizing an expected-information-gain criterion targeted at the quantity of interest, refitting the surrogate used by the criterion at every iteration.",
+        "source": "`uq_experiments/BayesianOptimalExperimentalDesign` — Goal-oriented BOED, Algorithm 2 of Holthuijzen et al. 2026.",
+        "math": (
+            "Each iteration: (i) fits a GP surrogate per output dimension to all `(θ, G(θ))` collected so "
+            "far, (ii) draws posterior samples from the current surrogate-based posterior via Transitional/"
+            "Sequential MCMC (Ching & Chen, 2007), (iii) selects the next batch of forward-model evaluations "
+            "by maximizing a closed-form Expected Information Gain (EIG) criterion targeted at the quantity "
+            "of interest, using the GP's predictive covariance."
+        ),
+        "math_eq": r"\mathrm{EIG}(X) = \frac{1}{k}\sum_j \frac{1}{2}\log\frac{\det K_{pp}^{(j)}}{\det \Sigma'^{(j)}}, \quad \Sigma'^{(j)} = K_{pp}^{(j)} - K_{pc}^{(j)}\left(K_{cc}^{(j)}\right)^{-1}K_{cp}^{(j)}",
+        "guardrails": (
+            "Candidate batches are optimized with `Optim.jl`'s `Fminbox(LBFGS())` under box constraints, "
+            "with a hard cap on raw EIG evaluations (`eig_call_limit`) and an outer-iteration cap "
+            "(`eig_outer_iters`) enforced manually — since Optim's own call limits don't cumulate across "
+            "Fminbox's outer barrier rounds — logging a warning that the returned point may be "
+            "\"under-optimized\" if either cap is hit, rather than failing silently; a diagonal jitter "
+            "(`eig_jitter`, relative to the GP signal variance) stabilizes the covariance solves/log-"
+            "determinants; batch points can be chosen greedily, jointly, or via a hybrid strategy that "
+            "switches from greedy to joint optimization once a greedy step's cost exceeds a threshold."
+        ),
+        "params": [
+            {"Parameter": "eig_call_limit", "Value": "2000 EIG evaluations"},
+            {"Parameter": "eig_outer_iters", "Value": "20"},
+            {"Parameter": "eig_jitter", "Value": "1e-6 × GP signal variance"},
+            {"Parameter": "batch_init_strategy", "Value": ":posterior_subsample"},
+        ],
+        "notes": "**Empirically, the inner EIG-maximization loop over candidate batches is a frequent source of problems (hitting the call-limit / outer-iteration guardrails, i.e. \"under-optimized\" batches), and every iteration slows down as the cumulative GP training set grows** (GP fit/predict cost scales super-linearly in training-set size) — this is also why the repo's own config drops to a smaller `max_iters` on the higher-dimensional L96 cases (\"it's so slow, so let's start here\").",
     },
     "LM-KGMM": {
         "citation": "Giorgini, Bischoff & Souza, arXiv:2503.18054, 2025",
         "url": "https://arxiv.org/abs/2503.18054",
-        "summary": "Score-based Levenberg-Marquardt using a K-means Gaussian Mixture Model to estimate the score function, which drives the gradient via the generalized fluctuation-dissipation theorem (GFDT).",
+        "source": "`opt_experiments/score_based_lm` — Levenberg-Marquardt with a GFDT/KGMM Jacobian surrogate.",
+        "math": (
+            "Same LM step as above, but the Jacobian is not differentiated through the solver — it is "
+            "estimated from trajectory data via the generalized fluctuation-dissipation theorem (GFDT): the "
+            "response of a fitted statistic `A(x)` to a parameter perturbation is approximated by a lag-"
+            "integrated, Tukey-tapered correlation with a \"conjugate\" variable `B(x)` built from the score "
+            "function `s(x)=∇log p(x)`, then chained through `dφ/dm` to the summary-statistic Jacobian."
+        ),
+        "math_eq": r"\frac{d\,\mathbb{E}[A]}{d\theta} \approx \int_0^{\tau_{\max}} \left\langle A(x_{t+\tau})\,B(x_t)\right\rangle\, w(\tau)\, d\tau",
+        "guardrails": (
+            "The score `s(x)` is estimated with a k-means Gaussian-mixture score estimator (KGMM): the "
+            "trajectory is clustered into components whose mixture has a closed-form score. "
+            "`stein_recalibrate` rescales the estimated score so `-E[x·s(x)ᵀ]=I` holds on the calibration "
+            "ensemble (a built-in consistency check/correction); `kgmm_ridge` shrinks per-cluster "
+            "covariances toward the global covariance to avoid singular clusters; `is_collapsed_window` "
+            "(minimum trajectory variance below a tolerance) detects windows that have collapsed onto a "
+            "fixed point — GFDT is undefined there, since there is no invariant measure to differentiate — "
+            "and falls back to a direct `ForwardDiff.jl` Jacobian on those draws; total cost is capped at "
+            "`outer_iter × N_ens ≤ budget_total` per cell, trading ensemble size against iteration count "
+            "under a fixed evaluation budget."
+        ),
+        "params": [
+            {"Parameter": "kgmm_ridge", "Value": "0.1"},
+            {"Parameter": "tukey_alpha (response taper)", "Value": "0.75"},
+            {"Parameter": "budget_total (outer_iter × N_ens)", "Value": "500"},
+            {"Parameter": "collapse tolerance (min variance)", "Value": "1e-2"},
+        ],
+        "notes": "**Much quicker to apply than LM-DSM** — fitting a k-means/Gaussian-mixture score is far cheaper than training a neural score network, so LM-KGMM stayed tractable on problems where LM-DSM's training cost made it impractical.",
     },
     "LM-DSM": {
         "citation": "Giorgini, Bischoff & Souza, arXiv:2509.19660, 2025",
         "url": "https://arxiv.org/abs/2509.19660",
-        "summary": "Score-based Levenberg-Marquardt using Denoising Score Matching to estimate the score function, which drives the gradient via the generalized fluctuation-dissipation theorem (GFDT).",
+        "source": "`opt_experiments/score_based_lm` — Levenberg-Marquardt with a GFDT/DSM Jacobian surrogate.",
+        "math": "Identical LM + GFDT scheme as LM-KGMM (see that entry's update equation), but the score `s(x)=∇log p(x)` is estimated by Denoising Score Matching (DSM) instead of KGMM.",
+        "guardrails": (
+            "A neural network is trained to denoise samples perturbed by Gaussian noise at a single fixed "
+            "scale `σ`; its optimal denoiser equals the noised density's score (Vincent, 2011), and as "
+            "`σ→0` this recovers the true score at the cost of a harder training problem. `σ` is fixed per "
+            "benchmark rather than annealed, chosen empirically as the smallest noise level at which the "
+            "network still receives a usable learning signal. Same Stein recalibration and collapsed-window "
+            "`ForwardDiff.jl` fallback as LM-KGMM; same Tukey-tapered response integral and evaluation-"
+            "budget cap."
+        ),
+        "params": [
+            {"Parameter": "σ (DSM noise scale)", "Value": "0.2 (L63) / 0.025 (L96 variants)"},
+            {"Parameter": "tukey_alpha (response taper)", "Value": "0.75"},
+            {"Parameter": "budget_total (outer_iter × N_ens)", "Value": "500"},
+            {"Parameter": "collapse tolerance (min variance)", "Value": "1e-2"},
+        ],
+        "notes": "**Training the DSM score network is very slow, even on moderately sized problems** — a 5-iteration smoke test on the higher-dimensional L96 forcing variants took ~39 minutes, extrapolating to several hours for a full run, and higher-dimensional experiments were killed after ~24h without finishing a sweep. Wall-clock cost, not accuracy, was the binding constraint on scaling LM-DSM to larger problems.",
     },
 }
 
+# KNOWN_METHODS is the source of truth for the abbreviation/full-name list,
+# so this page renders even without any NetCDF data loaded.
+abbrs = sorted(meta["abbreviation"] for meta in KNOWN_METHODS.values())
+full_name_by_abbr = {meta["abbreviation"]: meta["Method"] for meta in KNOWN_METHODS.values()}
+
 # Selection UI (defaults to query param if valid)
-default_idx = 0
-if isinstance(abbr, str) and abbr in abbrs:
-    default_idx = abbrs.index(abbr)
+abbr = st.query_params.get("method")
+default_idx = abbrs.index(abbr) if isinstance(abbr, str) and abbr in abbrs else 0
 sel = str(st.selectbox("Choose a method", options=abbrs, index=default_idx))
 
 # Persist selection to URL
 st.query_params["method"] = sel
 
 # Display details
-row = methods_df.loc[methods_df["abbreviation"] == sel].iloc[0]
 meta = method_meta.get(sel, {})
 
-st.subheader(f"{sel} — {row['Method']}")
+st.subheader(f"{sel} — {full_name_by_abbr.get(sel, '')}")
+if meta.get("source"):
+    st.caption(meta["source"])
+
+st.markdown("**Update Equation**")
+st.markdown(meta.get("math", "Mathematical form pending"))
+if meta.get("math_eq"):
+    st.latex(meta["math_eq"])
+
+st.markdown("**Robustness, Speed & Guardrails**")
+st.markdown(meta.get("guardrails", "Guardrail details pending"))
+
+st.markdown("**Configuration Parameters**")
+params = meta.get("params")
+if params:
+    st.dataframe(pd.DataFrame(params), hide_index=True, use_container_width=True)
+else:
+    st.write("Parameter details pending")
 
-col1, col2, col3 = st.columns(3)
+st.markdown("**Convergence & Speed Notes**")
+st.markdown(meta.get("notes", "No notes recorded yet"))
+
+col1, col2 = st.columns(2)
 with col1:
     with st.container(border=True):
         st.markdown("**Citation**")
@@ -139,96 +437,5 @@ with col2:
     with st.container(border=True):
         st.markdown("**Link**")
         st.link_button("Open reference", meta.get("url", "https://example.com"))
-with col3:
-    with st.container(border=True):
-        st.markdown("**Summary**")
-        st.write(meta.get("summary", "Summary pending"))
-
-st.markdown("**Benchmark Slice**")
-slice_df = metric_store[metric_store["abbreviation"] == sel].copy()
-slice_df = slice_df.sort_values(["benchmark", "rmse_target", "ensemble_size"])
-
-target_options = sorted(slice_df["rmse_target"].astype(str).unique().tolist())
-selected_target = st.radio("RMSE Target Level", options=target_options, horizontal=True)
-
-best_table_view = slice_df[slice_df["rmse_target"].astype(str) == selected_target]
-
-best_idx = best_table_view.groupby("benchmark")["metric"].idxmin()
-best_ensemble_df = best_table_view.loc[best_idx, ["benchmark", "rmse_target", "ensemble_size", "metric", "failure_rate"]].rename(
-    columns={"metric": "Mean Forward Model Runs", "failure_rate": "Failure Rate (%)", "ensemble_size": "Optimal Ensemble Size", "rmse_target": "RMSE Target"}
-)
-st.dataframe(best_ensemble_df, hide_index=True, use_container_width=True)
-
-if sel == "HM":
-    st.markdown("### Failure Analysis")
-    st.write(f"Failed calibration rate for History Matching at RMSE Target {selected_target} (as % of random seeds).")
-    
-    chart = (
-        alt.Chart(best_table_view)
-        .mark_bar()
-        .encode(
-            x=alt.X("ensemble_size:O", title="Ensemble Size"),
-            y=alt.Y("mean(failure_rate):Q", title="Failure Rate (%)", scale=alt.Scale(domain=[0, 100])),
-            color="benchmark:N",
-            tooltip=["benchmark", "ensemble_size", alt.Tooltip("mean(failure_rate):Q", format=".1f", title="Failure Rate (%)")]
-        )
-        .properties(height=350)
-        .interactive()
-    )
-    st.altair_chart(chart, use_container_width=True)
-best_by_benchmark = (
-    best_table_view.loc[best_idx, ["benchmark", "metric", "ensemble_size"]]
-    .rename(
-        columns={
-            "metric": "Best Mean Forward Model Runs",
-            "ensemble_size": "Optimal Ensemble Size",
-        }
-    )
-    .sort_values("benchmark")
-)
-
-st.markdown("**Best by Benchmark**")
-st.dataframe(
-    best_by_benchmark,
-    hide_index=True,
-    use_container_width=True,
-    column_config={
-        "benchmark": st.column_config.TextColumn("Benchmark"),
-        "Best Mean Forward Model Runs": st.column_config.NumberColumn("Best Mean Forward Model Runs", format="%.4f"),
-        "Optimal Ensemble Size": st.column_config.NumberColumn("Optimal Ensemble Size"),
-    },
-)
-
-st.markdown("**Scaling by Benchmark**")
-chart_view = slice_df[slice_df["rmse_target"].astype(str) == selected_target]
-chart_df = (
-    chart_view.groupby(["benchmark", "ensemble_size"], as_index=False)
-    .agg(mean_forward_runs=("metric", "mean"))
-)
-chart = (
-    alt.Chart(chart_df)
-    .mark_line(point=True)
-    .encode(
-        x=alt.X("ensemble_size:Q", title="Ensemble Size"),
-        y=alt.Y("mean_forward_runs:Q", title="Mean Forward Model Runs"),
-        color=alt.Color("benchmark:N", title="Benchmark"),
-        tooltip=["benchmark", "ensemble_size", alt.Tooltip("mean_forward_runs:Q", format=".4f")],
-    )
-)
-st.altair_chart(chart, use_container_width=True)
-
-st.markdown("**All Averaged Configurations for Method**")
-st.dataframe(
-    slice_df[["benchmark", "algorithm_alias", "rmse_target", "ensemble_size", "metric"]],
-    hide_index=True,
-    use_container_width=True,
-    column_config={
-        "benchmark": st.column_config.TextColumn("Benchmark"),
-        "algorithm_alias": st.column_config.TextColumn("Source Alias"),
-        "rmse_target": st.column_config.TextColumn("RMSE Target"),
-        "ensemble_size": st.column_config.NumberColumn("Ensemble Size"),
-        "metric": st.column_config.NumberColumn("Mean Forward Model Runs", format="%.4f"),
-    },
-)
 
 st.page_link("pages/OptimizationLeaderboard.py", label="⬅ Back to Optimization Leaderboard", icon="↩️")

src/pages/OptimizationLeaderboard.py

@@ -18,7 +18,7 @@ st.sidebar.title("Navigation")
 st.sidebar.page_link("streamlit_app.py", label="Home", icon="🏠")
 st.sidebar.page_link("pages/OptimizationLeaderboard.py", label="Optimization Leaderboard", icon="📊")
 st.sidebar.page_link("pages/UQLeaderboard.py", label="UQ Leaderboard", icon="🎯")
-st.sidebar.page_link("pages/MethodDetails.py", label="Methods", icon="📘")
+st.sidebar.page_link("pages/MethodDetails.py", label="Method configurations", icon="📘")
 st.sidebar.page_link("pages/RawData.py", label="Get Data", icon="🧾")
 
 st.markdown(r"**Optimization target.** A run succeeds when the normalized weighted distance from the ensemble-mean forward-model output to the true data falls at or below the (selected in the target controls) RMSE target level $\tau$:")

src/pages/RawData.py

@@ -16,7 +16,7 @@ st.sidebar.title("Navigation")
 st.sidebar.page_link("streamlit_app.py", label="Home", icon="🏠")
 st.sidebar.page_link("pages/OptimizationLeaderboard.py", label="Optimization Leaderboard", icon="📊")
 st.sidebar.page_link("pages/UQLeaderboard.py", label="UQ Leaderboard", icon="🎯")
-st.sidebar.page_link("pages/MethodDetails.py", label="Methods", icon="📘")
+st.sidebar.page_link("pages/MethodDetails.py", label="Method configurations", icon="📘")
 st.sidebar.page_link("pages/RawData.py", label="Get Data", icon="🧾")
 
 st.title("Raw Averaged Forward Model Runs")

src/pages/UQLeaderboard.py

@@ -18,7 +18,7 @@ st.sidebar.title("Navigation")
 st.sidebar.page_link("streamlit_app.py", label="Home", icon="🏠")
 st.sidebar.page_link("pages/OptimizationLeaderboard.py", label="Optimization Leaderboard", icon="📊")
 st.sidebar.page_link("pages/UQLeaderboard.py", label="UQ Leaderboard", icon="🎯")
-st.sidebar.page_link("pages/MethodDetails.py", label="Methods", icon="📘")
+st.sidebar.page_link("pages/MethodDetails.py", label="Method configurations", icon="📘")
 st.sidebar.page_link("pages/RawData.py", label="Get Data", icon="🧾")
 
 st.markdown(r"**UQ target.** Marginal coverage, $\widetilde{S}(q)$ measures the fraction of output dimensions where the true observation $y$ falls below the $q$-quantile of the posterior predictive distribution. This effectively treats each output dimension as an independent trial, so we also whitened the outputs and data by $\Gamma$, Though not notated, we also truncate to retain 99% of the variance:")

src/streamlit_app.py

@@ -19,7 +19,7 @@ st.sidebar.title("Navigation")
 st.sidebar.page_link("streamlit_app.py", label="Home", icon="🏠")
 st.sidebar.page_link("pages/OptimizationLeaderboard.py", label="Optimization Leaderboard", icon="📊")
 st.sidebar.page_link("pages/UQLeaderboard.py", label="UQ Leaderboard", icon="🎯")
-st.sidebar.page_link("pages/MethodDetails.py", label="Methods", icon="📘")
+st.sidebar.page_link("pages/MethodDetails.py", label="Method configurations", icon="📘")
 st.sidebar.page_link("pages/RawData.py", label="Get Data", icon="🧾")
 
 st.title("Calibration Benchmark")
@@ -100,8 +100,8 @@ st.subheader("Method taxonomy")
 st.markdown(
     "Every method carries four independent tags — how it searches, what update "
     "mechanism drives each step, what it's built to report, and whether/when it uses "
-    "a surrogate model. See the **📘 Methods** page for citations and per-method "
-    "performance charts."
+    "a surrogate model. See the **📘 Method configurations** page to investigate more "
+    "about any individual configuration."
 )
 _taxonomy_rows = [
     {