Bring rubem calibrate to parity with the previous calibration workflow

[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

Stacked on #346 (base feat/345-calibration-docs).

• Decision space (rubem/calibration/parameters.py): DecisionSpace built by decision_space(fixed, bounds); a fixed parameter leaves the decision vector and is re-inserted in the nine emitted parameters; a per-run bound may only narrow the range of appsettings.json (refused otherwise, naming both ranges); fixing one of w_1/w_2 narrows the other so the derived w_3 stays in range and drops the linear constraint, fixing both checks w_3; a narrowing that collapses a weight to a point moves it into the fixed set, so the announced dimension and budget describe the real search. The population size, x0, the constraint positions and the explicit init width follow the space; result.json records the effective bounds, the fixed values and the stations.
• Command line: --bound NAME=MIN:MAX and --fix NAME=VALUE (repeatable, malformed forms refused with the expected spelling), --stations ID[,ID...], --init (sobol, latinhypercube, halton, random), --strategy, --polish/--no-polish; the closing summary lists every artifact.
• Observations (objective.py): negative values are gaps (every model output is a non-negative flux or storage); a ; table without the 0;<id>;... header and a PCRaster time series without its header are refused naming the two accepted layouts (no head-less numbering); a byte order mark is ignored. StationMetrics (pairs, mean and standard deviation of both series, Pearson r, RMSE, NSE) per shared station; evaluate_series(..., stations=...) averages the NSE over the selected stations and still measures the others.
• Artifacts (runner.py, _worker.py): observed.csv (per station: selection, pairs in the compared window, dropped values, mean, std, min, max) and the coverage of the compared window logged before the search; every evaluation record carries started_at (UTC) and station_metrics; after the search the best candidate is run once more in the pool to write best_<variable>.csv (step, observed and simulated per shared station) and stations.csv (the per-station metrics of the winner); evaluations.csv gains started_at; an interrupted or failed search still consolidates evaluations.csv; a worker killed by the system is reported with the advice to lower --workers.
• Progress: the budget line, one line per generation (best objective, best NSE, evaluations recorded) and the final summary go through the rubem.progress logger the command line routes to standard output, as rubem run does.
• Documentation: the calibration page covers every option, artifact and definition (exact weights derivation, months as steps, one cell per point station, the reported best is an evaluated candidate, budget with N free parameters, memory per worker, where the winner's per-station efficiency is); the user guide's help block is regenerated from the command.
• Changelog entry under Added.

Related Issue

• Resolve Bring rubem calibrate to parity with the previous calibration workflow #348;

Motivation and context

• Calibrating a basin needs per-run control of the search box, the possibility of pinning a parameter from an independent source, a chosen set of stations with the others kept for validation, negative gap markers treated as gaps, per-station goodness-of-fit and the winner's series for inspection, and visible progress. The command offered none of these; the comparison with the calibration procedure the model was calibrated with before listed them (issue Bring rubem calibrate to parity with the previous calibration workflow #348).

Left as design notes in the code: 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

• 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 (mask table, StationMetrics on a concrete pair, bounds narrowing, constraint positions after removing a dimension, round trips); mutation checks (record without station_metrics, constraint kept with a fixed weight, mask accepting negatives) are caught.
• End to end through the command line on the synthetic dataset, default options (best objective 0) and with --fix x=0 --bound alpha=1:10 --stations 1 --init latinhypercube (7 free parameters, 35 members, artifacts consistent: stations.csv recomputed from best_arn.csv bit for bit).
• RUBEM_DATASET_DIR=<local datasets> python -m pytest tests/dataset: the Ipojuca smoke passes with the extra re-run of the best candidate.
• 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.

Screenshots

• N/A

[codecov]

Codecov Report

❌ Patch coverage is 97.73756% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.96%. Comparing base (5d0d77f) to head (f0656ee).

Files with missing lines	Patch %	Lines
rubem/calibration/runner.py	95.93%	4 Missing and 3 partials ⚠️
rubem/calibration/parameters.py	98.27%	1 Missing and 1 partial ⚠️
rubem/calibration/_worker.py	95.45%	1 Missing ⚠️

Additional details and impacted files

@@                      Coverage Diff                      @@
##           feat/345-calibration-docs     #350      +/-   ##
=============================================================
+ Coverage                      92.58%   92.96%   +0.38%     
=============================================================
  Files                             65       65              
  Lines                           4573     4935     +362     
  Branches                         557      617      +60     
=============================================================
+ Hits                            4234     4588     +354     
- Misses                           270      275       +5     
- Partials                          69       72       +3     

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

[soaressgabriel]

Superseded by #344, which now carries this work as part of one pull request for the calibration command (issue #343), in a commit series organized by concern. The tree is the one reviewed here, except the changelog, whose entries became one.