ISLANDS - M1: phase-space grids + operator-stack skeleton + MMS/AD harness

Project.toml

@@ -14,6 +14,7 @@ DoubleFloats = "497a8b3b-efae-58df-a0af-a86822472b78"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 FastGaussQuadrature = "442a2c76-b920-505d-bb47-c5924d526838"
 FastInterpolations = "9ea80cae-fc13-4c00-8066-6eaedb12f34b"
+ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 IMASdd = "c5a45a97-b3f9-491c-b9a7-aa88c3bc0067"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
@@ -43,6 +44,7 @@ DoubleFloats = "1.6.2"
 FFTW = "1.9.0"
 FastGaussQuadrature = "1.1.0"
 FastInterpolations = "0.4.10"
+ForwardDiff = "1.4.1"
 HDF5 = "0.17.2"
 IMASdd = "8"
 JLD2 = "0.6.3"

docs/src/islands.md

@@ -3,12 +3,50 @@
 The Islands module is a steady-state, multi-species drift-kinetic solver for the
 resonant magnetic island/layer region in tokamaks — the nonlinear analog of
 SLAYER, generalizing the Modified Rutherford Equation. It is under active
-development (milestone M1). The design documents live under `islands/design/` in
-the documentation source tree, and the module conventions in
-`src/Islands/CLAUDE.md`.
+development. The design documents live under `islands/design/` in the
+documentation source tree, and the module conventions in `src/Islands/CLAUDE.md`.
+
+## Status — milestone M1 (skeleton)
+
+M1 lands the numerical skeleton, not the physics numbers (module `CLAUDE.md`, the
+`[VERIFY]` policy):
+
+  - `Islands.PhaseSpace` — the `(x, ξ, λ→y, E, σ)` phase-space grids with
+    layer-clustered mappings (design `04 §1`): Fourier spectral `∂ξ`, high-order
+    finite-difference `∂x`/`∂y` on stretched grids, and Gauss energy quadrature.
+    Pure numerics; no physics coefficients.
+  - `Islands.Operators` — the `AbstractTerm` operator stack and residual assembly
+    (design `03 §2`) as allocation-free, AD-compatible *structural stubs*. Every
+    physics coefficient is a supplied data field, never a literal — literature
+    numbers stay `[VERIFY]`/`[CHECKED]`-gated until human-cleared.
+  - `Islands.Verify` — the manufactured-solution (MMS) and AD-vs-finite-difference
+    JVP harness backing verification ladder **A1/A2** (design `05 §A`), exercised
+    by `test/runtests_islands_{grids,operators}.jl`.
+
+The physics operators (drift-frequency coefficients, collision kernels, the
+Δ moments and York thresholds) land in later milestones and remain gated until
+their `[VERIFY]` tags are cleared.
 
 ## API Reference
 
 ```@autodocs
 Modules = [GeneralizedPerturbedEquilibrium.Islands]
 ```
+
+### Phase-space grids (`Islands.PhaseSpace`)
+
+```@autodocs
+Modules = [GeneralizedPerturbedEquilibrium.Islands.PhaseSpace]
+```
+
+### Operator stack (`Islands.Operators`)
+
+```@autodocs
+Modules = [GeneralizedPerturbedEquilibrium.Islands.Operators]
+```
+
+### Verification harness (`Islands.Verify`)
+
+```@autodocs
+Modules = [GeneralizedPerturbedEquilibrium.Islands.Verify]
+```

docs/src/islands/LOG.md

@@ -8,6 +8,37 @@ relevant.
 
 ---
 
