| # 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`](BENCHMARKS.md) |
| for the honest per-code numbers and [`FAMILY.md`](FAMILY.md) for the technical note. |
|
|
| ## Install |
|
|
| ```bash |
| 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 |
|
|
| ```python |
| 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. |
|
|
