OpenFUSIONToolkit · matt-pharr · Jul 8, 2026 · Jul 8, 2026 · Jul 9, 2026 · Jul 9, 2026
diff --git a/.claude/agent-memory/fortran-physics-reviewer/fortran_correspondence_map.md b/.claude/agent-memory/fortran-physics-reviewer/fortran_correspondence_map.md
@@ -1,33 +1,36 @@
 ---
 name: Fortran-Julia File Correspondence Map
-description: Mapping between Fortran GPEC source files at ~/Code/gpec and Julia JPEC modules for physics review
+description: Mapping between Fortran GPEC source files and Julia JPEC modules for physics review
 type: reference
 ---
 
+Fortran paths are relative to the root of the Fortran GPEC clone; Julia paths are
+relative to this repository.
+
 ## Coil/ForcingTerms
-- `~/Code/gpec/coil/coil.F` (coil_read) -> `src/ForcingTerms/CoilGeometry.jl` (apply_transforms)
-- `~/Code/gpec/coil/field.F` (field_bs_psi) -> `src/ForcingTerms/BiotSavart.jl` + `src/ForcingTerms/CoilFourier.jl`
+- `coil/coil.F` (coil_read) -> `src/ForcingTerms/CoilGeometry.jl` (apply_transforms)
+- `coil/field.F` (field_bs_psi) -> `src/ForcingTerms/BiotSavart.jl` + `src/ForcingTerms/CoilFourier.jl`
 
 ## PerturbedEquilibrium
-- `~/Code/gpec/gpec/gpeq.f` (gpeq_sol, gpeq_contra, gpeq_surface, gpeq_normal) -> `src/PerturbedEquilibrium/FieldReconstruction.jl` + `src/PerturbedEquilibrium/ResponseMatrices.jl`
-- `~/Code/gpec/gpec/gpresp.f` (gpresp_pinduct, gpresp_sinduct, gpresp_permeab) -> `src/PerturbedEquilibrium/ResponseMatrices.jl`
-- `~/Code/gpec/gpec/gpout.f` (gpout_singcoup, gpout_xbnormal) -> `src/PerturbedEquilibrium/SingularCoupling.jl` + `src/PerturbedEquilibrium/FieldReconstruction.jl`
-- `~/Code/gpec/gpec/gpvacuum.f` (gpvacuum_flxsurf) -> `src/PerturbedEquilibrium/SingularCoupling.jl` (compute_surface_inductance_from_greens)
+- `gpec/gpeq.f` (gpeq_sol, gpeq_contra, gpeq_surface, gpeq_normal) -> `src/PerturbedEquilibrium/FieldReconstruction.jl` + `src/PerturbedEquilibrium/ResponseMatrices.jl`
+- `gpec/gpresp.f` (gpresp_pinduct, gpresp_sinduct, gpresp_permeab) -> `src/PerturbedEquilibrium/ResponseMatrices.jl`
+- `gpec/gpout.f` (gpout_singcoup, gpout_xbnormal) -> `src/PerturbedEquilibrium/SingularCoupling.jl` + `src/PerturbedEquilibrium/FieldReconstruction.jl`
+- `gpec/gpvacuum.f` (gpvacuum_flxsurf) -> `src/PerturbedEquilibrium/SingularCoupling.jl` (compute_surface_inductance_from_greens)
 
 ## KineticForces (NTV, Fortran `pentrc/`) — see kinetic_ntv_map.md for the audit checklist
