[kim-fp-04] Match the periodic and hat electrostatic boundary-value problem

[krystophny]

Stage: KIM periodic electrostatic boundary-value problem
Source language: Fortran with symbolic/manufactured reference equations
Manuals to read first: #175; docs/plans/2026-07-10-kim-forced-periodicity-design.md, sections 2 decision R1, 3.4, 3.5, and 4.3; KIM/src/electrostatic_poisson/solve_poisson.f90, especially bc_type=3; KIM/src/electrostatic_poisson/fields_mod.f90
Depends on: #187

Goal

Make the periodic and hat solvers solve the same electrostatic equation for the same unknown. Their gauge and boundary condition must also agree. Derive the Fourier Poisson operator from the cylindrical CGS equation and implement the deviation psi = delta Phi - Phi_MA required by the branch design.

Reproduction and evidence

At d4ac12b0, periodic_solve_m solves directly for periodic delta Phi with D_m=-k_m^2. The hat solver's bc_type=3 instead applies the aligned-potential boundary. The design's resolved decision R1 says to solve for psi, but that path was deferred. The current 84.3% periodic/hat L2 difference therefore compares different boundary-value problems. Whether a physical helical -k_s^2 contribution belongs in D_m is also unresolved.

Files to edit

• KIM/src/electrostatic_poisson/periodic_solve.f90: assemble the derived operator, source, and gauge constraint.
• KIM/src/electrostatic_poisson/poisson_periodic.f90: project Phi_MA, solve for psi, and reconstruct delta Phi.
• KIM/tests/test_periodic_solve.f90: add analytic and manufactured boundary-value tests.

Behavior to implement

Starting from the same linearized CGS Poisson equation as the hat solver, derive the radial and helical metric terms for phase exp(+i(m theta+n phi)), the sign of 4 pi K, and the constant-B_r Fourier coefficient. Substitute delta Phi = Phi_MA + psi, form L psi = g-L Phi_MA, and state the periodic gauge/null-space rule. Map that continuous operator independently to the hat weak form and to D_m; do not choose -k_s^2 by fitting the benchmark.

Scaffold

call project_aligned_potential(Phi_MA, L, M, Phi_MA_m)
call assemble_periodic_operator(Kphi, geometry, L, M, A)
call apply_periodic_operator(A, Phi_MA_m, Lphi_ma)
b_psi = magnetic_drive_rhs(KB, Br_m) - Lphi_ma
call solve_with_derived_gauge(A, b_psi, psi_m, info)
Phi_m = psi_m + Phi_MA_m

Positive fixtures to add

• Uniform screened-Poisson case with an analytic Fourier solution for every mode, including mode zero.
• Manufactured complex psi(r) whose source is generated from the continuous equation and recovered after projection.
• A matched hat/periodic case in which Phi_MA is nonzero but psi is periodic and localized.

Negative fixtures to add

• A singular unregularized zero mode without a declared gauge: return a solver status rather than arbitrary output.
• A Phi_MA projection whose edge/Gibbs residual exceeds the declared tolerance: reject the benchmark configuration.

Makefile target

Extend test_periodic_solve; keep the matched cross-method test separate until #190.

Success criteria

cmake -S . -B build -G Ninja
cmake --build build --target test_periodic_solve.x
ctest --test-dir build -R test_periodic_solve --output-on-failure

The manufactured solution, matrix entries, RHS sign, gauge, and reconstruction must pass at roundoff-scaled tolerances for the chosen discretization.

Relation to existing work

PR #179 contains a separate Krook periodic system with a useful uniform Debye manufactured test. Its sign and operator conventions are not an FP authority. PR #180 supplies the constant-B_r driver pattern. Continue on feature/kim-forced-periodicity and retain the existing hat solver.

Non-goals

• Do not change the hat solver to make the profiles agree.
• Do not add electromagnetic unknowns in this PR.

Verification

cmake --build build -j$(nproc) && ctest --test-dir build --output-on-failure