Add D3D-like kinetic profiles and update example equilibrium

[d-burg]

Adds kinetic profiles and an NTV-torque demonstration to the DIII-D-like example, and fixes a grid setting that was producing inaccurate ideal stability results. Closes #268.

Changes

• New kinetic profile file (TkMkr_D3Dlike_Hmode_kinetic.gpeckf): six columns
  psi_n, n_i, n_e, T_i, T_e, omega_E.
• Replaced the example equilibrium with a new synthetic and self consistent geqdsk that uses the tokamaker DIII-D limiter and coils (toroidal field sign now negative, matching the physical DIII-D convention).
• Added a [KineticForces] section to the example gpec.toml, which turns on the NTV-torque diagnostic. The stability solve stays ideal; NTV torque is computed as a post-PE diagnostic.
• Added an NTV-torque regression quantity to the diiid_n1 case.

Grid fix

• The example used mpsi = 0 (auto), which under-resolves the edge (~11 edge points) and produced a spurious, sign-flipped delta_W and unphysical edge delta-prime (order 1e4). Switched to grid_type = "ldp" with a fixed mpsi = 256. Ideal delta_W and the inner-surface delta-prime values now agree with Fortran DCON.

Test updates

• Re-pinned the DIII-D parallel-integration regression for the corrected equilibrium and grid. et[1] and the inner-surface (q = 2, 3, 4) delta-prime are pinned tightly; the near-separatrix surfaces (q = 5, 6) are only checked for finiteness, since their values and signs are not grid-converged.

Notes

• The diiid_n1 regression baseline shifts as expected from the equilibrium and grid changes; the new values are the correct ones.
• Two follow-ups are out of scope here: the auto-mpsi edge under-resolution in the equilibrium grid builder, and more thorough testing of grid_type='log_asymptotic'

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.

This PR updates the DIII-D-like example to use a corrected, grid-converged setup and adds “D3D-like” kinetic profiles enabling an NTV-torque diagnostic/regression.

Changes:

• Update the example radial grid configuration (switch to grid_type="ldp" and fixed mpsi=256) to avoid edge under-resolution impacting δW/Δ′.
• Add a kinetic profile input file and enable [KineticForces] in the example to compute NTV torque.
• Re-pin parallel-integration and Δ′ matrix regression assertions to the corrected equilibrium/grid, and add an NTV torque regression quantity.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

File	Description
test/runtests_parallel_integration.jl	Tightens/pivots regression assertions for et[1] and Δ′ matrix real parts based on the corrected grid behavior.
regression-harness/cases/diiid_n1.toml	Adds an NTV torque quantity (FGAR) to the regression harness outputs.
examples/DIIID-like_ideal_example/gpec.toml	Switches grid settings and enables [KineticForces] for NTV torque diagnostics.
examples/DIIID-like_ideal_example/TkMkr_D3Dlike_Hmode_kinetic.gpeckf	Introduces a 6-column kinetic profile file used by the new [KineticForces] config.

[logan-nc]

Thanks @d-burg!

Two comments before doing a full review:

1. What's with this flat spot in omega_ExB? Looks odd/off. gradP is smooth, so it's not that. Must be something funky in the omega_toroidal profile?

2. I am trying to move to the new auto-grid so it is sad it didn't work well for you... but lets not just ditch it. Did you investigate the issue? The resolution is set be a parameter psi_accuracy - try scanning that to be tighter? ldp wastes a lot of points in the core

[d-burg]

Latest changes

• New HDF5 kinetic-profile format. read_kinetic_file dispatches on file
  extension; write_kinetic_h5 writes it. Datasets: psi, n_i, n_e, T_i, T_e,
  omega_E, with optional chi_e (perpendicular heat diffusivity) and chi_phi
  (toroidal momentum diffusivity), used by the resistive-layer analysis.
  Legacy 6-column ASCII (.gpeckf/.kin) still reads through the same path for
  backward compatibility.

• NTV profile loader refactored onto the new dispatcher. Verified bit-identical splines from the .h5 and the legacy .gpeckf, so NTV results are unchanged by the format switch.

• DIII-D-like example migrated to the .h5 (n, T, omega_E plus chi_e/chi_phi from transport analysis). The .gpeckf is retained for the back-compat tests.

• Example equilibrium updated to a more peaked j_phi profile, keeping the q=6 surface captured at psihigh=0.995.

• Analytic ExB rotation: omega_E = omega_tor - omega_dia, with omega_tor a smooth concave profile (107*(1-psi_N)^2 + 33 + 34*psi_N^29 krad/s) and omega_dia from n,T. omega_E decreases from +100 krad/s, crosses zero near psi_N~0.9, and dips into the pedestal, with a continuous core derivative to the axis. Replaces the raw rotation column.

• NTV torque performance: the outer psi-quadrature over-refines at the resonant rational surfaces. Interim mitigation: relaxed atol_psi/rtol_psi to 1e-2 and removed leftover per-evaluation debug prints. A proper fix (paneling the psi-integral at the rational surfaces) is tracked separately.

