[spectre-09] Implement Level-1 interface crossing map with derivation note

[krystophny]

Stage: SIMPLE / interface-crossing physics (milestone M2)
Source language: Fortran 2008 (+ derivation note in Markdown)
Manuals to read first: VENUS-LEVIS + SPEC crossing paper (https://doi.org/10.1016/j.cpc.2021.108191) — the RK4 + event-location precedent and its sheared-slab test; symplectic integration of discontinuous Hamiltonians (https://arxiv.org/abs/2101.11018) — refraction-map framework and order-collapse results; src/interface_crossing.f90 from [spectre-08] (the Level-0 map and infrastructure this issue upgrades).
Depends on: #443

Goal

Upgrade the interface crossing from the Level-0 energy-rescale map to the physically and geometrically correct "Level-1" jump map: the thin-current-sheet limit of guiding-center dynamics, which is symplectic by construction and adds the tangential sheet-drift kick and the drift-order v_par term that Level 0 omits. Deliverables: (a) a derivation note, (b) the upgraded map behind the existing apply_crossing entry point (callers untouched), (c) map-level selection between Level 0 and Level 1 for regression comparison.

Files to edit

• DOC/spectre-interface-crossing.md: NEW derivation note (see contract below).
• src/interface_crossing.f90: extend with the Level-1 map and its reflection branch; keep Level 0 selectable.
• test/tests/test_spectre_crossing.py + test/tests/test_crossing_map.f90: NEW.

Derivation contract (the note must establish exactly this)

Thin-layer limit of the guiding-center phase-space Lagrangian across a sheet at s = s0 carrying jumps [[B]] (pressure step) and [[h]] (rotational sheet):

• Jump = impulse along the Hamiltonian vector field of the interface function s under the guiding-center Poisson bracket: Delta z = lambda * {z, s} with components {s,s} = 0 (stays on the surface), tangential kick {theta,s}, {zeta,s} ~ (h x grad s)-drift direction, and {v_par, s} ~ (curl h)^s at drift order (leading term vanishes because B.n = 0).
• Single scalar lambda fixed by exact energy conservation H+ = H- with mu conserved (model assumption; stated with its adiabaticity caveat).
• Profile independence where it holds: the x and v_par kick integrands telescope to endpoint jumps (machine-verified, spectre-orbits ca/06). For MIXED sheets (simultaneous [[B]] and [[h]]) the tangential Delta-y kick is profile-ordering dependent at leading order (finding F4); the note must either adopt a force-balanced internal sheet profile or quantify the ordering spread as model uncertainty.
• Reflection branch: no real crossing solution (v_par'^2 < 0 at the kicked point) → same-side exit map, energy-exact.
• Discrete symplecticity: specify the evaluation point/symmetrization of the kick (e.g. generating-function or midpoint-on-surface form) such that the implemented discrete map is symplectic, not just its continuum limit.
• Explicit statement of what Level 0 omits and the resulting per-crossing error scaling.

Acceptance scenarios (BDD)

• Given a regularized reference (same equilibrium with the sheet smoothed over widths w, integrated with fine-tolerance RK45 in a single smooth chart), then the Level-1 post-crossing state converges to the reference as w → 0 at first order in w — for both the [[B]] kick and the tangential [[h]] kick; Level 0 shows a persistent tangential offset in the same test.
• Given a two-volume SPECTRE tokamak file with a pressure step, when a passing guiding center crosses, then total energy is conserved to 1e-14 per crossing and mu is unchanged (regression of the Level-0 guarantee under the upgraded map).
• Given a zero-pressure-step rotational-sheet interface, then |v_par| is unchanged and the tangential kick matches the curvature-drift formula from the note.
• Given a deeply trapped particle with a forbidden crossing, then the Level-1 reflection branch triggers with its tangential kick, energy exactly conserved.
• Given an identical multi-volume ensemble run under Level 0 and Level 1, then the crossing logs pair up one-to-one and the statistical difference in loss fractions is reported by the test (informational bound, no hard threshold).

Success criteria

make && make test TEST=spectre_crossing

Non-goals

• No symplectic-integrator wiring ([spectre-10] does exact-landing substeps and re-canonicalization).
• No mu-scattering model beyond conserved mu (full-orbit quantification is [spectre-11]).
• No grazing-incidence handling beyond the guard inherited from [spectre-08].

Verification

make test TEST=spectre_crossing

[krystophny]

Automated triage pass (Claude), grounded in the repository at d8b0e01. Verify before acting.

Keep open, narrowed: the Level-1 map shipped, but three of its own acceptance items are still unmet

The bulk of #440 is on main and works. What is left is small, concrete, and not covered by any other issue — so this issue should be narrowed to the residual rather than closed as completed.

Purpose

Finish the Level-1 interface crossing deliverable by closing the gap between what the issue's acceptance scenarios require and what the merged code and derivation note actually provide: restore the stated per-crossing energy tolerance, add the missing pure-rotational-sheet scenario, and repair the derivation note where it now contradicts the shipped map.

Current state

What landed (verified). All four commits are real and are ancestors of origin/main:

• e629ac0 "Add Level-1 interface crossing refraction map ([spectre-09] Implement Level-1 interface crossing map with derivation note #440)" — DOC/spectre-interface-crossing.md +187, src/interface_crossing.f90 +248, test/tests/test_spectre_crossing_l1.py +186, plus test/tests/CMakeLists.txt +13 and the params.f90 knob.
• 715c422 — validity-domain / mirror fallback (finding F5), note only.
• 55d35cb — GC-first SPECTRE sheet fallback.
• 6038262 — equal-|B| relocation of forbidden crossings (CA15).

Deliverable (a): DOC/spectre-interface-crossing.md exists, 230 lines. Deliverable (b): level1_map (src/interface_crossing.f90:454) is dispatched from apply_crossing (src/interface_crossing.f90:124) at src/interface_crossing.f90:197, with solve_crossing (:510), residual_at (:581) and relocate_forbidden (:282); callers are unchanged in shape (src/spectre_orbit.f90:140, src/spectre_sympl_orbit.f90:385). Deliverable (c): crossing_level defaults to 1 at src/params.f90:147, is in the &config namelist at src/params.f90:181, threaded through src/simple_main.f90:1297,1321,1398,1415, documented at DOC/coordinates-and-fields.md:1020, with error stop on unknown values at src/interface_crossing.f90:140. The midpoint symmetrization the contract demands is real: residual_at refreshes the generator at z + 0.5*lam*X by sym_iters = 2 fixed-point sweeps (src/interface_crossing.f90:70 region, parameters max_newton = 40, max_backtrack = 20, newton_rtol = 1.0d-14, max_kick = 0.3d0).

make test TEST=spectre_crossing resolves via Makefile:24 to ctest --test-dir test --output-on-failure -R "spectre_crossing", which matches test_spectre_crossing_l0 (test/tests/CMakeLists.txt:912), test_spectre_crossing_l1 (:926) and also the test_spectre_sympl_crossing* tests.

What is not done. Four items, each checkable:

1. Energy tolerance regressed against the issue's own scenario. BDD scenario 2 requires energy conserved "to 1e-14 per crossing" as a regression of the Level-0 guarantee. test/tests/test_spectre_crossing_l0.py:34 does assert H_TOL = 1.0e-14. test/tests/test_spectre_crossing_l1.py relaxes it to H_TOL = 1.0e-13 — a 10x weakening, applied to the very guarantee the scenario says must be preserved. Nothing in the note or the commits justifies the relaxation.
2. BDD scenario 3 is untested anywhere. "Given a zero-pressure-step rotational-sheet interface, then |v_par| is unchanged and the tangential kick matches the curvature-drift formula from the note." No test exercises a pure-[[h]] sheet. rg over test/ finds no rotational-sheet or curvature-drift case. tok2vol carries a [[B]] jump (the l1 test asserts one exists), so it cannot serve as this fixture.
3. The derivation note now contradicts the shipped code. The note was last touched by 894a594 ([spectre-10] Integrate crossing map into symplectic multi-volume orbits #441) and never updated for 6038262. DOC/spectre-interface-crossing.md:99-105 still states that a forbidden crossing "reflects as the Level-0 mirror (v_par -> -v_par, mu, |B| unchanged, stays home), which keeps the trapped sheet-skimming class identical to Level 0", and :145-151 repeats the mirror convention. The shipped relocate_forbidden does something materially different: it walks along the interface to the conjugate equal-|B| point at frozen v_par (vpar_new = vpar, not -vpar), and its transmit_hit branch can even set info%event_type = CROSS_CROSSING — so the event split does not always match Level 0, contrary to the note. The Level-0 mirror survives only as the fallback default.
4. The note cites a file that is not in the repo. DOC/spectre-interface-crossing.md:163 points the F4 ordering-spread work at "the regularized slab integrator in python/fig_crossing_convergence.py". That path does not exist (ls python/fig_crossing_convergence.py → no such file); the only hit for the name in the tree is the note itself. This is also the reference that BDD scenario 1 (the w -> 0 first-order convergence check) would be built against, so the note delegates to a tool nobody can run.

What is correctly delegated, and is not part of this issue. The full-orbit mu-scatter quantification and the production-scope mixed-sheet ordering-spread study are assigned by the note to SIMPLE#442 ([spectre-11] Validate SPECTRE losses, classification, and full-orbit crossing), which is open, and by #440's own non-goals ("full-orbit quantification is [spectre-11]"). Leave those there.

Also worth recording, not a blocker. The issue's "Files to edit" named test/tests/test_spectre_crossing.py and test/tests/test_crossing_map.f90; neither exists. The Python behaviour is covered by the _l0/_l1 split instead, and a Fortran unit test for the reflection branch does exist — test/tests/field_can/test_spectre_kicked_reflection.f90, registered as test_spectre_kicked_reflection at test/tests/field_can/CMakeLists.txt:113. Note that this name is not matched by -R spectre_crossing, so the issue's stated verification command does not exercise the reflection branch.

Reproduction / evidence

# 1. The tolerance gap: l0 holds 1e-14, l1 only 1e-13.
rg -n 'H_TOL *=' test/tests/test_spectre_crossing_l0.py test/tests/test_spectre_crossing_l1.py
# test_spectre_crossing_l0.py:34:H_TOL = 1.0e-14
# test_spectre_crossing_l1.py:  H_TOL = 1.0e-13

# 2. No rotational-sheet scenario anywhere.
rg -n 'rotational|curvature.drift|zero.pressure' test/    # no crossing-map hits

# 3. Note contradicts code on the forbidden branch.
sed -n '99,105p' DOC/spectre-interface-crossing.md         # "reflects as the Level-0 mirror ... stays home"
rg -n 'vpar_new = vpar$|CROSS_CROSSING' src/interface_crossing.f90 | sed -n '1,6p'
git log --oneline -- DOC/spectre-interface-crossing.md     # last touch 894a594, predates 6038262

# 4. Cited script is absent.
ls python/fig_crossing_convergence.py                      # No such file or directory

Also note that the l1 generator-identity assertion is narrower than it reads: check_identity filters to refr = cross[cross[:, C_LAM] != 0.0] and samples refr[:20], requiring only MIN_REFRACTED = 10 refracted events. The note itself records why (DOC/spectre-interface-crossing.md:132-134): on tok2vol the poloidal |B| variation is weak, so "most crossings take the Level-0 rescale and a minority refract with kicks up to ~0.2 rad". The headline upgrade is therefore validated on a minority of events on the only fixture that exercises it.

Behaviour (BDD)

• Given the tok2vol two-volume fixture under crossing_level = 1, when the ensemble runs, then every non-loss crossing event conserves H = v_par^2/2 + mu |B| to |dH|/H < 1e-14 — the same bound test_spectre_crossing_l0.py already holds Level 0 to.
• Given a zero-pressure-step rotational-sheet interface ([[B]] = 0, [[h]] != 0), when a guiding centre crosses under crossing_level = 1, then |v_par| is unchanged to round-off and the tangential kick (dtheta, dzeta) matches the X_theta = -ro0 h_zeta/(sqrtg Bstar_par), X_zeta = +ro0 h_theta/(sqrtg Bstar_par) formulas of DOC/spectre-interface-crossing.md:90-92 evaluated at the landing point.
• Given a reader of DOC/spectre-interface-crossing.md, when they read the forbidden-crossing branch, then the note describes the equal-|B| relocation actually implemented in relocate_forbidden — frozen v_par, possible relocated transmission, reloc_max_dirjump gate, Level-0 mirror as fallback — and no longer asserts that the Level-1 event split is identical to Level 0.
• Given the note's references, when a reader follows them, then every in-repo path it cites resolves.

Implementation plan

1. test/tests/test_spectre_crossing_l1.py — set H_TOL = 1.0e-14. If the Level-1 map genuinely cannot hold it, do not silently relax: record the achieved residual and the mechanism (most likely the newton_rtol * |hh| convergence test in solve_crossing, or |B| re-evaluation at the kicked angles) in the note, and state the weakened bound there as a deliberate Level-1 property.
2. New rotational-sheet case. Cheapest route is a Fortran unit test beside the existing one — test/tests/field_can/test_spectre_rotational_sheet.f90, calling apply_crossing(..., CROSSING_LEVEL1, ...) directly on a constructed [[B]] = 0 state, in the style of test_spectre_kicked_reflection.f90. Assert |v_par| invariance and compare info%xtheta/info%xzeta against magfie quantities at the landing point. Register it under a name matching spectre_crossing so make test TEST=spectre_crossing covers it; consider renaming test_spectre_kicked_reflection likewise.
3. DOC/spectre-interface-crossing.md — rewrite the "Crossing vs mirror" paragraph (:99-105) and the F5 implementation sentence (:145-151) to describe CA15 as shipped. Either add python/fig_crossing_convergence.py to the repo or replace the citation at :163 with the actual location of the slab integrator, or drop the pointer and state plainly that the regularized reference is not yet in-tree.
4. BDD scenario 1 (w -> 0 convergence) depends on item 3's slab reference existing. If that reference will not land here, say so explicitly in the note and move the scenario to [spectre-11] Validate SPECTRE losses, classification, and full-orbit crossing #442 by name, so the deferral is recorded rather than implicit.

Acceptance criteria

make && make test TEST=spectre_crossing

• test_spectre_crossing_l1 passes with H_TOL = 1.0e-14, or the note documents the achieved Level-1 bound and why it differs from Level 0.
• A rotational-sheet ([[B]] = 0) crossing test exists, is matched by -R spectre_crossing, and passes.
• rg -n 'Level-0 mirror' DOC/spectre-interface-crossing.md no longer describes the forbidden branch as an in-place mirror with a Level-0-identical event split.
• Every in-repo path cited by DOC/spectre-interface-crossing.md resolves.

References

• DOC/spectre-interface-crossing.md (230 lines) — derivation note; brackets at :62-65, SIMPLE-unit generator at :90-92, crossing-vs-mirror at :99-105, thin-layer fallback at :125-134, F5 at :136-151, F4 at :153-165, slab oracles at :167-179, mu caveat at :223-230.
• src/interface_crossing.f90 — apply_crossing:124, dispatch :197, relocate_forbidden:282, level1_map:454, solve_crossing:510, residual_at:581.
• test/tests/test_spectre_crossing_l0.py:34, test/tests/test_spectre_crossing_l1.py, test/tests/CMakeLists.txt:912,926, test/tests/field_can/CMakeLists.txt:113.
• Commits e629ac0, 715c422, 55d35cb, 6038262; note last touched by 894a594.
• SIMPLE#442 ([spectre-11]) owns the full-orbit mu-scatter and production-scope validation.
• The VENUS-LEVIS/SPEC and discontinuous-Hamiltonian references in the issue body were not independently verified in this pass; treat them as the issue author's citations, not as confirmed by triage.

Scope and risk

Low risk and small. Items 2-4 are additive (a new test and note edits) and cannot regress the shipped map. Item 1 is the only one that can fail: if Level 1 cannot reach 1e-14, that is a genuine physics/implementation finding worth recording rather than a test to loosen. Nothing here reopens the design — the impulse map, its symmetrization, the namelist knob and the CA15 relocation all stay as merged.