Loop boundary conditions from Eq. (37) through Riccati.jl

.claude/agent-memory/fortran-physics-reviewer/MEMORY.md

@@ -4,3 +4,4 @@
 - [Known Physics Issues in PerturbedEquilibrium](known_issues_perteq.md) — xss_mn not implemented, xi_modes placeholders
 - [KineticForces (NTV) Audit Checklist](kinetic_ntv_map.md) — pentrc->KineticForces map, Logan 2015 matrices, what to verify
 - [InnerLayer (Resistive) Audit Checklist](resistive_layer_map.md) — rmatch->InnerLayer map, GGJ Wasow basis / Δ′, what to verify
+- [Galerkin Δ′ Assembly Map](galerkin_assembly_map.md) — gal.f<->GalerkinAssembly.jl; resonant sign chain verified; PASS

.claude/agent-memory/fortran-physics-reviewer/galerkin_assembly_map.md

@@ -0,0 +1,83 @@
+---
+name: galerkin-assembly-map
+description: RDCON singular Galerkin Δ′ solver — gal.f ↔ GalerkinAssembly.jl element-level weak-form correspondence and audit notes
+metadata:
+  type: project
+---
+
+# RDCON Galerkin Δ′ assembly: gal.f ↔ GalerkinAssembly.jl
+
+File: `src/ForceFreeStates/Galerkin/GalerkinAssembly.jl` ↔ `GPEC_fortran/rdcon/gal.f`.
+On branch `feature/rdcon-galerkin`. Reviewed 2026-06-16.
+
+## Correspondence (verified, not just docstring-trusted)
+- gal_hermite (222-262) ↔ gal_hermite: pb/qb EXACT.
+- gal_get_fkg (1013-1071) ↔ gal_get_fkg: F=Fbar·sf[i]·sf[j], K=K·sf[i], G=G. singfac=mlow-nn*q+(0..mpert-1) = DIRECT (m-nq), not reciprocal. Correct.
+- gal_gauss_quad (1079-1138) ↔ gal_gauss_quad!: F·qq + K·qp + conj(K[jpert,ipert])·pq + G·pp. swap pb(2)/pb(3) (0-based) = Julia pb[3]/pb[4]. Correct.
+- gal_extension (1146-1322) ↔ gal_extension!: emat/ediag/rhs/erhs all match incl surface terms 1277-1300 and w1/w2.
+- gal_resonant! ↔ gal_lsode_int(780-900)+gal_lsode_der(908-954)+gal_make_arrays signs(1366-1369). QuadGK replaces LSODE.
+- gal_assemble_mat (694-772) ↔ gal_assemble_mat!: LU offset=kl+ku+1, chol offset=1, conj(e) Hermitian placement. Correct.
+- gal_assemble_rhs (642-686) ↔ gal_assemble_rhs!: isol++ at ext2-left / res-right. Correct.
+- gal_set_boundary (1554-1620) ↔ gal_set_boundary!: axis idx, edge 3-way (rpec/vac/fixed). DOF index 3(0-based)=Julia 4.
+
+## Resonant sign chain (the trap — verified correct)
+Fortran: LSODE integrates x0→x_lsode giving raw u; then line 882 `IF right: u=-u`; then make_arrays:
+erhs=-u_res(1), ediag=+u_res(2), rhs=-u_hermite1, emat=+u_hermite2.
+Net with s=+1(left)/-1(right): erhs=-s·res1, ediag=s·res2, rhs=-s·hbig, emat=s·hsmall.
+Julia sgn_u = s (=-1 right/+1 left): erhs=-sgn_u·raw1, ediag=sgn_u·raw2, rhs=-sgn_u·hbig, emat=sgn_u·hsmall. MATCHES.
+QuadGK limits x0→x_lsode preserve LSODE orientation so raw == pre-negation u. Correct.
+du_res conj-weight uses the SMALL solution (isol(2)) in both. Correct.
+
+## Only open item (MINOR, out-of-file)
+sing_get_ua_gal/dua_gal two-sided z<0 → sig=-1 series at -z with derivative ×(-1) is a REIMPLEMENTATION
+of sing.f's internal singular-surface handling, not a line port. The ×(-1) chain is internally consistent
+but worth a dedicated check against sing.f sing_get_ua/dua if Δ′ ever disagrees with Fortran. Lives outside
+GalerkinAssembly.jl.
+
+## RPEC matching (GalerkinMatch.jl <-> rmatch/match.f match_rpec) — reviewed 2026-06-20
+- match block (mat idx1..idx4, -delta1/delta2 signs) + rmat=-TRANSPOSE(delta coil block) + cout/cin split: EXACT port. PASS.
+- matched outer soln Σcout(isol)·sols + sols(:,:,csol): EXACT (match_output_solution L32-41).
+- resist.f E/F/H/M/G/K/taua/taur/v1: EXACT (Resist.jl). eta/rho caller-supplied = deliberate documented deviation.
+- gal quadrature: jacobi_alloc "gll" = Gauss-Lobatto = Julia gausslobatto. nq1 lower=|nn·q1|, upper=|q1|: match.
+
+## SUSPECT (should-fix) — RPEC forced eigenvalue γ
+GalerkinMatch.jl:66 uses γ = 2π·im·n·gal_rotation. Fortran match_rpec passes `initguess` (namelist,
+default 0.0) DIRECTLY to deltac_run — NOT i·n·rotation. The `guess+ifac*ntor*rotation` Doppler form
+lives only in match_delta (Newton eigenvalue search), NOT the RPEC path. Two issues:
+  (1) extra 2π: Fortran eig=ifac*ntor*rotation has NO 2π (rotation is ω[rad/s], eig is 1/time, q0=x0/taua).
+  (2) RPEC path in Fortran uses initguess (the user forced eigenvalue), not a per-surface i·n·rotation shift.
+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
+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).
+
+
+# Second pass
+
+
+## PR #266 "Galerkin Integrator" full review (2026-06-25) — PASS
+Exhaustive line-by-line vs gal.f / match.f / deltac.f / resist.f / sing.f. All physics-bearing code faithful.
+- RESOLVED (was SUSPECT): forced eig γ=2πi·n·rotation IS correct. match.f match_rpec line:
+  `rpec_eigenvalues(ising)=2*pi*rotation(ising)*REAL(ntor,r8)*ifac` — the 2π IS in Fortran. Julia matches exactly.
+  My earlier "no 2π in Fortran" note was wrong (confused match_delta Newton path with match_rpec). Closed.
+- Verified EXACT: gal_get_fkg (F=QF̄Q,K=QK̄,G=Ḡ,singfac=m-nq), gauss_quad weak form (F qq+K qp+K† pq+G pp),
+  gal_extension, gal_resonant (mpert-fastest hermite layout; Fortran's apparent (0:np,mpert,2) reshape is a
+  no-op relabel — der writes mpert-fastest, caller reads mpert-fastest), assemble_mat/rhs, set_boundary,
+  gal_get_solution (restore_uh/us/ul), PEST-3 A/B/Γ/Δ ± combos, Δ′ extraction, match_rpec matrix signs,
+  resist_eval E/F/G/H/K/M/taua/taur, mercier_di=E+F+H-1/4, rescale=sfac^(2p1/3)·v1^(2p1) + delta(1)↔(2) swap
+  (swap applied in BOTH solve_inner and solve_inner_profile), sing_matvec, sing_get_dua, ξ_s=-A⁻¹(Bξ'+Cξ).
+- Documented deviations (all fine): η/ρ caller-supplied (no Spitzer); gal_gamma default 5/3 = resist.f;
+  QuadGK replaces LSODE; sing_get_dua omits Fortran `sig` (moved to sing_get_dua_gal left-side ×(-1)).
+- InnerAsymptotics.jl + Shooting.jl diffs = PURE JuliaFormatter whitespace, zero numeric change.
+- Reference.jl G=8.950e1,H=1.292e-2,K=2.332e2 = corrected GW2020 Eq.55 (prior transcription bug fixed).
+
+## OPEN ITEM (latent, n≥2 only): gal_make_grid resonant-cell width asymmetry
+gal.f gal_make_grid genuinely uses nq1=ABS(nn*sing(ising)%q1) on the LOWER bound but nq1=ABS(sing(ising+1)%q1)
+(NO nn) on the UPPER bound. Julia GalerkinGrid.jl faithfully reproduces. Natural layer scale is 1/(n q1) on BOTH
+sides (singfac'≈-n q1), so the upper/left side of each interior surface gets cells ~n× too wide for n≥2.
+No effect at n=1 (RDCON resistive target). galerkin_solve allows single n≥2 (blocks only multi-n npert>1), so it
+IS reachable. Recommend: keep faithful but warn, or fix both sides to nn*q1 (deviation, more correct) gated by
+validation. Suspected upstream Fortran oversight, not a Julia port error.

.gitignore

@@ -1,3 +1,4 @@
+.codex
 *.cov
 *.mod
 *.dylib
@@ -7,11 +8,14 @@
 *.i
 *.out
 *.h5
+# kinetic-profile inputs are tracked despite the blanket *.h5 (output) ignore
+!examples/**/*kinetic*.h5
 .vscode
 *.DS_Store
 *.pdf
 !docs/resources/*.pdf
 *.png
+!docs/src/assets/**/*.png
 *.jld2
 .gitattributes
 Manifest.toml

CLAUDE.md

@@ -61,6 +61,11 @@ The PerturbedEquilibrium module implements GPEC-style perturbed equilibrium calc
   - Published: Physical Review Letters **99**, 195003 (2007)
   - Describes: Plasma response to resonant magnetic perturbations (RMP)
 
+- **Park et al. (2008)**: "Spectral asymmetry due to magnetic coordinates"
+  - Location: `docs/resources/2008-Park-Spectral_asymmetry_due_to_magnetic_coordinates.pdf`
+  - Published: Physics of Plasmas **15**, 064501 (2008)
+  - Describes: Coordinate-dependence of the perturbed-field Fourier spectrum, motivating area-normalization of the resonant harmonic to obtain the coordinate-invariant resonant field
+
 - **Park et al. (2009)**: "Importance of plasma response to nonaxisymmetric perturbations in tokamaks"
   - Location: `docs/resources/2009-Park-Importance_of_plasma_response_to_nonaxisymmetric_perturbations_in_tokamaks-compressed.pdf`
   - Published: Physics of Plasmas **16**, 056115 (2009)
@@ -373,7 +378,7 @@ GPEC consists of **seven main modules** organized in `src/`:
      - `Fourfit.jl` - Fourier fitting routines
      - `FixedBoundaryStability.jl` - Fixed boundary analysis
      - `Free.jl` - Free boundary stability
-     - `Mercier.jl` - Mercier stability criterion
+     - `Ballooning.jl` - Local stability scan: Mercier D_I, resistive interchange D_R, and high-n ballooning Δ' (s–α). Replaces the former standalone `Mercier.jl`.
    - Status: Stable, core DCON functionality implemented
 
 #### Perturbed Equilibrium Modules
@@ -617,6 +622,13 @@ Every consultation is bounded — see **Subagent Consultations** under Important
 - **Documentation coverage** - When adding a new module or submodule with public docstrings, add a corresponding `@autodocs` block in `docs/src/`. Documenter CI will fail with a `missing_docs` error if any exported docstring is not covered. The analysis submodule docs live in `docs/src/analysis.md`.
 - **Docstrings are rendered as Markdown** - Documenter parses docstrings as CommonMark, so `[text](...)` patterns become hyperlinks and will fail CI with `invalid local link/image` if the target doesn't exist. Common pitfall: unit annotations like `[degrees] (or [m] if ...)` parse as `[degrees](or [m] if ...)` — a broken link. Use plain words (`in degrees`) or backticks (`` `[m]` ``) for unit labels inside docstrings. Same rule for bracketed array-shape hints (`[ncoil]`) followed by parentheses. When in doubt, preview with `julia --project=docs docs/make.jl` before pushing.
 - **Keep code comments concise** - A comment should be one line where possible. Do not write multi-line block comments explaining the current session's investigation, what was tried, what was wrong before, or why a specific file/path behaves differently. State what the code does and why at a general level. Example of too much detail: a 6-line block explaining that efit_by_inversion uses psilow>0 while CHEASE starts at 0, that the old code was removed, and that spline spikes result. Preferred: `# Replicate Fortran inverse.f: overwrite deta at axis (r²=0) by extrapolating from innermost surfaces.`
+- **No PR/issue references in source** - Do not cite specific GitHub PR or issue numbers (e.g. `#171`, `#202`) in source or test comments/docstrings. During dynamic development these references quickly go stale and pollute the code. Just concisely state the objective or what the code does; the git history and PR threads track the provenance.
+- **Document struct fields in the docstring, not inline** - When adding a field to a struct, put its description in the struct's `## Fields` docstring rather than (or in addition to) a trailing inline comment, and document any non-obvious contract (e.g. which keys a `Dict`/ingest carries per variant). Do not annotate outer constructors with positional-argument counts ("passes 11 positional args") — those rot when a field is added; describe the intent instead.
+
+### Minimal-change discipline
+- **Reuse native ops and existing utilities before writing new ones.** FastInterpolations splines integrate and differentiate natively (`integrate`, `cumulative_integrate`, `deriv1`); the Equilibrium module already has flux-surface integration/average patterns. Do not reimplement spline integration, quadrature, or differentiation — grep for the existing idiom first.
+- **Size the change to the problem.** A small numerical correction (e.g. a ~1% fix) should be a handful of lines, not new general-purpose machinery. Resist faithfully porting Fortran scaffolding (custom integrators, power-law spline bases) when a native call plus a one-line correction gives the same numbers — verify equivalence instead of assuming the elaborate version is needed.
+- **Don't commit throwaway artifacts for minor fixes.** No in-repo benchmark scripts/outputs or agent-memory churn for a small change — these accumulate and outsize `src`. Verify with a scratch script (e.g. under `/tmp`) and the regression harness; the regression harness is the durable record of numerical behavior.
 
 ### Output Files
 - **Default output**: `gpec.h5` (previously `euler.h5` in older versions)
@@ -671,6 +683,43 @@ Additional file hygiene (enforced by pre-commit hooks):
 - Files must end with exactly one newline
 - LF line endings only (no CRLF)
 
+### TOML Annotation Conventions
+
+Config-style TOML files (`examples/*/gpec.toml`, `examples/*/sol.toml`, the
+`test/test_data/*` fixtures, and `regression-harness/cases/*.toml`) follow one shared
+annotation style so they stay consistent and self-documenting for users who copy and
+modify them. **Do not invent a new convention** — match what the existing example files do.
+
+1. **File header (2–10 lines).** Begin each config-style TOML with a plain `#` comment block
+   stating the example's purpose/context and calling out key settings (wall choice, forcing,
+   n-range, ideal vs kinetic). No ASCII-art separators or decorative dividers.
+2. **Inline annotation on every variable line.** Every `key = value` gets a trailing
+   `# description`. Source the wording from the matching config struct's docstring
+   (`EquilibriumConfig`, `WallShapeSettings`, `ForceFreeStatesControl`, `ForcingTermsControl`,
+   `PerturbedEquilibriumControl`, `SolovevConfig`, `TJAnalyticConfig`, `KineticForcesControl`)
+   and keep it to one terse line. **Use the same description for the same variable across all
+   files** — `examples/DIIID-like_ideal_example/gpec.toml` is the canonical reference for the
+   common sections.
+3. **Section comments only when informative.** No comment is required above a section. Keep a
+   block comment only when it carries real information (e.g. the Solovev `[Wall]` note on why a
+   conformal wall is needed). Never add decorative section dividers.
+4. **No Fortran references — annotations must be self-contained and Julia-centric.** The Julia
+   code is the production workhorse; a new user must not need to know the legacy Fortran GPEC
+   code to read an example. Headers explain the *scenario and its unique aspect*; inline comments
+   explain the *variable*. Do **not** cite Fortran namelist files (`dcon.in`/`equil.in`/`pentrc.in`),
+   Fortran flag names (`kin_flag`, `sas_flag`, `electron_flag`, …), or legacy code names
+   (`DCON`/`STRIDE`/`PENTRC`) as things the reader must know. Non-Fortran external-model citations
+   (e.g. the analytic TJ model behind `tj_analytic`) are acceptable provenance. (This applies to
+   the user-facing `examples/*` and `test/test_data/*` TOMLs; `regression-harness/cases/*` may
+   retain algorithm names as developer metadata.)
+5. **Only active, meaningful variables in examples.** Do not set deprecated or "not yet
+   implemented" variables just to mirror defaults — they add clutter and imply false relevance
+   (e.g. the `truncate_at_dW_peak` edge-peak truncation, `thmax0`). Omit them so examples show
+   only knobs that do something on that run.
+6. **`Project.toml`-family files are exempt.** `Project.toml`, `docs/Project.toml`,
+   `regression-harness/Project.toml`, and `.JuliaFormatter.toml` are machine-managed; do not
+   inline-annotate dependency UUIDs or `[compat]` entries.
+
 ### Performance
 - Pure Julia implementations are available for all major components and offer comparable or better performance than Fortran
 - Benchmarks available in `benchmark/` directory for Fourier transforms and vacuum calculations