[kim-fp-07] Integrate the verified Fokker-Planck periodic solver

[krystophny]

Stage: KIM forced-periodicity integration
Source language: Fortran, CMake, and documentation
Manuals to read first: #175 and children #185-#190; PRs #177-#184; docs/plans/2026-07-10-kim-forced-periodicity-design.md; KIM/README.md
Depends on: #37, #185, #186, #187, #188, #189, #190

Goal

Rebase the verified feature/kim-forced-periodicity implementation onto current main, select reusable parts of PRs #177-#184 without mixing Krook and FP semantics, and open one reviewable FP integration PR with CI and user documentation.

Files to edit

• KIM/src/CMakeLists.txt: register the final modules and tests once, without duplicate periodic implementations.
• KIM/README.md: document the run type and supported physics. Add separate configuration, generated-field, limitation, and benchmark sections.
• .github/workflows/: extend the existing KIM checks only where the accepted benchmark requires it.

Behavior to implement

Keep a single public periodic run type. Preserve the hat solver. Use explicit collision-model dispatch: Krook must call Krook kernels and FP must call the independently verified FP kernels. Resolve duplicate periodizers, drivers, Fourier grids, and solve modules by documented selection, not by retaining both hidden implementations. Preserve CGS units, Fourier phase, species composition, host-return status behavior, and existing golden records.

Branch and PR map

• feature/kim-forced-periodicity at d4ac12b0: FP implementation and the branch to continue.
• Restore Fourier-space KIM kernels with behavioral tests #177: historical continuous Krook kernels and behavioral tests; convention reference only.
• Add radial background periodization #178: independent C-infinity periodizer; compare seam and gradient behavior.
• Add periodic Fourier kernel assembly and solve #179: independent Krook Fourier assembly/solve; retain only generic tested infrastructure.
• Add periodic-Fourier run mode behind config switch #180: run-type/config seam and per-species background feed; strongest reuse candidate after convention review.
• Add electrostatic no-op benchmark case with unconverged-reference finding #181: packaged comparison harness and rejected Krook benchmark.
• Add KIM collision-frequency scale #182: optional collision-frequency sensitivity parameter, not an FP acceptance mechanism.
• Recompute Krook argument after interpolation #183: recompute derived Krook z0 after primitive interpolation; keep as an independent hat-path correctness fix.
• Reject unsupported periodic collision models #184: semantic guard preventing a Krook kernel from being labeled FP; adapt or supersede only when [kim-fp-03] Verify the off-diagonal Fokker-Planck Fourier kernel #187 and [kim-fp-06] Establish a matched Fokker-Planck shielding benchmark #190 pass.
• 37-add-parallel-flow-to-x2-in-kim-fp at 152bf013: old unmerged implementation of Add parallel flow to x2 in KIM-FP #37; reimplement or rebase rather than blindly cherry-pick.

Scaffold

select case (trim(collision_model))
case ('Krook')
    call assemble_periodic_krook(...)
case ('FokkerPlanck')
    call assemble_periodic_fp_verified(...)
case default
    return_status = KIM_UNSUPPORTED_COLLISION_MODEL
end select

Positive fixtures to add

• Existing hat and electromagnetic golden cases remain unchanged.
• Accepted FP periodic benchmark from [kim-fp-06] Establish a matched Fokker-Planck shielding benchmark #190 runs in CI and records all model switches.
• Krook and FP dispatch tests prove each label reaches the intended kernel.

Negative fixtures to add

• FP label routed to Krook kernel, duplicate run-type registration, or unsupported model: fail before solve.

Makefile target

Use the repository's full fo check plus CMake/CTest and the KIM golden dispatcher.

Success criteria

fo
cmake -S . -B build -G Ninja
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure
GR_CONFIG=kim test/golden/bin/gr_dispatch.sh

Open a non-draft PR to main. Its body must state which PRs #177-#184 are superseded, retained, or still independent, and include real failing-before and passing-after verification output.

Non-goals

• Do not merge the current FP branch because its internal tests happen to exit zero.
• Do not add toroidal, electromagnetic, or full current-kernel extensions in this integration PR.

Verification

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