docs(palmer): add equation-to-code provenance record (REFIMPL-26)

MO
9h ago
+185-2

Refs #1628

What

Adds docs/algorithm_refs/palmer-provenance.md: one row per Palmer computation step, tracing it to the published equation or reference-code statement and to the Python and Rust functions that realize it. Linked from palmer.md and the explanation toctree. A second commit corrects one word in a docstring (Wells, Goddard and Hayes, not Wilhite). No algorithm change.

Evidence standard

Each row is marked V (formula read in an opened source), R (reference code only), V+R, or S (secondary source). Sources opened: Palmer (1965), Alley (1984), Karl (1986) and Wells et al. (2004) from the supplied copies, Heim (2002) as a secondary source for PMDI, the Sibada/scPDSI 0.1.3 C++ and R wrapper (read only, nothing copied; GPL-3), and NCEI's divisional-readme.txt. Not opened, and listed under "Unresolved rows" for REFIMPL-06 (#1608): Heddinghaus and Sabol (1991), Karl and Knight (1985), Jacobi et al. (2013), NCEI pdi.f, and the original Wells C++.

Differences found (recorded, not changed)

D1 PL denominator is max(awc, 1) where Palmer Eq. 4, Alley and the Wells C++ use AWC; D2 PMDI tie and tolerance handling differs from getWPLM, and no opened paper gives a tie rule; D3 spell establishment at ±1.0 (Palmer, Alley) vs ±0.5 (Wells 2004), both published; D4 the citation typo fixed here; D5 0.15 vs 0.5·m, not described in Wells 2004; D6 the Wells C++ pairs the dry slope with the wet intercept, which Wells Eq. (19) does not; D7 Wells 2004 describes one percentile rescale and the port applies three (REFIMPL-33); D8 Karl (1986) prints the K′ equation with the 2.8 outside the logarithm, unlike Palmer and Wells.

Checks

  • sphinx-build -W html and doctest builds pass
  • tests/test_review_scripts.py and tests/test_self_calibration.py pass
  • llms.txt and llms-full.txt regenerated

Summary by Sourcery

Document the provenance and known source discrepancies of the Palmer implementations without changing the algorithm.

Enhancements:

  • Add a comprehensive Palmer provenance record linking computation steps to published sources, reference-code evidence, and their Python and Rust implementations, including documented deviations and unresolved source gaps.

Documentation:

  • Link the new Palmer provenance reference from the Palmer algorithm documentation and explanation toctree.

Chores:

  • Correct the Wells et al. (2004) author attribution from Wilhite to Hayes in self-calibration documentation and test descriptions.

Summary by CodeRabbit

  • Documentation
    • Added a detailed reference tracing Palmer index computations to published equations and reference implementations, including documented differences and remaining verification gaps.
    • Linked the new reference from the Palmer documentation and related documentation indexes.
  • Other
    • Corrected the attribution for the self-calibration procedure.