Add hotstart creation and resume (#194)

- [x] Create a hotstart archive from a running simulation
- [x] Store metadata as JSON
- [x] Store raster domain state as `.npz`
- [x] Store SWMM hotstart state when drainage is enabled
- [x] Restore a simulation from a hotstart archive
- [x] Validate archive structure and metadata
- [x] Validate raster/SWMM payload integrity with hashes
- [x] Validate domain congruence on reload
- [x] Validate mask congruence on reload
- [x] Validate drainage presence/absence compatibility
- [x] Restore scheduler/runtime state (`sim_time`, `dt`, `next_ts`, counters, continuity state)
- [x] Restore raster domain state
- [x] Restore drainage coupling state needed after SWMM hotstart reload
- [x] Handle SWMM elapsed time / resumed start datetime for resumed runs
- [x] Add unit tests for writer/loader validation
- [x] Add integration tests for core hotstart round-trip
- [x] Add drainage/EA8b hotstart integration tests

Author: lrntct

AGENTS.md

@@ -0,0 +1,17 @@
+# Itzi flood model
+
+## Common commands
+- Run a single test: `uv run pytest tests/my_test.py`
+- The GRASS-based tests need `--forked` so each tests run in a separate process: `uv run pytest --forked tests/grass`.
+- It is not necessary to run core tests with `--forked`. Additionally, `--forked` prevents the display of print statements and other outputs.
+- Enforce code formatting: `uvx ruff format .`
+
+## Code style
+- Use python type hints. When a function that does not yet use hints is substantially edited, take the opportunity to add type hints.
+- Since the arguments types and return types are already documented by the hints, there's no need to duplicate this information in the docstrings.
+- Apart from particular cases, use pydantic BaseModel instead of dataclass
+- Place imports at the top of the file. Only break this rule to prevent heavy imports in a rarely used function (for example, CLI options).
+
+## General comments
+- The project uses `uv`. To run a command in the correct environment, use `uv run`
+- Running the whole test suite is slow. Do it only after all the specific tests are passing, as a final check.

src/itzi/data_containers.py

@@ -1,5 +1,5 @@
 """
-Copyright (C) 2025 Laurent Courty
+Copyright (C) 2025-2026 Laurent Courty
 
 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
@@ -22,6 +22,7 @@
 from pydantic import BaseModel, ConfigDict
 
 from itzi.const import DefaultValues, TemporalType, InfiltrationModelType
+from itzi.providers.domain_data import DomainData
 
 if TYPE_CHECKING:
     from itzi.drainage import DrainageNode
@@ -216,6 +217,52 @@ class SimulationConfig(BaseModel):
     free_weir_coeff: float = DefaultValues.FREE_WEIR_COEFF
     submerged_weir_coeff: float = DefaultValues.SUBMERGED_WEIR_COEFF
 
+    def as_str_dict(self) -> Dict:
+        """Convert the configuration to a dictionary with string representations."""
+        raw_dict = self.model_dump()
+        raw_dict["start_time"] = self.start_time.isoformat()
+        raw_dict["end_time"] = self.end_time.isoformat()
+        raw_dict["record_step"] = self.record_step.total_seconds()
+        return raw_dict
+
+
+class HotstartSimulationState(BaseModel):
+    """Runtime state to be restored from a hotstart file."""
+
+    model_config = ConfigDict(frozen=True)
+
+    sim_time: str  # ISO format datetime
+    dt: float  # seconds
+    next_ts: Dict[str, str]  # ISO format datetimes
+    time_steps_counters: Dict[str, int]
+    accum_update_time: Dict[str, str]  # ISO format datetimes
+    old_domain_volume: float
+    # Hashes are computed by HotstartWriter and injected before serialization;
+    # callers building the state before archive creation leave them as empty defaults.
+    raster_domain_hash: str = ""
+    swmm_hotstart_hash: str | None = None
+    # SWMM elapsed time in seconds at the hotstart point.
+    # Required to correctly initialise DrainageSimulation.elapsed_time so that
+    # the first swmm_step() after hotstart restoration computes the correct _dt.
+    swmm_elapsed_time: float | None = None
+
+
+class HotstartMetadata(BaseModel):
+    """Metadata schema for hotstart archive files.
+
+    Provides a single source of truth for hotstart metadata structure,
+    enabling validation during both creation and loading.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    creation_date: datetime
+    itzi_version: str
+    hotstart_version: int
+    domain_data: DomainData
+    simulation_config: SimulationConfig
+    simulation_state: HotstartSimulationState
+
 
 class GrassParams(BaseModel):
     """Parameters for GRASS GIS session."""

src/itzi/drainage.py

@@ -1,5 +1,5 @@
 """
-Copyright (C) 2016-2025 Laurent Courty
+Copyright (C) 2016-2026 Laurent Courty
 
 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
@@ -12,9 +12,14 @@
 GNU General Public License for more details.
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
 import math
 from datetime import timedelta
 from enum import StrEnum
+from io import BytesIO
+import tempfile
 
 import pyswmm
 import numpy as np
@@ -29,6 +34,10 @@
     DrainageNodeAttributes,
 )
 
+if TYPE_CHECKING:
+    from datetime import datetime
+    from pyswmm.swmm5 import PySWMM
+
 
 class CouplingTypes(StrEnum):
     NOT_COUPLED = "not coupled"
@@ -41,27 +50,72 @@ class CouplingTypes(StrEnum):
 class DrainageSimulation:
     """manage simulation of the pipe network"""
 
-    def __init__(self, pyswmm_sim, nodes_list, links_list):
+    def __init__(
+        self,
+        pyswmm_sim: pyswmm.Simulation,
+        nodes_list: list[DrainageNode],
+        links_list: list[DrainageLink],
+        hotstart_filename: str | None = None,
+        hotstart_start_datetime: datetime | None = None,
+    ):
+        """Initialize the drainage simulation.
+
+        Args:
+            pyswmm_sim: A pyswmm Simulation object.
+            nodes_list: List of DrainageNode objects.
+            links_list: List of DrainageLink objects.
+            hotstart_filename: Path to SWMM hotstart file (.hsf) to restore state from.
+            hotstart_start_datetime: datetime to set as SWMM's start time after hotstart
+                restore. This is used to ensure SWMM reads timeseries from the correct
+                point after resuming from a hotstart.
+        """
         # A list of DrainageNode object
         self.nodes = nodes_list
         # A list of DrainageLink objects
         self.links = links_list
         # create swmm object, open files and start simulation
         self.swmm_sim = pyswmm_sim
-        self.swmm_model = self.swmm_sim._model
+        self.swmm_model: PySWMM = self.swmm_sim._model
         # Check if the unit is m3/s
         if self.swmm_sim.flow_units != "CMS":
             msgr.fatal("SWMM simulation unit must be CMS")
+        # Start model
+        if hotstart_filename:
+            self.swmm_model.swmm_use_hotstart(hotstart_filename)
+        if hotstart_start_datetime is not None:
+            self.swmm_model.setSimulationDateTime(
+                pyswmm.toolkitapi.SimulationTime.StartDateTime, hotstart_start_datetime
+            )
         self.swmm_model.swmm_start()
         # allow ponding
         # TODO: check if allowing ponding is necessary
         self._dt = 0.0
         self.elapsed_time = 0.0
+        self._closed = False
 
     def __del__(self):
         """Make sure the swmm simulation is ended and closed properly."""
-        self.swmm_model.swmm_report()
-        self.swmm_model.swmm_close()
+        self.close()
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        try:
+            self.swmm_model.swmm_end()
+        except Exception:
+            pass
+        try:
+            self.swmm_model.swmm_report()
+        except Exception:
+            pass
+        try:
+            self.swmm_sim.close()
+        except Exception:
+            try:
+                self.swmm_model.swmm_close()
+            except Exception:
+                pass
+        self._closed = True
 
     @property
     def dt(self):
@@ -106,6 +160,19 @@ def get_drainage_network_data(self) -> DrainageNetworkData:
             links_data.append(link.get_data())
         return DrainageNetworkData(nodes=tuple(nodes_data), links=tuple(links_data))
 
+    def get_hotstart(self) -> BytesIO:
+        """Save a temp SWMM hotstart, return a binary object."""
+        with tempfile.NamedTemporaryFile(suffix=".hsf", delete_on_close=False) as tmp:
+            temp_hotstart = tmp.name
+            # Close the file handle so SWMM can open it exclusively
+            tmp.close()
+            self.swmm_model.swmm_save_hotstart(temp_hotstart)
+            with open(temp_hotstart, "rb") as f:
+                buffer = BytesIO(f.read())
+            buffer.seek(0)
+            return buffer
+        # File is automatically deleted on context manager exit, even on exception
+
 
 class DrainageNode(object):
     """A wrapper around the pyswmm node object.