Skip to content

[math-02] Derive kinetic response and Fokker-Planck susceptibilities#214

Draft
marjohma wants to merge 1 commit into
fix/kim-fp-193-conventionsfrom
fix/kim-fp-194-susceptibility-oracle
Draft

[math-02] Derive kinetic response and Fokker-Planck susceptibilities#214
marjohma wants to merge 1 commit into
fix/kim-fp-193-conventionsfrom
fix/kim-fp-194-susceptibility-oracle

Conversation

@marjohma

Copy link
Copy Markdown
Member

Summary

  • derive the FP susceptibility identities and limiting cases independently
  • commit deterministic arbitrary-precision oracle values
  • add a Fortran oracle consumer covering values, symmetries, and mutation sensitivity

Why

KIM susceptibility functions are checked against an independent symbolic reference rather than implementation self-comparison.

Validation

Validated cumulatively at the stack head:

  • cmake --build build -j2
  • ctest --test-dir build -E 'test_rhs_balance|test_periodic_convergence|test_periodic_vs_global' --output-on-failure — 35/35 passed

Known red gates are intentionally excluded from that command: the pre-existing test_rhs_balance baseline failure, the periodization-deformation acceptance gate, and the unresolved periodic-vs-global 5% agreement gate.

Stack

Base: fix/kim-fp-193-conventions
Head: fix/kim-fp-194-susceptibility-oracle

Closes #194

@marjohma

Copy link
Copy Markdown
Member Author

Review (standards + spec vs #194) — keeping this in draft. The core deliverable is genuinely good: the WL script defines I^kl from an independent generating integral (OU propagator, 02_kinetic_and_susceptibilities.wl:14-22) rather than the Fortran recurrences — the anti-circularity non-goal is satisfied — and test_fp_susceptibility_oracle.f90 exercises production getIfunc/W2_arr against the committed oracle at a real, failable 1e-12 scaled tolerance (all 8 (k,l) pairs, m_phi=−1/0/+1, 56 rows enforced, provenance header present, runs in CI). That part can stand as-is.

What keeps it in draft is that several spec-required proofs are missing or are check-theater, and the index overstates them:

  1. No derivation of the linearization / action-angle response denominator / dimensionless variables — the integral is asserted via comment, while FORMULA_INDEX.md:592-596 claims the script "traces x1/x2 through (4.1), (4.26)…(A.1)–(A.29)". It doesn't. Please make the claim match the artifact (either derive, or state "asserted from thesis eq. X").
  2. Collision-moment checks are tautologies: ouEigenvalues is a hardcoded association checked against its own literals two lines below (.wl:118-127) — nothing integrates the operator, so "particle/momentum/energy moments required by each collision model" is not verified, and the FP-vs-Krook separation check is vacuous.
  3. "Prove recurrence relations and derivatives": two numeric recurrence checks at a single probe point (.wl:131-146), applied to the energy-corrected functions; no symbolic proof and no derivative checks at all.
  4. Low/high-collisionality and zero/large-x1/x2 limits are fixture points only — never compared against analytic limits (the collisionless closed form in getIfunc.f90:24-35 would be a free cross-check).
  5. Negative fixtures: spec requires each mutation to fail "at least one symbolic and one oracle check". All four mutations Exit via FinishChecks[] before the oracle-comparison block is reached — the oracle side never participates; the Fortran side has no negative fixtures.
  6. KiLCA unverified (calc_Imn_array, calc_I_array_drift_serg) although the goal is "every susceptibility function used by KIM and KiLCA" — the disclosure in FORMULA_INDEX.md:573-575 is honest, but the issue isn't satisfied by disclosure.

Minor:

  • The oracle test recomputes the x1/x2 mapping inline (test:52) rather than exercising the production mapping (calculate_thermodynamic_forces_and_susc) — the mapping is verified by duplication; production mapping coverage currently rests on the Add parallel flow to x2 in KIM-FP #37/Add parallel flow to x2 in KIM-FP #213 flow test. (Note: an earlier draft of this review claimed the kpar·Vpar term was absent from production x2 — that is incorrect; it is present via the conditional Doppler correction in species_mod.f90:410-417.)
  • Cell-center path also consumes I10/I12 (species_mod.f90:433-434), covered only via untested symmetrization.
  • Line width >100 in checklib.wl:4, 02_kinetic_and_susceptibilities.wl:77, and three Makefile recipe lines (AGENTS.md: 100 max).
  • Commit type verify: still outside AGENTS.md's documented set — consider documenting it, it's now stack convention.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant