KrononosFE/kronos-ml

KODEX — the Kronos Family of Codes

A benchmarked AI/ML surrogate suite for fusion. Fast, calibrated stand-ins for expensive physics — every code knows when it is out of its depth.

• One contract: predict(x) -> Prediction(y, uncertainty, in_domain)
• Calibrated uncertainty on every prediction (the KHALO layer)
• An abstention gate on every prediction (the KGATE trust boundary)
• Honest provenance in the type: every surrogate is [T] tagged, naming the real code it stands in for (retired_by) — nothing is ever mistaken for high-fidelity, and nothing is called "live."

30 codes across three rollout phases (Phase 1 = data-backed, ships first; Phase 2 = partial data; Phase 3 = roadmap). See BENCHMARKS.md for the honest per-code numbers and FAMILY.md for the technical note.

Install

pip install -e ".[ml,data,nn]"     # kronos-toolkit + numpy/scipy are the core

The core imports with no torch and no sklearn; heavy dependencies load only when a surrogate actually runs.

Quickstart

import kronos_ml as K

K.list_surrogates()                 # the 30 K-codes
K.fleet(phase=1)                    # Phase-1 cards

# a real CGYRO transport prediction (representative fidelity, mu=400)
p = K.run("KYRO", [3.5, 1.6])       # a/L_T, magnetic shear
p.y, p.uncertainty, p.in_domain     # ion heat flux Q_i, 1-sigma, trust gate

# the model-free safety gate
K.get("KGATE").clamp([2.0, 0.3, 9.0, 5.0, 0.9, 60.0])   # -> projected onto the envelope

# provenance travels with the value
p.as_tagged("CGYRO (nonlinear gyrokinetic)")            # [T] retired_by CGYRO

The fleet (30 codes)

Spine: KHALO (uncertainty) · KGATE (abstention gate). Phase-1 members: KOIL (magnet twin + quench) · KFLOW (state estimation) · KMAT (materials screen) · KYRO (CGYRO transport) · KWARD (disruption) · KORE (equilibrium) · KAIROS (control) · KQUBIT (quantum-ML, no-advantage). Phase-2/3: breeder/burner/isotope/neutronics/operational codes, more quantum (KQROSS, KSENSE, KTENSOR), multi-fidelity (KFUSE), and roadmap codes (KFORGE, KDRIVE, KLAW, KGEN, KPILOT, …). KECON is a generic open techno-economics calculator with a financial firewall — it carries no Kronos cost/price/valuation data, ever.

Honesty

Every pre-registered miss is kept (KFLOW AC-18, KWARD <30 ms warning, KORE 1% bar). CGYRO-backed results are at representative fidelity (reduced electron mass μ=400); the real-mass "gold" validation point is the single open item. No economics or Kronos financials in any physics code. Apache-2.0.