InnerLayer (GGJ) - NEW - rotated-ray collocation backend (:ray), robust to |Q| ~ 500

[matt-pharr]

Summary

Adds a third interchangeable solver to the GGJ inner-layer model — GGJModel{:ray} — and makes it the default. It returns the same parity-projected matching data (Δ₁, Δ₂) in the same deltac convention as :galerkin and :shooting, but remains accurate far into the regime where both existing backends fail: validated to Q = 500i, the territory resistivity scans (|Q| ∝ η^(−1/3)) and rotation physics actually visit.

Method (one paragraph)

The layer equations are continued analytically onto the complex ray x = e^{iθ}s with θ = arg(Q)/4, which makes the parabolic-cylinder WKB exponent exactly real (no oscillation along the contour) and moves the coefficient pseudo-resonance x² ≈ −Q²(G+KF) — which sits on the real axis for imaginary Q — off the path. Δ is an analytic invariant of the contour angle within the Stokes sector, which doubles as a built-in error diagnostic (outward θ-consistency check). On [0, s_m] a global Chebyshev spectral-element collocation BVP is solved in plain variables with parity conditions at the origin and (Δ, c₁, c₂) as bordered unknowns of one sparse LU per parity (rank-3 Woodbury correction for the second parity). The far-field condition reuses the existing, validated inps Wasow kernel (InnerAsymptotics.jl) — evaluated at complex x via new methods in RayAsymptotics.jl, construction untouched — applied at the series radius S and transported inward by an L-stable 2-stage Radau IIA march in the quotient modulo the decaying exponential pair. The damped-zone march arithmetic runs in Complex{Double64}: at large S the near-parallel power-pair geometry amplifies the structured backward error of the ill-conditioned implicit solves into Δ-mixing ~1e-4 at |Q| = 500 in Float64 (a floor generic to any inps-based method handed to double-precision linear algebra at large S).

Validation

Developed and validated in a standalone package before porting; highlights:

• Manufactured bordered problem with prescribed Δ*: agreement 3e-14.
• Fortran rmatch pins and :galerkin cross-check at moderate Q: 1e-5–1e-9.
• Physical q=4 benchmark surface pinned at Q = 100i and 500i.
• Campaign scale (Slurm, 102 equilibria × 65-point Q-grids incl. DIII-D and ITER PFPO cases, ~14k solves): zero θ-consistency flags above 1e-3 at any |Q|; worst Δ₁ drift 5.8e-4, worst Δ₂ 3.7e-6. The legacy Galerkin self-disagrees at O(1) for |Q| ≳ 1 on the same points.
• In-repo: test/runtests_innerlayer.jl gains a :ray testset (agreement with :galerkin at the GW2020 Eq. 55 paper point; q4 pins at 500i; θ-invariance). 19/19 pass.

Default backend change

GGJModel() now defaults to :ray. Blast radius checked: there are no bare GGJModel() call sites in the repo — all 17 benchmark uses and the regression harness pass solver=:galerkin explicitly. The backends take different numerical-knob keywords, so any stale galerkin-knob call fails loudly rather than returning a silently wrong Δ.

Dependencies

• Random (stdlib, zero footprint) promoted from test-extras to [deps] — seeds the decaying-pair extraction (provably Δ-neutral; kept fixed for bit-reproducibility).
• DoubleFloats was already a project dependency; only the using line is new.

Files

• src/InnerLayer/GGJ/RayAsymptotics.jl (new) — complex-x evaluation methods for the existing inps kernel.
• src/InnerLayer/GGJ/Ray.jl (new) — ODE system, WKB-graded mesh, decaying-pair extraction, Radau march, bordered collocation solve, refinement, delta_convergence error-bar battery, profile reconstruction, and the solve_inner(::GGJModel{:ray}, …) interface method.
• GGJ.jl / InnerLayer.jl — backend registration, exports, docs.

A complete replication-grade methods write-up (strong form, cell-by-cell matrix assembly, march schedule derivation, finite-precision floor analysis) exists and will accompany the paper in preparation.

---

Update (2026-07-10): RPEC matching + PerturbedEquilibrium integration

