Drift-kinetic island/layer solver#318
Draft
logan-nc wants to merge 44 commits into
Draft
Conversation
…an under src/islands Design bundle for ISLET (Integrated SoLver for Evolving Tearing), a planned steady-state multi-species drift-kinetic solver for the resonant island/layer region, generalizing the Modified Rutherford Equation the way SLAYER generalized linear layer theory. Revised against the full Imada/Dudkovskaia/Leigh reference set in docs/resources/Drift_Kinetic_Island_References (see REVISION-2026-07-07). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…uthor-title convention Renames the nine PDFs under docs/resources/Drift_Kinetic_Island_References to the YEAR-Author-Title convention used by the rest of docs/resources, and extends the .gitignore resources-PDF negation to subdirectories (!docs/resources/**/*.pdf) so these tracked references match the existing docs/resources/*.pdf policy. Syncs the filename references in the ISLET reference-library doc (docs/08). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…e convention) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…n into in-repo layout
Drop the working acronym ISLET in favour of the plain module name Islands, and
record the module-naming convention (simple intuitive names, not standalone-code
acronyms) in the repo-root CLAUDE.md.
Reconcile the design bundle from its standalone-package assumptions into the
in-repo layout:
- module conventions -> src/Islands/CLAUDE.md
- overview -> docs/src/islands/index.md
- design docs 00-08 -> docs/src/islands/design/
- Physics Book / state / derivations / papers / notes / LOG / QUESTIONS
-> docs/src/islands/{,state,derivations,papers,notes}
- benchmarks + figures -> benchmarks/islands/{,figures}
- verify harness -> src/Islands/verify/
- tests -> test/runtests_islands_*.jl (top-level test/)
- regression cases -> integrated under regression-harness/ (islands_*)
Islands is a submodule of the GeneralizedPerturbedEquilibrium package (no separate
Project.toml), not a standalone subpackage; docs/03/06 updated accordingly.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
logan-nc
changed the title
… infrastructure Stand up the Islands submodule and the infrastructure the autonomous-run protocol (design doc 06) assumes: - src/Islands/Islands.jl (module Islands, skeleton) wired into the package - docs/src/islands/LOG.md + QUESTIONS.md (session memory + blocker queue; Q1 records that julia is not on the automation shell PATH) - .claude/settings.json + hooks (guard-bash PreToolUse, stop-check Stop) for unattended dontAsk runs; physics-verifier subagent as the [VERIFY] backstop - docs/src/islands/design/M1-launch-prompt.md (the milestone contract fed to the overnight loop) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…docs The exported Islands module carries a docstring, which checkdocs=:exports requires be covered in the manual. Add docs/src/islands.md with an @autodocs block and wire it into make.jl (API Reference), matching the other submodule pages. Fixes the missing_docs docs-build failure introduced by the module stub. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…tings.json /doctor flagged two deny rules as skipped: the :* prefix wildcard is only valid at the end of a pattern. Rewrite them with a mid-pattern wildcard so the rules load and again restrict the protected-branch pushes for any remote or flags.
A loaded OMFIT module leaks the conda env lib dir onto LD_LIBRARY_PATH, shadowing Julia's bundled artifacts (CHOLMOD, glib/Cairo/GR) and producing false 'broken build' blocks in the Stop hook. Strip the var for the julia smoke check via env -u; this is a no-op on a clean shell and in CI.
M1 needs forward-mode AD for the JVP/AD-compatibility checks (design docs/src/islands/design/04-numerics.md §9). Adds ForwardDiff to Project.toml (already present transitively in the manifest); removes nothing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ck + verify harness Land the milestone-M1 numerical skeleton (design 03 §1-2, 04; ladder A1/A2), structure only — no [VERIFY] physics coefficients assigned in src/. - phasespace/PhaseSpace.jl: the (x, ξ, y, E, σ) grids with layer-clustered maps. Fourier spectral ∂ξ; Fornberg high-order finite differences for ∂x/∂y on sinh-stretched grids (per-derivative window widths so D1 and D2 are both 4th-order including boundaries); composite-Simpson quadrature weights; Gauss-Laguerre energy nodes. Pure numerics. - operators/Operators.jl: AbstractTerm + apply! + residual! and the term structs of 03 §2 (ParallelStreaming, MagneticDrift with the :original/:improved toggle, ExBDrift as the (x,ξ) Poisson bracket, Collisions, GradientDrive, PerpTransport and RadiationSink L4 stubs, Quasineutrality field residual). Every physics coefficient is a supplied data field, never a literal; allocation-free and generic over eltype so ForwardDiff duals flow through. - verify/Verify.jl: manufactured-solution (MMS) + AD-vs-finite-difference JVP harness, plus allocation probes. Manufactured coefficients are arbitrary order-unity test values (not physics), exercising the discretization only. - Islands.jl: wire the three submodules. physics-verifier: PASS (no [VERIFY]-policy violation). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…to runtests test/runtests_islands_grids.jl and test/runtests_islands_operators.jl, included in test/runtests.jl: - A1 per-operator MMS: 4th-order convergence for the ∂x/∂y differential terms, machine precision for the Fourier ∂ξ (drift) term; assembled kinetic residual converges at 4th order. - A2: forward-mode-AD JVP of the (nonlinear) assembled residual matches the central finite-difference directional derivative to ~1e-9. - Allocation regression: every apply! and residual! hot path allocates 0 bytes. - Grid unit tests: Fourier exactness, mapped-FD order, Simpson/Gauss quadrature, layer-clustered packing, IslandGrid assembly and input validation. All 53 Islands tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…path) - docs/src/islands.md: document the M1 skeleton (PhaseSpace/Operators/Verify), restating the structure-only [VERIFY] discipline. - LOG.md: M1 session entry (what moved / blocked / next). - QUESTIONS.md: Q1 RESOLVED — julia is at the ncl2128 software dir and must be invoked with a clean LD_LIBRARY_PATH (OMFIT contamination); used here to run the suite locally. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Set up the next milestone (M2 — L0 solve machinery) for the autonomous loop, mirroring the M1 launch-prompt bootstrap. - docs/src/islands/design/M2-launch-prompt.md: the M2 milestone contract. Scope = full L0 solve machinery (solvers/, moments/, frames/, fields/, species/, neoclassical-matching BCs) as AD-compatible allocation-free structure with every physics coefficient a [VERIFY]-gated parameter. DoD = the physics-free structural gates (A5 null, assembled solve-MMS, A8 y_c conditioning, A4 conservation, A3 parity, A7 ⟨∂²h/∂x²⟩=0) + suite + PR + Paper-I OUTLINE + the clearance queue. The York gates (B5a/b/c, B2, B4) are explicitly OUT — they need human-cleared physics; reaching one by hardcoding is a policy violation, not completion. - QUESTIONS.md: seed the parallel-human clearance queue — Q2 (ratify D7/D8), Q3 (clear the L0 [CHECKED] coefficient set with exact cites), Q4 (open [VERIFY]s: the psi-tilde q_s'/q_s typo, B5a collisionality, acquire WCHH96 + Park 2022). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the overnight-loop framing (dontAsk/--continue header, unattended language, Stop-hook exit-criteria) — M2 is driven interactively via /goal in auto mode. Blocked coefficients are surfaced to the user to clear live rather than only parked in QUESTIONS.md. The contract (scope, DoD, [VERIFY] hard rule, gated York gates) is unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ylov solver Matrix-free GMRES backend for the L0 solve (design docs/src/islands/design/04-numerics.md $5, $9). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…es, fields, moments
Land the Level-0 solve structure (design 03 §1-3, 04 §3-5; M2 contract), every
physics coefficient a supplied [VERIFY]-gated parameter — no literal in src/:
- solvers/Solvers.jl: matrix-free Newton-Krylov (Krylov.jl GMRES on a
preallocated ForwardDiff JVP operator; Eisenstat-Walker forcing; backtracking
line search; convergence on both norm and max-norm per 04 §5), YBlockJacobi
physics-block preconditioner skeleton with TSVD-regularized pencil solves
(the explicit y_c treatment of 04 §3), dense tiny-grid debug Jacobian, and a
pseudo-arclength continuation scaffold with fold detection from day one.
- species/Species.jl: Species{AbstractBackground}, Maxwellian/SlowingDown,
Bulk/Trace roles, validation + trace-criteria check (warn, never degrade) —
the D3 first-class species plumbing (02 §1).
- frames/Frames.jl: Level0Parameters input vector (01 §5) and the frame
conversion FORMS with every sign/normalization a NaN-defaulted gated
FrameConvention field — an un-cleared convention poisons results instead of
guessing (QUESTIONS Q3).
- fields/Fields.jl: Q(Ω)/h(Ω) flattened-electron closure structure (prefactor
supplied), the coefficient-free A7 identity ⟨∂²h/∂x²⟩_Ω = 0, and the
NaN-gated ElectronClosure constant set.
- moments/Moments.jl: J̄_∥ assembly from charge-scaled weighted moments,
Δ_cos/Δ_sin projections with REQUIRED gated prefactors (ψ̃ open [VERIFY],
sin normalization unpinned — QUESTIONS Q4), Ω label + ⟨·⟩_Ω average +
channel-split diagnostics (pinned half-width convention).
- operators/: PitchAngleDiffusion in mimetic divergence form (exact discrete
particle conservation + entropy sign, ladder A4), FarFieldConditions
matching BCs (never bare Neumann, 01 §3), weighted_moment!, flat-index
helpers; IslandGrid now records y_c for the A8 monitor.
- verify/: solve-level MMS + zero-drive configurations (A5/A1-solve) and the
yc_block_sigma_min conditioning monitor (A8, the L23 §4.2 silent-noise
regression tripwire).
All new kernels pass a --check-bounds=yes run (M1 lesson).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…/A8 + solve-MMS) test/runtests_islands_solve.jl (67 tests, wired into runtests.jl): - A5 zero-drive null: residual exactly machine zero at g ≡ 0; Newton falls back to the zero state from a perturbation. - A1-solve: assembled Newton-Krylov solve recovers the manufactured state at design order (observed 3.98 on the nx = 17→33 pair). - A4: exact discrete particle conservation (≲1e-11) + entropy sign of the mimetic pitch-angle operator; allocation-free apply!. - A3: Δ_cos even / Δ_sin odd under ξ-reflection, spectrally exact projections. - A7: ⟨∂²h/∂x²⟩_Ω = 0 to 1e-10 across Ω and prefactors (coefficient-free). - A8: y_c-block σ_min monitor is finite/positive and detects an artificially singularized pencil. - Preconditioner gate: YBlockJacobi cuts GMRES iterations >2× at identical solutions; far-field BC rows; pseudo-arclength fold detection; species + gated-frames plumbing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…ctural regression case - benchmarks/islands/ (+ figures/): the docs/05 B-ladder scripts B2 (large-w limits), B4 (polarization ω_E structure), B5a/b/c (York threshold triangle) — all SKIPPED, each naming the QUESTIONS.md entries (Q2-Q4) whose human clearance un-gates it. Un-skipping by filling in a coefficient is the forbidden action; the scripts say so. - regression-harness: new computed case islands_l0_structural tracking the structural numbers that silently move if the discretization/solver/quadratures drift — solve-MMS error + Newton/GMRES iteration counts (nx=17), the A7 closure identity, and the A8 y_c-block sigma_min. Verified locally: err=5.254e-2, 6 Newton / 1210 GMRES, A7=8.0e-17, sigma_min=0.1139. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
- docs/src/islands/papers/paper-1/OUTLINE.md: the Level-0 figure contract (docs/07 §3), claims → figures → ladder IDs. C1-C3 (discretization order, solver conditioning, conservation structure) are green as CI artifacts; C4-C8 (neoclassics, large-w limits, the York triangle, the Δ_pol(ω_E) reversal, the L23 electron-Δ_pol question) are gated on QUESTIONS Q2-Q4. - docs/src/islands.md: M2 status (all seven submodules, gating summary). - LOG.md: M2 session entry, including the solve-well-posedness lesson (generic y-diffusion without BCs is unstable; the mimetic degenerate form + far-field x-BCs are the correct structure). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…docs missing_docs) Documenter's checkdocs=:exports requires every exported docstring in the package (including submodules) to appear in a page; the islands.md @autodocs block only listed the top-level Islands module, so the PhaseSpace/Operators/ Verify exports failed the docs build. Add per-submodule @autodocs sections. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…ocs missing_docs) Extend the islands.md API reference with @autodocs sections for the five M2 submodules (SpeciesLists, Frames, Fields, Moments, Solvers) on top of the M1 fix — checkdocs=:exports requires every exported docstring covered. Local docs build passes clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
ISLANDS - M1: phase-space grids + operator-stack skeleton + MMS/AD harness
…uations + figures, Islands site section Address the missing narrative documentation: the design docs existed in-repo but were never wired into the rendered site, and no figures existed because the figure pipeline was contracted to the (gated) B-ladder. - docs/src/islands/numerics.md: "numerics as implemented (M1-M2)" — the equations of everything actually built (sinh layer maps, spectral/Fornberg operators, the operator-stack residual, the mimetic collision form with its exact discrete conservation/entropy identities, Newton-Krylov + EW forcing + TSVD preconditioning, pseudo-arclength fold detection, Ω/⟨·⟩_Ω/h(Ω) geometry and the A7 identity, the Δ projections with gated prefactors), each anchored to its implementing symbols, with the A-ladder evidence table. - benchmarks/islands/figures/make_structural_figures.jl: pinned script (docs/07 §2) generating the five structural figures from the verification machinery (grid clustering, MMS+solve convergence, Q/h profiles + A7, preconditioner GMRES comparison, continuation fold); PNGs committed under docs/src/islands/figures/ (gitignore exception) as docs assets. - docs/make.jl: new "Islands" nav section — overview, numerics chapter, Paper-I figure contract, and the full design-document set (00-08). - docs/src/islands.md: now links the narrative pages from the API reference. Local docs build passes clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
ISLANDS - M2: Level-0 solve machinery (Newton-Krylov, Δ moments, species/frames/fields) — structure, gated physics
…tract (derivation lane) User decisions (2026-07-08): PR #324 merged; D7 and D8 ratified as written (Decision Log updated, Q2 RESOLVED); Q3 clearance mode = re-derivation first. M2b-launch-prompt.md is the next milestone contract: independent derivations of the L0 coefficient set into docs/src/islands/derivations/ with cross-check tables against the [CHECKED] transcriptions, item-by-item human sign-off (recorded in docs/01) clearing coefficients into a named-configuration builder, progressive un-skipping of the B-ladder with docs/05 reporting, and honest triage of any threshold disagreement. Provenance rules sharpened: [DERIVED] never presented as transcription, no unsigned coefficient in src/, no tuning to pass benchmarks. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…citation The docs/08 island-subfolder map missed the SLAYER paper sitting in the general GPEC library (docs/resources/2022-Park-Parametric dependencies...). Map and Q4 corrected; only WCHH96 (Wilson, Connor, Hastie & Hegna, Phys. Plasmas 3, 248 (1996), doi:10.1063/1.871830) remains to acquire. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…R-matching template - WCHH96 (Wilson, Connor, Hastie & Hegna, PoP 3, 248 (1996)) added to the island reference library by the user and promoted into the docs/08 primary table: first-hand source for the flattened-electron closure (docs/01 §2.4) and the large-w Eq. (85) target (ladder B2) — previously cited only via I19/L23/Diss19 transcriptions. - Burgess 2026 (toroidal Δ' + Park-2022 SLAYER two-fluid slab layer) recorded as B26: the outer/inner regime-generalized matching template that Islands extends from zero-width linear layers to finite-width islands (ladder D1). - Q4 acquisition sub-items resolved; remaining open: ψ̃ amplitude check and B5a run collisionality. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…caling-first)
User-flagged flaw: absolute literature numbers (w_c 2.76/8.73, 0.45/1.46 rho,
the kokuchou 0.440 fit, the -0.89 omega_dia reversal, D23a shaping widths) were
propagated as pass/fail targets, but reproducing an absolute number requires
every input of the source's exact scenario — which the lineage under-specifies
(B5a's own collisionality is internally contradictory: I19 §4.2 nu*=0.01 vs L23
nu*=1e-3).
Decision D9 (docs/00): four-tier target taxonomy in docs/05 —
T1 exact math; T2 internal cross-checks & toggle differentials (sharpest,
primary quantitative gates); T3 scalings/trends/existence vs literature
(primary literature-facing gates); T4 absolute reproduction (audit-gated,
never pass/fail without an input manifest, downgraded to T3 where the source
is under-specified). Plus a fifth triage outcome ("under-specified source
configuration") and three reporting rules (publish the manifest; prefer
ratios/differentials; sensitivity scans).
Applied across docs/05 (all B/C rows retagged, A7 constants marked T1), docs/00
(gate softened, D9 logged), Paper-I OUTLINE (C5-C7 scaling-first; new C9 = the
input-completeness audit as a methods deliverable), the three B benchmarks +
README (tier-labeled), the M2b prompt (new deliverable: per-source input
manifests; B-ladder DoD = T2 differential + T3 scalings, T4 only with
manifests), QUESTIONS (B5a collisionality reframed as the audit type specimen),
numerics.md and islands.md status. Docs-only; local docs build green. Aligns the
ladder with the SLAYER-validation precedent (Park 2022 / Burgess 2026).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…closes the psi-tilde [VERIFY] First M2b derivation-lane chapter (Decision D7, re-derivation-first). Independent re-derivation of the island flux amplitude from the helical-flux island geometry: psi-tilde = (w_psi^2 / 4) (q_s' / q_s) [DERIVED: 2026-07-11] with q_s' = dq/dpsi. Three independent arguments give q_s'/q_s: (a) the helical flux chi_0 = psi - psi_tor/q_s has curvature chi_0'' = -q_s'/q_s; the constant-psi island half-width w_psi = 2 sqrt(psi-tilde/|chi_0''|) inverts to psi-tilde = (w_psi^2/4)|chi_0''|; (b) dimensional analysis makes q_s/q_s' impossible (it gives [psi]^3, not [psi]); (c) Omega = chi/psi-tilde reproduces the pinned Omega = 2(psi-psi_s)^2/w_psi^2 - cos xi exactly. Closes the open [VERIFY] (QUESTIONS Q4). First-hand check of I19: the paper as printed (print p.3, text after Eq.6) shows q_s/q_s', but its own Eq.(7) Omega requires q_s'/q_s and it defines L_q = q/q' — so I19 is internally inconsistent and the amplitude text is a published typo (docs/05 triage: their published- equation error, same class as the L23 §2.6 amendments). This is exactly the failure mode the re-derivation-first policy exists to catch. physics-verifier: PASS (provenance clean, logic verified, no src/ coefficient assigned — psi-tilde stays gated in Moments.delta_moments until human sign-off). Docs-only; local docs build green; wired into the Islands > Derivations nav. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…ned-off coefficient) Human sign-off 2026-07-11 of the psi-tilde derivation (D7). Records the clearance and un-gates the cleared relation: - docs/01 §1: [CHECKED: I19 Eq.5...] -> [CLEARED: sign-off 2026-07-11, derivation link]; the psi-tilde [VERIFY] marked RESOLVED (I19 published typo; physical form q_s'/q_s). - Moments.island_flux_amplitude(; w_psi, dq_dpsi, q_s) = (w_psi^2/4)(q_s'/q_s), anchored to the derivation, with 4 tests (value, w^2 scaling, half-width round-trip, q_s=0 guard). 71 islands-solve tests green. - delta_moments prefactors stay required/gated (mu_0 R + sin-normalization pin are separate open items); Frames/Fields NaN-gates untouched. physics-verifier: PASS (formula matches signed-off derivation; clearance recorded, not a silent promotion; nothing else un-gated). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…iginal/:improved toggle (D7)
Second M2b derivation-lane chapter. Independent re-derivation of the orbit-
averaged magnetic drift frequency from the guiding-centre drift (I19 Eq.8) and
p_phi conservation:
omega_hat_D = (sigma v_hat/(1+eps))[ (1/L_hat_q)<sqrt(1-yb)/b>
- (1/2)<(1/L_hat_B)(2-yb)/(b sqrt(1-yb))> ]
Two physical pieces: (1) the drift-orbit radial width x_D = rho_hat_theta_i
(sigma v_hat/(1+eps)) sqrt(1-yb)/b coupled to the safety-factor shear (1/L_q);
(2) the grad-B drift from dB/dpsi (1/L_B). The :original/:improved toggle is the
treatment of dB/dpsi: D21 Eq.(A2) gives dB/dpsi = -(B_phi/R_0^2 B_theta) cos theta
(low beta), so the cos theta orbit-averages to O(eps) => :improved sets
L_hat_B^-1 = 0; :original keeps it finite. This toggle is the highest-impact
physics item (the T2 ~x6 threshold-width differential; absolute 8.73->1.46 rho_bi
is T4/audit-gated, per D9).
Cross-checks (all first-hand): I19 Eq.(32), D21 Eq.(B1) [with the identity
V_par + lambda V^2/(2 V_par) = V(2-lambda B)/(2 sqrt(1-lambda B))], D21 Eq.(A2).
No discrepancy (unlike the psi-tilde typo).
physics-verifier: PASS (algebra (a)-(d) verified by hand, D21-B1 reconciliation
confirmed, provenance clean, no src/ change; MagneticDrift.c_D stays gated).
Docs-only; local docs build green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…le; drift-model toggle usable) Human sign-off 2026-07-11 of the omega-hat-D derivation (D7). Records the clearance (docs/01 §2.1: [CHECKED] -> [CLEARED]) and implements the cleared coefficient: - New src/Islands/coefficients/Coefficients.jl: the home for human-cleared L0 physics coefficient builders (M2b fill-ins). magnetic_drift_frequency(...) computes omega-hat-D = (sigma v_hat/(1+eps))[inv_Lq A - (1/2) inv_LB G] via the orbit-average brackets A=<sqrt(1-yb)/b>, G=<(2-yb)/(b sqrt(1-yb))> (QuadGK; passing full-circuit, trapped bounce-integral with the integrable turning-point singularity). variant=:improved forces inv_LB=0 (D21 proxy). Wired into Islands.jl. - 13 tests: eps->0 analytic limit (A->sqrt(1-y), G->(2-y)/sqrt(1-y)), the toggle (:improved == :original with L_B=0), sigma-odd / v_hat-linear prefactor, trapped finiteness, forbidden-y and bad-variant guards. 84 islands-solve tests green. The toggle is a large effect at the test point (grad-B nearly cancels the shear term) -- the mechanism behind the ~x6 threshold differential. physics-verifier: PASS (formula matches signed-off derivation; clearance recorded; trapped branch sound; Frames/Fields NaN-gates and Moments prefactors untouched). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…deflection frequency + nu_star (D7) Third M2b derivation-lane chapter. Independent re-derivation of the Level-0 momentum-conserving pitch-angle (Lorentz) collision operator (I19 Eq.9), the deflection frequency (I19 Eq.11), and the nu_star normalization (L23 Eq.2.3.40): - The pitch operator is Lorentz scattering in self-adjoint form w^-1 d_lambda(P d_lambda) with diffusivity P(lambda)=lambda sqrt(1-lambda B) and measure w=B/sqrt(1-lambda B); the change of variables from the pitch cosine derives the exact 2 nu_jj prefactor. This is the same divergence form the mimetic PitchAngleDiffusion discretizes (conservation gate A4). - Deflection frequency nu_jj = nu_tilde[phi(v_hat)-G(v_hat)]/v_hat^3 (Chandrasekhar), with the :chandrasekhar/:vcubed sub-toggle. Low-v: phi-G -> (4/3 sqrt-pi) v_hat (LINEAR) so nu_jj ~ 1/v_hat^2 diverges -- the "nu_tilde ~ u^-2 divergence" of docs/01 §2.3 motivating the analytic average. - nu_star = nu_jj Rq/(eps^3/2 v_th) normalization. Two sub-items honestly DEFERRED (not asserted, policy rule 4): the analytic <nu_hat_ii>_u constant (L23 Eq.4.1.6, its own short derivation) and the discretized diffusivity profile (numerics, ties to A4). Review caught two errors, both fixed before sign-off: the §3 low-v limit (phi-G is linear, not cubic -> nu_jj diverges, not finite) -- caught independently by me and the physics-verifier -- and a §2 factor-of-2 in the change of variables (now derives the exact 2 nu_jj). Docs-only; local docs build green. Awaiting human sign-off. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
… src (P(lambda), deflection frequency) Human sign-off 2026-07-11 of the collision-operator derivation (D7). Records the clearance (docs/01 §2.3: [CHECKED] -> [CLEARED] for the operator structure, deflection frequency, and nu_star; the <nu_hat_ii>_u constant stays [CHECKED]- gated as a deferred sub-item) and un-gates the cleared building blocks: - Coefficients.pitch_diffusivity(lambda, B) = lambda sqrt(1-lambda B): the Lorentz operator's self-adjoint diffusivity P (feeds conservative_pitch_operator; vanishes at both endpoints, preserving the A4 gate). - Coefficients.deflection_frequency(v_hat; model): nu_jj = nu_tilde[phi-G]/v_hat^3 (:chandrasekhar) or nu_tilde/v_hat^3 (:vcubed), phi via QuadGK, G Chandrasekhar. - 11 tests: P endpoints/positivity/domain; deflection high-v (-> nu_tilde/v_hat^3, with the slow 1-1/2v_hat^2 approach) and low-v (-> (4/3 sqrt-pi)/v_hat^2 divergence, the derived linear phi-G limit); chandrasekhar < vcubed at low v; model/domain guards. 96 islands-solve tests green. The full discretized/orbit-averaged PitchAngleDiffusion assembly and the <nu_hat_ii>_u momentum-restoring constant remain deferred (docs/01 §2.3 note). Derivation physics-verifier: PASS (after review caught + fixed a low-v limit error and a change-of-variables factor). Un-gate implements the just-verified cleared forms directly, validated by the eps/velocity-limit tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…a) + amplitude (D7); fix Coefficients docs coverage Fourth M2b derivation-lane chapter (awaiting sign-off). Independent re-derivation of the flattened-electron profile function and its amplitude: - The closure constraint <d2h/dx2>_Omega = 0 (the A7 identity) gives the ODE 2 h'' <Omega+cos xi>_Omega + h' = 0; with <Omega+cos xi>_Omega = Q/(2Q') (Q=(1/2pi)∮sqrt(Omega+cos xi)dxi) this integrates to h'(Omega) = C/Q(Omega) -- i.e. h = Theta(Omega-1) C ∫_1^Omega dOmega'/Q. The already-green A7 gate IS this closure constraint. - Far-field matching h -> x (Q -> sqrt(Omega)) fixes the amplitude C = w_psi/(2 sqrt2), matching I19 Eq. 18 exactly. - The I19 Eq. 22 flow-relation structure is presented; the two constants k ~= -1.173 (Hirshman-Sigmar) and the 1.46 in f_p = 1 - 1.46 sqrt(eps) are honestly DEFERRED (their own short derivations), not asserted. physics-verifier: PASS (algebra (a)-(e) verified first-hand incl. h'=C/Q and the C=w_psi/2sqrt2 matching; provenance clean; deferred constants not asserted). Also FIXES the docs build (was red since the omega-D commit): the new Coefficients module's exported docstrings were not in the manual; added its @autodocs section to islands.md (checkdocs=:exports). Local docs build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…ts.h_amplitude) Human sign-off 2026-07-11 of the electron-closure derivation (D7). Records the clearance (docs/01 §2.4: h(Omega) form + amplitude [CLEARED]; the flow constants k ~= -1.173 and f_p's 1.46 stay [CHECKED]-gated as deferred sub-items) and un-gates the cleared amplitude: - Coefficients.h_amplitude(w_psi) = w_psi/(2 sqrt2): the flattened-electron profile prefactor C, derived from the flattening constraint (h'=C/Q) + far- field matching h->x. Feeds Fields.h_profile's prefactor. - 3 tests: the amplitude value; the far-field asymptote h_profile(Omega; C) -> (w_psi/sqrt2)(sqrt(Omega)-1) (a real check of the §3 derivation + the Q->sqrt(Omega) asymptotics); ElectronClosure k/f_p stay NaN. 98 islands-solve tests green. Derivation physics-verifier: PASS (h'=C/Q ODE and C=w_psi/2sqrt2 matching verified first-hand). Un-gate is a one-line cleared relation; far-field test validates it physically. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
…), arbitrary tau (D7) Fifth M2b derivation-lane chapter (awaiting sign-off). Independent re-derivation of the Level-0 quasineutrality closure from the ion/electron density moments: - Ion moment n_i = n0(1-ePhi/T_i) + n0'(psi-psi_s) + dn_bar_i (from f_i, I19 Eq.23). - Electron moment n_e = n0(1+ePhi/T_e) + n0' h(Omega) (flattened closure; the v_par-odd term vanishes). - n_i=n_e => Phi_hat = tau/(tau+1)[dn_bar_i/n0 + L_n0^-1(x - h_hat)]. The denominator (tau+1)/tau is the SUM of ion+electron adiabatic shielding responses (1/T_i + 1/T_e) -- the origin of the "2" in 1/(2 L_n0). At tau=1 this reduces exactly to I19 Eq. A.11 [dn_i/n0 + x - h_hat]/(2 L_n0), and the derivation adds the arbitrary-tau generalization docs/01 §3 asks for. Initial pass surfaced a structural question (dn_i inside vs outside the 1/L_n0 factor); read I19 Eq. A.11 first-hand (print p.11) and resolved it: no discrepancy -- I19's normalized dn_i = L_n0 * (raw moment), a definitional convention, flagged openly. The invariant x-h_hat structure and the tau=1 coefficient match I19 exactly with nothing tuned. physics-verifier: PASS (algebra a-e verified first-hand incl. the (tau+1)/tau factor and tau=1 reduction; provenance clean, no src/ change; dn_i normalization honestly a convention). Local docs build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016pUwoFRo9a5AjF8HuwcZMr
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design plan (docs only) for Islands, a new GPEC submodule (
src/Islands/): a steady-state, multi-species drift-kinetic solver for the resonant island/layer region that returns the growth moment Δ_cos(w, ω; p) and torque moment Δ_sin(w, ω; p) for arbitrary parameters — replacing the sum of regime-specific Modified Rutherford Equation terms with a single calculation, and in its small-amplitude limit reducing to the linear layer response so that error-field shielding, penetration, seeded-NTM onset, and island saturation become faces of one solution manifold.Draft: this PR lands the design docs (
docs/src/islands/, module conventions insrc/Islands/CLAUDE.md) and the drift-kinetic reference library, revised against the Imada / Dudkovskaia / Leigh source set. No solver code yet.🤖 Generated with Claude Code