KF - NEW FEATURE - Near-axis kinetic validity suppression with profile-derived boundary

[logan-nc]

Stacked on #408 (performance/decoupled-el-matrix-grid). Physics ruling from the issue #376 DIII-D kinetic investigation: do not chase drift-kinetic physics where the model has lost validity near the axis.

What

1. Near-axis kinetic validity suppression (axis_validity_suppression, default on; a single Bool — no tuning parameters). The zero-orbit-width drift-kinetic ordering fails where thermal ion orbit widths reach the local minor radius. The boundary is computed from the equilibrium + kinetic profiles at runtime: ψ_c = outermost ψ where max( potato width (q²ρ²R₀)^⅓, banana width qρ/√ε, poloidal gyroradius qρ/ε ) ≥ ⟨r⟩ (all coefficient 1). A C² quintic envelope zeroes the calculated kinetic increments below ψ_c (kernel evaluation is skipped there), rising to 1 at 2ψ_c; the kernel grid is augmented with knots across the band so coarse decks resolve the envelope. The same boundary and envelope apply to the NTV ψ torque quadrature — one source of truth.
2. KineticForces/Validity/ output group, written whenever kinetic profiles are used: rho_i, rho_banana, rho_theta, w_potato, r_minor, L_p, L_q, d_separatrix, psi_c, envelope, is_valid (true where max orbit width < ⟨r⟩, ρ_banana < L_p and L_q, and max orbit width < distance to separatrix). The far edge and steep-gradient regions are flagged, never suppressed — they can dominate the physical NTV; suppression is reserved for the region where the model both fails and poisons the numerics.

Why (measured, DIII-D kinetic-calculated on the production auto grid)

The kinetic increments diverge toward the axis (~ψ^−0.7; rtol-invariant, identical on develop and the stack — real model output, evaluated outside its validity domain, no clamp anywhere in the kernel), and on the stack 94% of 223,271 EL integration steps land at ψ < 0.01 while contributing nothing physical:

	grid / kernel evals	et[1]	EL steps	wall (FFS, 32 threads)
develop c42d558 (ad-hoc auto grid, no adjustments)	554 / 554	1.006441 − 0.259620i	7,972	427 s
stack unsuppressed	288 / 288	1.005545 − 0.259371i	223,271	905 s
stack suppressed (ψ_c = 0.04)	288 / ~258	1.005298 − 0.259472i (Δ 2.5e-4)	4,246	365 s

Honest framing (bisected): the 223k-step explosion is a stack regression introduced by #398 (that branch alone reproduces it bit-for-bit; develop does not explode — see #398's disclosure). This PR cures it on physics grounds and finishes below the develop baseline on every axis: fewer steps (4,246 vs 7,972), less than half the kernel evaluations (~258 vs 554 — develop spends 45 of its evals below ψ_c on invalid physics), and et[1] within 1.1e-3 of develop / 2.5e-4 of the stack's converged unsuppressed reference.

A 53× step collapse (also eliminating multi-GB solution dumps) for a 2.5e-4 eigenvalue change, measured against a doubly-converged reference (kernel tolerance ×10: Δ 2.7e-7; denser equilibrium grid: Δ 1.6e-4) and cross-checked against develop (Δ 1.1e-3).

Fortran precedent

ktanh_flag (dcon/fourfit.F:1117) suppressed the same region with four hand-tuned user knobs (ktc, ktw, kinfac1/2) and no physics setting the location. Adopted as supporting evidence for the decision; rejected as a design — here the boundary is profile-derived with zero user parameters.

Regression harness

regress --cases solovev_kinetic_calculated,solovev_kinetic_ntv,solovev_kinetic_nuzero,diiid_n1 --refs performance/decoupled-el-matrix-grid,local:

• diiid_n1 (ideal): 47/47 unchanged — bit-identical.
• Solovev kinetic cases: et[1] moves ≤ 0.07%, NTV torque 0.12% (the quadrature domain now starts at ψ_c), ODE steps ≤ 2%. These are the documented physics change of the suppression and become the new baselines.

High-ρ* caveat, verified on a10: on the low-aspect-ratio a10 kinetic example the criterion yields ψ_c = 0.28 — a quarter of the machine is beyond the zero-orbit-width model. A/B: et[1] = 0.5522−0.0076i unsuppressed → 0.5521−0.0000i suppressed. Re is unchanged (0.02%), and the small kinetic damping vanishes because it originated entirely inside the invalid region — i.e., the model could never legitimately produce that number on this machine. The @info line and the Validity group make this visible per-run; spherical-tokamak-class cases need finite-orbit-width physics, not a looser criterion.

Full investigation record: handoff/issue376/RESULTS.md §28–§29 (experiment/issue-376-mpsi-investigation).

⚠️ REQUIRES THIRD-PARTY HUMAN REVIEW BEFORE MERGING — NON-NEGOTIABLE. DO NOT MERGE WITHOUT AN APPROVING HUMAN REVIEW.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LzbLFQKyuRE5DYZmLokKmk

[logan-nc]

Reviewer package (figures: validity-scale crossings defining ψ_c, before/after step distribution, flow diagram, verification record): https://claude.ai/code/artifact/09745676-ff9b-49c6-a14b-74f093427d00 — flip to shared for reviewers as with #398/#408.