KineticForces - Validate calculated kinetic-DCON vs Fortran (#227); thread nutype, guard torque diagnostics

[logan-nc]

Summary

Closes the regression-validation gaps in #227 (PV+residue energy-integral pole handling)
and folds in the collisionless energy-integral fix (#282, merged into this branch).

Investigation finding: the PV+residue rewrite #227 proposed is already on develop
(exact analytic Sokhotski-Plemelj; ximag deprecated; the proposed x_residue_radius
knob is unnecessary). The open gap was #227's acceptance criterion 2 — the calculated-path
Solovev et[1] was pinned to a code-captured value rather than a physics baseline.

Criterion 2 — physics validation against Fortran kinetic DCON

benchmarks/benchmark_solovev_kinetic_stability.jl generates a Fortran kinetic-DCON deck
matched to the Solovev calculated fixture (same Solovev params, kinetic profile, mode band,
nl, collision operator, grid, edge truncation), runs Fortran dcon, and compares its
W_t[1] to Julia's XiNorm/eigenmode_energies[1]:

	Julia	Fortran	Error
Re(et[1])	15.888	15.619	1.7 %
Im(et[1])	−0.711	−0.660	7.6 %

Passes the DIIID kinetic acceptance thresholds (Re ≤5 %, Im ≤20 %): the PV-era value is
correct; the pre-rewrite ximag value was not.

Criterion 3 — collisionless energy integral (now included via #282)

The energy integral (src/KineticForces/EnergyIntegration.jl) is a single real-x-space
path over [0, X_ENERGY_MAX] for all collisionalities (matching Fortran PENTRC
energy.f90). Each resonance pole x_pole = x_res − i·ν/Ω′ is removed analytically by
principal-value + residue (Sokhotski-Plemelj); the collisionless case (ν ≡ 0) is the exact
ν→0⁺ limit, with its on-axis pole resolved by the analytic Laurent regular-part limit
[h′ − h·Ω″/(2Ω′)]/(iΩ′). This resolves the collisionless NaN that earlier blocked the
nuzero sentinel, which is now added as both a runtests_fullruns.jl end-to-end smoke test
and a solovev_kinetic_nuzero regression case (the calculated deck run collisionless via a
new harness [overrides] mechanism).

Bug fixes

1. Calculated path ignored nutype/f0type/nufac — compute_kinetic_matrices_at_psi!
   never accepted them, so a user setting them in [KineticForces] was silently ignored
   (hardcoded "harmonic"/"maxwellian"). Now threaded from kf_ctrl; defaults match the
   prior values, so existing cases are byte-identical.
2. Standalone NTV torque diagnostics crashed when [KineticForces] was present without
   PE data (the calculated path). Now skipped with an info message.
3. nstep_total was 0 on the kinetic paths — the Riccati callback and the parallel-FM
   propagator solves never counted solver steps. Now counted (Riccati callback per accepted
   step; parallel-FM chunks via per-proxy accumulation summed after the BVP barrier).

Verification

• Kinetic unit tests pass (energy-integral output byte-identical for ν>0).
• Regression harness (local): solovev_kinetic_calculated et[1] ≈ 1.894−1.525i,
  solovev_kinetic_nuzero et[1] ≈ 2.333−2.174i, both matching the pressure-consistent
  kinetic.dat. The calculated case's example_dir now points at a new
  examples/Solovev_kinetic_calculated_example (absent on develop), so the first baseline
  is captured with --refs local.

Review response (this PR)

• Benchmark: renamed local run→rundir (shadowed Base.run); mirrored nufac into the
  Fortran deck.
• Trimmed over-long comments to the project convention (X_ENERGY_MAX, the resonant-integral
  docstring, the NTV-skip comment).
• Energy-integral hot path: sizehint! the pole buffers and replaced the type-unstable
  breaks... splat into quadgk with an explicit breakpoint-count branch.

🤖 Generated with Claude Code

[logan-nc]

@claude review this pr

[claude]

Code Review

Bug fixes (correct)

nutype/f0type/nufac threading (CalculatedKineticMatrices.jl, Torque.jl): Real bug - these control parameters were silently ignored on the calculated path, forcing the harmonic/Maxwellian defaults regardless of what the user configured. The fix is correct: add them as keyword args with those same defaults (preserving byte-identical results for existing cases) and thread them from kf_ctrl.

NTV torque diagnostic guard (GeneralizedPerturbedEquilibrium.jl): Real bug - compute_torque_all_methods! requires perturbation interpolants that only exist when a PE state was computed. The fix correctly gates the entire block (including KineticForcesInternal construction) on pe_state being defined.

Issues

1. run shadows Base.run in run_julia_reference() (benchmark_solovev_kinetic_stability.jl, line 143): run is a Julia built-in. Rename to tmpdir or rundir.

2. Comment block length (GeneralizedPerturbedEquilibrium.jl): The 6-line comment explaining the NTV skip exceeds the project convention (one line where possible; only the non-obvious why). The reasoning is worth keeping but it can be halved:

# NTV torque diagnostics require PE displacements (xi); the calculated path folds
# kinetic into the stability solve and produces no PE state, so skip this block.

3. nufac not mirrored into the Fortran benchmark deck (benchmark_solovev_kinetic_stability.jl, build_matched_fortran_deck): nl, nutype, and f0type are written into pentrc.in, but nufac is not. For the current fixture this is harmless (default 1.0), but if the fixture ever sets nufac != 1.0 the Fortran reference will silently diverge. Worth adding a replace_namelist_value! call for nufac (assuming the Fortran pentrc.in has a matching key).

Test coverage

No test explicitly exercises the NTV skip path (KineticForces block present, no PE state). The ex5 fullrun already covers the calculated path completing without error, so the skip is exercised indirectly - acceptable, but a targeted check would make the intent explicit.

Benchmark script

The deck construction logic (namelist patching, fixture-to-Fortran conversion) is well-structured. The env-var overrides (GPEC_FORTRAN_DCON, GPEC_FORTRAN_SOLDIR) are the right way to handle optional Fortran dependencies.