[logan-nc]

@matt-pharr, please read this first. @logan-nc asked for this rewrite and set its goals, but has not read the result. Claude agents wrote it overnight. Treat every change as a proposal: you are fully authorized to override, rework, or throw out any part of it, including the whole approach. Nothing here needs to survive just because it was done.

Release note

• Audience: users
• Numerical impact: none (documentation only; no file under src/ changes)
• Migration: none

The user documentation now leads with the pipeline and its physics. Every module page has the same layout: what it computes, the governing equations, how to run it, its outputs, numerical notes, and the API. Long passages about implementation details and project history are gone. The setup guide, the workflow map and several pages had factual errors, which are fixed.

What the goal was

The audience is physics PhD users. In the old pages, AI-written passages often ran for paragraphs on minor details (edge cases, numerical trivia, what used to be wrong), while the overall workflow and the core physics got little space. This pass rebalances that and standardizes the language.

How it was done:

1. One reviewer read all 19 pages and wrote a style guide and a page-by-page plan.
2. One implementer carried the plan out page group by page group, keeping context across groups so the balance stayed consistent.
3. A fresh reviewer read the result.
4. The implementer fixed what that reviewer found.

docs/src went from 5200 to 2564 lines.

What changed, by page

Page	Lines	Main change
workflow.md	195 → ~220	Rebuilt as a physics-first map of the 8 stages main runs, with a "which stage do I need" table that gives the gpec.h5 paths, a card per stage, a deck-section index and all examples
set_up.md	460 → 88	One install procedure; clone URL fixed (OpenFUSIONToolkit/GPEC); first run and reading the outputs
index.md	35 → ~50	A "what GPEC computes" table pointing into the workflow map
stability.md	494 → 154	Ideal stability physics (δW, free-boundary energies, Δ′ from the Riccati BVP), the integrators, and an outputs table
ballooning.md → Local Stability	919 → 100	The 327-line equivalence proof and the module history removed; Mercier, resistive D_R and ballooning on one page
galerkin.md	57 → 54	Citation fixed; the Q convention stated once
perturbed_equilibrium.md	158 → 168	Response physics (P, L, Λ, b̄ʳ, island width, Chirikov), an outputs table, and the prerequisites (see below)
kinetic_forces.md	218 → 111	NTV physics with a displayed torque integral, collision operators, the method table and outputs; Fortran line-number citations removed
forcing_terms.md	224 → 121	Its contradiction on coil normalization resolved from the source
error_fields.md	560 → 178	The five-step workflow, physics, outputs; the scripting recipes condensed
inner_layer.md → Tearing	309 → 169	Tearing physics (outer Δ′ plus inner-layer response gives the dispersion relation), SLAYER vs GGJ, critical resonant field, outputs
equilibrium.md, vacuum.md, conventions.md, api.md, analysis.md, utilities.md, developer_notes.md, citations.md		Condensed, with errors fixed; api.md opens with the whole pipeline as a short script

Also in this PR:

• Navigation: "API Reference" becomes "Modules", in pipeline order.
• Unused figures: five figures nobody referenced are deleted, along with their generator scripts and manifest entries.
• README: the opening sentence was "three-stage pipeline"; it now matches the eight-stage table.
• DOC_STANDARD.md: describes the new page layout.
• One example deck: a header-comment fix in examples/DIIID-like_ideal_example/gpec.toml, which called itself the Δ′-matrix fixture. It runs "Forward", so it isn't; the Riccati example is.

Facts checked against the code

• The default integrator is "Riccati".
• The n < 1 clamp exists.
• Every gpec.h5 path in the tables is checked against the writers or the schema registry.
• The delta_prime.matrix diagonal is the outer-region Δ′. The per-surface delta_prime vector is a stub the code calls "not physically valid".
• Perturbed equilibrium requires integrator = "Forward" and no [Wall]. A wall or a Galerkin/matched result is an error. A Riccati result skips the response with a warning, so the failure only shows when a field is applied. The docs now say this plainly, and say that the Δ′ (tearing) and response cases therefore need separate decks.
• The swapped Glasser 2016 article numbers are fixed.
• Every @docs/@autodocs entry is unchanged against the base, so nothing dropped out of the API reference.

