Create and use a hot-start file

[lrntct]

It could be useful to have the possibility of stopping and restarting a simulation at an arbitrary time.
The goal of the hot-start file is not to create a portable simulation file, but rather to be able to restart in the same environment a simulation that has been stopped. Therefore, it will not include all input data files.

Creating the hotstart file

The hot-start file format would be a ZIP file containing:

• As JSON:
  • Creation time
  • itzi version
  • hotstart file version number
  • original provider types
  • SimulationConfig
  • DomainData (north, south, east, west, rows, cols, crs_wkt)
  • Time state: sim_time, dt of all models, next_ts, nextstep, time_steps_counters
  • Infiltration model state: cumulative infiltration (for Green-Ampt) or equivalent state for other models - It might be worth adding the cumulative infiltration array to RasterDomain instead of treating it separately
  • Accumulation tracking: accum_update_time, old_domain_volume
• RasterDomain, including mask with numpy.savez
• SWMM own hot-start file

Possible hotstart

hotstart_file:
  ├── metadata/
  │   ├── creation_time
  │   ├── itzi version
  │   ├── hotstart_version
  │   ├── original_provider_types
  │   └── SimulationConfig
  │   └── domain_data (north, south, east, west, rows, cols, crs_wkt)
  ├── time_state/
  │   ├── sim_time
  │   ├── dt
  │   ├── next_ts
  │   └── time_steps_counters
  ├── domain/
  │   ├── all raster_domain arrays
  │   └── arr_mask
  ├── accumulation_tracking/
  │   ├── accum_update_time
  │   └── old_domain_volume
  └── models/
      └── swmm_hotstart_path (if applicable)

This would require to:

• Add a function to create and save the hotstart file to disk
• Add a factory function to create a simulation from a hotstart file

What CAN change safely:

• Output providers (different output format is fine)
• Reporting frequency (record_step)
• End time (can extend simulation)
• Output map names

What CANNOT change:

• Grid dimensions/resolution/extent
• Infiltration model type
• Surface flow parameters that affect numerical scheme
• Presence/absence of drainage coupling

Steps for loading the hotstart:

1. Load DomainData from hotstart file
2. Get DomainData from new provider
3. Validate they match exactly (tolerance for floating point: ~1e-6)
4. Validate arr_mask matches
5. Check configuration compatibility
6. Only then proceed to restore simulation state

To do:

• Create a hotstart archive from a running simulation
• Store metadata as JSON
• Store raster domain state as .npz
• Store SWMM hotstart state when drainage is enabled
• Restore a simulation from a hotstart archive
• Validate archive structure and metadata
• Validate raster/SWMM payload integrity with hashes
• Validate domain congruence on reload
• Validate mask congruence on reload
• Validate drainage presence/absence compatibility
• Restore scheduler/runtime state (sim_time, dt, next_ts, counters, continuity state)
• Restore raster domain state
• Restore drainage coupling state needed after SWMM hotstart reload
• Handle SWMM elapsed time / resumed start datetime for resumed runs
• Add unit tests for writer/loader validation
• Add integration tests for core hotstart round-trip
• Add drainage/EA8b hotstart integration tests
• Test and document which simulation parameter changes are supported when resuming from hotstart
• Add explicit tests for allowed changes:
  • output provider changes
  • record_step changes
  • end time extension
  • output map name changes
• Add explicit tests for rejected incompatible changes:
  • infiltration model type
  • surface-flow numerical parameters affecting solver behavior
  • drainage enabled/disabled mismatch
  • grid/resolution/extent mismatch
• Test hotstart compatibility with time-variable inputs through InputRasterProvider
• Decide whether to enforce config compatibility more strictly in code, not only in tests/docs
• Document current hotstart guarantees and limitations

Nice to have

• Add original_provider_types to hotstart metadata if still considered useful
• Provide a higher-level convenience API/factory for creating a simulation directly from a hotstart file