add --resume-from hotstart in CLI

docs/cli.rst

@@ -1,20 +1,68 @@
 Command line usage
-------------------
+==================
 
 Run a simulation
-~~~~~~~~~~~~~~~~
+----------------
 
 .. argparse::
    :filename: ../src/itzi/parser.py
-   :func: arg_parser
+   :func: build_parser
    :prog: itzi
    :path: run
+   :nodefault:
+
+
+Hotstart usage
+~~~~~~~~~~~~~~
+.. versionadded:: 26.6
+
+Use ``--resume-from`` to resume a run from a hotstart file created by a
+previous simulation. The hotstart file does not replace the configuration file:
+you still pass the normal Itzi configuration file(s), and Itzi validates the
+resumed configuration against the hotstart before starting.
+
+Checkpoint creation and resume-time configuration constraints are documented in
+:doc:`conf_file`.
+Known restart limitations are summarized in :doc:`faq`.
+
+Single simulation
+^^^^^^^^^^^^^^^^^
+
+Resume a single configuration file from one hotstart file:
+
+.. code-block:: bash
+
+   itzi run my_case.ini --resume-from checkpoints/latest_hotstart.zip
+
+Batch mode
+^^^^^^^^^^
+
+For batch runs, map each resumed simulation explicitly:
+
+.. code-block:: bash
+
+   itzi run a.ini b.ini \
+      --resume-from a.ini=checkpoints/a_hotstart.zip \
+      --resume-from b.ini=checkpoints/b_hotstart.zip
+
+Rules
+^^^^^
+
+- With a single configuration file, ``--resume-from HOTSTART_PATH`` is valid.
+- With multiple configuration files, each ``--resume-from`` value must use the
+  ``CONFIG_PATH=HOTSTART_PATH`` form.
+- The ``CONFIG_PATH`` part may be either the config path or a basename such as
+  ``a.ini``. When basenames are not unique, use the config path.
+- At most one hotstart file may be mapped to a given configuration file.
+- When multiple ``CONFIG_PATH=HOTSTART_PATH`` mappings are supplied, any batch
+  configuration file left unmapped still runs from scratch.
+
 
 Get the version number
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 .. argparse::
    :filename: ../src/itzi/parser.py
-   :func: arg_parser
+   :func: build_parser
    :prog: itzi
    :path: version

docs/conf_file.rst

@@ -37,9 +37,10 @@ Valid combinations:
 ----------
 
 .. versionadded:: 26.6
-    The hotstart feature is added.
 
-A hotstart file saves the current state of the simulation at a give point in time, allowing to restart a simulation from a given point.
+
+A hotstart file saves the current state of the simulation at a given point in
+time, allowing the run to be resumed later with ``itzi run --resume-from``.
 
 .. list-table::
    :header-rows: 1
@@ -49,12 +50,112 @@ A hotstart file saves the current state of the simulation at a give point in tim
      - Description
      - Format
    * - wallclock_step
-     - Wall clock duration between records.
+     - Wall-clock duration between checkpoint writes.
      - HH:MM:SS
    * - save_file
-     - File name for the hotstart file. Each new file overwrites the anterior. Only the last created file is kept.
+     - Path to the hotstart file written by the simulation.
      - Text string
 
