PERTURBED EQUILIBRIUM - Coupling matrices and resonant vectors for singular coupling

[logan-nc]

Summary

• PerturbedEquilibriumState: Replaces zero-padded [npert, msing] arrays and legacy coupling_coefficient/resonant_amplitude fields with dense [n_rational × numpert_total] coupling matrices (C_resonant_flux, C_resonant_current, C_island_width_sq, C_penetrated_field, C_delta_prime) and applied resonant vectors [n_rational] = C · amp_vec. Adds surface metadata arrays (rational_psi, rational_q, rational_m_res, rational_n, rational_surface_idx). Matches Fortran GPEC's C_f_x_out / Phi_res output structure.
• SingularCoupling: Rewrites compute_singular_coupling_metrics! to collect all resonant (surface, n) pairs, compute full coupling rows using the off-diagonal ca_l/ca_r column (jump_vec = ca_r[:,resnum,2,s] - ca_l[:,resnum,2,s]), precompute L_surf once per pair, and apply forcing via R = C * amp_vec. Updates compute_island_diagnostics! for the new [n_rational] vector structure.
• Utils: Rewrites write_outputs_to_HDF5 to write ComplexF64 directly (no _real/_imag splits), write all C_ matrices, applied vectors, and metadata. Removes unused ctrl parameter.
• benchmarks/benchmark_fortran.jl: New script comparing Julia vs Fortran GPEC outputs using Fortran NetCDF files; reads rational_psi/rational_q for surface matching, resonant_flux as [n_rational] vector.
• benchmarks/Project.toml: Separate benchmarks project for NCDatasets (benchmark-only dependency, not in main Project.toml).

Test plan

• Run benchmark_fortran.jl against DIIID_ideal_example to confirm 4 resonant surfaces are found with matching ψ locations (--skip-run after first run)
• Verify gpec.h5 structure: perturbed_equilibrium/singular_coupling/ should contain C_resonant_flux (4,34), resonant_flux (4,), rational_psi (4,), etc.
• Merge normalizations fix branch and re-run benchmark to confirm magnitudes converge toward Fortran reference

🤖 Generated with Claude Code

[logan-nc]

Current status (bad disagreement to be fixed in the other branch)

---

GPEC Fortran vs Julia Comparison — DIIID_ideal_example

Scalar Parameters — excellent match:

  ┌────────┬──────────┬──────────┬──────┐                                                                               
  │        │ Fortran  │  Julia   │ Rel% │                                                                                 
  ├────────┼──────────┼──────────┼──────┤                                                                               
  │ psilim │ 0.991539 │ 0.991538 │ 0.0% │
  ├────────┼──────────┼──────────┼──────┤
  │ qlim   │ 5.200000 │ 5.200000 │ 0.0% │                                                                                 
  └────────┴──────────┴──────────┴──────┘                                                                                 
                                                                                                                          

W_t Eigenvalue (least stable) — 0.7% difference (very good)

q Profile RMS — 0.00% (essentially identical)

Mercier Criterion — ~1.4% RMS mismatch (small)

Resonant Surface Comparison — the coupling structure is now working (4 surfaces found, matching Fortran's 4 rational
surfaces), but magnitudes differ substantially:

  | q | psi   | Φ_res Fort | Φ_res Julia | w_isl Fort | w_isl Julia |                                               
  | 2 | 0.594 | 6.06e-4    | 5.68e-3     | 0.102      | 0.069 |                                                                       
  | 3 | 0.819 | 4.25e-4    | 1.68        | 0.066      | 0.697 |                                                                          
  | 4 | 0.928 | 8.75e-5    | 5.35        | 0.024      | 0.873 |                                                                          
  | 5 | 0.988 | 9.42e-4    | 0.348       | 0.037      | 0.099 |