Provide the pan coefficient formula as a preprocessing tool

[soaressgabriel]

Checklist

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Added tests for changed code.
• Updated documentation for changed code.

Description

• One implementation of the pan coefficient formula (supplement S29, kp = 0.482 + 0.024 ln(B) - 0.000376 U2 + 0.0045 UR) in rubem/hydrological_processes/_pan_coefficient.py, with the natural logarithm injected by the caller so the model (pcraster.ln) and the tool (numpy.log) evaluate the same terms in the same order. Evapotranspiration.get_pan_coef_et_open_water_area is kept and delegates to it; a test pins its previous numbers (for example B = 25, U2 = 2, UR = 70 gives 0.8735010197968368).
• rubem preprocess kp (rubem/preprocessing/pan_coefficient_series.py): two GeoTIFF series (wind speed at 2 m in m/s, relative humidity in %), paired in natural order, plus a fetch distance in metres as a scalar (--fetch, warned outside the 20 to 30 m of the supplement) or as a raster (--fetch-raster); one member per pair, named like the other series tools name theirs (kp000000.001 or kp00000001.tif), no-data propagated from every input, geometry checked against the first wind raster, atomic writes and manifest.csv written last. The model refuses a kp raster that is not positive, so the series is evaluated and checked before anything is written: a member with a non-positive or non-finite cell refuses the whole run naming every offending member; cells above the configured kp maximum (which the model only reports) are warned about, as are cells missing in an input. A member that would overwrite one of its own inputs is refused.
• Conformity test of the formula against S29 (float64 expectation from the printed coefficients, numpy and PCRaster paths), the series operation end to end (PCRaster and GeoTIFF output, no-data, fetch raster, manifest), the error paths (member count, geometry, non-positive coefficient, fetch distance, input overwrite) and the CLI through CliRunner.
• Docs: a "Class A Pan Coefficient (Kp) Series" section in preprocessing.rst (formula, units, options, naming, the kp > 0 rule) and a pointer from the kp input description in the user guide and in the file formats page. Changelog entry under Added.

Related Issue

• Resolve Provide the pan coefficient formula (S29) as a preprocessing tool #330;

Motivation and context

• The model never calls the S29 formula because kp is an input series by design, but the authors want it available for users who have the climate data (finding 16 of the scientific review). Keeping a single implementation avoids the model and the tool drifting apart.

How has this been tested

• python -m pytest -q -p no:cacheprovider --ignore=tests/integration/doc -n 4: 1035 passed, 1 skipped, on main at 176f204 (Linux, Python 3.13, PCRaster 4.4.2).
• uvx ruff@0.16.4 format --check . and uvx ruff@0.16.4 check .: clean.
• sphinx-build -W -b html doc/source: no warnings.

For the maintainer: the formula exceeds 1 for a relative humidity close to 100 % while the configured kp range is [0, 1] (reported, not blocking, by the model); the tool follows the model and warns. The "or a station table" input of the issue was not implemented: rubem preprocess krige already turns station tables into raster series that this command can read.

Screenshots

• N/A

[codecov]

Codecov Report

❌ Patch coverage is 97.79412% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.93%. Comparing base (93b56d7) to head (0381307).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
rubem/preprocessing/pan_coefficient_series.py	97.36%	1 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #340      +/-   ##
==========================================
+ Coverage   92.75%   92.93%   +0.18%     
==========================================
  Files          61       63       +2     
  Lines        4028     4163     +135     
  Branches      510      532      +22     
==========================================
+ Hits         3736     3869     +133     
  Misses        235      235              
- Partials       57       59       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.