+Current behavior and limitations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- The ``[hotstart]`` section is optional. If it is absent, no checkpoint is
+  written.
+- When the ``[hotstart]`` section is present, both ``wallclock_step`` and
+  ``save_file`` must be provided.
+- ``wallclock_step`` is measured in wall-clock time, not simulation time.
+- ``save_file`` is overwritten every time a new checkpoint is written. Only the
+  most recent checkpoint is kept automatically.
+- There is no extra automatic checkpoint at the very end of the simulation.
+- If the run finishes before ``wallclock_step`` has elapsed in real time, no
+  hotstart file is written.
+
+Resume requirements
+^^^^^^^^^^^^^^^^^^^
+
+To resume from a hotstart file, pass the configuration file together with the
+``--resume-from`` CLI option described in :doc:`cli`.
+
+Before resuming, Itzi validates the hotstart against the current configuration.
+Resume is rejected when any of the following checks fail:
+
+- the hotstart archive is missing or invalid;
+- the resumed domain bounds, grid size, or coordinate reference system do not
+  match the archived domain;
+- the current GRASS mask does not match the archived mask;
+- the archived run contains drainage state but the resumed configuration has no
+  drainage model, or the reverse;
+- the infiltration model changes between the archived run and the resumed run;
+- a surface-flow parameter changes outside the set explicitly allowed on
+  resume;
+- ``end_time`` is changed to a value that is not strictly after the archived
+  checkpoint time;
+
+
+Config changes allowed on resume
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The table below reflects the current implementation.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Config option(s)
+     - Status
+     - Notes
+   * - ``[time] end_time``
+     - Allowed
+     - May stay unchanged or be extended. If changed, it must be strictly after
+       the checkpoint time stored in the hotstart.
+   * - ``[time] record_step``
+     - Allowed
+     - Changes the output cadence from the resume point onward. It must stay
+       positive.
+   * - ``[options] dtinf``
+     - Allowed
+     - The resumed hydrology schedule uses the new value.
+   * - ``[options] cfl``, ``theta``, ``dtmax``, ``slope_threshold``,
+       ``max_slope``, ``vrouting``, ``max_error``
+     - Allowed
+     - These are the only surface-flow options explicitly allowed to change on
+       resume.
+   * - ``[hotstart] wallclock_step``, ``[hotstart] save_file``
+     - Allowed
+     - These control only new checkpoints creation after the resume. The input
+       hotstart file itself is selected with ``--resume-from``.
+   * - ``[output] prefix``, ``[output] values``, ``[statistics] stats_file``
+     - Allowed
+     - Output targets come from the resumed configuration file.
+   * - ``[options] hmin``, ``g``
+     - Must match
+     - Changing any of these raises a hotstart compatibility error.
+   * - Infiltration model selection from ``[input]``
+     - Must match
+     - The model type must stay the same: no infiltration, constant
+       infiltration, and Green-Ampt are not interchangeable on resume.
+   * - Drainage enabled or disabled
+     - Must match
+     - A run with drainage can only resume from a hotstart that also contains
+       drainage state, and vice versa.
+   * - ``[time] start_time``
+     - Keep unchanged
+     - The archived simulation clock and scheduler are restored from the
+       hotstart. They are not remapped to a new start time.
+   * - Input map names, ``[drainage] swmm_inp``, and other forcing paths
+     - Not cross-checked
+     - Itzi validates the resumed domain and mask, but it does not verify that
+       these files are the same as in the archived run. Changing them changes
+       the forcing applied after the resume.
+   * - ``[drainage] output``, ``orifice_coeff``, ``free_weir_coeff``,
+       ``submerged_weir_coeff``
+     - Not cross-checked
+     - These values are taken from the resumed configuration, but Itzi does not
+       compare them with the archived configuration before resuming.
+
+If you want a pure restart, keep every option unchanged except for the options
+listed as ``Allowed`` above.
+
 
 [input]
 -------

docs/faq.rst

@@ -26,18 +26,38 @@ which could be achieved by changing two options:
 The second one is by reducing the *theta* option.
 Please note however that a value below 0.7 could be counter-productive.
 
+
+Why does a resumed run differ from an uninterrupted run?
+--------------------------------------------------------
+
+.. versionadded:: 26.6
+
+Hotstart resume is a continuation mechanism, not a guarantee of bitwise
+identity with an uninterrupted run.
+
+For surface-only cases, resumed runs should normally be very close to the
+original run. With drainage enabled, the current SWMM hotstart behavior is not
+always restart-exact.
+A resumed run can therefore show small differences relative to an uninterrupted run
+even when the hotstart file and configuration are valid.
+
+See :doc:`conf_file` for the configuration constraints enforced when resuming.
+
+
 Performances and computer resources usage
 -----------------------------------------
 
-*Itzï* is parallelized using OpenMP.
+*Itzï* is parallelized using OpenMP and makes use of compiler-level vector optimizations.
 By default, it will try to use all available hardware threads on the machine.
 The number of threads used can be changed by setting the environment variable OMP\_NUM\_THREADS.
 
