FAMILY.md

# The Kronos Family of Codes (KODEX) — technical note

*Methods-paper seed. Draft — not published. 2026-09-09.*

## Abstract

KODEX is a unified suite of machine-learning surrogates for fusion design and
control. Each code replaces an expensive first-principles computation with a fast
approximation that carries **calibrated uncertainty** and an **abstention gate**,
so a consumer always knows both the prediction's error bar and whether the input
is inside the region the surrogate is trusted on. The suite consolidates
previously scattered research prototypes behind one API,
`predict(x) -> (y, uncertainty, in_domain)`, ships as the `kronos-ml` package
(depending on the published `kronos-toolkit` physics engine), and reports honest,
reproducible benchmarks on data already on disk.

## Architecture

A two-layer **spine** wraps every predictive member:

- **KHALO** — the shared uncertainty layer. A Gaussian-process head (Matérn-5/2 ×
  constant + white-noise kernel, optional delta-learning on a cheap baseline) for
  regression, and a soft-vote deep ensemble (HistGB + RandomForest + MLP) for
  classification. Calibration is a first-class output: reliability curve, ECE,
  90% coverage, sharpness, and NLL from one canonical module.
- **KGATE** — the shared trust boundary. A deterministic, model-free projection of
  any command onto a frozen physical envelope (Sabbagh β_N, Greenwald density,
  q95, REBCO strain), fail-closing to a hold on non-finite input. Safety does not
  depend on any model being correct.

Predictive members attach both layers and expose the same contract, so the
toolkit's existing UQ/Study machinery consumes any KODEX surrogate unchanged.

## Data and honest provenance

All training/validation data is on disk; nothing is regenerated on gated
hardware. The flagship transport surrogate **KYRO** is trained and validated on
**real CGYRO nonlinear kinetic-electron turbulence flux** — the **complete 16/16
A1e map (12 turbulent / 4 quiet)** at **representative fidelity, reduced electron
mass μ=400**. The turbulent structure is clean: ITG (ion-dominated) at high
gradient/shear, electron-dominated (TEM-like, Q_i≈0, Q_e carries transport) along
the low-shear line, and a quiet basin at high shear / low gradient — so the
**operating point (a/L_T ≈ 1.3–1.6) sits below the entire map: subcritical**. A
fully-converged real-mass (μ=3672) "gold" validation point is a separate deferred
check. Every surrogate is tagged `[T]`, naming the real code that
retires it; results that stand in for the reduced-order twin or an analytic
closure say so.

## Benchmarks (honest; see BENCHMARKS.md)

- **KGATE** — 0 escapes over 150,000 injected-violation steps (model-free).
- **KYRO** — on the complete 16/16 CGYRO map: **turbulent/quiet classification
  16/16 correct** (leave-one-out), R² = 0.86 on log total heat flux with 88% 90%-interval
  coverage; **~0.26 ms per prediction versus ~2.9 GPU-hours per point** for the CGYRO
  solve (μ=400). At the subcritical operating point it returns `in_domain=False` —
  it abstains rather than extrapolate below the map.
- **KHALO** — ECE 0.033, 90% coverage 0.888 (sourced); live GP calibration on the
  CGYRO points confirms the machinery.
- **KOIL** — magnet-twin strain surrogate rel-L2 ≈ 0.4% live; quench precursor
  AUC 0.9998, 47 ms lead (sourced).
- **KFLOW** — sensor imputation beats the naive baseline ~2×; the trained GNN
  missed the pre-registered AC-18 0.05 bar (0.084) — the miss is kept.
- **KWARD** — twin AUC 0.99 but warning 22.3 ms < the 30 ms actionability bar —
  kept; probability calibration is the KODEX net-new addition.
- **KQUBIT / KQROSS** — no quantum advantage this decade (rigor cards, not speedups).

## Honest limitations

Most members are trained against the reduced-order twin or analytic closures, not
operating-plant data (Kronos has no plant). CGYRO fidelity is representative
(μ=400). Several pre-registered accuracy bars were missed and are reported as
such. The hardware failsafe behind KGATE has an unmeasured trip-time (the largest
residual). KECON is a generic community calculator only — it holds no Kronos
economics.

## Reproducibility

Fixed seed (20260726), CPU-only, no network. `PYTHONPATH=<kronos-ml>:<kronos-toolkit>
python benchmarks/run_all.py` regenerates `BENCHMARKS.md` and `benchmarks.json`;
`pytest tests/` checks the contract, the calibration math, the KGATE fail-closed
behaviour, and the KECON financial firewall. Apache-2.0.