Top level organization of unified Perturbed Equilibrium code

[logan-nc]

This branch has already merged in the changes from #118, and supersedes that PR.

I think it should be merged quickly, and not necessarily wait for full PerturbedEquilibrium functionality / benchmarking. This is because the organizational changes will quickly cause many conflicts if others are working on feature branches from the old develop. Let's get the organization reviewed by @matt-pharr and merged, then keep going on the details of the perturbed equilibrium

[logan-nc]

@claude please summarize the changes of this PR. Be succinct. Do it only once and do not repeat it when new commits are pushed unless explicitly asked to do so.

[claude]

Claude finished @logan-nc's task in 53s —— View job

---

Summary of PR Changes

This PR reorganizes JPEC to support unified perturbed equilibrium calculations with a cleaner architecture:

Major Structural Changes:

• Module Rename: DCON → ForceFreeStates (more descriptive name for stability analysis)
• New Modules: Added PerturbedEquilibrium/ (945 lines) and ForcingTerms/ for response calculations
• Config Consolidation: Replaced separate equil.toml, dcon.toml, and vac.in files with unified jpec.toml containing [Equilibrium], [WALL], [ForceFreeStates], and [PerturbedEquilibrium] sections
• Main Refactor: JPEC.jl now orchestrates full workflow: equilibrium → stability → perturbed equilibrium response

Code Organization:

• Moved all DCON functionality to src/ForceFreeStates/ with consistent naming
• Added perturbed equilibrium skeleton with data structures (PerturbedEquilibriumControl, PerturbedEquilibriumState) and core functions for plasma response and singular coupling calculations
• Updated Vacuum.jl to support new data flow

Cleanup:

• Removed 14,741-line test GEQDSK file from benchmarks (moved to external data)
• Deleted legacy config files across all examples and tests
• Removed obsolete DCON/Main.jl after migration

Documentation:

• Added PERTURBED_EQUILIBRIUM_PLAN.md and GPEC_RESPONSE_IMPLEMENTATION.md design docs
• Updated CLAUDE.md to reflect new module structure

The changes are primarily organizational to establish clean foundations for perturbed equilibrium work, with minimal functional changes to existing equilibrium/stability code.

---

Tasks

• Read key changed files to understand reorganization
• Provide succinct summary of changes
• Post summary to comment

---

[logan-nc]

As expected from #145, the large scale reorg of Vacuum in that and this branch has a lot of conflicts making the merge with develop difficult. I doubt I will get it right the first time around, so to facilitate tracking down the resulting bugs, I've compiled a summary of the Vacuum changes on each branch. On this branch the key changes are:

1. Dual Green's Function Computation (Major Feature)

• Previously: Computed only one Green's function (grri) with a single kernelsign parameter
• Now: Computes both interior (grri, kernelsign=-1) and exterior (grre, kernelsign=+1) Green's functions
• Rationale: Required for GPEC-style surface inductance calculations at singular surfaces
• API Change: compute_vacuum_response() now returns (wv, grri, grre, xzpts) instead of (wv, grri, xzpts)
• Implementation: Applies different kernel signs via apply_kernelsign!() helper function

2. New File: VacuumFromEquilibrium.jl (254 lines)

   Enables vacuum calculations at arbitrary interior flux surfaces (not just plasma edge):

• extract_plasma_surface_at_psi(): Extracts R, Z, delta, and qa from equilibrium bicubic spline at any ψ coordinate
• create_vacuum_input_at_psi(): Packages extracted geometry into VacuumInput structure
• compute_greens_functions_only(): Lightweight version that computes only Green's functions without full wv matrix
• Use case: Computing Green's functions at singular surfaces for island width diagnostics

3. Fourier Transform Refactoring

• Moved: fourier_transform!() and fourier_inverse_transform!() from VacuumInternals.jl to
  src/Utilities/FourierTransforms.jl
• Added: compute_fourier_coefficients() utility for consistent basis function calculation
• Benefit: Shared Fourier utilities across Vacuum and PerturbedEquilibrium modules
• Removed from structures: Pre-computed trigonometric basis arrays (cslth, snlth, etc.) are now computed on-demand

4. Data Structure Cleanup

   PlasmaGeometry - Removed unused fields:

• cnqd, snqd (cos/sin of nqadelta)

• sinlt, coslt, snlth, cslth (Fourier basis arrays)

  WallGeometry - Removed unused fields:

• is_closed_toroidal flag

• dx_dtheta, dz_dtheta (wall derivatives)

  VacuumInput - Removed field:

• kernelsign parameter (deprecated since both Green's functions are now computed)

5. Function Renaming (Clarity Improvement)

• set_dcon_params() → set_surface_params() (both Julia and Fortran)
• unset_dcon_params() → unset_surface_params() (both Julia and Fortran)
• Rationale: "DCON" is misleading - these functions set general surface geometry, not DCON-specific parameters

6. Module Integration

• Added imports: ..Spl, ..Equilibrium modules
• Added FourierTransforms utility import
• New exports: extract_plasma_surface_at_psi, create_vacuum_input_at_psi, compute_greens_functions_only

7. Bug Fixes

• Fixed field access and module import errors in PerturbedEquilibrium integration (commit e2f75a9)

---

Key Commits (in chronological order)

1. aae973c: JPEC - REORGANIZE - Set up module structure to integrate IPEC calculations
2. 2e24e09: VAC/PE - NEW FEATURE - Computes both Green's functions for proper GPEC surface inductance
3. f701d45: UTILITIES - NEW FEATURE - Add FourierTransforms utility for efficient theta ↔ mode transforms
4. 12b7f4b: VACUUM - REFACTOR - Use FourierTransforms utility for coefficient calculation
5. 32d4787: UTILITIES - REFACTOR - Move Vacuum's fourier_transform! functions to shared Utilities module
6. 7b64953: VACUUM - REFACTOR - Remove unused fields from PlasmaGeometry and WallGeometry
7. ee82562: PERTURBED EQUILIBRIUM - NEW FEATURE - Implement Green's functions at interior flux surfaces for singular
   coupling
8. e2f75a9: GPEC - BUG FIX - Fix multiple field access and module import errors in PerturbedEquilibrium

---

Impact

These changes enable JPEC to compute plasma response diagnostics at singular surfaces (where q = m/n), including:

• Δ' (tearing stability parameter)
• Island half-widths
• Surface inductance
• Resonant flux and currents

This is essential for GPEC-style perturbed equilibrium analysis.

[logan-nc]

On the develop branch, we had:

📁 Major Reorganization (Feb 6, 2026)

Commit: acee88e by Jake Halpern

• File Renames:
  • VacuumStructs.jl → DataTypes.jl
  • VacuumInternals.jl → Kernel2D.jl
• Code Extraction:
  • Created new MathUtils.jl (+536 lines)
  • Moved equal_arc_grid and related utilities to MathUtils
  • Prep work for future 3D vacuum capability
• Net Impact: 4 files changed, 540 insertions(+), 541 deletions(-)

🐛 Critical Bugfix (Feb 6, 2026)

Commit: d219e7a by Jake Halpern

• Fixed force_wv_symmetry function
• Bug: Incomplete Fortran-to-Julia conversion meant symmetry wasn't actually being enforced
• Impact: Vacuum.jl (-11 lines of broken code, +3 lines correct implementation)

⚡ Performance Improvements (Jan 25, 2026)

Commit: 4397e52

Critical hot-loop optimizations:

• VacuumInternals.jl (now Kernel2D.jl):
  • Create deriv1() views ONCE outside loops instead of inside nested Gaussian quadrature
  • Eliminated ~4096 allocations per call
  • Use broadcasting d1.(theta_vec) instead of comprehensions
• VacuumStructs.jl (now DataTypes.jl):
  • Same pattern fixes for wall geometry initialization
  • Broadcasting instead of comprehensions in periodic_cubic_deriv

🔧 FastInterpolations API Migration (Jan 20-25, 2026)

Series of commits migrating to FastInterpolations v0.2.4+:

1. Enhanced FastCubicSpline1D (0c23d48):
   - Removed Interpolations.jl dependency
   - Added d3_view using FastInterpolations.deriv3
   - Added search/hint kwargs for O(1) sequential lookups (2.9 ns/pt)
   - Vectorized derivative evaluation
2. Keyword BC Arguments (41c3412):
   - Changed API: FastCubicSpline1D(xs, fs, bc) → FastCubicSpline1D(xs, fs; bc=NaturalBC())
   - More consistent with underlying FastInterpolations API
3. Removed Wrapper Types (72ebf03):
   - Eliminated FastCubicSpline1D and FastCubicSpline1DMulti wrappers
   - Use native CubicInterpolant API directly
   - Simplified abstraction layer

📝 Minor Documentation (Jan 12, 2026)

Commit: 2bb45b7

• Added warning annotation about x<0 wall geometry gotchas

[logan-nc]

@jhalpern30 this is pretty much ready and runs the stability part of the examples fine.
Unfortunately, it is giving me dW = 1.744 for the DIII-D-like example when the develop branch is 1.707. It looks like both the plasma and the vacuum are off:

This branch gives

Least Stable Eigenmode Energies:
  Plasma = +9.069e-02 +2.895e-05i
  Vacuum = +1.653e+00 -6.301e-17i
  Total  = +1.744e+00 +2.895e-05i
All free-boundary modes stable for n = 1.

The develop branch gives

Least Stable Eigenmode Energies:
  Plasma = -3.475e-02 +1.911e-05i
  Vacuum = +1.742e+00 -8.452e-17i
  Total  = +1.707e+00 +1.911e-05i
All free-boundary modes stable for n = 1.

Can you (a) skim through the ForceFreeStates and Vacuum changes to make sure my reorganizations play well with yours and (b) keep an eye out for my bug while you do so?

Thanks!

[logan-nc]

It works!
This branch solovev example:

Least Stable Eigenmode Energies:
  Plasma = -1.102e+01 +5.192e-06i
  Vacuum = +1.058e+01 -1.208e-17i
  Total  = -4.372e-01 +5.192e-06i
Free-boundary mode unstable for n = 1.
Writing saved data to jpec.h5

============================================================
Run time: 1.206e+01 seconds
Normal termination.
============================================================

On develop:

Least Stable Eigenmode Energies:
  Plasma = -1.102e+01 +5.192e-06i
  Vacuum = +1.058e+01 +1.166e-17i
  Total  = -4.372e-01 +5.192e-06i
Free-boundary mode unstable for n = 1.
Writing saved data to euler.h5
----------------------------------
Run time: 1.011e+01 seconds
Normal termination.

[logan-nc]

@jhalpern30 @mfairborn23 have fun merging develop into your branches! It's a big one, but it'll be worth it in the end. This officially makes us a unified perturbed equilibrium code. The structure no longer has main routines in sub directories - there is one main function at the top level. So we now run the code like so:

$ julia
julia> using Pkg; Pkg.activate("./"); using Revise; using JPEC
julia> JPEC.main(["examples/DIIID-like_ideal_example/"]);