FFS - IMPROVEMENT - Cap the core knot density of the EL coefficient splines

[logan-nc]

Summary

The Euler-Lagrange coefficient splines (fmats/kmats/gmats and the primitives) inherited every knot of the equilibrium grid. A cubic spline's third-derivative jumps at knots scale as (node error)/Δψ³, so the equilibrium's near-axis packing (Δψ ~ 1e-6 at high mpsi) amplifies even tolerance-level node error (~1e-9, measured) into huge C² kinks — and the adaptive integrator's step size becomes slaved to the knot spacing. Measured directly: core jump magnitudes grow ~34× per mpsi doubling, and an (tol/J)^¼ step model reproduces the observed step-count ladder.

The coefficients are near-cylindrical in the core and do not need that packing. This PR builds their splines on a subset of the equilibrium grid with core density capped at Δψ ≥ 0.05·ψ below ψ = 0.1. Node values are unchanged — only interpolation density — which is why the physics moves at the 1e-7–1e-8 level.

Stacked on #398 (route (a), same investigation); diff shows only the cap once #398 lands.

Measured (DIII-D stripped decks, route-(a) base, mpsi 512/1024)

	mψ=512	mψ=1024
accepted EL steps	2768 → 2188	4403 → 3034
step growth per doubling	—	1.59× → 1.39×
warm run	12.8 → 10.4 s (−19%)	—
et[1] relative change	3e-8	3e-8
Riccati Δ′ diagonal (all 5 surfaces)	4e-7	—

Not a tuned hack: the rule's basis and its generalization

Form: near the axis every component is a Frobenius power law in ψ; power laws are scale-free, so log-uniform sampling (Δψ ≥ c·ψ) resolves them at constant relative accuracy. Constant: cubic interpolation of ψ^p on a log-uniform grid errs by ~(p·c)⁴/384, so c = 0.05 resolves even the steepest spectrum component (p = m_max/2 = 11) to ~2e-4 — and the physics responds far below that because the steep components carry vanishing solution amplitude. Region: ends at min(0.1, innermost rational − RATIONAL_RES_RADIUS), and no knot inside a rational's resolution window is ever removed — guards for decks (e.g. higher n) whose rationals reach the core; verified no-ops on every current case.

Cross-equilibrium check (four equilibria, two construction paths, three grid families):

case	knots	EL steps	et[1] change
DIII-D efit, traced, log-family m1024	1025→575	−31%	3e-8
tj_analytic_direct, traced, log-family m1024	1025→575	−35%	1.3e-9
LAR, inversion, packed auto m1024	1025→575	−8%	exact to 8 digits
Solovev, traced, ldp m512/m1024	505→468	~0	~4.5e-7 abs (3e-5 rel via the ±10.4 → 0.0146 cancellation)

The LAR row is the anti-over-fit witness: clean geometry with no noise to exploit, and the cap is still harmless.

Two properties reviewers should know

1. No-op on production decks. The two-pass auto grid's core spacing already satisfies the cap — verified: 287 → 287 knots on the DIII-D auto deck, and the full harness (diiid_n1, solovev_n1, diiid_n1_riccati, gal_resistive_diiid) reproduces Equilibrium - BUGFIX! - Sample all flux surfaces on common straight-fieldline abscissae and cap the coefficient-spline core knots #398's numbers exactly. The cap engages only on explicitly packed fine grids (large mpsi), which is precisely the issue Performance: Why do large equilibrium splines slow down the code? #376 scenario.
2. A fixed cap beats general curvature selection — measured, not assumed. Removal-error knot selection (drop any knot whose interpolated value matches within δ for every element of all 12 matrices) was implemented and swept: it reaches the physics plateau only at δ=1e-7 where it keeps 504/513 knots and buys nothing, and breaks et[1]/Δ′ at any δ loose enough to matter. The core knots that are safe to remove fail the interpolation test (real coefficient curvature, but the solution components multiplying them vanish as ψ^|m|/2). Interpolation error is the wrong objective; the fixed mechanism-based cap is the right scope for the ideal path. Record: handoff/issue376/RESULTS.md §22–§23 (experiment branch).

Verification

• Tests: runtests_eulerlagrange, runtests_riccati, runtests_sing — all pass.
• Harness vs develop @ 9491f89 across all four cases: identical to Equilibrium - BUGFIX! - Sample all flux surfaces on common straight-fieldline abscissae and cap the coefficient-spline core knots #398's report (see property 1); Δ′-tracking cases included.
• Mechanism measurement and step-model validation: handoff/issue376/RESULTS.md §22.

⚠️ Requires third-party human review before merging — do not merge without an approving review.

🤖 Generated with Claude Code

[logan-nc]

Review package (visual companion to this PR — decoupling diagram, knot-density and step-distribution before/afters, the Frobenius-scale basis for the cap, the cross-equilibrium generalization table, and the why-not-general-curvature-selection sweep):

📦 https://claude.ai/code/artifact/e1ed1ea9-1362-40bd-9f52-ccd386118e21

Self-contained page; complements rather than duplicates the description and diff. If the link does not resolve, ask @logan-nc to enable sharing on it.

[logan-nc]

Folded into #398 — its branch already contained these three commits, so this was a fast-forward with no history rewrite. Both changes are grid-side fixes aimed at the same symptom (Euler-Lagrange integration cost), the cap is a no-op on production auto grids so its measurements only mean anything alongside #398's step numbers, and they have been reviewed and benchmarked as a pair throughout. Closing to keep the review surface at one PR; the content and its evidence move into #398's body. Branch performance/decoupled-el-matrix-grid is left in place.