[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