-- `~/Code/gpec/pentrc/torque.F90` -> `src/KineticForces/Torque.jl` (tpsi! single-surface torque)
-- `~/Code/gpec/pentrc/pitch.f90` -> `src/KineticForces/PitchIntegration.jl` (pitch-angle lambda integration, bounce-averaged operator assembly)
-- `~/Code/gpec/pentrc/energy.f90` -> `src/KineticForces/EnergyIntegration.jl` (energy-space quadrature integrand)
-- `~/Code/gpec/pentrc/pentrc.F90` (orchestration) -> `src/KineticForces/{KineticForces.jl,Compute.jl}`
-- `~/Code/gpec/pentrc/inputs.f90` + `params.f90` -> `src/KineticForces/KineticForcesStructs.jl`
-- `~/Code/gpec/pentrc/dcon_interface.f` -> `src/KineticForces/CalculatedKineticMatrices.jl` (bridge to ForceFreeStates kinetic stability) + `src/ForceFreeStates/{Kinetic.jl,FixedKineticMatrices.jl}`
+- `pentrc/torque.F90` -> `src/KineticForces/Torque.jl` (tpsi! single-surface torque)
+- `pentrc/pitch.f90` -> `src/KineticForces/PitchIntegration.jl` (pitch-angle lambda integration, bounce-averaged operator assembly)
+- `pentrc/energy.f90` -> `src/KineticForces/EnergyIntegration.jl` (energy-space quadrature integrand)
+- `pentrc/pentrc.F90` (orchestration) -> `src/KineticForces/{KineticForces.jl,Compute.jl}`
+- `pentrc/inputs.f90` + `params.f90` -> `src/KineticForces/KineticForcesStructs.jl`
+- `pentrc/dcon_interface.f` -> `src/KineticForces/CalculatedKineticMatrices.jl` (bridge to ForceFreeStates kinetic stability) + `src/ForceFreeStates/{Kinetic.jl,FixedKineticMatrices.jl}`
 - bounce averaging of the 6 perturbed-action matrices -> `src/KineticForces/BounceAveraging.jl`
 
 ## InnerLayer (resistive matched-asymptotics, Fortran `rmatch/`) — see resistive_layer_map.md for the audit checklist
-- `~/Code/gpec/rmatch/deltac.f` (Galerkin solver) -> `src/InnerLayer/GGJ/Galerkin.jl`
-- `~/Code/gpec/rmatch/deltar.f` (shooting solver) -> `src/InnerLayer/GGJ/Shooting.jl`
-- `~/Code/gpec/rmatch/inps.f` + `inpso.f` (Wasow asymptotic basis: T,J,P,B,Q,C,D,Y,Z,U matrices) -> `src/InnerLayer/GGJ/InnerAsymptotics.jl`
-- `~/Code/gpec/rmatch/{inner.f,match.f,msing.f,gamma.f}` -> `src/InnerLayer/GGJ/` (parameters, matching data, special functions)
+- `rmatch/deltac.f` (Galerkin solver) -> `src/InnerLayer/GGJ/Galerkin.jl`
+- `rmatch/deltar.f` (shooting solver) -> `src/InnerLayer/GGJ/Shooting.jl`
+- `rmatch/inps.f` + `inpso.f` (Wasow asymptotic basis: T,J,P,B,Q,C,D,Y,Z,U matrices) -> `src/InnerLayer/GGJ/InnerAsymptotics.jl`
+- `rmatch/{inner.f,match.f,msing.f,gamma.f}` -> `src/InnerLayer/GGJ/` (parameters, matching data, special functions)
 - SLAYER drift-MHD two-fluid solver: `src/InnerLayer/SLAYER/` is a placeholder pending implementation
 
 ## Key Fortran Conventions

diff --git a/.claude/agent-memory/fortran-physics-reviewer/galerkin_assembly_map.md b/.claude/agent-memory/fortran-physics-reviewer/galerkin_assembly_map.md
@@ -49,7 +49,7 @@ lives only in match_delta (Newton eigenvalue search), NOT the RPEC path. Two iss
 Confirm intended convention vs Fortran before trusting resistive Δ(Q); ideal_flag path (γ unused) is unaffected.
 RESOLUTION 2026-06-20: author confirms the Hz convention is DELIBERATE (gal_rotation is f[Hz], so γ=2πi·n·f);
 the overstated comments were corrected. Δ(Q) now guarded by test/runtests_innerlayer.jl (Julia self-pin on
-glasser_wang_2020_eq55). Remaining follow-up (mpharr): upgrade that guard to a Fortran deltac_run / paper
+glasser_wang_2020_eq55). Remaining follow-up: upgrade that guard to a Fortran deltac_run / paper
 cross-check to fully close the convention question.
 
 ## Verdict: PASS WITH REQUIRED ANNOTATIONS for outer solve; RPEC γ convention is SHOULD-FIX (verify vs match.f).