• Tests and docs: added HDF5 round-trip, ASCII-vs-HDF5 equivalence, writer, and missing-field testsets; re-pinned the parallel-integration regression (et[1] and the Delta-prime diagonal) for the updated equilibrium; documented the kinetic file formats.

  • NTV torque performance: the outer psi-quadrature over-refines at the resonant rational surfaces (NTV torque psi-quadrature over-refines at rational surfaces, dominating runtime #303). Interim mitigation here: relaxed atol_psi/rtol_psi to 1e-2 and removed leftover per-evaluation debug prints; the proper fix (paneling the psi-integral at rationals) is tracked in NTV torque psi-quadrature over-refines at rational surfaces, dominating runtime #303.

• The example uses a fixed mpsi (256) rather than auto mpsi and grid_type='ldp' instead of 'log_asymptotic', which under-resolved the edge and gave spurious dW/Delta-prime (auto mpsi under-resolves the edge, giving spurious dW and Delta-prime #302). Upon resolution of auto mpsi under-resolves the edge, giving spurious dW and Delta-prime #302, log_asymptotic and auto mpsi will become the default settings once more and the regression harness will need to be re-pinned.

Related issues

• auto mpsi under-resolves the edge, giving spurious dW and Delta-prime #302 auto mpsi edge under-resolution (use fixed mpsi)
• NTV torque psi-quadrature over-refines at rational surfaces, dominating runtime #303 NTV torque psi-quadrature over-refinement (interim mitigation applied)
• FreeBoundaryStability eigenmode energies written as ~0 in gpec.h5 #304 power-normalized eigenmode energies read ~0 in gpec.h5 (pre-existing
  output bug; ideal-stability physics is correct in-memory and matches DCON)

[logan-nc]

this looks very promising! I like the new rotation.

thanks for getting it together. I'll need to find time to look into the related issues, but we can get through them I'm sure. almost there!

[d-burg]

@logan-nc do we have your blessing to merge this new profile architecture, or should I run it by @matt-pharr first?

[logan-nc]

definitely get a second human to review it before merging plz. I probably won't get to read any gpec code until Thursday

[matt-pharr]

@d-burg I can review this. I want to see this so I can get profiles set up for resistive

[logan-nc]

(Updated with final numbers from #313, which panels the ψ quadrature at the rational surfaces and the located kinetic resonances Ω_ℓ(x=1)=0 for the case's full ℓ ∈ −nl:nl range.)

Ran this PR's DIII-D-like example through the #303 fix branch (PR #313). Data files from this branch (geqdsk + TkMkr_D3Dlike_Hmode_kinetic.gpeckf — the .h5 reader is PR-only so the legacy file was used), code from develop vs the fix branch.

Run	Code	atol_psi / rtol_psi	Torque (N·m)	ψ evals	KF stage	Full n=1 pipeline
pre-mitigation (#303 report)	develop	1e-3 / 1e-3	—	1375+	~30 min	—
interim (this PR)	develop	1e-2 / 1e-2	82.93 − 14.80i	345	158 s	4.0 min
same tol, atol=0	develop	0 / 1e-2	82.93 − 14.80i	345	158 s	3.1 min
#313 defaults	paneled: 5 rationals + 8 kinetic resonances	0 / 1e-2	83.16 − 14.92i	210	108 s	3.3 min
#313, tight tol	paneled: 5 rationals + 8 kinetic resonances	1e-9 / 1e-3	83.18 − 14.95i	450	296 s	5.3 min

Takeaways:

• The converged torque is ≈ 83 − 15i N·m; the KineticForces - PERFORMANCE - Panel NTV psi quadrature at rational and kinetic-resonance surfaces with rtol-primary tolerances #313 defaults land within 0.024% (Re) of the tightly-converged answer at 1.6× fewer evaluations than develop at equal tolerance — and 210 evaluations = 14 panels × 15 nodes exactly, i.e. the initial quadrature pass alone converges because the panels sit precisely on the torque-density peaks. rtol_psi = 1e-2 (~2 significant figures, the NTV model's validity limit) is the right target.
• The dominant dT/dψ structure is kinetic, not just rational: the ℓ=0 (ω_d-shifted ExB) resonance at ψ_N ≈ 0.917 and ℓ≠0 bounce resonances at 0.94/0.955/0.99 line up with the pedestal peaks (including the previously unexplained ψ_N ≈ 0.955 bump), and two near-axis ℓ≠0 surfaces explain the small ψ→0 feature. KineticForces - PERFORMANCE - Panel NTV psi quadrature at rational and kinetic-resonance surfaces with rtol-primary tolerances #313 locates all of them with the RLAR closed-form frequencies and panels them:

• The interim atol_psi = 1e-2 line is redundant: with |T| ≈ 83 N·m, rtol·|T| dominates and the atol=0 run is bit-identical. Once KineticForces - PERFORMANCE - Panel NTV psi quadrature at rational and kinetic-resonance surfaces with rtol-primary tolerances #313 merges, the atol_psi/rtol_psi lines here can simply be dropped — the new defaults do the right thing, and atol=0 also avoids the silent-underconvergence trap for weak applied fields (NTV ∝ δB², so a fixed N·m atol is amplitude-sensitive).
• Rebase heads-up: this PR's [ForceFreeStates] section sets bal_flag, mer_flag, delta_mband, and thmax0, which no longer exist on develop (local_stability_flag replaces the first two; the kwargs splat errors on unknown keys) — the TOML will need those pruned when develop is merged in.