macOS installation instructions

.claude/agents/clean-code-reviewer.md

@@ -20,7 +20,7 @@ You adhere strictly to:
 
 **Context awareness**: You are working with JPEC, a Julia/Fortran hybrid codebase for MHD equilibrium and stability analysis. Consider:
 - Julia 1.11 conventions and idioms
-- The existing module structure (Splines, Equilibrium, Vacuum, DCON)
+- The existing module structure (Splines, Equilibrium, Vacuum, ForceFreeStates, ForcingTerms, PerturbedEquilibrium)
 - The ongoing Fortran-to-Julia conversion effort
 - The need for parity between Fortran and Julia implementations
 
@@ -93,6 +93,6 @@ For each issue, provide:
 - Follow the commit message format: `MODULE - TAG - Detailed message`
 - Be aware of 0-based to 1-based indexing conversions from Fortran
 - Ensure compatibility with the existing test structure in `test/`
-- Consider whether changes affect diagnostic outputs (gsec.h5, gse.h5, gsei.h5)
+- Consider whether changes affect diagnostic outputs (jpec.h5, and legacy files gsec.h5, gse.h5, gsei.h5)
 
 Your goal is to help create code that a fusion physicist with moderate Julia experience can read, understand, and maintain confidently.

.claude/agents/julia-performance-optimizer.md

@@ -1,6 +1,6 @@
 ---
 name: julia-performance-optimizer
-description: Use this agent when you need to optimize Julia code for maximum performance. Specifically:\n\n<example>\nContext: User has written a function that processes large arrays and suspects it could be faster.\nuser: "I wrote this function to compute pairwise distances but it's really slow on large datasets:\n\nfunction pairwise_distances(points)\n    n = length(points)\n    distances = []\n    for i in 1:n\n        for j in 1:n\n            d = sqrt(sum((points[i] .- points[j]).^2))\n            push!(distances, d)\n        end\n    end\n    return distances\nend\n\nCan you help optimize it?"\nassistant: "I'll use the julia-performance-optimizer agent to analyze and optimize this code for maximum performance."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>\n\n<example>\nContext: User has completed implementing a new ODE solver in JPEC and wants to ensure it's optimally performant.\nuser: "I just finished implementing the new stability ODE solver in src/DCON/Ode.jl. Here's the core integration loop:\n\nfunction integrate_stability_equation(psi_grid, q_profile, omega)\n    results = []\n    for i in 1:length(psi_grid)\n        # Complex calculation here\n        val = compute_eigenvalue(psi_grid[i], q_profile, omega)\n        push!(results, val)\n    end\n    return results\nend\n\nCan you review it for performance?"\nassistant: "Let me use the julia-performance-optimizer agent to analyze this code and identify any performance bottlenecks specific to your ODE solver implementation."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>\n\n<example>\nContext: User is proactively seeking optimization after writing vacuum response calculations.\nuser: "I've converted the vacuum wall geometry calculation from Fortran to Julia in src/Vacuum/Vacuum_vac.jl. The function works correctly and passes tests, but I want to make sure it's as fast as the Fortran version."\nassistant: "Excellent - let me use the julia-performance-optimizer agent to analyze your converted code and ensure it matches or exceeds the Fortran performance."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>\n\n<example>\nContext: User mentions performance concerns during code discussion.\nuser: "The bicubic spline interpolation in src/Splines/BicubicSpline.jl seems slower than expected when evaluating on dense grids."\nassistant: "I'll launch the julia-performance-optimizer agent to profile the bicubic spline code and identify optimization opportunities."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>
+description: Use this agent when you need to optimize Julia code for maximum performance. Specifically:\n\n<example>\nContext: User has written a function that processes large arrays and suspects it could be faster.\nuser: "I wrote this function to compute pairwise distances but it's really slow on large datasets:\n\nfunction pairwise_distances(points)\n    n = length(points)\n    distances = []\n    for i in 1:n\n        for j in 1:n\n            d = sqrt(sum((points[i] .- points[j]).^2))\n            push!(distances, d)\n        end\n    end\n    return distances\nend\n\nCan you help optimize it?"\nassistant: "I'll use the julia-performance-optimizer agent to analyze and optimize this code for maximum performance."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>\n\n<example>\nContext: User has completed implementing a new ODE solver in JPEC and wants to ensure it's optimally performant.\nuser: "I just finished implementing the new stability ODE solver in src/ForceFreeStates/Ode.jl. Here's the core integration loop:\n\nfunction integrate_stability_equation(psi_grid, q_profile, omega)\n    results = []\n    for i in 1:length(psi_grid)\n        # Complex calculation here\n        val = compute_eigenvalue(psi_grid[i], q_profile, omega)\n        push!(results, val)\n    end\n    return results\nend\n\nCan you review it for performance?"\nassistant: "Let me use the julia-performance-optimizer agent to analyze this code and identify any performance bottlenecks specific to your ODE solver implementation."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>\n\n<example>\nContext: User is proactively seeking optimization after writing vacuum response calculations.\nuser: "I've converted the vacuum wall geometry calculation from Fortran to Julia in src/Vacuum/Vacuum_vac.jl. The function works correctly and passes tests, but I want to make sure it's as fast as the Fortran version."\nassistant: "Excellent - let me use the julia-performance-optimizer agent to analyze your converted code and ensure it matches or exceeds the Fortran performance."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>\n\n<example>\nContext: User mentions performance concerns during code discussion.\nuser: "The bicubic spline interpolation in src/Splines/BicubicSpline.jl seems slower than expected when evaluating on dense grids."\nassistant: "I'll launch the julia-performance-optimizer agent to profile the bicubic spline code and identify optimization opportunities."\n<tool use with Task tool to launch julia-performance-optimizer agent>\n</example>
 model: opus
 color: green
 ---