diff --git a/.claude/agent-memory/fortran-physics-reviewer/kinetic_ntv_map.md b/.claude/agent-memory/fortran-physics-reviewer/kinetic_ntv_map.md
@@ -6,7 +6,7 @@ type: reference
 
 The KineticForces module computes neoclassical toroidal viscosity (NTV) torque and the
 kinetic energy/matrices from trapped-particle nonambipolar transport. Fortran counterpart is
-`~/Code/gpec/pentrc/` (file mapping in fortran_correspondence_map.md).
+the Fortran `pentrc/` sources (file mapping in fortran_correspondence_map.md).
 
 ## Governing theory
 - Logan & Park (2013) PoP 20, 122507: diamagnetic frequency (Eq. 7), energy integrand (Eq. 8), torque normalization Im(T) = 2n·δW_k (Eq. 19).

diff --git a/.claude/agent-memory/fortran-physics-reviewer/resistive_layer_map.md b/.claude/agent-memory/fortran-physics-reviewer/resistive_layer_map.md
@@ -7,7 +7,7 @@ type: reference
 The InnerLayer module performs matched-asymptotic analysis of resistive MHD stability at
 rational surfaces — solving the resistive inner-layer equations and computing the tearing
 stability parameter Δ via parity-projected splitting (Δ_odd, Δ_even). Fortran counterpart is
-`~/Code/gpec/rmatch/` (file mapping in fortran_correspondence_map.md).
+the Fortran `rmatch/` sources (file mapping in fortran_correspondence_map.md).
 
 ## Governing theory
 - Glasser (2016) PoP 23, 072505: computation of resistive instabilities by matched asymptotic expansions; shooting method, Frobenius exponent splitting.

diff --git a/.claude/agents/fortran-physics-reviewer.md b/.claude/agents/fortran-physics-reviewer.md
@@ -35,7 +35,7 @@ You operate under a hard budget to protect the user's token quota:
   - **KineticForces** (NTV, formerly PENTRC): Logan & Park (2013) PoP 20, 122507; Logan (2015) PhD Thesis (Ch. 7 Eqs 7.30–7.35, App. C/D); Park et al. (2009) PRL 102, 065002
   - **InnerLayer** (resistive matched-asymptotics, GGJ/SLAYER): Glasser (2016) PoP 23, 072505; Glasser (2018) PoP 25, 032501; Glasser (2020) "Asymptotic solutions and convergence studies of the resistive inner region equations"; Wang et al. (2020) PoP 27, 122509
   - **Analysis**: visualization/post-processing only — no physics kernels; verify it reads the correct HDF5 groups and applies correct conventions rather than auditing equations.
-- Locate the corresponding Fortran GPEC source at `~/Code/gpec` (ask the user for the path if not found there). KineticForces ↔ `~/Code/gpec/pentrc/`, InnerLayer ↔ `~/Code/gpec/rmatch/`. Read the relevant Fortran routines carefully. Your project memory holds a maintained correspondence map and per-domain audit checklists — consult it first.
+- Locate the corresponding Fortran GPEC source in the user's local Fortran GPEC clone (ask the user for its path). KineticForces ↔ `pentrc/`, InnerLayer ↔ `rmatch/`. Read the relevant Fortran routines carefully. Your project memory holds a maintained correspondence map and per-domain audit checklists — consult it first.
 
 ### Step 2: Read the Fortran implementation
 - Open and carefully read the relevant Fortran source files.
@@ -132,7 +132,7 @@ Examples of what to record:
 
 # Persistent Agent Memory
 
