Document the calibration method and add the dataset smoke test

[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 #344 (base feat/343-calibrate).

• doc/source/calibration.rst, a new page in the toctree between the preprocessing and the API pages: what the command fits and against what; the objective (the Nash-Sutcliffe efficiency over the pairs valid in both series, the masked values, the two guards, the average over stations, the spin-up window, FO = 1000 (100 (1 - NSE))^2); the eight free parameters with the bounds of appsettings.json, w3 = 1 - (w1 + w2), the constraint and the starting point; the differential evolution settings with a reason for each and the evaluation budget (max(5, 8 popsize) rounded up to a power of two for the Sobol' initialization; 128 members and up to 12,928 runs with the defaults, 64 members with --popsize 5; the convergence test SciPy applies); the observed series formats and the fixed drainage network a calibration on arn requires (RASTERS.ldd, with the PCRaster recipe); the artifacts; the process model (one spawned interpreter per evaluation, silenced workers, failures recorded per evaluation); running on a cluster (--workers, memory, --temp-dir, shorter windows, continuing from a calibrated configuration). Linked from the user guide's command section and from the API page, which states that rubem.calibration is not part of the stable surface yet.
• dataset pytest marker and the RUBEM_DATASET_DIR convention in tests/conftest.py: tests marked dataset are skipped, with the reason, when the variable is unset or does not name a directory, whether or not they request the dataset_dir fixture; the suite stays self-contained in CI.
• tests/dataset/test_calibrate_ipojuca.py: the manifest of the Ipojuca basin is rebased onto the local copy, the window restricted to six monthly steps, the drainage network generated once and named in the configuration, GDAL's auxiliary metadata disabled so nothing is written beside the dataset; a base run with the manifest's own parameters gives the observed series and a one-generation differential evolution from a five-member initial population with two workers finds that configuration again: best objective exactly 0.0 (without the fixed network it is 4.4e-7, which is what the exact comparison guards), the artifacts consistent, no process left behind.
• Changelog entry under Added.

Related Issue

• Resolve Document the calibration method and add the dataset smoke test #345;

Motivation and context

• The command shipped with its options only (Add the rubem calibrate command (differential evolution on the station streamflow) #343, Add the rubem calibrate command #344); the method, the cost of a run, the inputs it needs on a real basin and the way to run it on a large machine were undocumented, and nothing exercised the command on a published dataset.

How has this been tested

• python -m pytest -q -p no:cacheprovider --ignore=tests/integration/doc -n 2 without RUBEM_DATASET_DIR: 1301 passed, 2 skipped (the smoke skipped with its reason).
• RUBEM_DATASET_DIR=<local datasets> python -m pytest -q -p no:cacheprovider tests/dataset: 1 passed in about 10 s (Ipojuca, six steps, ten evaluations on two workers).
• Every statement of the page was checked a second time against the code and the installed SciPy source (formulas, defaults, bounds, budget arithmetic, artifact fields, the LDD requirement).
• 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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.58%. Comparing base (deb85e2) to head (5d0d77f).

Additional details and impacted files

@@                 Coverage Diff                 @@
##           feat/343-calibrate     #346   +/-   ##
===================================================
  Coverage               92.58%   92.58%           
===================================================
  Files                      65       65           
  Lines                    4573     4573           
  Branches                  557      557           
===================================================
  Hits                     4234     4234           
  Misses                    270      270           
  Partials                   69       69           

☔ 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 the calibration page, the dataset marker and the Ipojuca smoke test as part of one pull request for the calibration command (issue #343).