Diagnose local Lorentz projector compatibility

[krystophny]

Summary

Add an opt-in, observation-only diagnostic for testing whether the existing global Lorentz solvability projector can be moved to individual local propagators.

For a local boundary map (A_k), incoming and outgoing constant-distribution band vectors (w_\mathrm{in}) and (w_\mathrm{out}), and the particle invariant (e^T), endpoint projectors can commute with propagation only if

[
e_\mathrm{out}^T A_k=e_\mathrm{in}^T,
\qquad
A_k w_\mathrm{in}=w_\mathrm{out},
\qquad
P_\mathrm{out}A_k=A_kP_\mathrm{in}.
]

The diagnostic records these residuals, the local source compatibility defect, and the flux contraction with the constant-distribution direction. It runs only when NEO2_LOCAL_PROJECTION_TRACE_FILE is set and otherwise returns before allocation. This PR is stacked on #161. It does not apply a projector or change a numerical result.

Why the constant-distribution vector is fixed

DOC/ripple_solver_normalizations_and_output.tex identifies each stored pitch unknown as

[
Y_k=\int_{\eta_{k-1}}^{\eta_k} f,d\eta.
]

Consequently, a pitch-independent distribution is represented by the band widths, including the truncated final band at (\eta=1/B). This is the discrete target supplied by the continuous Lorentz gauge; it is not a fitted numerical null vector.

The continuous Fredholm calculation has since established the following constraints on the interpretation of this diagnostic:

• constant (f) is the right gauge of the monoenergetic Lorentz equation;
• collisional pitch flux vanishes at (\eta=0) and (\eta=1/B);
• moving mirror-boundary terms cancel between the two signs of parallel velocity;
• periodic streaming integrates to zero;
• the parallel-electric drive is sign-odd and compatible;
• the axisymmetric radial drive reduces, after pitch integration, to a periodic Boozer total derivative and is globally compatible;
• the finite global join_ends source correction is therefore a numerical compatibility repair that should converge to zero, not an additional physical Pfirsch-Schlueter source.

Result

The 480-step Lorentz reconstruction contains 199 local propagators. The measured maxima are:

• left-invariant transport: (5.88\times10^{-15});
• constant-distribution transport: (1.8403\times10^{-3});
• projector intertwining: (1.8404\times10^{-3}).

The latter two residuals exceed (10^{-12}) in 139 of 199 propagators. A stage-0 spatial scan at fixed eta_part=30 gives (3.58\times10^{-3}), (1.84\times10^{-3}), and (6.69\times10^{-4}) at 240, 480, and 960 spatial steps. The 240-step run contains solver recoveries, the 960-step value is diagnostic only, and a 60-pitch attempt failed bounds checks before producing physics evidence. The trend suggests a converging spatial consistency error but does not establish its order.

The call site is decisive: the trace is written immediately after each single-ripple solve, before adaptive pitch transfer, join_ripples, its Lorentz column normalization, and join_ends. The pinned final-end transfer matrices are exactly identity. The defect therefore enters in one of three places:

1. the single-ripple sparse discretization, including moving mirror matching;
2. the sparse solve of the basis columns;
3. extraction of those columns into the four boundary-map blocks.

The signed local source-defect sums for forces 1 and 3 reproduce the global pre-projection defects to reported precision; force 2 is cancellation dominated. Global compatibility alone does not determine a unique local affine-source correction, and a rank-one map repair is also non-unique. No operator change follows from this PR.

Next diagnostic

Evaluate the assembled single-ripple sparse equations on the exact constant-(f) state at every internal spatial point, before factorization. Then compare:

1. the sparse-equation residual;
2. the solved basis-column combination for constant boundary data;
3. the extracted boundary map applied to the same band vector;
4. the same residual before and after later pitch transfer and column normalization as controls.

If the first residual is nonzero, the fault is in the discretization or mirror matching. If it is zero but the second is not, the sparse solve is responsible. If the second closes and the third does not, map extraction is responsible. Only this evidence, followed by a failure-free multidimensional convergence campaign, can justify a numerical correction.

Preserved invariants

The change is diagnostic only. It leaves unchanged:

• the Lorentz collision operator, particle conservation, and physical sources;
• the discretization, sparse-solver criteria, and reconstruction order;
• Fourier convention, CGS units, and periodic/mirror boundary conditions;
• ABI, serialized propagator layout, and generated physics data.

With tracing enabled and disabled, all 596 matching local propagator files and all 199 reconstruction propagators were byte-identical. The local-response and reconstruction summaries were identical. All local HDF5 response files and the final transport/current files were equal under h5diff; configuration differences were limited to run metadata.

Verification

Failing before:

Test project .../build
No tests were found!!!
Errors while running CTest

Passing after:

lorentz_projection_diagnostic_test PASS 0.07s
Summary: 1 passed, 0 failed, 0 skipped
join_failure_diagnostic_test PASS 0.07s
Summary: 1 passed, 0 failed, 0 skipped
Static: OK
Build: OK
Tests: OK
Lint: OK
Fmt: WARN (legacy propagator.f90)
All stages passed

The build and tests used bounds checks, backtraces, debug optimization, and floating-point traps for invalid, division-by-zero, and overflow operations.