KineticForces - PERFORMANCE - Panel NTV psi quadrature at rational and kinetic-resonance surfaces with rtol-primary tolerances

[logan-nc]

Closes #303. Built on #312 (feature/two-pass-psi-grid is merged into this branch, so its commits appear in this diff until #312 lands — merge #312 first, after which this PR reduces to the KineticForces changes).

---

Update (2026-07) — merged develop, and made Δ′ grid-robust

origin/develop is now merged into this branch. develop had retargeted the DIII-D example to Ip=1.15 MA and switched that example to a fixed ldp/mpsi=256 grid; the merge conflicts (DIIID gpec.toml, EquilibriumTypes.jl, and the parallel-integration tests) were resolved to keep this branch's two-pass auto grid running on the new equilibrium.

That surfaced a real problem the merge exposed: on the two-pass auto grid the delta-prime matrix diagonal was not grid-converged — a psi_accuracy (τ) scan swung dpm[1,1] (q=2) by ~30%. Root cause: Δ′ extracts the subdominant small-solution coefficient through a dpsi^{-2α}-conditioned Frobenius projection, so it tracks the equilibrium-spline error in the layer around each rational; the old packing was τ-scaled and its merge snapped out the pinned rational's own neighbors, so the local stencil changed topology with τ. (et[1], a whole-plasma integral, stayed robust to <1% — confirming this is a local singular-layer matching problem, not a global-response one.)

Fix — rational_psi_ladder: a geometric knot ladder straddling each rational with a fixed absolute innermost step h0 = 1e-3, independent of τ and matched to the equilibrium's native radial resolution, emitted as mandatory grid knots. Anchoring h0 to the equilibrium resolution — not the far finer perturbed matching offset singfac_min/|n·q1| (~5e-5), which rings the re-splined equilibrium and blew Δ′ up to ~149 — is what makes Δ′ grid-robust. A min-spacing thinning prevents overlapping ladders from nearby rationals (low shear / multi-n) creating sub-h0 intervals; merge_mandatory_nodes collapse now uses an absolute tolerance so fine ladder knots survive.

DIII-D case	before (τ-scaled packing)	after (ladder)
dpm[1,1] spread across τ ∈ {2e-3…2.5e-4}	~30%	~4% (q3, q4 <1%)
dpm[1,1] value	6.4–8.9 (τ-dependent)	8.40, matches ldp mpsi=512 (8.48)
Δ′-matrix runtime vs develop's ldp mpsi=256	—	2.2× faster (158 s vs 353 s)

The converged value matches the finer ldp mpsi=512 grid; develop's ldp mpsi=256 (7.28) undershoots by under-resolving the rationals. In the diiid_n1 harness, equilibrium, energies, NTV torque, and ‖resonant flux‖ are unchanged (<0.5%); the delta-prime and its downstream island/Chirikov diagnostics move intentionally (the ladder converges Δ′). A fortran-physics-reviewer audit passed: the fixed ladder is a faithful analog of DCON (equilibrium splined at native resolution, singular layer handled analytically by the Frobenius matching at dpsi = singfac_min/|n·q1|), and it flagged the overlapping-ladder edge case that the min-spacing thinning now guards.

Re-pinned the parallel-integration dpm diagonals at rtol=0.1 on the ladder values (real parts only; et_par kept tight); added a grid-refinement test pinning the ladder min-spacing invariant in the multi-n regime. The NTV-quadrature description below is unchanged by this update.

---

Problem

