Drift-kinetic island/layer solver

.claude/agents/physics-verifier.md

@@ -0,0 +1,73 @@
+---
+name: physics-verifier
+description: "Use this agent to adversarially audit an Islands-module (src/Islands/) diff for [VERIFY]-policy violations before it is committed — most importantly during autonomous overnight runs, where a guessed physics coefficient is the single worst failure mode. It hunts for numbers pulled from thin air, literature transcriptions committed as fact, and sign/convention errors against the Islands design docs. It is read-only and adversarial by charter. Invoke it before committing ANY physics-adjacent change in src/Islands/, and always before opening a PR that touches physics.\\n\\n<example>\\nContext: An autonomous run just wired a bootstrap-drive term and is about to commit.\\nuser: \"The GradientDrive term is implemented — about to commit.\"\\nassistant: \"Before committing, let me run the physics-verifier agent to confirm no [VERIFY] coefficient was assigned a value and the half-width/sign conventions match docs/01.\"\\n<commentary>Physics-adjacent code before a commit — launch physics-verifier to enforce the [VERIFY] policy.</commentary>\\n</example>\\n\\n<example>\\nContext: A term transcribes ω̂_D from D21 Eq. B1.\\nuser: \"Added the magnetic drift frequency from the paper.\"\\nassistant: \"I'll use the physics-verifier agent to check that the transcription carries a [CHECKED] tag with the exact Eq./page cite and a skipped benchmark, and was not silently promoted to confirmed.\"\\n</example>"
+tools: Read, Grep, Glob, Bash
+model: opus
+color: red
+---
+
+You are the physics-verifier for the GPEC `Islands` module — a steady-state
+drift-kinetic island/layer solver. Your single job is to **find the guessed
+number and the silent transcription** before they enter the repository. You are
+read-only and adversarial: assume the diff contains a `[VERIFY]` violation and
+try to prove it. A fast-but-wrong physics result is worthless; your review is the
+last gate before an autonomous run commits physics-adjacent code.
+
+## Budget discipline
+
+Hard cap: **≤25 tool uses, ≤8 minutes**. One concrete deliverable: a verdict
+(`PASS` / `BLOCK`) plus a short itemized findings list. The invoking prompt hands
+you the diff or file paths — do not go spelunking the whole module. If you cannot
+finish in budget, stop and report what you checked and what remains.
+
+## What you enforce (the [VERIFY] policy — Islands CLAUDE.md, `src/Islands/CLAUDE.md`)
+
+1. **No guessed coefficients.** Every physics O(1) coefficient, threshold number,
+   sign, or normalization must be one of: (a) `[CHECKED: source, Eq./p.]` with an
+   exact citation, (b) `[VERIFY: source]` and *parameterized* (not baked into a
+   literal) with a failing/skipped benchmark referencing it, or (c)
+   `[DERIVED: date]` with a derivation under `docs/src/islands/derivations/`. A
+   bare numeric literal in a physics expression with none of these is a **BLOCK**.
+2. **No silent promotion.** A `[VERIFY]`/`[CHECKED]` expression implemented as if
+   confirmed (hardcoded value, no skipped benchmark, no parameter) is a BLOCK —
+   even if the value happens to be right. Only a human clears a tag.
+3. **No "fix the coefficient to make the test pass."** If a benchmark was made to
+   pass by editing a physics constant rather than the code, BLOCK and flag it.
+
+## Convention checks (Islands design docs — `docs/src/islands/design/`)
+
+- **Island width `w` is a HALF-width**; Ω = 2x²/w² − cos ξ; O-point Ω = −1,
+  separatrix Ω = +1 (docs/01 §1, CLAUDE.md). Flag any full-width/half-width
+  confusion, especially in threshold numbers (report always with the gyroradius
+  unit stated; ρ_bi = ε^{1/2}ρ_θi).
+- **Frames**: every ω sign convention must live in `src/Islands/frames/` and
+  nowhere else (docs/01 §5, CLAUDE.md). A sign convention or frame conversion
+  outside the frames module is a finding. The polarization-current sign depends
+  on frame — check ω − ω_E vs ω_E vs ω₀ = −ω_E usage against docs/01 §5.
+- **No regime branches** in operator physics code (`if collisional … else banana`)
+  — allowed only in `verify/` and preconditioners (CLAUDE.md).
+- Cross-check any transcribed equation against the cited source in the reference
+  library (`docs/src/islands/design/08-reference-library.md`) — the published
+  Imada 2019 set has documented errata (L23 §2.6); a term matching I19 Eq. (A.1)
+  *as printed* rather than the L23-amended form is a finding.
+
+## Method
+
+1. `git diff` (or read the named files) — enumerate every physics-adjacent
+   change: coefficients, signs, normalizations, transcribed equations, thresholds.
+2. For each, ask: is it tagged? parameterized? cited to an exact Eq./page? backed
+   by a skipped benchmark if `[VERIFY]`? Does it match the source and the
+   half-width/frame/sign conventions?
+3. Grep the diff for bare float literals inside physics expressions and for
+   `[VERIFY]`/`[CHECKED]` tags whose companion benchmark is missing.
+
+## Output
+
+- **Verdict**: `PASS` or `BLOCK`.
+- **Findings**: each as `file:line — <what> — <why it violates the policy> —
+  <the fix>` (e.g. "parameterize + add skipped benchmark", "add [CHECKED] cite",
+  "write a QUESTIONS.md entry and escalate"). Rank most-severe first.
+- If BLOCK, state plainly that the change must not be committed until the flagged
+  coefficient is escalated to `docs/src/islands/QUESTIONS.md` (never guessed).
+
+You never edit code. You never clear a `[VERIFY]` tag. You find the error.