Please check

• Two new citations.md entries for the error-field correction papers: Logan et al. 2026, Nucl. Fusion; Leuthold et al. 2026, J. Plasma Phys. They carry only the journal, year and DOI the old page printed. An agent had written titles from memory, and those were removed. Please add the real titles.
• Two new LocalStability entries: Glasser, Greene & Johnson 1975; Connor, Hastie & Taylor 1978.
• The workflow diagram is a text sketch; a D2 figure would be better.

Found but not changed (code, not docs)

• The SLAYER Δ′ fallback. src/Tearing/TearingProblem.jl:100–112 falls back, with a warning, to the per-surface delta_prime stub when no Δ′ matrix exists. So a Forward run can give SLAYER growth rates from a quantity the type docs call invalid.
• A wrong citation in a source comment. src/ForceFreeStates/Riccati/DeltaPrimeBVP.jl:504 cites Glasser–Kolemen 2018 as PoP 25, 032501. It is 082502 (DOI 10.1063/1.5029477).
• Riccati into plasma_response. plasma_response on a Riccati result warns and returns empty operators rather than erroring early.

Regression report

Documentation only: no file under src/ changes, so the harness does not apply. The docs build passed (Slurm job 137285), and so did pre-commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VdRsGGg4YRG6E9fgLGbpdF

[matt-pharr]

@logan-nc I am working on this FYI. You should take a look when you wake up and also at the two small tweak PRs I requested your review on and assigned to you, merge them when you are happy.

[logan-nc]

@matt-pharr: I pushed 332d400 on top of your develop merge (c5e1287). It only adds text or edits lines you hadn't touched; I left your fixes alone. This comes from my review plus an independent pass by a second Claude agent, with each claim checked against src/.

• gpec launcher: the first line is now #!/usr/bin/env -S julia --project=@script. The old #!/usr/bin/env julia --project=@. hangs forever on Linux: GNU env reads julia --project=@. as a variable assignment and runs the script again, endlessly. That made "First run" fail at its first step. @script also finds the project from any working directory.
• README opening: now "This Julia implementation of GPEC continues the legacy of the Fortran GPEC suite…". The stage list is rewritten as four plain items naming the Fortran ancestors. It no longer claims that GPEC solves the Grad-Shafranov equation.
• [Match]: workflow.md and inner_layer.md no longer say a matched result makes the plasma response resistive, because the code refuses a matched result. They now say where the matched solution is written and that driving a response from it is not yet supported.
• New sections:
  • index.md, "Coming from the Fortran codes": maps DCON, STRIDE, RDCON, VACUUM, GPEC, PENTRC and SLAYER to their deck sections.
  • workflow.md, "Replaying a run": the command, its flags and the side files it writes, plus what to do when a file can't be replayed (matching Repo - BUGFIX - Name the GPEC version that wrote a gpec.h5 and the ways forward when it cannot be replayed #642's error text). It replaces the one-line rerun note.
• Smaller fixes:
  • "Every key is documented on its module page" was not true (mtheta_vacuum and singfac_min appear on no page). It now points at the control-struct API reference, and says that old v1 keys stop with a pointer to their new home.
  • Equilibrium.LargeAspectRatioConfig is now qualified. The api.md error_fields line now runs (tolerances=read_tolerance_toml(...)).
  • The shape of the omega_E_kHz table is given.
  • The "(Riccati solves)" label on SingularCoupling/Delta_prime is dropped. The value comes from the forward-solve jump; the HDF5 schema's long_name in src/PerturbedEquilibrium/Utils.jl still says "Riccati".
  • The efit_fixedbdy_separatrix_example row now says it has no deck.
  • The Fitzpatrick Nucl. Fusion citation is now 66, 046025 (2026). I checked all 28 DOIs against Crossref, and the rest match.

Open questions:

1. The ARC citation note says the paper applies "the same model to ARC, with the zero-rotation torque_only limit". That paper is the broad "ARC physics basis–MHD", so please confirm the note, or cut it to one neutral line.
2. DIIID-like_gal_resistive_pe_example errors at its [PerturbedEquilibrium] stage when run as shipped. Drop that section from the deck, or the whole example, before the release?