+## 2026-07-08 — M1 skeleton: phase-space grids + operator stack + MMS/AD harness
+
+- **PR**: #320 (`feature/islands-m1` → `feature/islands`); full suite green.
+- **Moved**: Landed the M1 core (design `03 §1–2`, `04`, ladder `A1/A2`). Three
+  `src/Islands/` submodules, all structure-only (no `[VERIFY]` physics numbers):
+  - `phasespace/PhaseSpace.jl` — the `(x, ξ, y, E, σ)` grids with layer-clustered
+    maps: Fourier spectral `∂ξ`, Fornberg high-order FD `∂x`/`∂y` on `sinh`-stretched
+    grids (window sized per-derivative so `D1`/`D2` are both 4th-order incl.
+    boundaries), composite-Simpson quadrature weights, Gauss–Laguerre energy nodes.
+  - `operators/Operators.jl` — `AbstractTerm` + `apply!` + `residual!`; the term
+    structs of `03 §2` (`ParallelStreaming`, `MagneticDrift` with the
+    `:original/:improved` toggle, `ExBDrift` as the `(x,ξ)` Poisson bracket,
+    `Collisions`, `GradientDrive`, `PerpTransport`/`RadiationSink` L4 stubs,
+    `Quasineutrality` field residual). Every physics coefficient is a **supplied
+    data field** — no literal in `src/`. Allocation-free, AD-generic.
+  - `verify/Verify.jl` — manufactured-solution + AD-vs-FD JVP harness.
+  - Tests `test/runtests_islands_{grids,operators}.jl` (wired into `runtests.jl`):
+    A1 per-operator MMS → 4th order for `∂x/∂y` terms, machine-precision for the
+    `∂ξ` term; assembled kinetic residual → 4th order; A2 JVP-vs-FD agree to ~6e-9;
+    **allocation regression = 0 bytes** for every `apply!` and `residual!`. All
+    53 Islands tests green. Added `ForwardDiff` to `Project.toml` (design `04 §9`).
+- **physics-verifier**: PASS — audited all six new/changed files, no
+  `[VERIFY]`-policy violation; the flagged literature numbers (8.73/1.46 ρ_bi,
+  k=−1.173, …) appear only in docstring prose, never assigned to a coefficient.
+- **Blocked**: nothing. **Q1 RESOLVED**: julia is at
+  `/mnt/homes_global/ncl2128/software/julia-1.11.7/bin/julia`; must be run with
+  `env -u LD_LIBRARY_PATH` (OMFIT contamination). Used it to run the suite here.
+- **Next**: M2 — wire moments (`Δ_cos`, `Δ_sin`), `frames/`, `species/`, and the
+  Newton–Krylov solver toward the L0 single-species solve; every physics
+  coefficient stays `[VERIFY]`-gated with a skipped benchmark until cleared.
+
 ## 2026-07-08 — Harden Stop hook against OMFIT LD_LIBRARY_PATH contamination
 
 - **Moved**: Diagnosed why the Stop hook's package-load check fails on this box.

docs/src/islands/QUESTIONS.md

@@ -21,21 +21,91 @@ supervising sessions.
 
 ---
 
-## Q1 — Julia not on the automation shell PATH — OPEN
+## Q1 — Julia not on the automation shell PATH — RESOLVED (by Claude, 2026-07-08)
 
 - **Context**: Phase A bootstrap. Verifying the `Islands` module skeleton loads
   (`using GeneralizedPerturbedEquilibrium`) and running the test suite requires
-  `julia`, but it is not on the non-interactive shell's PATH (no `julia` module,
+  `julia`, but it was not on the non-interactive shell's PATH (no `julia` module,
   none in `$HOME`; other users have installs under `/mnt/homes*/…/julia*`).
 - **Question**: What is the canonical `julia` invocation for automation on this
   cluster, and will the overnight loop's scratch-clone environment expose it?
