KIM: revive Fourier-space solver via enforced radial periodicity (localized solutions)

[krystophny]

Goal

Deliver one verified electrostatic Fokker-Planck periodic-Fourier solver for KIM. Markus continues from feature/kim-forced-periodicity at d4ac12b0; the independent PR stack #177-#184 remains comparison and reuse material. The accepted implementation must preserve CGS units, the Fourier phase exp(+i(m theta+n phi)), species composition, collision-model dispatch, and the existing hat solver.

Current evidence

The branch builds and its focused tests exit zero, but it is not ready to merge:

• test_periodic_vs_global reports raw relative L2 0.8434, periodic/global peak ratio 0.2321, and DC-removed relative L2 1.3449 for the static (m,n)=(-6,2), q=3, constant-B_r, m_phi=0 case. The test only warns.
• N_rg and M refinement converge to 7.63e-4 and 1.02e-12, respectively. The window-deformation sequence is non-monotone and ends at relative L2 0.7836, but the test still exits zero.
• The production window uses plasma%spec(0)%rho_L. At r_m=36.8 cm, the same case has rho_Le=0.0038313 cm and rho_Li=0.23217 cm, a factor 60.6. The current window and comparison interval therefore resolve electron rather than ion FLR scales.
• Multi-ion reconstruction assigns n_s=n_e Z_s/sum Z, which does not satisfy sum Z_s n_s=n_e in general, and copies one ion-temperature profile to every ion.
• The off-diagonal FP kernel defaults to dropping k_s^2; its tests mostly share or duplicate the implementation algebra. Production uses only m_phi=0 without a measured tail.
• The periodic solve reconstructs full delta Phi with periodic edges, while hat bc_type=3 uses the aligned-potential boundary. Design decision R1 to solve psi=delta Phi-Phi_MA is not implemented. The physical status of a helical -k_s^2 Poisson term is unresolved.
• zgesv reports singularity only. There is no condition estimate or scaled backward residual.
• No accepted Vaclavik comparison, periodic golden record, E_perp comparison, or layer-current comparison exists.

Branch and PR relation

Work	Role after this audit
feature/kim-forced-periodicity	Primary FP implementation. Continue here through children #185-#190.
37-add-parallel-flow-to-x2-in-kim-fp, 152bf013	Historical implementation of #37. Rebase or reimplement for current x2(:,m_phi).
#177	Historical continuous Krook kernels. Use for Fourier/Debye convention comparisons, not as the FP source.
#178	Independent C-infinity periodizer. Compare seam and derivative behavior with Markus's periodizer.
#179	Independent Krook Fourier assembly and dense solve. Reuse only generic verified infrastructure.
#180	Run-type/config seam and per-species background feed. Strongest reuse candidate after convention review.
#181	Packaged comparison harness plus the negative result that Krook is not a converged reference.
#182	Collision-frequency sensitivity control. It is not an FP validation mechanism.
#183	Valid hat-path repair: recompute derived Krook z0 after primitive interpolation. Keep independent of FP acceptance.
#184	Prevents a Krook periodic kernel from being labeled FP. Retain until the verified FP dispatch replaces that unsupported path.

PRs #177-#184 must not be merged mechanically into Markus's branch. #191 decides which pieces are retained, superseded, or remain independent after the physics gates pass.

Atomic split

• [kim-fp-01] Size the periodic window from active-species Larmor radii #185 [kim-fp-01] Size the periodic window from active-species Larmor radii.
• [kim-fp-02] Preserve multispecies profiles in periodic backgrounds #186 [kim-fp-02] Preserve multispecies profiles in periodic backgrounds.
• [kim-fp-03] Verify the off-diagonal Fokker-Planck Fourier kernel #187 [kim-fp-03] Verify the off-diagonal Fokker-Planck Fourier kernel.
• [kim-fp-04] Match the periodic and hat electrostatic boundary-value problem #188 [kim-fp-04] Match the periodic and hat electrostatic boundary-value problem.
• [kim-fp-05] Make periodic convergence and solve checks hard gates #189 [kim-fp-05] Make periodic convergence and solve checks hard gates.
• [kim-fp-06] Establish a matched Fokker-Planck shielding benchmark #190 [kim-fp-06] Establish a matched Fokker-Planck shielding benchmark.
• [kim-fp-07] Integrate the verified Fokker-Planck periodic solver #191 [kim-fp-07] Integrate the verified Fokker-Planck periodic solver.
• Add parallel flow to x2 in KIM-FP #37 Add parallel flow to the current FP x2 representation.