The outer ψ-integration of the NTV torque tpsi(ψ) used a single whole-domain adaptive quadrature with no interior breakpoints, no maxevals bound, and a discarded error estimate. The resonant torque-density peaks — at the rational surfaces and at the kinetic resonances (dominantly the ExB/superbanana-plateau resonance near ω_E ≈ 0) — forced deep adaptive bisection (1375+ evaluations, ~30 min reported in #303 on the DIII-D-like case). Separately, the atol_psi = 1e-2 N·m default was an amplitude-sensitive trap: NTV ∝ δB², so a 10× weaker applied field gives a 100× smaller torque and a fixed absolute tolerance can silently dominate termination with O(1) relative error.

Changes

ψ-quadrature paneling at resonant surfaces

• Rational-surface ψ locations the stability run resolved (sing + kinsing) are threaded into KineticForcesInternal.sing_psis and passed as quadrature panel boundaries — Gauss–Kronrod handles peaks at interval endpoints natively instead of hunting them by bisection.
• Kinetic-resonance locations are identified and paneled for the case's full bounce-harmonic range: kinetic_resonance_psi_nodes(kinetic_profiles, equil; n, nl, ...) scans for zeros of the trapped-branch resonance denominator at thermal energy, Ω_ℓ(x=1; ψ) = ℓ·ω_b(ψ) + n·(ω_E(ψ) + ω_d(ψ)) for every ℓ ∈ −nl:nl, using the pitch-averaged RLAR closed-form frequencies already in tpsi! (single spline evaluations, no bounce averaging). The ℓ=0 node is the ω_d-shifted ExB resonance; ℓ≠0 nodes capture the bounce resonances. On the DIII-D case this finds 8 in-range surfaces that line up with the observed pedestal dT/dψ structure (see figure) — including the previously unexplained bump at ψ_N ≈ 0.955.
• Panel boundaries and located resonance surfaces are persisted to the output (kinetic_forces/<method>/panel_psi, resonance_psi) for diagnostics/plotting; the per-method log line reports torque, error estimate, evaluation count, and panel composition.
• A fortran-physics-reviewer audit of the locator passed all checks: frequency conventions match tpsi!/torque.F90 exactly (the wdhat = q·T/(2εR₀²ZeB₀) closed form verified algebraically identical), the denominator correctly uses ω_E alone (diamagnetic terms are numerator-only), and leff = ℓ matches the trapped branch. Passing-branch (ℓ+nq transit) resonances are a documented non-goal (broad/Landau-like; quadrature resolves them without dedicated panels).

Unified helpers (one source of truth per concept, no drift)

• New src/KineticForces/Utils.jl: find_sign_change_roots(f, grid) (grid sign-scan + Brent) — also replaces the two pre-existing inline copies of the same idiom in Torque.jl (dB/dθ extrema).
• kinetic_resonance_psi_nodes is the single kinetic-resonance locator, shared-signature-ready for the Kinetic-aware equilibrium grid packing: place knots on rational and kinetic-resonance surfaces #309 grid-knot packing (refined_psi_nodes = rational_psi_nodes ∪ this). Rational-surface identification stays unified under _find_rational_surfaces (shared by sing_find! and EQUIL + GPEC - Two-pass measured-curvature auto psi grid with rational-surface knots #312's rational_psi_nodes).
• psi_panel_points owns sort/dedupe/bound-filtering of the merged panel list.

Tolerance redesign (rtol-primary)

• atol_psi: 1e-2 → 0.0. Convergence is controlled by rtol_psi = 1e-2 (~2 significant figures — the limit of the NTV model's validity; tighter tolerances buy digits the physics can't back).
• New maxevals_psi = 2000 runaway guard; the error estimate is checked and a clear warning fires when the quadrature terminates without meeting tolerance, or when a user-set nonzero atol_psi dominates termination (the weak-field silent-garbage scenario).
• psilims stays [0.0, 1.0]. (An interim commit floored it at 0.1 to dodge a near-axis dT/dψ spike; measurement showed that was over-optimization — at rtol=1e-2 only 7 of 345 develop evaluations land below ψ=0.1 and the core carries a real 0.3% of the torque — so the floor was reverted. The near-axis feature itself turns out to be two located ℓ≠0 resonance surfaces, now paneled like the rest.)

Coverage

• New examples/Solovev_kinetic_NTV_example (ideal FFS → PE → NTV torque) — previously no shipped config exercised this code path — plus a solovev_kinetic_ntv regression case pinning the fgar torque and ψ evaluation count.
• Removed the inert atol_psi/rtol_psi keys from the a10 example (it stops after kinetic stability and never reaches the torque quadrature).

Benchmarks (DIII-D-like case from #295, n=1, C-coil 1 kA, nl=6, 5 rationals)

Code	Panels	atol/rtol_psi	Torque (N·m)	ψ evals	KF stage
develop	–	1e-3 / 1e-3 (pre-#303 mitigation)	—	1375+	~30 min (reported)
develop	–	0 / 1e-2	82.93 − 14.80i	345	158 s
this PR	5 rational + 8 kinetic resonance	defaults (0 / 1e-2)	83.16 − 14.92i	210	108 s
this PR	5 rational + 8 kinetic resonance	1e-9 / 1e-3	83.18 − 14.95i	450	296 s

The defaults run agrees with the tightly-converged answer to 0.024% in Re(T) at 1.6× fewer evaluations than develop at equal tolerance — and 210 = 14 panels × 15 nodes exactly: the initial pass alone converges, i.e. the panels sit precisely where the quadrature work is. Whole n=1 pipeline: ~3 minutes. Regularization note: the PE default reg_spot = 0.05 must stay on for this post-PE diagnostic — with raw (unregularized) ξ the "torque" becomes the grid-capped ideal-MHD 1/(m−nq)² divergence (~66,000× larger on a Solovev test) rather than a physical answer.

Torque density with the identified resonance locations (rationals dashed gray; located kinetic resonances Ω_ℓ(x=1)=0 dash-dot violet — note the match to the pedestal structure and the small near-axis feature):

Quadrature evaluation clustering — develop (no panels) goes near-vertical at the edge resonances; the paneled defaults run spreads effort almost uniformly:

Cumulative torque integral — all runs overlay; ~95% of the torque accumulates in the pedestal, with the sharp rise starting at the ℓ=0 kinetic resonance:

Regression

• solovev_n1: 21/21 unchanged; diiid_n1: 46/46 unchanged vs feature/two-pass-psi-grid (this PR's changes are isolated to [KineticForces]-configured runs).
• solovev_kinetic_ntv: NTV torque and evaluation count move intentionally with the quadrature improvements (final baseline pinned at this head).
• Unit tests: 222 kinetic (new: root-scan, resonance-node scan with analytic locations, panel assembly, tolerance warnings) + 39 grid-refinement, all green.

Notes for reviewers

• The pre-existing solovev_kinetic_calculated/solovev_kinetic_nuzero regression cases are broken on develop and this branch alike ([SOL_INPUT] in a separate sol.toml that build_inputs_from_toml doesn't resolve) — separate fix needed; not touched here.
• PR Add D3D-like kinetic profiles and update example equilibrium #295's interim atol_psi/rtol_psi = 1e-2 lines can simply be dropped after this merges — the new defaults are equivalent or better.
• The figures are committed under docs/src/assets/ (same pattern as EQUIL + GPEC - Two-pass measured-curvature auto psi grid with rational-surface knots #312's grid figure) and can back a future docs page on NTV tolerance settings.

🤖 Generated with Claude Code

[logan-nc]

FYI @d-burg I had claude go another round with this now that a few other things merged.
The auto grid looks pretty good to me. I am seeing the dpm regression values change outside the pinned range with changes in either the auto tau or the ldp mpsi though.

I had claude working through a smarter auto grid. It tried denser packing near the rationals, but that failed. It was looking into at least just consistent packing around the rationals, but I ran out of tokens. That seems like a hack to force "robustness" anyways - why trust any given fixed packing? Do you have any better ideas for how to make a smart grid that gets the "right" answer for dpm?