-  The unattended loop **cannot run `julia --project` tests without it** — this is
-  a hard prerequisite for Phase B, not just a local convenience.
-- **Options**: (a) a `module load <julia>` line prepended in the loop's shell
-  rc / launch script; (b) an absolute path to a `juliaup`/`julia` binary the
-  user owns; (c) install juliaup under `ncl2128` and pin 1.11.
-- **Recommendation**: user provides the module/path; bake it into the tmux
-  launch script (and the Stop hook, which runs the fast test subset). Until
-  then, CI (`test.yaml`) is the only validation of Julia changes.
-- **Gated work**: local verification of every Julia change; the Phase-B overnight
-  loop's ability to run tests / meet its definition-of-done.
+- **Resolution**: the `ncl2128`-owned install is at
+  `/mnt/homes_global/ncl2128/software/julia-1.11.7/bin/julia` (option (b): an
+  absolute path to a user-owned binary), and it is on this session's PATH. The
+  M1 run used it to build and run `test/runtests.jl` locally. The **only caveat**
+  is the OMFIT `LD_LIBRARY_PATH` contamination already documented in LOG
+  (2026-07-08): the binary must be invoked with a clean loader path —
+  `env -u LD_LIBRARY_PATH /mnt/homes_global/ncl2128/software/julia-1.11.7/bin/julia
+  --project=. …` — or the conda libs shadow Julia's bundled artifacts. The Stop
+  hook already applies `env -u LD_LIBRARY_PATH`; the overnight loop's launch
+  script must do the same for its own gpec runs.
+- **Gated work (now unblocked)**: local verification of every Julia change; the
+  overnight loop's ability to run tests / meet its definition-of-done.
+
+## Q2 — Ratify Decisions D7 and D8 — OPEN
+
+- **Context**: M2 setup. The L0 equation set and benchmark targets rest on two
+  Decision-Log proposals (`docs/00`) that are dated 2026-07-07 and still marked
+  "needs human ratification". Until ratified, M2 cannot fix the L0 physics form or
+  pin its benchmark tolerances.
+- **Question**: Ratify (or amend) **D7** — implement Level-0 physics from an
+  *independent re-derivation* cross-checked against the L23-amended equation set,
+  treating I19 Eq. (A.1) as printed as known-errata (L23 §2.6), with ω_E a scanned
+  input from day one — and **D8** — pin the benchmark grid as the three-code
+  triangle (DK-NTM / RDK-NTM / kokuchou) with B5a/b/c configs, superseding the
+  single "York thresholds" gate item.
+- **Options**: (a) ratify both as written; (b) ratify with amendments; (c) direct a
+  different L0 derivation strategy.
+- **Recommendation**: ratify both — they encode the project's core anti-guessing
+  thesis (published O(1) coefficients in this lineage are demonstrably wrong) and
+  the benchmark structure the ladder already assumes.
+- **Gated work**: pinning any L0 physics coefficient; the York gates B5a/b/c; the
+  Paper-I physics claims.
+
+## Q3 — Clear the Level-0 coefficient set ([CHECKED] → human sign-off) — OPEN
+
+- **Context**: M2 builds the L0 solve machinery with every physics coefficient a
+  parameterized `[VERIFY]` stub. Reaching the York gates needs these `[CHECKED]`
+  (AI-transcribed, cited, but not human-signed-off) items cleared. `[CHECKED]` is
+  not permission to hardcode (`docs/01` header). Each is implemented structurally;
+  none has a value in `src/`.
+- **Question**: Check each against its source PDF and sign off (record paper + Eq./p.
+  in `docs/01`), or flag a discrepancy:
+  - `ω̂_D` magnetic-drift frequency + the `:original`/`:improved` `L̂_B⁻¹` toggle
+    `[CHECKED: I19 Eq. (32) def.; D21 Eqs. 15, B1; D21 Eq. A2, p. 16]` — drives the
+    8.73 → 1.46 ρ_bi threshold shift.
+  - Pitch-angle collision kernel `[CHECKED: I19 Eqs. (9)–(12); Diss19 Eqs. 2.25–2.30;
+    WCHH96 Eq. (62)]` + the analytic velocity average
+    `⟨ν̂_ii⟩_u = (4ε^{3/2}ν_★/3√π)(√2 − ln(1+√2))` `[CHECKED: L23 Eq. 4.1.6, p. 88]`
+    + normalization `ν_★ = ν_jj Rq/(ε^{3/2}v_th)` `[CHECKED: L23 Eq. (2.3.40)]`.
+  - Electron-closure constants `k ≃ −1.173` (Hirshman–Sigmar) and `f_p ≃ 1 − 1.46√ε`
+    `[CHECKED: I19 Eq. (22); L23 Eqs. 2.5.5–2.5.8]`.
+  - Quasineutrality closure `e_iΦ̂/T_i = [δn̄_i/n₀ + x − ĥ(Ω)]/(2 L̂_{n0})`
+    `[CHECKED: I19 Eq. (A.11); L23 Eq. (2.4.14)]` and the Picard form
+    `δΦ̂ = (δn̂_i − δn̂_e)/2` `[CHECKED: Diss19 Eq. 2.45]`.
+- **Options**: (a) clear item-by-item after PDF check; (b) require an independent
+  re-derivation first (couples to Q2/D7) before clearing.
+- **Recommendation**: clear via re-derivation (per D7) rather than transcription
+  alone — L23 §2.6 documents concrete errors in the published set.
+- **Gated work**: populating any of these coefficients; the York/large-w/polarization
+  gates (B5a/b/c, B2, B4); the A7 number-bearing identities (`k`, `f_p`, `⟨ν̂_ii⟩`).
+
+## Q4 — Resolve open [VERIFY]s and acquire two missing sources — OPEN
+
+- **Context**: Independent of the `[CHECKED]` clearances above, three genuinely
+  open `[VERIFY]` items block pinning M2's moment normalization and B5a tolerance.
+- **Question**:
+  - `ψ̃` amplitude: is it `(w_ψ²/4)(q_s′/q_s)` (Diss19/D21/L23, dimensional analysis)
+    or `(w_ψ²/4)(q_s/q_s′)` (one I19 extraction)? `[VERIFY: check I19 as printed —
+    possible typo in the paper itself]` — sets the `Δ_cos/Δ_sin` prefactor.
+  - B5a run collisionality: I19 §4.2 states `ν_★ = 0.01`; L23 p. 82 quotes DK-NTM at
+    `ν_★ = 10⁻³`. Resolve before pinning the B5a tolerance.
+  - Acquire **WCHH96** (analytic electron closure / large-w limits, B2) and **Park
+    PoP 29 (2022)** (SLAYER Q-convention map, D1) into the `docs/08` reference
+    library — both are currently cited only via transcription.
+- **Options**: (a) user resolves from the source PDFs; (b) an independent
+  re-derivation pins `ψ̃` and the collisionality is read from the reproduced run.
+- **Recommendation**: resolve `ψ̃` by re-derivation (it is a clean dimensional check);
+  read the B5a collisionality from whichever run the D8 triangle pins as canonical.
+- **Gated work**: the `Δ_cos/Δ_sin` normalization; the B5a threshold tolerance; the
+  B2 large-w and D1 SLAYER comparisons.