Verification sequence

1. Fix physical scale and multispecies state ([kim-fp-01] Size the periodic window from active-species Larmor radii #185, [kim-fp-02] Preserve multispecies profiles in periodic backgrounds #186).
2. Establish the independent kernel and Poisson equations ([kim-fp-03] Verify the off-diagonal Fokker-Planck Fourier kernel #187, [kim-fp-04] Match the periodic and hat electrostatic boundary-value problem #188). Do not tune factors against the 84% discrepancy.
3. Add numerical trust diagnostics and hard gates ([kim-fp-05] Make periodic convergence and solve checks hard gates #189).
4. Run the matched hat/periodic/Vaclavik benchmark ([kim-fp-06] Establish a matched Fokker-Planck shielding benchmark #190).
5. Reconcile duplicate branches and open the final integration PR ([kim-fp-07] Integrate the verified Fokker-Planck periodic solver #191).

The benchmark pre-registers its gates: roundoff-scaled oracle agreement; backward residual below 1e-10; self-convergence below 1e-3 relative L2; periodization error below 1%; and matched observables within 5% or their tighter combined uncertainty. A failed gate exits nonzero.

Acceptance

This tracker is closed now that every child has been filed as an independently reviewable implementation issue. The children remain open and assigned to Markus. Reopen this tracker only to change the split; use #191 for final integration status.

[krystophny]

Update from the author (2026-07-06): the periodization code already exists (written together with the notes) and will be shared shortly. The work items above then reduce to integrating it with the recovered kernels and the k-grid assembly; effort estimate drops accordingly.

[krystophny]

Progress: the first three split items are on a stacked branch family, each with behavioral ctest coverage and green CI:

• Restore Fourier-space KIM kernels with behavioral tests #177 restores the continuous-Fourier kernels as kernels_m against the current species_m background (Debye screening, gyroaverage, swap/phase properties, force linearity). The historical kernel_debye_case short-circuit is deliberately not restored verbatim: it flipped the sign of the adiabatic limit and dropped the Fourier phase; the restored switch only zeroes the thermodynamic-force terms, matching the artificial_debye_case semantics.
• Add radial background periodization #178 adds the C-infinity radial periodization (periodize_m): untouched resonant layer, exact L = 2 (dr + dr_tr) periodicity, smooth seams. Gradients must be computed from the periodized profile; periodizing a gradient is wrong in the transition zone.
• Add periodic Fourier kernel assembly and solve #179 adds fourier_periodic_m: modes k_m = 2 pi m / L, one-period midpoint assembly of K_{m,m}, dense screened-Poisson solve (k_m^2 - 4 pi K) Phi = rhs, inverse expansion. On a uniform background the assembly is exactly diagonal with the adiabatic value -1/(4 pi lambda_D^2) summed over species, so the zero mode is regularized by the kinetic term and no gauge handling is needed.

Remaining, for the driver-integration item: add a run type behind the kim_solver_t/kim_mod_m factory seam selected from the config namelist; feed the periodized profiles into the species pipeline before calc_plasma_parameter_derivs (gradient-ordering constraint above); take r_m from the resonance preparation and dr, dr_tr as new config keys; build the RHS from the K^{rho B} assembly with the configured type_br_field perturbation; then the no-op benchmark against the hat basis on one localized standard case, and the Vaclavik cross-benchmark.