-Given the type of numerical scheme, using a computer with more cores and
-faster RAM will likely decrease the computation time.
-No parallel efficiency test has been performed so far, though.
-For an example of expected performance, a 24h simulation of urban floods with direct
-rainfall on a 5m DEM of 3.5 millions cells takes around 3 hours with an Intel Core i7-4790 (4 cores, 8 threads).
+Using a computer with more cores and faster RAM will likely decrease the computation time.
+Additionally, it is recommended to disable multithreading (SMT) if your CPU support it;
+SMT is counterproductive for the type of computing *Itzï* does.
+
+For an example of expected performance with *Itzï* version 26.6, a 24h simulation of urban floods with direct
+rainfall on a 5m DEM of 3.5 millions cells takes around 2 hours on a 16 cores AMD Ryzen 5900XT.
+
 
 How to decrease computation time
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -48,20 +68,20 @@ The factors that influence the computation time are:
 -  The number of cells in the domain.
 -  The number of wet cells in the domain.
    Direct rainfall is more demanding.
--  The cell size. A smaller cell size decreases the time-step.
+-  The cell size. A smaller cell size decreases the time-step duration.
 -  The maximum water depth in the domain.
-   The higher the water, the smaller the time-step.
--  The amount and frequency of result maps. Disk operations being slow
-   and not yet parallelized (as of version 17.1), writing more maps to
-   the disk will slow the simulation down.
+   The higher the water depth, the shorter the time-step.
+-  The number and frequency of result maps.
+   Disk operations are slow; writing more maps to the disk will slow down the simulation.
 
 As we can see, they are two main categories of factors.
-Those that increase the raw computation load (more cells),
+Those that increase the raw computation load (more cells, longer simulations),
 and those that lower the simulation time-step.
-For the same study area, increasing the cell size is the more efficient way to make a simulation faster,
-because it influence both the number of cells and the time-step.
+For the same study area, increasing the cell size is the easiest way to make a simulation run faster,
+because it influences both the number of cells and the time-step.
+
 
 Memory usage
 ~~~~~~~~~~~~
 
-On average, *Itzï* 17.1 uses around 250 MB of RAM for each million cells in the domain.
+*Itzï* 26.6 uses around 275 MB of RAM for each million cells in the domain.

docs/prog_manual.rst

@@ -24,7 +24,7 @@ Once the itzi repository is cloned and uv installed, you can run itzi with:
 
     uv run itzi
 
-This will create a virtual environment, install all the dependencies listed in the *pyproject.toml* file, and build the Cython extensions.
+This will create a virtual environment, install all the dependencies listed in the *pyproject.toml* file, including dev dependencies, and build the Cython extensions.
 Now, every change you make to the Python code will be directly reflected when running the tests or *uv run itzi* .
 
 
@@ -71,12 +71,14 @@ To estimate the test coverage:
 The GRASS-specific tests could be sped up a bit by running them separately:
 
 .. code:: sh
+
     uv run pytest tests/grass/test_itzi.py && uv run pytest tests/grass/test_bmi.py && uv run pytest tests/grass/test_tutorial.py
 
 
 The tests not relying on GRASS can be run directly:
 
 .. code:: sh
+
     uv run pytest tests/core
 
 
@@ -99,8 +101,9 @@ Documentation
 The documentation is written in reStructuredText and is built with Sphinx.
 It is located in the *docs* directory.
 It is automatically built and published on `readthedocs <https://itzi.readthedocs.io>`__.
-To build the documentation locally, you first need to install *sphinx*, along with *sphinx-argparse* and *sphinx_rtd_theme*.
-You can then build the documentation locally:
+The packages *sphinx*, *sphinx-argparse*, and *sphinx_rtd_theme* are needed to build the docs locally.
+They are normally installed automatically with the rest of the dev dependencies.
+You can then build the documentation:
 
 .. code:: sh
 

pyproject.toml

@@ -59,6 +59,9 @@ dev = [
     "ty>=0.0.51",
     "pyinstrument==5.*",
     "rioxarray>=0.19.0",
+    "sphinx>=9.1.0",
+    "sphinx-argparse>=0.5.2",
+    "sphinx-rtd-theme>=3.1.0",
 ]
 
 [build-system]