The branch has grown beyond the standalone backend. Additions, each an independently validated commit:

Documentation (with a correctness pass): JCP-style doc standard, full InnerLayer page with four provenance-tracked figures, a ggj_ray_q500i regression case, and fixes from review — pole-locus physics (Δ's poles lie on/near the real-Q axis; the imaginary-axis difficulty is the on-path pseudo-resonance), per-backend Eq.-55 validation values, platform-aware regression thresholds (the damped-zone structured roundoff is BLAS-dependent at ~1e-5 relative).

Penetrated field from the inner layer (bug fix + new): the physical penetrated (reconnected) resonant field is the layer-center Ψ(0) — the outer large solution ~|δψ|^(1/2−p₁) makes any pointwise evaluation bracket-offset dependent. The ported match.f-style scale omitted a −2π/v₁ factor (surface-dependent error, 3.5–7× on the DIII-D benchmark); the corrected scale is derived from the code's own outer b-convention chained with GWP2016 Eqs. 16/A17 and validated by an overlap test (the matched inner b^ψ profile lies on the outer eigenfunction through the matching region, magnitude and phase, all four DIII-D surfaces). The layer value is now the official C_penetrated_area_weighted_field via the standard C_coeffs contraction; ideal runs (either integrator) produce exactly zero (perfect shielding); kinetic shooting remains on the pointwise fallback.

Coefficient-based Δ_mn: computed from the matched solution's asymptotic coefficients (per-surface unit-small-solution kernels at the conventional ±5e-4/(n|q′|) brackets × the small-solution content bookkeeping) instead of finite-differencing the outer solution across its near-surface divergence. Validates against the finite-jump evaluation to ~1e-5 on the ideal gal path. Dispatch mirrors B_pen: a ForceFreeStates-provided object replaces the jump; shooting runs keep the fallback (now with analytic gal derivatives where available) until the planned non-galerkin ideal Δ object lands.

Ray as the RPEC matching default: new gal_inner_solver control ("ray" default | "galerkin"), consistent with GGJModel() defaulting to :ray. Certified Δ from the optimal-θ contour; profile quantities from a θ=0 re-solve (the on-axis pseudo-resonance is a regular point, resolved by the BVP refinement — tested clean to |Q| = 100 imaginary); the θ=0-vs-θopt Δ agreement is logged as a runtime certificate. b_pen agrees with the galerkin backend to 1.8e-4 → 6e-6 across the DIII-D surfaces with identical normalization. No settings are read from environment variables anywhere in the project.

Output additions: galerkin/match/inner_params/{E,F,G,H,K,M,taua,taur,v1} (the per-surface layer coefficients, S = taur/taua), galerkin/match/{delta_mn, inner/b_$i}, and singular_coupling/{penetrated_field_inner, C_penetrated_field_inner, forcing_solution_weights, rational_area}.

Physics motivation for the matching work: on a DIII-D k_η scan the legacy galerkin inner layer produces a non-monotonic-in-η jump of the matched resonant field at the lowest resistivity (|Q| ≳ 1); the ray backend restores a smooth, monotonic shielding family — the inner-layer solver choice materially changes a physical prediction exactly where |Q| grows beyond the legacy regime.

🤖 Generated with Claude Code

[matt-pharr]

@logan-nc @d-burg this is something I have been working on with claude for a few weeks. It has a number of advantages over the galerkin GGJ solver. It uses collocation which is also a finite element method, but I learned that the reason that the galerkin solver sometimes freaks out is because there are poles to the GGJ solutions in Q space, and when you get near those poles the solutions become super oscillatory on the real axis. However, since we are solving this in a complex domain, you can show that the GGJ solutions should be entire in the complex plane, so the mercier terms in the large |X| limit are the same polynomial + coefficient even off of the real-axis (which is where the physically-relevant part of the solution lies). So you can get a much cleaner/quicker exponential decay of the non-limiting terms if you integrate on a ray that is rotated off of the real axis. This also gives way to an entirely different numerical stability check, which is to re-integrate for multiple rotation angles and see that you get the same Delta_even and Delta_odd. Overall this method is far superior to the galerkin one in all of my testing so far, and can safely go up to Q ~ 500i with a maximum error in the final Delta of ~1e-4 which is pretty good for this problem. Error stays ~1e-7 for more reasonable Q. This enables scanning to lower resistivities (Q ~ 1/eta^1/3) and higher rotation rates (or to absurd growth rates). It also makes the solve more robust for lower |Q|. I will do some more testing on this branch before I merge but I am opening it for review now.

[logan-nc]

Documentation for the :ray backend + a repeatable docs standard

This adds full user-facing documentation for the new rotated-ray inner-layer backend, and uses it as the occasion to establish a reusable Journal of Computational Physics-style documentation standard for the repo.

📖 Rendered preview (live now for this PR)

• Inner Layer page (the main deliverable, with all four figures inline): https://openfusiontoolkit.github.io/GPEC/previews/PR323/inner_layer/
• Ballooning page (migrated to the new figure layout): https://openfusiontoolkit.github.io/GPEC/previews/PR323/ballooning/
• Preview home: https://openfusiontoolkit.github.io/GPEC/previews/PR323/

What's here

Documentation standard — docs/DOC_STANDARD.md defines a module-page template (governing equations → numerical method → validation figures → API) and the figure policy. Linked from Developer Notes; ballooning.md and the new inner_layer.md are the reference exemplars.

Figure infrastructure — docs/figure_tools.jl provides save_doc_figure, which stamps every PNG with its generating git commit + date and records provenance (script, commit, date, depends) in docs/src/figures/manifest.toml.

• Content figures now live in docs/src/figures/<module>/, each PNG committed next to the make_*.jl that produced it. docs/src/assets/ is reserved for Documenter chrome.
• Figures are pre-generated and committed, never rebuilt at docs-build time — regenerate only when a file in a figure's depends list changes the numbers it shows (see DOC_STANDARD.md).

Inner Layer page (docs/src/inner_layer.md, stub → full page) with four computed figures on the q=4 benchmark surface: backend accuracy vs :ray along the imaginary axis (shooting reaches |Q|≈1, galerkin ≈4, ray to 500), the rotated-ray/pseudo-resonance geometry, the seamless collocation↔asymptotic field match, and the Q=500i convergence error bar.

Ballooning migration — the two existing figures moved to docs/src/figures/ballooning/ as the second exemplar, registered legacy (their generators predate the provenance system; one compared the since-removed Mercier.jl).

Review-related fixes folded in

• rescale_delta docstring correction (GGJParameters.jl): the physical-rescale exponent was mislabeled X₀^{+2√(−D_I)}; the code correctly applies X₀^{−2√(−D_I)}·v₁^{2√(−D_I)} (verified against the Fortran rmatch pins). Docstring now matches the code. No behavior change.
• New regression case ggj_ray_q500i pins the :ray matching data at Q=500i on the q=4 surface (Δ_odd = 2.472008 + 13.35402i, Δ_even = 0.1374966 + 0.7427542i).
• Unit tests for the internal machinery (cheblobatto, ode_matrix, parity_rows, decaying_pair, profile diagnostics, delta_convergence).

Verification

• Docs build clean (no missing-docs / invalid-link / cross-ref errors); all six figures embed — confirmed live in the preview above.
• test/runtests_innerlayer.jl: 37/37 pass.
• Regression harness: both GGJ cases compute; the :ray case matches the test pins.

_{Note: committed figure stamps read 3a0837e3-dirty (generated before this commit existed). Content is final; the stamps can optionally be refreshed to the clean hash by re-running the make_*.jl scripts.}

🤖 Generated with Claude Code

[logan-nc]

@matt-pharr I was having trouble understanding/trusting all your claims from the pure text descriptions above. As such, I am taking this opportunity to initiate a new, more-complete docs standard that includes figures. Figures were already creeping in (see legacy ballooning figures) and a standard was needed anyways - I figured I might as well lump it in here so i could actually see what was happening 😝

[logan-nc]

@matt-pharr can you check the "Review-related fixes folded in".
Also read through https://openfusiontoolkit.github.io/GPEC/previews/PR323/inner_layer for (a) accuracy and (b) any improvements you want to make.