@@ -82,7 +82,7 @@ When presented with code to optimize, follow this structured approach:
 You are working on JPEC, a scientific computing codebase for MHD equilibrium and stability analysis:
 
 - Target Julia version: 1.11
-- Key modules: Splines, Equilibrium, Vacuum, DCON
+- Key modules: Splines, Equilibrium, Vacuum, ForceFreeStates, ForcingTerms, PerturbedEquilibrium
 - Often deals with large numerical arrays and spline interpolations
 - Performance parity with legacy Fortran code is important
 - Many functions use 0-based indexing converted to 1-based Julia indexing

.github/copilot-instructions.md

@@ -1,21 +1,23 @@
 # Copilot instructions for JPEC
 
 ## Project overview
-- JPEC is a Julia/Fortran hybrid port of GPEC for MHD equilibrium and stability analysis. Core modules live in [src](src): Splines, Equilibrium, Vacuum, DCON (see [CLAUDE.md](CLAUDE.md)).
+- JPEC is a Julia/Fortran hybrid port of GPEC for MHD equilibrium and stability analysis. Core modules live in [src](src): Splines, Equilibrium, Vacuum, ForceFreeStates, ForcingTerms, PerturbedEquilibrium (see [CLAUDE.md](CLAUDE.md)).
 - Data flow: equilibrium setup → vacuum response → stability analysis (documented in [CLAUDE.md](CLAUDE.md)).
 - Vacuum is mid-conversion from Fortran to Julia; Fortran libraries are built and called via `ccall` (see [deps/build.jl](deps/build.jl)).
 
 ## Architecture and entry points
+- Main entry point: `JPEC.main()` in [src/JPEC.jl](src/JPEC.jl).
 - Equilibrium: `setup_equilibrium(path|config)`; types in [src/Equilibrium](src/Equilibrium).
 - Vacuum: `compute_vacuum_response()` (Julia) and `mscvac()` (Fortran); code in [src/Vacuum](src/Vacuum) and [src/Vacuum/fortran](src/Vacuum/fortran).
-- DCON stability: entry points in [src/DCON/Main.jl](src/DCON/Main.jl).
+- ForceFreeStates (ideal MHD stability): types and functions in [src/ForceFreeStates](src/ForceFreeStates).
+- PerturbedEquilibrium (plasma response): entry point in [src/PerturbedEquilibrium](src/PerturbedEquilibrium).
 - Splines: Julia + Fortran implementations in [src/Splines](src/Splines).
 
 ## Data flow and key structures
 - Equilibrium: TOML config → read equilibrium → solve → diagnostics (gse*.h5) when relevant.
 - Vacuum: initialize plasma/wall surfaces → compute response matrix → return wv, grri, xzpts.
 - Stability: equilibrium + vacuum response → integrate ODEs → compute energies.
-- Core types: `PlasmaEquilibrium` and `EquilibriumConfig` in [src/Equilibrium/EquilibriumTypes.jl](src/Equilibrium/EquilibriumTypes.jl); `DconControl` in [src/DCON/DconStructs.jl](src/DCON/DconStructs.jl).
+- Core types: `PlasmaEquilibrium` and `EquilibriumConfig` in [src/Equilibrium/EquilibriumTypes.jl](src/Equilibrium/EquilibriumTypes.jl); `ForceFreeStatesControl` and `ForceFreeStatesInternal` in [src/ForceFreeStates/ForceFreeStatesStructs.jl](src/ForceFreeStates/ForceFreeStatesStructs.jl).
 
 ## Build, test, docs
 - Build Fortran libraries:
@@ -48,7 +50,8 @@
 - Add new Fortran builds via `build_*_fortran()` in [deps/build_helpers.jl](deps/build_helpers.jl).
 
 ## Configuration examples
-- TOML configs: `equil.toml` uses `[EQUIL_CONTROL]` and `[EQUIL_OUTPUT]`; `dcon.toml` uses `[DCON_CONTROL]` and `[WALL]`.
+- Unified configuration: `jpec.toml` uses `[Equilibrium]`, `[Wall]`, `[ForceFreeStates]`, `[PerturbedEquilibrium]`, and `[ForcingTerms]` sections.
+- Legacy configs (`equil.toml`, `dcon.toml`, `vac.in`) are deprecated.
 - Example configs in [examples/DIIID-like_ideal_example](examples/DIIID-like_ideal_example) and [examples/Solovev_ideal_example](examples/Solovev_ideal_example).
 
 ## Development tips

CLAUDE.md

@@ -76,7 +76,7 @@ The PerturbedEquilibrium module implements GPEC-style perturbed equilibrium calc
   - Published: Physics of Plasmas **24**, 032505 (2017)
   - Describes: Self-consistent coupling with neoclassical effects
 
-### Resistive DCON Module (Future Work)
+### Resistive MHD Stability Analysis (Future Work)
 
 JPEC will eventually implement resistive MHD stability analysis based on: