Merge branch 'develop' into bugfix/kf-periodic-vpar-spline

Author: logan-nc

src/PerturbedEquilibrium/PerturbedEquilibriumStructs.jl

@@ -144,8 +144,10 @@ well-conditioned flux-space inductances L, Λ:
 
   - `vacuum_energy`  - Re( ⟨Φ_x,  L⁻¹·Φ_x⟩ ) / 4   (energy to perturb the vacuum)
   - `surface_energy` - Re( ⟨Φ_tot, L⁻¹·Φ_tot⟩ ) / 4 (energy at the control surface)
-  - `plasma_energy`  - Re( ⟨Φ_tot, Λ⁻¹·Φ_tot⟩ ) / 4 (energy to perturb the plasma; Fortran's "total energy")    # Response fields in mode space [npsi, mpert]
-  - `toroidal_torque` - -2·n·Im( ⟨Φ_tot, Λ⁻¹·Φ_tot⟩ / 4 )
+  - `plasma_energy`  - Re( ⟨Φ_tot, Λ⁻¹·Φ_tot⟩ ) / 4 (energy to perturb the plasma; Fortran's "total energy")
+  - `toroidal_torque` - -2·n·Im( ⟨Φ_tot, Λ⁻¹·Φ_tot⟩ / 4 ) — the boundary-response torque, zero for ideal
+    (Hermitian) runs. Equals the volume-integrated Euler-Lagrange kinetic torque only for converged
+    self-consistent solutions, and is a distinct construction from the KineticForces NTV torque.
 """
 @kwdef mutable struct PerturbedEquilibriumState
     # Radial grid (FFS ODE integration ψ_n values) [npsi]

src/PerturbedEquilibrium/Response.jl

@@ -95,6 +95,8 @@ function compute_plasma_response!(
     state.vacuum_energy = real(vy)
     state.surface_energy = real(sy)
     state.plasma_energy = real(py)              # Fortran's "total energy" is this pengy
+    # Boundary-response torque: distinct construction from the KineticForces NTV torque —
+    # see the PerturbedEquilibriumState docstring for the delineation of GPEC torque outputs.
     state.toroidal_torque = -2 * nn * imag(py)
 
     xi_modes, b_modes = reconstruct_physical_fields(

src/PerturbedEquilibrium/Utils.jl

@@ -345,7 +345,10 @@ const PE_H5_ANNOTATIONS = [
     "Energies/vacuum_energy" => (; long_name="perturbed vacuum energy", units="J"),
     "Energies/surface_energy" => (; long_name="perturbed surface energy", units="J"),
     "Energies/plasma_energy" => (; long_name="perturbed plasma energy", units="J"),
-    "Energies/toroidal_torque" => (; long_name="net toroidal torque on the plasma", units="N*m")
+    "Energies/toroidal_torque" => (;
+        long_name="boundary-response toroidal torque −2n·Im⟨Φ_tot,Λ⁻¹Φ_tot⟩/4: equals the volume-integrated Euler-Lagrange kinetic torque for converged self-consistent solutions; distinct construction from the KineticForces NTV torque",
+        units="N*m"
+    )
 ]
 
 # Attach long_name/units/dims + dimension scales (declared in-table) to the