-You have a persistent, file-based memory system at `~/.claude/agent-memory/fortran-physics-reviewer/` (shared across all clones of this repo on this machine). When reading or writing files, expand `~` to the absolute home directory path (e.g. use `/Users/yourname/.claude/agent-memory/fortran-physics-reviewer/`). Create the directory if it does not exist before writing.
+You have a persistent, file-based memory system in this repository at `.claude/agent-memory/fortran-physics-reviewer/` (versioned with the repo, so findings are shared with everyone working on it). Resolve it relative to the repository root, and create the directory if it does not exist before writing.
 
 You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.
 

diff --git a/.gitignore b/.gitignore
@@ -16,9 +16,13 @@
 !docs/resources/*.pdf
 *.png
 !docs/src/assets/**/*.png
+# committed documentation figures (generated by docs/src/figures/**/make_*.jl)
+!docs/src/figures/**/*.png
 *.jld2
 .gitattributes
 Manifest.toml
+# the docs figure-provenance manifest is not a Julia Manifest.toml (case-insensitive FS collides)
+!docs/src/figures/manifest.toml
 *.log
 docs/build/
 anaconda_projects/

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -8,7 +8,7 @@ GPEC (Generalized Perturbed Equilibrium Code, Julia implementation) is a compreh
 
 **Relationship to Fortran GPEC**: This Julia GPEC is an evolution of the Fortran GPEC code suite, available at https://github.com/PrincetonUniversity/GPEC. When users reference "the Fortran code", "the original GPEC", "Fortran GPEC", or "legacy VACUUM", they are referring to that Fortran codebase — not a runtime dependency of this Julia implementation. This Julia implementation reimplements and extends GPEC's functionality with improved performance and maintainability.
 
-**Local GPEC Repository**: For code conversion or comparison with the original Fortran implementation, check for a local GPEC repository at `~/Code/gpec`. If not found at this location, ask the user for the correct path.
+**Local GPEC Repository**: For code conversion or comparison with the original Fortran implementation, a local clone of the Fortran GPEC repository is needed; ask the user for its path.
 
 ## Key References
 

diff --git a/Project.toml b/Project.toml
@@ -25,6 +25,7 @@ PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
@@ -57,14 +58,11 @@ QuadGK = "2.11.3"
 Roots = "2.2.13"
 SparseArrays = "1"
 SpecialFunctions = "2.5.1"
+Random = "1"
 StaticArrays = "1.9.15"
 Statistics = "1"
 TOML = "1"
 Test = "1"
 julia = "1.11"
 
-[extras]
-Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 
-[targets]
-test = ["Random"]
diff --git a/benchmarks/benchmark_coil_ForcingTerms_against_fortran.jl b/benchmarks/benchmark_coil_ForcingTerms_against_fortran.jl
@@ -13,7 +13,8 @@ runs the Julia Biot-Savart pipeline, and produces a 4-panel diagnostic figure:
 Usage:
     julia --project=. benchmarks/check_coil_pipeline.jl [/path/to/fortran/run]
 
-Default run directory: ~/Code/gpec/docs/examples/DIIID_ideal_example
+The Fortran run directory (a DIII-D ideal example run) is taken from the command
+line, or from the GPEC_FORTRAN_DIR environment variable if no argument is given.
 """
 
 using GeneralizedPerturbedEquilibrium
@@ -149,7 +150,8 @@ end
 # Main
 # ---------------------------------------------------------------------------
 
-run_dir = length(ARGS) > 0 ? ARGS[1] : expanduser("~/Code/gpec/docs/examples/DIIID_ideal_example")
+run_dir = length(ARGS) > 0 ? ARGS[1] : get(ENV, "GPEC_FORTRAN_DIR", "")
+isempty(run_dir) && error("No Fortran run directory given: pass it as the first argument or set GPEC_FORTRAN_DIR")
 isdir(run_dir) || error("Run directory not found: $run_dir")
 mkpath(OUTPUT_DIR)
 

diff --git a/benchmarks/benchmark_diiid_ideal_ntv_torque.jl b/benchmarks/benchmark_diiid_ideal_ntv_torque.jl
@@ -20,8 +20,8 @@ the Fortran example directory.
 Usage:
     julia --project=. benchmarks/benchmark_diiid_ideal_ntv_torque.jl [fortran_dir]
 
-    fortran_dir defaults to \$GPEC_FORTRAN_DIIID or
-    ~/Code/gpec/docs/examples/DIIID_ideal_example.
+    fortran_dir is a Fortran GPEC DIII-D ideal example run directory, taken from
+    the command line or from \$GPEC_FORTRAN_DIIID. One of the two is required.
 """
 
 using Printf
