Known ceilings
Every deliberate shortcut the code currently takes, what it limits, and what would lift it. A ceiling is lifted, never deleted, so the history stays visible.
| ID | Component | Shortcut | Limit | What lifts it | Status |
|---|---|---|---|---|---|
| K-001 | transport-solver | dense linear solve for the tridiagonal system in the toy Tier A solver | adequate to a few hundred cells; cost grows as n^3 | tridiagonal (Thomas) scan | open |
| K-002 | coupling-loop | dense Jacobian in the toy Newton solver (no band structure exploited) | about 200x slower than Picard per step on the toy problem (C-004) | banded Jacobian, once transport and pedestal models are confirmed local in radius | open |
| K-003 | coupling-loop | fixed time step; no adaptive retry when a nonlinear step fails to converge | up to 6 non-converged steps in the ITER hybrid ramp-up at dt <= 0.5 s; effect on stored energy 2e-5 relative (C-011) | adaptive dt with retry (owner decision OQ-5, 1 Oct 2026: keep TORAX's line-search floor; stalls stay reported) | open |
| K-004 | equilibrium | flux-surface cross-section area reconstructed as volume / (2 pi R_geo) with the centroid at the geometric centre (Pappus), since grid counting fails near a diverted boundary | about 2% at mid-radius; the quantity is carried for export only, never used in the transport solve | contour integration of each flux surface | open |
| K-005 | guard | ensemble-spread check inactive (the current surrogate is a single network, not an ensemble); input-domain box, finiteness and output bounds are active | no statistical uncertainty enters the guard decision yet | ensemble surrogates (M3) and conformal calibration (M4) | open |
| K-006 | equilibrium | the free-boundary equilibrium is solved standalone; it does not yet drive the transport loop | no coupled free-boundary run exists | feeding the equilibrium geometry into the transport solver, once a transport model valid for a spherical tokamak exists (M2/M3) | open |
| K-007 | imas-adapters | exporting an equilibrium to IMAS assumes the toroidal-flux radius at the boundary equals the geometric minor radius, which is exact only for the circular toy geometry | for shaped plasmas the exported rho_tor, dvolume_drho_tor and gm3 are scaled wrongly by rho_tor_b / a (C-030 for ITER, C-021 for MAST-U) and its square; found 2026-09-30 while writing the technical pages. Import is correct, the transport solve never uses these exported fields, and no published number depends on them | carry rho_tor_b in the equilibrium state and use it in the export; test the exported boundary rho_tor against the source code's own value Lifted 2026-09-30: Equilibrium.rho_tor_b (None means the circular case, where it equals a_minor); the analytic, transport-code and equilibrium-code backends each set it; regression test tests/unit/test_adapters_roundtrip.py::test_equilibrium_export_uses_toroidal_flux_radius exports a shaped case and round-trips it; independent checks against TORAX's and FreeGSNKE's own boundary flux radius (C-033). Commit 6b0845c, entry 7 |
lifted |
| K-008 | guard | the guard's normalised-gradient features use -R0 (du/drho_tor_norm) / (a u), not QLKNN's own input convention -R0 (du/dr_mid) / u with r_mid the midplane minor radius | the two agree only for circular geometry; on the ITER hybrid scenario they differ by up to about a third at the edge (C-032). No published number is affected (open or arbitrary boxes so far), but a verified domain (M4) must be expressed in the surrogate's input space | owner decision on the feature convention (OQ-10, deferred to M3), then features computed in the surrogate's own variables (or a documented map between the two) | open |
| K-009 | coupling-loop | gradients through TORAX's Newton-Raphson solver are reverse mode only | TORAX 1.4.3 differentiates its Newton solve implicitly (jax.lax.custom_root); reverse mode matches central differences (C-055), but forward mode (jax.jvp / jacfwd) returns NaN in every tangent, even through one step. Forward mode works with the linear solver. Matters for M5's linearised propagation, which the brief writes with jacfwd | use reverse mode (jacrev) for Newton runs, or find and report the NaN upstream Lifted 2026-10-01: Cause: custom_root's forward-mode rule differentiates the residual w.r.t. every closed-over constant with explicit zero tangents; TORAX's calculate_f_trap takes sqrt(epsilon) with epsilon = 0 on the axis face, so 0 * inf = NaN. tkit.physics.torax_patches replaces it (guarded by the upstream source hash) with a sqrt whose derivative at 0 is 0; values bit-identical; forward = reverse to 2e-15 (C-062). Commit 8aa70ee, entry 14 |
lifted |
| K-010 | pedestal | fixed pedestal (TORAX set_T_ped_n_ped), held at rho = 0.9 by an adaptive pinning source | the pinning source removes 87-98% of the heating in the ITER hybrid ramp-up (C-038), and TORAX's P_SOL counts that power as crossing the edge. Accepted at the M1 physicist review for core profiles inside rho = 0.9; P_SOL and edge power accounting from these runs are not used | a predictive pedestal model, revisited at M3 when the pedestal becomes a surrogate target | open |
| K-011 | fast-ions | ASCOT5 alpha markers are taken as generated by tkit.physics.ascot_alpha | the markers' birth power is 1.5% above AFSI's birth rate times 3.52 MeV. The marker weights sum to AFSI's rate exactly; the excess is the markers' mean birth energy, 3.573 MeV (C-063). Thermal motion of the reacting ions raises the mean alpha birth energy above 3.52 MeV; whether it accounts for all of the 1.5%, or AFSI's momentum binning adds to it, is not yet determined. Earlier estimates (1.3-1.4%) were 640-marker samples | compare the mean birth energy with the D-T kinematics for TORAX's ion temperature, before ASCOT5 is used for neutral-beam ions (M1 physicist review, 1 Oct 2026) | open |
| K-012 | fast-ions | ASCOT5 power-deposition moments on 50 equal-width rho_pol bins, interpolated onto TORAX's cells | inside rho_tor_norm 0.3 the alpha heating profile is not resolved cell by cell: neighbouring cells of the 6400-marker run differ by up to 41% (ions), and its deviation from TORAX's local model there is no smaller than that of the 640-marker samples, so the scatter does not fall with marker count. Outside 0.3 every sample agrees with TORAX's model to 2-5% (NRMSD). Totals, the electron/ion split and the shape moments (C-064, C-065) are resolved | a binning study (equal-volume bins near the axis, or a smoothed moment) before ASCOT5 profiles are used cell by cell in the core | open |
| K-013 | equilibrium | FreeGSNKE's IMAS writer gives the flux-surface triangularity that TORAX reads (delta_face), on FreeGSNKE's default 65 x 129 grid | inside rho_tor_norm about 0.6 the triangularity is grid noise: on the MAST-U-like reference the 65 x 129 and 129 x 257 grids give 0.194 and 0.028 at rho 0.1 and 0.012 and 0.073 at rho 0.4, and the profile is not monotonic. They agree within 0.01 from rho 0.7 out; elongation agrees within 0.01 everywhere. Any TORAX run on FreeGSNKE geometry with a shape-dependent transport model (TGLF) sees this noise. The M2 sampling ranges take delta and its shear from r/a >= 0.6 only | a smooth Miller fit to FreeGSNKE's flux surfaces (or a finer grid checked for convergence) before TGLF-based transport runs on FreeGSNKE geometry | open |
| K-014 | guard | inside TORAX, the fixed-step loop records the guard decision re-evaluated on each accepted end-of-step state | the decisions TORAX's solver takes at its own transport evaluations (start of step and each nonlinear iterate) never reach its outputs, so the trace cannot say which model served each face during a step. It records a post-step domain diagnostic, rejected_fraction_poststep, not a fraction served by the fallback. With the guard always open or always closed (C-014, C-015) the two coincide; for a partial guard they can differ | per-evaluation guard decisions returned from TORAX's solver (an upstream hook), or tkit's own iteration around TORAX's transport call, before a fallback fraction is reported for a partial guard (code review 2 Oct 2026, R11) | open |
| K-015 | transport | TGLF runs as a TORAX transport model (in-process wrapper) with TORAX's legacy TGLF defaults and no transport radial domain | on TORAX's iterhybrid_predictor_corrector case the first step fails (job 2293936): TGLF gives NaN fluxes on the axis face and about 1e6 gyro-Bohm units on the edge face, and TGLF then stops on a zero impurity charge, most likely from the diverged step (TORAX's neon charge follows T_e). TORAX's own TGLF transport-model tests pass on the same node, and every single-face TGLF call outside TORAX runs | a transport domain excluding the axis and the pedestal (as the QLKNN setup has), then a short TORAX run with TGLF, before TGLF-in-TORAX spot checks at M3/M4 | open |
| K-016 | datasets | the ITER dataset (v1) takes its geometry from one plasma shape, TORAX's ITER hybrid equilibrium, plus the q profiles of TORAX's ITER current ramp-up example | elongation and triangularity rows are narrow (LCFS kappa 1.87, delta 0.43); the 15 MA baseline scenario (q95 about 3) is not covered. The ramp-up widens q and magnetic shear only (owner, OQ-16 b) | baseline-scenario equilibria, from EQDSK files of the ITER scenario database or from FreeGSNKE's ITER-like machine with inverse solves, before an ITER v2 dataset | open |
| K-017 | datasets | points are rejected above a fixed alpha_MHD (MAST-U 4, ITER 2), independent of the magnetic shear | about half the Latin-hypercube draws are rejected and the kept set is reshaped: kept beta_e mean 23-25% below the box mean, kept q concentrated at low q since alpha_MHD grows as q^2 (C-073). An s-alpha ballooning boundary depends on the shear, which a fixed cap ignores (owner, OQ-16 c: fixed caps for v1) | a shear-dependent cap (s-alpha boundary times a margin) set by the physicist, or sampling alpha_MHD in place of beta_e | open |
| K-018 | datasets | geometry inputs are sampled independently, each over a range derived from the measured equilibria, not jointly from the measured flux surfaces | the datasets contain combinations that no measured equilibrium has, for example high q at low magnetic shear on MAST-U (figure in the datasets section); 63-94% of points lie inside the measured 1st-99th percentile envelope input by input (C-076), fewer jointly | joint sampling from the measured faces (a draw of face plus a perturbation), or a weighting of the training loss by distance to the measured set, decided before M3 training | open |
| K-019 | datasets | the v1 datasets are stored with every TGLF output as computed; no filter on flux magnitude | 28% of MAST-U cases and 10% of ITER cases have Q_e + Q_i above 10^4 gyro-Bohm units (C-075), mostly at steep electron temperature gradients. Not yet established whether these are physical (far above threshold, electromagnetic modes at high beta_e) or come from the inputs as constructed | a check of a sample of the high-flux cases with the electromagnetic terms off and against CGYRO spot checks, and a physicist decision on a flux range or loss weighting, before M3 training | open |
| K-020 | fast-ions | ASCOT5's electron and ion power deposition is taken from its binned distribution moments, and the energy check compares their sum (plus lost, unfinished and thermalised energy) with the markers' birth energy | the sum comes out about 1% below the birth energy and varies run to run: 0.989 +/- 0.014 over 16 runs of 32 markers (range 0.967-1.011), 0.991 +/- 0.010 over 8 runs of 128 markers, so it is not marker count alone. The energy-book test therefore checks to +/-0.05 (owner, 3 Oct 2026); at +/-0.03 it failed about 1 run in 12. Where the 1% goes (bin width, the time integration of the deposited power, markers ending with no end condition) is not yet determined | trace the deficit to its source and tighten the test back to +/-0.03 or below, before ASCOT5 deposition is used for neutral-beam ions | open |
| K-021 | transport-surrogate | Q_e and Q_i are clipped at zero in use (ReLU per member; OQ-19 3), so negative TGLF heat fluxes are not represented | on the v1 test splits TGLF gives Q_e <= 0 in 4.6% / 5.2% (MAST-U / ITER) and Q_i <= 0 in 12-13% of cases; among |Q| > 1 gB, Q < -1 gB in 0.7% / 0.7% (Q_e) and 6.5% / 4.3% (Q_i), where the clipped prediction has relative error >= 1. The clipped flux is 0.8-0.9% of the summed |Q_i|; where Q_e + Q_i >= 1 gB the sum changes by more than 10% in 0.9-1.0% of cases (blog C-104). TORAX clips the resulting diffusivity at chi_min anyway | a signed heat-flux output with its own stability treatment, if a use needs negative ion heat flux (electron-driven cases) | open |
| K-022 | transport-surrogate | the TGLF surrogate inside TORAX's Newton solver evaluates all 20 members on every face, including faces the guard hands to the fallback | about 2 s per Newton step on one core: the RAPTOR L-mode case takes 374-405 s against 29 s with QLKNN (14x slower end to end), although one surrogate call is 3.3e4 times faster than TGLF (3.1 ms against 103 s for 51 faces). Final v3 locally takes 60.58 s for 40 tightly converged Newton steps (median 1.47 s), while isolated 51-face inference takes 4.36 ms. A three-step execution trace is captured; fused HLO labels have not yet separated ensemble inference from Jacobian construction. The offline interval-union audit (C-148) confirms that all HLO events share one fused module and runtime source; component attribution remains unresolved. With the linear predictor-corrector solver (job 2650336, RAPTOR L-mode, 40 steps, compilation excluded) final v3 takes 1.25 s against 0.117 s with QLKNN (10.7x) and 539 s with TGLF on 51 workers | profile the Newton step (Jacobian through the ensemble), then evaluate only guarded faces, fewer members in the Jacobian, or a linear/predictor-corrector solver | open |
| K-023 | transport-surrogate | the guard domain is the per-feature box of the v1 training inputs | on the RAPTOR L-mode case the ITER box serves about half the faces (rho 0.1-0.66; rejection fraction 0.51, iterhybrid 0.27): r/a < 0.1, XNUE > 0.1 from rho 0.54 (the approved ITER collisionality range), CHEASE triangularity shear slightly below zero, edge geometry | dataset v3 (OQ-19 1) covers the loop's geometry; XNUE > 0.1 needs a wider approved ITER kinetic range (owner). OQ-20 widened it for v3; the v3 model's post-step rejection is 33.1% on the short RAPTOR run (C-135). Axis, edge and out-of-box states still require fallback; the v1 ceiling is not erased | open |
| K-024 | transport-surrogate | the surrogate's Q_i is the main ion's flux; TORAX's TGLF model passes the sum over ions. The M2/v3 datasets set no DEBYE input | about 1% in Q_i on the RAPTOR case | store and train on the summed ion heat flux in the next dataset version | open |
| K-025 | transport-surrogate | the TGLF surrogates are monotone by construction (OQ-20) - Q_e non-decreasing in a/L_Te, Q_i in a/L_Ti - although TGLF SAT2 is not | on 35 scans per machine and pair (data/m3/scans/tglf-mono-v1) TGLF decreases somewhere along 51-80% of them, by more than 50% in 34-57% (mode switches and smooth decreases). The best monotone (isotonic) fit departs from TGLF at its worst point by a median of 0.6-1.05 signed-log units (about a factor 1.8-2.9 for |Q| >> 1) and 3.5-5.7 at the 90th percentile; a monotone surrogate must depart where TGLF decreases. Final v3 models: median maximum per-scan departure 3.14/3.36 (MAST-U Q_e/Q_i), 2.51/2.11 (ITER), C-131; these include approximation error as well as the imposed monotonicity | owner decision to drop the requirement, or a regime-aware structure (monotone within a mode, with mode switches represented explicitly) | open |
| K-026 | transport-surrogate | TORAX's default Newton residual tolerance is 1e-5; implicit differentiation assumes a converged root and can differ from finite differences of that approximate solve | On three RAPTOR steps, v3 core-temperature derivatives differ by about 1.8e-5 relative; peak relative energy defects are 1.11e-5 for v1 and 1.36e-6 for v3 (C-140). Solver status zero alone does not establish the stricter derivative and conservation limits | use a tighter converged solve and recheck gradients and balance; the v3 comparison runner uses residual_tol 1e-10 for Newton and records it explicitly. Historical default settings and linear-solver timing evidence retain their original limitations | open |
| K-027 | rf-pedestal-surrogates | the EC surrogate learns one code (GENRAY) with one equilibrium (K-028) and one ray per case; the ITER pedestal is the selected pretrained EPEDNN network, used as is | EC accuracy holds on held-out runs of the training family (C-168); outside the training box (for example core T_e above the largest training value) the Gaussian fallback serves the source, so central EC at high power falls back on part of a trajectory. EPEDNN has no ensemble spread; its input box and range checks are the only guard. Neither model's spread or error is calibrated (M4). MAST-U predictive pedestal and IC are deferred by the owner | wider EC sampling (beam width, equilibria per state, higher T_e), calibration at M4, and a MAST-U pedestal reference if the owner adds one | open |
| K-028 | rf-dataset | every EC dataset v1 case traces rays through one equilibrium (the upstream deck's 15 MA ITER EQDSK); only T_e, n_e and Z_eff come from the TORAX state | states whose own geometry or current differ from 15 MA get labels for an inconsistent plasma; all 27 cases above 60 kA/MW (up to 279 kA/MW) are early ramp-up states at t = 8 s (T_e0 16-41 keV, n_e0 1.3e19 m^-3, I_p about 3-4 MA in TORAX). The collisional heating channel is zero in every case (not enabled in the deck) | write an EQDSK per state from the TORAX geometry, or restrict EC states to those near the equilibrium's current and shape. Restriction applied 2026-10-10 (owner, option b) for the structured EC dataset, states with prescribed I_p of at least 10 MA (2910 of 3120 cases); the remaining states (10.5-11.5 MA, different shape) still use the 15 MA equilibrium | open |
| K-029 | transport-surrogate | the MAST-U v3 surrogate in TORAX's Newton solver from dataset-v3 initial states | Newton reaches TORAX's default tolerance on every step only at small steps for some equilibria (eq57 at 0.5 ms); at the runs' 5 ms steps the first step does not converge and at 1 ms steps are accepted at the coarse tolerance. The runs' own linear predictor-corrector converges on every step at 5 ms. The initial states are not in equilibrium (native Bohm/gyro-Bohm transport raises core T_e by about 0.1 keV per 5 ms step) | start Newton from an equilibrated state, adaptive steps with retry, or a smoother surrogate near the guard boundary | open |
| K-030 | transport-surrogate | final monotone v3 MAST-U surrogate serves half the faces at the final accepted state | M4 V8 saved matched run 2650876 fails the unchanged 15% closed-loop limit: served-face NRMSD T_e 35.3331%, T_i 49.1458%. Both cell-centred profiles are interpolated to the guard faces. Whole-profile errors are 41.5052/62.3861%; using only cells with both adjacent faces served gives 11.8629/23.2419%, still failing ion temperature. This mask is a final-state diagnostic, not trajectory fallback-call accounting. ITER passes at 7.4235/8.1840%. The approved feedback-candidate replay completes finite and converged, but its formal comparison cannot reuse the saved reference: candidate-served face 4 (rho 0.16) uses reference fallback. Candidate fixed-baseline-mask errors 42.1252/48.1182% retain the electron regression; own-mask descriptive distances against the hybrid trajectory are not acceptance metrics. Current model/guard remain selected. The consumed OQ-31 diagnostic reproduces the historical profiles/mask exactly. Final face 4 has valid inputs but negative raw electron heat diffusivity; reference coverage remains ineligible. The physical/numerical origin and reference remedy remain unresolved (OQ-32). | MAST-U model/domain remediation and a new matched comparison under a separately approved compute request, or an explicit limited scope at the certification review (OQ-25) | open |
| K-031 | verification-export | strict 1e-12 relative-only parity compares different float64 reduction implementations | V2 has 17 scalar discrepancies on the complete random/held-out audit (raw and physical views counted separately), all failing absolute errors below 8e-15 in the declared units. Worst relative error is 9.0625e-12 near a 0.000330872 gB particle flux; JAX JIT versus eager also reaches 9.1148e-12 on the same near-zero member output. This was the strict relative-only criterion, before OQ-26; served ensemble means and the pedestal passed it. | Owner approved rtol=1e-12 and atol=1e-12 in each declared output unit (OQ-26, 2026-10-11). All 13 export tests pass per mode under that explicit mixed criterion; no physics or closed-loop tolerance changed. | lifted |