[kim-fp-06] Establish a matched Fokker-Planck shielding benchmark

[krystophny]

Stage: KIM periodic physics benchmark
Source language: Fortran, Python comparison tooling, and golden-record data
Manuals to read first: #175 benchmark criteria; docs/plans/2026-07-10-kim-forced-periodicity-design.md, sections 5 and 7; test/golden/README.md; test/golden/kim/config.sh
Depends on: #37, #185, #186, #187, #188, #189

Goal

Establish one reproducible FP shielding benchmark in which periodic Fourier KIM, hat-basis KIM, and an independent Vaclavik limiting solution solve the same physical problem. Gate complex potential, misalignment field, charge response, and layer current with separated uncertainty estimates.

Files to edit

• KIM/tests/test_periodic_vs_global.f90: compare matched boundary-value problems and all required observables on common physical points.
• KIM/tests/test_data/benchmark_electrostatic_fp/: NEW frozen inputs, independent reference data, provenance, and comparison script.
• test/golden/kim/cases/electrostatic_periodic/: NEW CI golden case after physics acceptance.

Behavior to implement

Use the static CGS (m,n)=(-6,2), q=3, constant-B_r case unless the independent reference requires a simpler declared limit. Freeze phase exp(+i(m theta+n phi)), units, species, collision model, parallel flow, m_phi range, boundary condition, and normalization. Compare complex Phi-Phi_MA, E_perp, charge density, and layer current on an ion-FLR interval. Remove a constant offset only if #188 proves a gauge null space. Implement the Vaclavik reference from its published equations, not by translating either KIM implementation.

Scaffold

reference = load_reference_with_provenance()
for observable in ("psi", "E_perp", "rho", "j_layer"):
    hat = interpolate_to_common_points(load_hat(observable))
    periodic = interpolate_to_common_points(load_periodic(observable))
    compare_complex(hat, periodic, reference[observable], uncertainty[observable])

Positive fixtures to add

• Analytic or high-precision Vaclavik-limit data with an independently checked normalization.
• Matched hat and periodic outputs on the same ion-FLR points.
• Frozen numerical, periodization, harmonic-truncation, and reference uncertainties stored separately.

Negative fixtures to add

• Deliberate 4 pi, sign, phase, or electron-window mutation: the benchmark exits nonzero.
• Gauge removal requested without a derived null space: comparison rejects the request.

Makefile target

Add a CTest benchmark target with a bounded runtime, then add the accepted case to the golden dispatcher. Do not freeze the present 84% mismatch as a golden reference.

Success criteria

cmake -S . -B build -G Ninja
cmake --build build -j$(nproc)
ctest --test-dir build -R 'test_periodic_(vs_global|benchmark)' --output-on-failure
GR_CONFIG=kim test/golden/bin/gr_dispatch.sh

Pre-register the acceptance policy before rerunning: self-convergence below 1e-3 relative L2, periodization error below 1%, and matched hat/periodic observables within 5% or their tighter combined uncertainty. Conservation and quasineutrality residuals must pass independently.

Relation to existing work

PR #181's Krook campaign is a reusable harness and a negative result, not a physics reference. PR #183 fixes derived z0 interpolation on the hat path and should be included if applicable to the chosen comparison. PR #184's collision-model guard must remain until this FP benchmark is accepted.

Non-goals

• Do not spend more time tuning the rejected Krook benchmark.
• Do not claim validation from agreement of peak magnitudes alone.

Verification

ctest --test-dir build --output-on-failure && GR_CONFIG=kim test/golden/bin/gr_dispatch.sh