KineticForces: cut dead NTV diagnostic-records scaffold; plan proper energy/pitch integrand diagnostics

[logan-nc]

Summary

The KineticForces (PENTRC port) "integration records" machinery is dead code — scaffolded but never wired to a producer. This issue triages it: cut the dead scaffold, note the live diagnostics that already cover part of the need, and scope the genuinely-useful per-λ / per-x resonance diagnostics as clean future work (not a resurrection of the abandoned scaffold).

Surfaced while cleaning up the NTV total_energy storage in #310; kept out of that PR to avoid noise. The reference Fortran PENTRC tree used below is at ~/Code/gpec_1/2026-Julia-GPEC-2.0-Overview-src-fortran/pentrc/.

What is dead (CUT)

Never populated / never read (verified exhaustively; only these dead-path references exist):

• MethodResult.records::Vector{EnergyIntegrationResult} (KineticForcesStructs.jl:467) — always empty; the sole MethodResult(...) constructor (Compute.jl:222) never sets it.
• write_integration_records! + its if !isempty(result.records) guard (Output.jl:38-87) — unreachable.
• EnergyIntegrationResult struct's trajectory fields x_trajectory / integrand_trajectory / integral_trajectory (KineticForcesStructs.jl:451-453), and its kinetic_energy::ComplexF64 (:450) — the same "real value stored as complex" confusion just fixed for the scalar totals in kinetic NTV δW inflated vs Fortran: χ₁ over-scaling + three bounce-averaging bugs #310.
• Dead control flags: save_records (:134), xlmda_out (:128), eqpsi_out (:129) — defined, never read.
• The aspirational docstring at KineticForcesStructs.jl:442 ("only populated when ctrl.save_records=true") documents behavior no code delivers.

Cutting these removes ~40 lines of unreachable code + 3 misleading flags and eliminates a second instance of the complex-when-really-real pattern. EnergyIntegrationResult has no other users, so the whole struct can go with the records field.

What already exists and should be KEPT

The energy-integrand diagnostic is not lost by cutting the scaffold — it already exists as a live, exported, tested API:

• evaluate_energy_integrand(x_grid; …) and energy_integrand_scalar / EnergyParams (EnergyIntegration.jl:353, exported at KineticForces.jl:75, tested at runtests_kinetic.jl:308). Gives the energy integrand vs x programmatically.
• The per-ψ NTV profiles written to HDF5 — psi, dTdpsi_real/imag, T_real/imag (Output.jl:32-35) — the bulk torque-density deliverable.

What is worth preserving as future diagnostics

(This answers "are the energy/pitch integrands available somehow?" — yes, and here's how to expose them properly.)

PENTRC gates its resonance diagnostics behind xlmda_out (per-λ pitch + per-x energy) and theta_out (per-θ orbit) — pentrc.F90:196-205. Ranked by value for debugging the integrable NTV resonances (Logan thesis Appendix D):

1. Per-λ pitch diagnostic (high value, cheap). PENTRC's output_pitch writes dT/dΛ, running T(Λ), and ω_b(Λ), ω_D(Λ), dJdJ·ω_b vs pitch (pitch.f90:805-810). In Julia these are already computed and discarded per λ in _pitch_gar_kernel_quadgk! (PitchIntegration.jl:120-156) and are directly evaluable on any λ grid from the existing fbnce CubicSeriesInterpolant (PitchIntegration.jl:47), which already returns [ω_b, ω_D, ω_b·|δJ|²/ro², …]. Recommend an exported evaluate_pitch_integrand(λ_grid; …) mirroring evaluate_energy_integrand — no QuadGK re-instrumentation, no new physics.

2. Per-x energy diagnostic to HDF5 (highest value, but the careful one). PENTRC's output_energy records the resonant integrand dT/dx and running ∫dx along the complex x-contour (energy.f90:657-672) — the single best tool for spotting pole mishandling. Julia's evaluate_energy_integrand is a start but two gaps must be closed to be faithful: (a) it returns the raw integrand, whereas production integrates the pole-subtracted smooth integrand plus an analytic add-back (EnergyIntegration.jl:246-284) — a raw curve is visually singular and won't integrate to the production value; (b) it has no cumulative (integral_trajectory) form and no complex-contour x. Scope this as an opt-in diagnostic that reproduces the production contour, gated by a real flag (not the resurrected save_records).

3. Per-θ orbit records (low priority / cut candidate). Innermost bounce-integral trajectory (δJ, h_E/h_D); heavy 5-D array, needed only when the bounce integral itself is suspect. Do not port unless a specific need arises.

Also worth porting as unit tests (not a runtime output path): PENTRC's diagnose_all analytic-limit self-tests (diagnostics.f90), which check the energy/pitch kernels against CGL/Krook/ω_D→0 limits.

Recommendation

• Now / small PR: cut the dead scaffold (records + writer + trajectory fields + redundant kinetic_energy + dead flags + docstring). Keep evaluate_energy_integrand and the per-ψ HDF5 profiles.
• Follow-up: add evaluate_pitch_integrand (item 1) as the cheap, high-value diagnostic; then, if wanted, a faithful opt-in per-x/per-λ HDF5 diagnostic group (item 2) with the pole-subtraction/complex-contour semantics handled correctly.

🤖 Generated with Claude Code