Add the rubem calibrate command

[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

Based on #342 (feat/341-python-api): the workers run the model through rubem.api.Model. This pull request carries the whole calibration command; it replaces #346 and #350, whose work is folded in here. The series is meant to be reviewed commit by commit:

1. Package SciPy as the optional calibration extra: rubem[calibration] (scipy>=1.16.2, the first release with CPython 3.14 wheels on Linux and Windows), in the dev extra and in the CI test installation; the dependency guard in rubem._deps; ci/dev-requirements.in committed (the lock header pointed at an uncommitted file) and ci/dev-requirements.lock recompiled keeping every pin (scipy==1.18.1, numpy==2.5.3 added; pip-audit --strict clean).
2. Objective, station metrics and series readers (rubem/calibration/objective.py): the NSE over the pairs valid in both series (NaN, negative values, -9999 and the PCRaster missing value are gaps), the objective 1000 (100 (1 - NSE))^2, StationMetrics per shared station (pairs, means, standard deviations, Pearson r, RMSE, NSE), evaluate_series (alignment on shared steps and ids, spin-up, a chosen selection of stations), read_series for the model's table layout and for PCRaster time series with their header; head-less files are refused.
3. Decision space (parameters.py): eight free parameters, w_3 derived, w_1 + w_2 <= 1; per-run bounds that only narrow the settings ranges; fixed parameters that leave the vector; the weight cases (one fixed, one collapsed to a value, both fixed).
4. Runner (_worker.py, runner.py): one spawned, silenced worker per evaluation running Model.run() in-process on a derived format 1.0 document; atomic JSON records; differential_evolution (best1exp, sobol, x0, no polishing, deferred) over executor.map; the pre-flight of the observed series; observed.csv, evaluations.csv, stations.csv, best_<variable>.csv, result.json and the calibrated configuration; progress through rubem.progress; interrupt and out-of-memory handling.
5. Command (rubem calibrate): options for the variable, spin-up, generations, population, seed, workers, temporary directory, --bound, --fix, --stations, --init, --strategy, --polish/--no-polish; the progress and the closing summary; exit codes as rubem run.
6. Dataset marker and smoke test: dataset marker, RUBEM_DATASET_DIR with a skip reason, and the Ipojuca smoke (six steps, a drainage network generated once, best objective exactly 0.0; without the fixed network it is 4.4e-7).
7. Documentation: the calibration page, the command in the user guide, the entry point in the API page.
8. Changelog: one entry under Added.

Related Issue

• Resolve Add the rubem calibrate command (differential evolution on the station streamflow) #343;

Motivation and context

• The corrected soil moisture coefficient (Fix units soil moisture equation for ch #321) invalidated the published parameter sets of the three basins (Pin dataset provenance and normalization for integration testing #217), and the model had no reproducible calibration: each parameter was edited by hand. The command implements the method the model was designed around, from the SciPy API and the Nash-Sutcliffe definition, with the process isolation PCRaster requires, per-run control of the search box, a chosen set of stations, per-station goodness-of-fit and visible progress.

Pending, tracked in #343: the rejection of candidates whose weights violate C_wp <= 1 needs the check merged by #336, which this branch does not contain until it is rebased onto main. Design notes left in the code: a repeated time step of an observed table is aligned on its first row; a BrokenProcessPool in the final re-run of the best candidate is reported without the --workers advice (that pool runs one task); the per-generation progress re-reads the records (negligible beside the model runs).

How has this been tested

• The tree of this branch is the one verified on the former stack (Bring rubem calibrate to parity with the previous calibration workflow #350), byte for byte, except the changelog, whose three entries became one: git diff --stat against that head lists doc/source/changelog.rst only.
• python -m pytest -q -p no:cacheprovider --ignore=tests/integration/doc -n 2: 1445 passed, 2 skipped (Linux, Python 3.13, PCRaster 4.4.2, SciPy 1.18.1). Every numeric expectation was re-derived by hand a second time; mutation checks (record written before the run, constraint dropped, w_3 ignoring w_2, mask accepting negatives, record without station metrics, constraint kept with a fixed weight) are caught.
• End to end through the command line on the synthetic dataset, with the default options (best objective 0, 70 evaluations in one generation) and with --fix x=0 --bound alpha=1:10 --stations 1 --init latinhypercube (7 free parameters, artifacts consistent: stations.csv recomputed from best_arn.csv bit for bit); no lingering process.
• RUBEM_DATASET_DIR=<local datasets> python -m pytest tests/dataset: 1 passed in about 13 s.
• uvx ruff@0.16.4 format --check . and uvx ruff@0.16.4 check .: clean. sphinx-build -W -b html doc/source with the documentation's Python 3.13 environment: no warnings. uvx pip-audit --strict -r ci/dev-requirements.lock: no known vulnerabilities.

Screenshots

• N/A

[codecov]

Codecov Report

❌ Patch coverage is 95.76366% with 38 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.36%. Comparing base (dc80787) to head (99023b4).

Files with missing lines	Patch %	Lines
rubem/calibration/runner.py	95.40%	12 Missing and 5 partials ⚠️
rubem/calibration/_worker.py	90.90%	7 Missing and 2 partials ⚠️
rubem/calibration/objective.py	95.58%	4 Missing and 4 partials ⚠️
rubem/calibration/parameters.py	98.50%	1 Missing and 1 partial ⚠️
rubem/cli.py	97.87%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #344      +/-   ##
==========================================
+ Coverage   92.87%   93.36%   +0.48%     
==========================================
  Files          64       68       +4     
  Lines        4365     5260     +895     
  Branches      558      675     +117     
==========================================
+ Hits         4054     4911     +857     
- Misses        248      274      +26     
- Partials       63       75      +12     

☔ 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.