@@ -36,7 +36,9 @@ const KF = GPE.KineticForces
 const Eq = GPE.Equilibrium
 const PE = GPE.PerturbedEquilibrium
 
-const DEFAULT_FORTRAN_DIR = expanduser("~/Code/gpec/docs/examples/DIIID_ideal_example")
+"Fortran GPEC DIII-D ideal example run directory, from the environment (no on-disk default)."
+default_fortran_dir() = get(() -> error("Set GPEC_FORTRAN_DIIID, or pass the Fortran run directory as the first argument"),
+    ENV, "GPEC_FORTRAN_DIIID")
 
 """
     discover_inputs(fortran_dir) → (; eq_file, kin_file, xclebsch, pentrc_nc)
@@ -218,7 +220,7 @@ end
 _p(args...) = (println(stderr, args...); flush(stderr))
 _pf(fmt, args...) = (print(stderr, Printf.format(Printf.Format(fmt), args...)); flush(stderr))
 
-function run_benchmark(fortran_dir::String=DEFAULT_FORTRAN_DIR)
+function run_benchmark(fortran_dir::String=default_fortran_dir())
     _p("=" ^ 70)
     _p("  DIIID Kinetic Benchmark: Julia KineticForces vs Fortran PENTRC")
     _p("  Fortran example: $fortran_dir")
@@ -479,6 +481,6 @@ end
 # Run only when invoked as a script (so other benchmarks can `include()` this
 # file to reuse `load_fortran_xclebsch` without triggering the full run).
 if abspath(PROGRAM_FILE) == @__FILE__
-    fortran_dir = length(ARGS) >= 1 ? ARGS[1] : get(ENV, "GPEC_FORTRAN_DIIID", DEFAULT_FORTRAN_DIR)
+    fortran_dir = length(ARGS) >= 1 ? ARGS[1] : default_fortran_dir()
     results = run_benchmark(fortran_dir)
 end
diff --git a/benchmarks/benchmark_diiid_kinetic_stability.jl b/benchmarks/benchmark_diiid_kinetic_stability.jl
@@ -24,8 +24,8 @@ the non-Hermitian FKG reduction and the inner kinetic-matrix tolerances.
 Usage:
     julia --project=. benchmarks/benchmark_diiid_kinetic_stability.jl [fortran_dir]
 
-    fortran_dir defaults to \$GPEC_FORTRAN_DIIID_DCON or
-    ~/Code/gpec/docs/examples/DIIID_kinetic_example.
+    fortran_dir is a Fortran GPEC DIII-D kinetic example run directory, taken from
+    the command line or from \$GPEC_FORTRAN_DIIID_DCON. One of the two is required.
 """
 
 using Printf
@@ -36,7 +36,9 @@ using GeneralizedPerturbedEquilibrium
 const GPE = GeneralizedPerturbedEquilibrium
 const AnalysisFFS = GPE.Analysis.ForceFreeStates
 
