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).

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