[logan-nc]

Release note

• Audience: users
• Numerical impact: none (harness @ 136b0fb)
• Migration: none

The Lagrangian δ|B|/B and ∇·ξ⊥ spectra are what a neoclassical-transport calculation is driven by,
and GPEC already formed them — but only inside KineticForces, on the way to the torque, so getting
them out meant running our own NTV model. Another code wanting to run on GPEC's perturbation had no
way to read it.

Nothing kinetic enters them. They are the perturbed-equilibrium Clebsch displacement put through the
S,T,X,Y,Z geometric matrices and deweighted by J·B², so they belong to the perturbed equilibrium —
which is where the Fortran parent puts them: gpout_pmodb runs in gpec under pmodb_flag, and
pentrc reads that file back (read_pmodb). The Julia port fused the two executables and the output
landed on the wrong side of a seam that is no longer visible.

So the construction moves to PerturbedEquilibrium.compute_modb_modes and is written to
PerturbedEquilibrium/Response/{dBoB_lagrangian, div_xi_perp}, beside the displacement it
transforms and on the same Response/psi scale. An ideal run with no [KineticForces] block now
carries the spectra; KineticForces consumes them and gets smaller.

PerturbedEquilibrium	+169 −2
KineticForces	+20 −105

Two spectra, not Fortran's four

Fortran writes Eulerian δ|B|, Lagrangian δ|B|, ∇·ξ⊥ and the curvature term, each as modes and
again as θ-functions. Only the two independent spectra are written here:

• the curvature term is exactly −(dBoB_lagrangian + div_xi_perp);
• the Eulerian form differs from the Lagrangian by ξ·∇|B|/|B|, which Response/xi_clebsch_psi,
  Response/xi_clebsch_alpha and the equilibrium geometry already determine;
• θ-space is Analysis.PerturbedEquilibriumModes.modes_to_theta, which FieldReconstruction.jl:983
  already cites as the reason not to inflate stored output. Verified on a real run: it returns
  (1608, 256, 1) θ-space arrays for both new datasets with n = 3 taken from Info/nlow.

Both relations are stated in the dataset annotations, so a consumer can recover either.

Single toroidal mode only, as before: the geometric matrices are assembled at n = nlow, so a
multi-n run writes nothing rather than something wrong.

What this does not change

The move relocated the output, not the computation — same inputs, same matrices, same θ resolution
derived the same way from the equilibrium, same loop order.

Measured twice, on two different bases:

• On the ITPA TC-24 ITER case (4 multi-ion n=3 runs, 8 threads, pre- and post-move builds
  differing only in where the spectra are written) both spectra come back bitwise identical, ψ
  grid included, and KineticForces/fgar/total_torque is unchanged to the last digit
  (292.91305542711694 for the perturbative even-phasing case). That branch pair predates Equilibrium - BUGFIX! - Sample flux surfaces on common straight-fieldline angles, cap core EL knots, and suppress near-axis kinetic terms #398 and
  KineticForces - FEATURE! - Suppress kinetic terms inside the near-axis validity limit and report validity profiles #414, so it isolates the relocation cleanly but says nothing about this base.
• On this base, the harness row that exercises the moved code is solovev_kinetic_ntv — see the
  report below. No test deck in test/test_data/ has a [PerturbedEquilibrium] section, so that
  case is where the computation actually runs.

Where to look

file	what to check
PerturbedEquilibrium/FieldReconstruction.jl	compute_modb_modes + _jbb_deweight!, moved whole. The ψ loop stays serial: its sticky bracket hints are shared mutable state, and threading it would make the spectra depend on the thread count.
PerturbedEquilibrium/Response.jl	one call after reconstruct_physical_fields, guarded on ffs.npert == 1.
PerturbedEquilibrium/Utils.jl	the two datasets and their annotations.
KineticForces/KineticForcesStructs.jl	the part that shrinks: geometric-matrix build, ψ loop and deweighting helper gone; equil and metric left the signature with them.
test/runtests_h5_schema.jl	the output contract: present with the right shape, on the ψ dimension scale, absent rather than empty when the run cannot produce them.

Tests

All re-run on the merged branch, not on the pre-merge one:

runtests_kinetic.jl 5073/5073 · runtests_multiion.jl 52/52 · runtests_ntv_limits.jl 98/98 ·
runtests_fullruns.jl 21/21 · runtests_h5_schema.jl 31/31 (6 + 16 + 9).

And the suites the merged-in work brought, since the conflicts were resolved in code they cover:
runtests_sfl_sampling.jl 7/7 · runtests_core_capped_knots.jl 8/8 ·
runtests_kinetic_validity.jl 27/27.

No test deck in test/test_data/ has a [PerturbedEquilibrium] section, so the computation itself is
exercised by the harness case solovev_kinetic_ntv and by the TC-24 runs above rather than by a unit
test; the unit tests cover the output contract.

Integrated, not rebased

This branch now contains develop @ 9fb32c9, including #398 (common straight-fieldline sampling,
core knot capping) and #414 (near-axis kinetic validity suppression). Three conflicts, all of them
"the output moved" against "the implementation that used to be here", resolved to the relocated
form; develop had not changed the dropped code beyond a formatter reindent, and
build_kinetic_metric_matrices, which the relocated copy calls, is unchanged.

Regression report

All 19 cases, origin/develop vs this branch:

19 cases / 268 quantities: 260 unchanged, 0 changed, 8 missing on both refs.

Ref 1: origin/develop                 @ 9fb32c9a6 (2026-10-20)
Ref 2: feature/kf-write-perturbation   @ 136b0fb9f (2026-10-20)
env (both): julia 1.11.7, x86_64-linux-gnu, manifest cb9237e9 (pinned), 16 threads/16 BLAS

The one case that runs the moved code:

Regression Report: solovev_kinetic_ntv
---------------------------------------------------------------------------------------------------------
Quantity                                   origin/develop  feature/kf-write-perturbation  Diff     Status
---------------------------------------------------------------------------------------------------------
NTV torque fgar [Re, Im]                   [1 elem]        [1 elem]                       0.0e+00  OK
NTV psi quadrature evaluations             45              45                             0.0e+00  OK
root-area-weighted total energy Re(et[1])  1.090570e-02    1.090570e-02                   0.0e+00  OK
# singular surfaces                        2               2                              0.0e+00  OK
singular psi locations                     [2 elem]        [2 elem]                       0.0e+00  OK
q0                                         1.900006e+00    1.900006e+00                   0.0e+00  OK
---------------------------------------------------------------------------------------------------------
Summary: 6 unchanged

Two rows that need a word

gal_resistive_pe reports all 8 quantities N/A — on both refs, and in a develop-vs-develop
run as well. Pre-existing, not this PR.

diiid_slayer_n1 passes here (SLAYER γ_Hz diff 1.2e-02, threshold 1e-1), but an earlier run of
this same branch flagged that row at 0.1834. It is the case's own noise, not a code change:
running examples/DIIID-like_SLAYER_example twice at one commit, one deck, 16 threads, one
machine gives Tearing/Roots/gamma[1] = 224.65453423959883 and 224.4712047505119 — a
difference of 0.1833, matching what the harness had reported between refs. omega and Q_root
move by ~1e-5 in the same pair, so it is the 2/1 root extraction specifically. The case's
noise_threshold therefore sits at the edge of its own run-to-run spread, which is worth fixing —
but deliberately not here, since re-pinning a gate inside an unrelated PR is how a real regression
gets through later.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01FabuzB6rkkv638ZUCzaAA2