Document the calibration method and add the dataset smoke test

.github/workflows/ci.yml

@@ -113,7 +113,7 @@ jobs:
           MATRIX_PYTHON: ${{ matrix.python }}
         shell: bash -el {0}
       - name: Install RUBEM with test dependencies
-        run: pip install -e ".[test,docs]"
+        run: pip install -e ".[test,docs,calibration]"
         shell: bash -el {0}
       - name: Run the test suite
         run: pytest -n auto -ra --cov=rubem --cov-report=xml --junitxml="TestResults-Rubem.xml"

ci/dev-requirements.in

@@ -0,0 +1,18 @@
+# Direct development requirements audited by the pip-audit job. Refresh the
+# lock with:
+#   uv pip compile ci/dev-requirements.in -o ci/dev-requirements.lock --python-version 3.12
+# An existing lock keeps its pins; add --upgrade to move every package forward.
+build
+codespell
+pre-commit
+pyfakefs
+pytest-cov
+pytest-mock
+pytest-xdist
+ruff
+scipy>=1.16.2
+sphinx-autodoc-typehints
+sphinx-rtd-theme
+sphinxcontrib-email
+sphinxcontrib-youtube
+twine

ci/dev-requirements.lock

@@ -1,11 +1,11 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile dev-requirements.in -o dev-requirements.lock --python-version 3.12
+#    uv pip compile ci/dev-requirements.in -o ci/dev-requirements.lock --python-version 3.12
 alabaster==1.0.0
     # via sphinx
 babel==2.18.0
     # via sphinx
 build==1.5.0
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 certifi==2026.7.22
     # via requests
 cffi==2.1.1
@@ -15,7 +15,7 @@ cfgv==3.5.0
 charset-normalizer==3.5.1
     # via requests
 codespell==2.4.3
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 coverage==7.15.4
     # via pytest-cov
 cryptography==50.0.0
@@ -73,6 +73,8 @@ nh3==0.3.7
     # via readme-renderer
 nodeenv==1.10.0
     # via pre-commit
+numpy==2.5.3
+    # via scipy
 packaging==26.3
     # via
     #   build
@@ -86,11 +88,11 @@ pluggy==1.6.0
     #   pytest
     #   pytest-cov
 pre-commit==4.6.2
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 pycparser==3.0
     # via cffi
 pyfakefs==6.2.0
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 pygments==2.21.0
     # via
     #   pytest
@@ -101,16 +103,15 @@ pyproject-hooks==1.2.0
     # via build
 pytest==9.1.1
     # via
-    #   -r dev-requirements.in
     #   pytest-cov
     #   pytest-mock
     #   pytest-xdist
 pytest-cov==7.1.0
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 pytest-mock==3.15.1
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 pytest-xdist==3.8.0
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 python-discovery==1.5.2
     # via virtualenv
 pyyaml==6.0.3
@@ -132,29 +133,30 @@ rich==15.0.0
 roman-numerals==4.1.0
     # via sphinx
 ruff==0.16.4
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
+scipy==1.18.1
+    # via -r ci/dev-requirements.in
 secretstorage==3.5.0
     # via keyring
 snowballstemmer==3.1.1
     # via sphinx
 sphinx==9.1.0
     # via
-    #   -r dev-requirements.in
     #   sphinx-autodoc-typehints
     #   sphinx-rtd-theme
     #   sphinxcontrib-email
     #   sphinxcontrib-jquery
     #   sphinxcontrib-youtube
 sphinx-autodoc-typehints==3.13.2
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 sphinx-rtd-theme==3.1.0
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0
     # via sphinx
 sphinxcontrib-email==0.3.6
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jquery==4.1
@@ -166,9 +168,9 @@ sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 sphinxcontrib-youtube==1.5.0
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 twine==7.0.0
-    # via -r dev-requirements.in
+    # via -r ci/dev-requirements.in
 urllib3==2.7.0
     # via
     #   id

doc/source/api.rst

@@ -122,6 +122,37 @@ Importing ``rubem.api`` does not require PCRaster or GDAL; running the model
 does. Without them, loading a configuration or running raises ``ImportError``
 with the same installation guidance the command line prints.
 
+Calibration
+-----------
+
+``rubem calibrate`` is built on this API: each of its workers calls
+``Model.run()`` in its own process, on a configuration derived from the one
+being calibrated. The same search is available from Python as
+``rubem.calibration.runner.calibrate``, which takes the configuration file, the
+observed series, the run directory and a ``CalibrationSettings``:
+
+.. code-block:: python
+
+   from rubem.calibration.runner import CalibrationSettings, calibrate
+
+   if __name__ == "__main__":
+       result = calibrate(
+           "config.json",
+           "observed.csv",
+           "calibration",
+           CalibrationSettings(seed=42, maxiter=20, popsize=5),
+       )
+       print(result.best_parameters, result.best_nse)
+
+The entry point guard is required: the calibration starts its workers with the
+``spawn`` method, which imports the main module of the caller in every one of
+them. SciPy is needed as well, from the ``rubem[calibration]`` extra.
+
+``rubem.calibration`` is **not** part of the stable surface yet: only
+``rubem.api`` is, and the calibration package may change without a minor
+version bump until it is promoted. The method behind the command is documented
+in :doc:`Calibration </calibration>`.
+
 Logging
 -------