.claude/hooks/guard-bash.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) guard for unattended Islands runs.
+# Reads the hook JSON on stdin; `exit 2` blocks the tool call and returns the
+# stderr text to Claude as the denial reason. `exit 0` allows it.
+# Defense-in-depth under `dontAsk` (permissions.deny is the first layer; this is
+# the second, since glob deny-rules are coarse).
+set -euo pipefail
+
+payload="$(cat)"
+cmd="$(printf '%s' "$payload" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))' 2>/dev/null || true)"
+
+# Never force-push.
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push([[:space:]]|.)*(--force|--force-with-lease|[[:space:]]-f([[:space:]]|$))'; then
+  echo "BLOCKED: force-push is not allowed in unattended runs." >&2
+  exit 2
+fi
+
+# Never push to protected branches — pushes go only to feature/islands*.
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push'; then
+  if printf '%s' "$cmd" | grep -Eq '(^|[[:space:]/])(main|develop)([[:space:]]|$|:)'; then
+    echo "BLOCKED: push to main/develop is not allowed; push only to feature/islands*." >&2
+    exit 2
+  fi
+fi
+
+# Refuse obviously destructive filesystem ops on absolute/home roots.
+if printf '%s' "$cmd" | grep -Eq 'rm[[:space:]]+(-[a-zA-Z]*r[a-zA-Z]*[[:space:]]+)(/|~|\$HOME|/mnt/homes)'; then
+  echo "BLOCKED: refusing recursive rm on an absolute/home path." >&2
+  exit 2
+fi
+
+exit 0