-const DEFAULT_FORTRAN_DIR = expanduser("~/Code/gpec/docs/examples/DIIID_kinetic_example")
+"Fortran GPEC DIII-D kinetic example run directory, from the environment (no on-disk default)."
+default_fortran_dir() = get(() -> error("Set GPEC_FORTRAN_DIIID_DCON, or pass the Fortran run directory as the first argument"),
+    ENV, "GPEC_FORTRAN_DIIID_DCON")
 
 """
     discover_inputs(fortran_dir) → (; eq_file, kin_file, dcon_nc)
@@ -174,7 +176,7 @@ end
 _p(args...) = (println(stderr, args...); flush(stderr))
 _pf(fmt, args...) = (print(stderr, Printf.format(Printf.Format(fmt), args...)); flush(stderr))
 
-function run_benchmark(fortran_dir::String=DEFAULT_FORTRAN_DIR)
+function run_benchmark(fortran_dir::String=default_fortran_dir())
     _p("=" ^ 70)
     _p("  DIIID Kinetic-DCON Benchmark: Julia KF→FFS vs Fortran DCON")
     _p("  Fortran example: $fortran_dir")
@@ -253,7 +255,6 @@ end
 
 # Run only when invoked as a script.
 if abspath(PROGRAM_FILE) == @__FILE__
-    fortran_dir = length(ARGS) >= 1 ? ARGS[1] :
-                  get(ENV, "GPEC_FORTRAN_DIIID_DCON", DEFAULT_FORTRAN_DIR)
+    fortran_dir = length(ARGS) >= 1 ? ARGS[1] : default_fortran_dir()
     run_benchmark(fortran_dir)
 end
diff --git a/benchmarks/benchmark_solovev_kinetic_stability.jl b/benchmarks/benchmark_solovev_kinetic_stability.jl
@@ -31,10 +31,9 @@ the pre-rewrite (`ximag`) value of 34.176 was not.
 Usage:
     julia --project=. benchmarks/benchmark_solovev_kinetic_stability.jl
 
-Environment:
-    GPEC_FORTRAN_DCON   path to Fortran `dcon` (default ~/Code/gpec/bin/dcon)
+Environment (both required):
+    GPEC_FORTRAN_DCON   path to the Fortran `dcon` executable
     GPEC_FORTRAN_SOLDIR Fortran solovev_kinetic_example dir used as deck template
-                        (default ~/Code/gpec/docs/examples/solovev_kinetic_example)
 """
 
 using Printf
@@ -46,9 +45,8 @@ const GPE = GeneralizedPerturbedEquilibrium
 
 const REPO            = normpath(joinpath(@__DIR__, ".."))
 const JULIA_FIXTURE   = joinpath(REPO, "test", "test_data", "regression_solovev_kinetic_calculated")
-const FORTRAN_DCON    = get(ENV, "GPEC_FORTRAN_DCON", expanduser("~/Code/gpec/bin/dcon"))
-const FORTRAN_SOLDIR  = get(ENV, "GPEC_FORTRAN_SOLDIR",
-                            expanduser("~/Code/gpec/docs/examples/solovev_kinetic_example"))
+const FORTRAN_DCON    = get(ENV, "GPEC_FORTRAN_DCON", "")
+const FORTRAN_SOLDIR  = get(ENV, "GPEC_FORTRAN_SOLDIR", "")
 
 _p(args...) = (println(stderr, args...); flush(stderr))
 
@@ -86,7 +84,7 @@ fields that must match the Julia regression fixture (read from its `gpec.toml`
 and `sol.toml`). Converts the fixture's `kinetic.dat` into Fortran `kinetic.txt`.
 """
 function build_matched_fortran_deck(workdir::String)
-    isdir(FORTRAN_SOLDIR) || error("Fortran deck template not found: $FORTRAN_SOLDIR")
+    isdir(FORTRAN_SOLDIR) || error("Fortran deck template not found: '$FORTRAN_SOLDIR' (set GPEC_FORTRAN_SOLDIR)")
     for f in ("sol.in", "equil.in", "dcon.in", "pentrc.in", "vac.in")
         cp(joinpath(FORTRAN_SOLDIR, f), joinpath(workdir, f); force=true)
     end