Add circular Kasilov offset-rotation showcase

[krystophny]

Summary

• Replace the frozen-D algebraic check with a self-consistent circular Kasilov offset-rotation test.
• Distinguish the prescribed electric precession Omega_tE, orbit-dependent magnetic precession, and fluid contravariant toroidal rotation Vphi.
• Use the requested circular closure k = 1.17 and (Bphcov/(B0 R0))^2 geometry factor.
• Recompute D11 and D12 at every bisection point while solving Vphi - Vphi_in = 0; magnetic drift remains enabled.
• Test restoring torque below the offset, vanishing torque at the offset, and restoring torque above it on four flux surfaces in a four-thread OpenMP loop.
• Add an independent Cartesian E cross B oracle for the Omega_tE / radial-electric-field / A1 sign contract.
• Add derivation and units documentation plus a reproducible plotting script. The test generates all numerical data on demand.

No production solver code, output file, HDF5 schema, library type, or downstream consumer changes. Generated CSV, PNG, and PDF files are not committed.

Closes #98.

Showcase

Temporary direct PNG: https://box.sloppy.at/10140.png

At s = 0.075, the test finds Vphi_in ≈ -1.172e5 s^-1. The native torque changes from +5.24e4 below the offset to approximately zero at it and -6.04e4 above it.

Verification

• fo: static analysis, build, all tests, and lint pass.
• fo test test_circular_offset_rotation: passes with four OpenMP threads and four flux surfaces.
• fo test test_parallel_transport: passes.
• fo fmt --check test/test_circular_offset_rotation.f90 test/test_parallel_transport.f90: passes.
• Generated plot inspected in color and grayscale; labels, units, markers, and line styles remain legible.

The full run retains the repository's existing parser-recovery diagnostics from POTATO/generated build sources; no new warnings originate in this patch.

[krystophny]

Review verdict: Approve

Summary: PR #170 adds a self-consistent circular Kasilov offset-rotation regression test (test/test_circular_offset_rotation.f90), registers it in CTest, documents the conversion in doc/offset_rotation.md, and ships a plotting showcase (examples/circular_offset_rotation/). The net diff is purely additive (test + docs + example; the four commits' earlier production-code churn was fully reverted, so no solver/output/HDF5 changes are shipped). I verified the test's logic end-to-end: M_t (threadprivate) is set before neort_compute_no_splines and survives init_profiles (which only recomputes Om_tE = vth*M_t/R0); Dco/Dctr/Dt, Tco/Tctr/Tt, B0, R0, psi_pr, Bphcov, q, sign_theta all exist with matching semantics; algebraically the torque satisfies T = −C·(Vφ − Vφ_in) with C > 0 identically (for any handedness), so the restoring-sign assertions are convention-robust; the E×B oracle is internally consistent with the code's A1 sign convention; the CSV/plot contract works with the pinned numpy>=2.2 (delta_omega_s-1 sanitizes to delta_omega_s1); and GitHub Actions shows both build (Fast) and build (Debug) green, including Run ctest. The M_t scan (±2e3 s⁻¹ ≈ ±0.0038 in Mach) and the bisection tolerance (1 s⁻¹ vs ~0.5 s⁻¹ worst-case truncation error) are tight but empirically pass in both CI configs.

Findings:

1. [minor] doc/offset_rotation.md:91, examples/circular_offset_rotation/README.md:11 — the "Reproduce the showcase" instructions use fo test test_circular_offset_rotation, but fo is not a repository command (no Makefile target, script, or alias anywhere in the repo). A reader following the docs gets "command not found". Fix: use the real invocation, e.g. ctest --test-dir build -R test_circular_offset_rotation (or make ctest), in both files.
2. [minor] test/test_circular_offset_rotation.f90:235 — the Kasilov closure constant - 2.5_dp (the 5/2 in k_NA = D12/D11 − 5/2 + …) is the physics quantity this test exists to pin, but it is a bare magic number, contrary to the repository's mandatory named-constants rule. Fix: real(dp), parameter :: KASILOV_FIVE_HALVES = 2.5_dp (and likewise the implicit 1.5 in the Vφ decomposition, if kept explicit).
3. [minor] test/test_circular_offset_rotation.f90:108-135 — the PR body claims the E×B oracle validates "the Omega_tE / radial-electric-field / A1 sign contract", but the oracle only checks two algebraic identities with arbitrary constants (ω = −cΦ′/Bθ and qΦ′/T = −qBθω/(cT)); it never compares against the code's actual A1/Om_tE values, so the documented sign contract is not machine-verified against the solver. I confirmed by hand that the doc's convention is algebraically consistent with init_thermodynamic_forces (A1_elec = −qi/(Ti·ev)·(χ′/c)·Om_tE ⇔ Om_tE = −cΦ′/χ′), so this is scope-of-claim rather than a correctness bug. Consider strengthening the oracle by evaluating A1 at a manufactured Phi/M_t and comparing, or soften the claim in the PR description.
4. [minor] .gitignore — only examples/circular_offset_rotation/*.csv is ignored; running the documented plot script also creates .png/.pdf in the example directory, which would dirty git status despite the README's "Generated CSV, PNG, and PDF files are not committed" statement. Add the *.png/*.pdf patterns.

Verdict: Approve — the change is well-scoped (test/docs/example only), the regression test is a genuine, CI-verified check of solver self-consistency (torque sign vs. the recomputed-D offset rotation on four surfaces), and the only issues found are minor documentation/quality nits that do not affect the shipped solver or the test's validity.