.claude/hooks/stop-check.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Stop hook for unattended Islands runs.
+# `exit 2` blocks the session from ending (Claude keeps working, sees stderr);
+# `exit 0` lets it stop. Purpose: never end a night with a dirty tree or a
+# broken build.
+set -uo pipefail
+
+payload="$(cat)"
+
+# Avoid an infinite loop: if we are already continuing because of this hook,
+# let the session stop.
+active="$(printf '%s' "$payload" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("stop_hook_active", False))' 2>/dev/null || echo False)"
+if [ "$active" = "True" ]; then
+  exit 0
+fi
+
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || echo .)}"
+cd "$root" 2>/dev/null || exit 0
+
+# 1. Working tree must be clean (commit granularly, per the protocol).
+if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+  echo "BLOCKED stop: uncommitted changes present. Commit (to feature/islands) or stash before ending; then write a LOG.md entry." >&2
+  exit 2
+fi
+
+# 2. Build/tests must pass. Requires julia on PATH (see QUESTIONS.md Q1); if
+#    julia is absent the check is skipped with a warning rather than blocking.
+# Run julia with LD_LIBRARY_PATH stripped: a loaded OMFIT module leaks the conda
+# env's libs onto the path, shadowing Julia's bundled artifacts (CHOLMOD, glib)
+# and giving false "broken build" blocks. Julia uses its own RPATH, so unsetting
+# is a no-op on a clean shell / CI.
+if command -v julia >/dev/null 2>&1; then
+  # Once M1 lands test/runtests_islands_*.jl, prefer running just those:
+  #   julia --project=. test/runtests.jl test/runtests_islands_grids.jl ...
+  # Until then, a package-load smoke check.
+  if ! env -u LD_LIBRARY_PATH julia --project=. -e 'using GeneralizedPerturbedEquilibrium' >/dev/null 2>&1; then
+    echo "BLOCKED stop: package fails to load (using GeneralizedPerturbedEquilibrium errored)." >&2
+    exit 2
+  fi
+else
+  echo "WARN: julia not on PATH — skipping the build check in the Stop hook (QUESTIONS.md Q1)." >&2
+fi
+
+exit 0

.claude/settings.json

@@ -0,0 +1,65 @@
+{
+  "$comment": "Project-scoped Claude Code settings for GPEC. The permissions.allow list is sized for the Islands overnight autonomous loop run under --permission-mode dontAsk (anything not allowed is auto-denied, no prompt). permissions.deny + the PreToolUse hook are defense-in-depth against destructive git/filesystem ops. The Stop hook keeps an unattended session from ending with a dirty tree or a broken build. DRY-RUN THESE ONCE, SUPERVISED, before trusting an unattended run (design doc docs/src/islands/design/06 §2.3).",
+  "permissions": {
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Edit",
+      "Write",
+      "NotebookEdit",
+      "TodoWrite",
+      "Task",
+      "Bash(julia:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git switch:*)",
+      "Bash(git stash:*)",
+      "Bash(git pull --ff-only:*)",
+      "Bash(git push origin feature/islands:*)",
+      "Bash(gh pr:*)",
+      "Bash(gh run:*)",
+      "Bash(gh api:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)"
+    ],
+    "deny": [
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git push origin main:*)",
+      "Bash(git push origin develop:*)",
+      "Bash(git push* main)",
+      "Bash(git push* develop)",
+      "Read(./.env)",
+      "Read(~/.ssh/**)",
+      "Read(~/.claude.json)",
+      "Read(~/.config/gh/**)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.sh\"" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/stop-check.sh\"" }
+        ]
+      }
+    ]
+  }
+}

.gitignore

@@ -14,8 +14,10 @@
 *.DS_Store
 *.pdf
 !docs/resources/*.pdf
+!docs/resources/**/*.pdf
 *.png
 !docs/src/assets/**/*.png
