PerturbedEquilibrium - DOCS - Delineate the boundary-response torque from the KineticForces NTV torque

[logan-nc]

Small clarity fix prompted by issue #423's torque cross-validation: PerturbedEquilibrium/Energies/toroidal_torque was annotated simply as "net toroidal torque on the plasma", which invites direct comparison with KineticForces/<method>/total_torque — a distinct construction.

This PR renames nothing (clean-break renames deferred until the gpout_dw port lands, issue #423) but states the delineation in all three places a user would look: the PerturbedEquilibriumState docstring, the HDF5 long_name, and the computation site in Response.jl. The delineation:

• Boundary-response torque (this output): −2n·Im⟨Φ_tot, Λ⁻¹Φ_tot⟩/4 — the anti-Hermitian boundary quadratic form. Equals the volume-integrated Euler–Lagrange kinetic torque for converged self-consistent solutions (δW surface-term identity); their numerical difference is a solution/grid diagnostic.
• ψ-resolved EL torque profile (gpout_dw, unported — issue Port gpout_dw / gpout_dw_matrix (psi-resolved torque response profiles and matrices) as the grid-logic diagnostic #423): same model, volume-resolved.
• NTV torque (KineticForces/): independent energy-space bounce-average evaluation; agreement with the above tests whether the EL matrices faithfully discretize the drift-kinetic operator.

Release note

• Audience: users
• Numerical impact: none (harness @ 4a3c163)
• Migration: none

The toroidal_torque output in the perturbed-equilibrium results is now documented as the boundary-response torque, distinguishing it from the separately-computed NTV torque under KineticForces/. No output was renamed or moved and no value changed; only the docstring, the HDF5 long_name attribute, and a source comment.

Regression report

Regression Report: diiid_n1
=================================================================================================
Ref 1: develop  @ 987e63f3b (2026-08-28)
       env: julia 1.11.7, x86_64-linux-gnu, manifest 7027ae20 (pinned), 112 threads/1 BLAS
Ref 2: local  @ local (2026-09-04)
       env: julia 1.11.7, x86_64-linux-gnu, manifest 7027ae20 (pinned), 112 threads/1 BLAS
-------------------------------------------------------------------------------------------------
Quantity                                      develop          local            Diff       Status
-------------------------------------------------------------------------------------------------
total energy Re(et[1])                        8.012318e-01     8.012318e-01     0.0e+00    OK
total energy Im(et[1])                        4.142529e-05     4.142529e-05     0.0e+00    OK
plasma energy Re(ep[1])                       -1.348486e+00    -1.348486e+00    0.0e+00    OK
vacuum energy Re(ev[1])                       2.149718e+00     2.149718e+00     0.0e+00    OK
vacuum matrix min eigenvalue                  1.873976e-01     1.873976e-01     0.0e+00    OK
plasma energy (all)                           [35 elem]        [35 elem]        0.0e+00    OK
vacuum energy (all)                           [35 elem]        [35 elem]        0.0e+00    OK
total energy (all)                            [35 elem]        [35 elem]        0.0e+00    OK
ODE steps (saved)                             2576             2576             0.0e+00    OK
ODE steps (total)                             4572             4572             0.0e+00    OK
q0                                            1.204212e+00     1.204212e+00     0.0e+00    OK
q95                                           4.781723e+00     4.781723e+00     0.0e+00    OK
beta_t                                        1.327024e-02     1.327024e-02     0.0e+00    OK
beta_n                                        1.372511e+00     1.372511e+00     0.0e+00    OK
internal inductance li1                       8.842392e-01     8.842392e-01     0.0e+00    OK
internal inductance li2                       7.080847e-01     7.080847e-01     0.0e+00    OK
internal inductance li3                       7.304433e-01     7.304433e-01     0.0e+00    OK
poloidal beta betap1                          6.680744e-01     6.680744e-01     0.0e+00    OK
poloidal beta betap2                          5.349834e-01     5.349834e-01     0.0e+00    OK
poloidal beta betap3                          5.518761e-01     5.518761e-01     0.0e+00    OK
# singular surfaces                           5                5                0.0e+00    OK
singular psi locations                        [5 elem]         [5 elem]         0.0e+00    OK
singular q values                             [5 elem]         [5 elem]         0.0e+00    OK
current beta betaj                            4.236478e-01     4.236478e-01     0.0e+00    OK
plasma volume                                 1.829472e+01     1.829472e+01     0.0e+00    OK
plasma current                                1.152130e+00     1.152130e+00     0.0e+00    OK
mpert                                         35               35               0.0e+00    OK
npert                                         1                1                0.0e+00    OK
toroidal field bt0                            2.006573e+00     2.006573e+00     0.0e+00    OK
wall field bwall                              3.880145e-01     3.880145e-01     0.0e+00    OK
aspect ratio                                  2.845746e+00     2.845746e+00     0.0e+00    OK
elongation kappa                              1.708350e+00     1.708350e+00     0.0e+00    OK
q profile (checksum)                          0cd285cea88d...  0cd285cea88d...  identical  OK
pressure profile (checksum)                   a1c48b266622...  a1c48b266622...  identical  OK
Mercier D_I profile (checksum)                eeb06744e795...  eeb06744e795...  identical  OK
resistive interchange D_R profile (checksum)  fa37296851f6...  fa37296851f6...  identical  OK
ballooning Delta' profile (checksum)          bb713caf14eb...  bb713caf14eb...  identical  OK
island half-widths                            [5 elem]         [5 elem]         0.0e+00    OK
Chirikov parameter                            [5 elem]         [5 elem]         0.0e+00    OK
||resonant area-weighted field||              5.189179e-04     5.189179e-04     0.0e+00    OK
PE plasma energy                              3.422677e+00     3.422677e+00     0.0e+00    OK
PE vacuum energy                              3.174510e+00     3.174510e+00     0.0e+00    OK
PE surface energy                             5.826684e+00     5.826684e+00     0.0e+00    OK
PE toroidal torque                            5.087465e-02     5.087465e-02     0.0e+00    OK
NTV torque FGAR [N·m]                         5.549513e-01     5.549513e-01     0.0e+00    OK
NTV kinetic energy dW FGAR [J]                6.840635e-02     6.840635e-02     0.0e+00    OK
Runtime (s)                                   395.6s           375.7s                      --
resonant area-weighted field b^r              [5 elem]         [5 elem]         0.0e+00    OK
=================================================================================================
Summary: 47 unchanged

Notes for reviewers

The branch history has two cleanup commits on top of the original annotation commit, which are worth reading in order:

• b211020f reverts JuliaFormatter churn that the first commit had swept in (~120 lines of collapsed column alignment in Utils.jl and PerturbedEquilibriumStructs.jl). A broader reformatting pass is planned separately; this PR deliberately carries none of it, so the net diff is three hunks in three files.
• 22f62810 cuts the toroidal_torque docstring bullet from eight lines to three, keeping only the boundary-response identification, the converged-solution equivalence, and the distinction from the NTV torque.
• 101eedb3 drops a stray # Response fields in mode space [npsi, mpert] that had leaked from the struct body onto the end of the plasma_energy docstring bullet.

develop is merged in (4a3c163a); the one non-trivial overlap was in Response.jl, where develop's ffit::FourFitVars → mats::MatrixSplines rename sits two lines below the comment this PR adds. Both sides merged cleanly and the package precompiles.

⚠️ REQUIRES THIRD-PARTY HUMAN REVIEW BEFORE MERGING — NON-NEGOTIABLE.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LzbLFQKyuRE5DYZmLokKmk

[ebursch]

Approved