+!docs/src/islands/figures/*.png
 *.jld2
 .gitattributes
 Manifest.toml

CLAUDE.md

@@ -327,6 +327,15 @@ This workflow is reflected in the modular structure and data flow.
 
 GPEC consists of **seven main modules** organized in `src/`:
 
+**Module naming convention**: `src/` module names are simple, intuitive descriptions
+of what the module *is* (`Vacuum`, `Equilibrium`, `ForceFreeStates`, `KineticForces`,
+`Islands`) — CamelCase, matching the directory. Do **not** give a feature a fancy
+standalone-sounding acronym or codename as if it were an independent code needing its
+own name recognition (e.g. no `ISLET`, `PENTRC`-style names for new modules). The
+domain the module addresses is the name. Working titles/acronyms from a paper or design
+doc are dropped when the module lands in `src/`. This keeps the codebase legible as one
+integrated tool rather than a bag of separately-branded programs.
+
 #### Foundation Modules
 
 1. **Splines** (`src/Splines/`) - Numerical interpolation library

Project.toml

@@ -14,9 +14,11 @@ 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"
+Krylov = "ba0b0d4f-ebba-5204-a429-3ac8c609bfb7"
 LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
@@ -43,9 +45,11 @@ 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"
+Krylov = "0.10.8"
 LaTeXStrings = "1.4.0"
 LinearAlgebra = "1"
 OrdinaryDiffEq = "6.102.0"

benchmarks/islands/README.md

@@ -0,0 +1,30 @@
+# Islands benchmark ladder (docs/05)
+
+Benchmark scripts for the Islands verification ladder
+(`docs/src/islands/design/05-verification.md`). Each script names its ladder
+ID, configuration, target (with source cites), and status.
+
+**Status policy (the `[VERIFY]` discipline, `src/Islands/CLAUDE.md`):** every
+physics benchmark whose target or input coefficients are `[VERIFY]`/uncleared-
+`[CHECKED]` ships **skipped** — the script states exactly which
+`docs/src/islands/QUESTIONS.md` entries gate it and exits without running.
+Un-skipping a benchmark requires the human clearances it names; silently
+filling in a coefficient to make one run is the failure mode this project
+exists to prevent. The structural A-ladder (A1–A8) runs in CI via
+`test/runtests_islands_*.jl`, not here.
+
+**Targets are tiered (Decision D9, docs/05 "Target tiers").** The primary
+literature-facing gates are **scalings, trends, existence, and internal
+differentials** (T1/T2/T3); **absolute literature numbers (T4) are audit-gated**
+— never pass/fail without a published input manifest and sensitivity scan, and
+downgraded to a trend where the source is under-specified. Each script's header
+labels its targets by tier.
+
+Figure scripts (docs/07 pipeline) live in `figures/` and read archived
+benchmark data only.
+
+| Script | Ladder ID | Primary tier(s) | Status |
+|---|---|---|---|
+| `benchmark_B2_large_w_limits.jl` | B2 | T3 scalings (1/w, 1/w³); coeff T4 | SKIPPED — gated on Q2/Q3/Q4 |
+| `benchmark_B4_polarization_omegaE.jl` | B4 | T3 ω_E² + reversal existence; location T4 | SKIPPED — gated on Q2/Q3 |
+| `benchmark_B5_york_thresholds.jl` | B5a/b/c | T2 toggle ratio + T3 existence/trend; absolutes T4 | SKIPPED — gated on Q2/Q3/Q4 |

benchmarks/islands/benchmark_B2_large_w_limits.jl

@@ -0,0 +1,46 @@
+# benchmark_B2_large_w_limits.jl — ladder B2 (docs/05 §B)
+#
+# Targets are TIERED (Decision D9; docs/05 "Target tiers"):
+#   PRIMARY (T3): the large-w SCALINGS Delta_bs + Delta_cur ~ 1/w and
+#                 Delta_pol ~ 1/w^3, plus the parametric trend
+#                 eps^(1/2) (L_q/L_p) (beta_theta/w). Checked by fitting the
+#                 exponent over a w sweep — reproducible without absolute inputs.
+#   AUDIT-GATED (T4): the 1/w COEFFICIENT vs WCHH96 Eq. (85) mapped to the
+#                 island frame (Diss19 p. 86 frame caveat) [CHECKED: Diss19
+#                 pp. 84-86; D21 Fig. 8-class curves]. Report only with an input
+#                 manifest + sensitivity scan (docs/05 reporting rules 6-8).
+#
+# WCHH96 is now in the reference library (docs/08): Wilson, Connor, Hastie &
+# Hegna, Phys. Plasmas 3, 248 (1996).
+#
+# STATUS: SKIPPED. Wired to the M2c assembly (Islands.Configure.configure_level0)
+# the same way as benchmark_B5 — un-skip is the ONE-LINE `const UNGATED = true`.
+# Gated per docs/src/islands/QUESTIONS.md:
+#   Q5  the remaining L0 coefficient families + the QN (x-h) field source are
+#       uncleared, so configure_level0 runs only STRUCTURALLY (no physics Δ(w))
+#   Q3/Q4  the Δ moment prefactors are now CLEARED (M2b); the electron-closure
+#       constants and ψ̃ [VERIFY] are folded into the Q5 lane
+
+using GeneralizedPerturbedEquilibrium
+const Isl = GeneralizedPerturbedEquilibrium.Islands
+
+"""
+Flip to `true` only when QUESTIONS Q5 clears the remaining L0 coefficient families.
+"""
+const UNGATED = false
+
+# The large-w Δ(w) sweep would assemble one configure_level0 per island width w
+# (varying w_psi in Level0Physics) and fit the 1/w, 1/w^3 exponents (T3). GATED:
+# a physics Δ(w) needs the Q5-cleared far field + QN source (see benchmark_B5).
+function run_b2()
+    error("B2 large-w scalings are gated on QUESTIONS Q5 (physics Δ(w) unavailable).")
+end
+
+if UNGATED
+    run_b2()
+else
+    println("SKIPPED: B2 large-w limits — gated on QUESTIONS Q5 (Δ moment prefactors CLEARED).")
+    println("  Scaffold wired to configure_level0; un-skip = `const UNGATED = true`.")
+    println("  Primary tier when un-gated: the 1/w and 1/w^3 SCALINGS (T3, fit the")
+    println("  exponent). The WCHH96 Eq. 85 coefficient is T4 (audit-gated).")
+end

benchmarks/islands/benchmark_B4_polarization_omegaE.jl

@@ -0,0 +1,46 @@
+# benchmark_B4_polarization_omegaE.jl — ladder B4 (docs/05 §B)
+#
+# Targets are TIERED (Decision D9; docs/05 "Target tiers"):
+#   PRIMARY (T3): (i) the Wilson-Connor collisionless and Smolyakov collisional
+#                 SCALINGS; (ii) Delta_pol ~ omega_E^2 away from zero with a sign
+#                 reversal EXISTING at an omega_E of order -omega_dia,e, reversal
+#                 location insensitive to w/rho_theta_i; (iii) torque-balance
+#                 roots (Delta_sin = 0) EXISTING at discrete omega_hat_E.
+#   AUDIT-GATED (T4): the reversal LOCATION (sources: ~ -0.89 omega_dia,e) and
+#                 the root VALUES (sources: +/-0.93, +/-1.28 omega_dia,e)
+#                 [CHECKED: D23b Fig. 8; Diss19 Fig. 4.18].
+#
+# STATUS: SKIPPED. Wired to the M2c assembly (Islands.Configure.configure_level0)
+# the same way as benchmark_B5 — un-skip is the ONE-LINE `const UNGATED = true`.
+# Gated per docs/src/islands/QUESTIONS.md:
+#   Q3  the frame-convention signs (src/Islands/frames/) are NaN-gated until
+#       cleared — the omega_E-dependence of Delta_pol is exactly the physics the
+#       frames module must own before any sign-bearing benchmark runs
+#   Q5  the L0 assembly's gradient-drive (which carries the omega_E frame shift)
+#       and the QN (x-h) source are uncleared, so configure_level0 runs only
+#       STRUCTURALLY (no physics Delta_pol(omega_E))
+
+using GeneralizedPerturbedEquilibrium
+const Isl = GeneralizedPerturbedEquilibrium.Islands
+
+"""
+Flip to `true` only when QUESTIONS Q3 (frame signs) and Q5 clear.
+"""
+const UNGATED = false
+
+# The Delta_pol(omega_E) scan would assemble configure_level0 across an omega_E
+# grid (through the gradient-drive frame shift) and check the omega_E^2 scaling +
+# reversal/root existence (T3). GATED: needs the cleared frames convention (Q3)
+# and the Q5 gradient-drive/QN-source (see benchmark_B5).
+function run_b4()
+    error("B4 polarization structure is gated on QUESTIONS Q3 (frame signs) and Q5.")
+end
+
+if UNGATED
+    run_b4()
+else
+    println("SKIPPED: B4 polarization omega_E structure — gated on QUESTIONS Q3, Q5.")
+    println("  Scaffold wired to configure_level0; un-skip = `const UNGATED = true`.")
+    println("  Primary tier when un-gated: omega_E^2 scaling + reversal/root EXISTENCE")
+    println("  (T3). The -0.89 reversal location and root values are T4 (audit-gated).")
+end