#include <HotStartManager.hpp>

Collaboration diagram for openswmm::HotStartManager:

Public Member Functions
	HotStartManager ()=delete
	Prevent instantiation of the static hot-start utility class.

Static Public Member Functions
static HotStartFile *	save (const SimulationContext &ctx, const std::string &path)
	Capture current engine state and write a feature-dependent native hot start.

static HotStartFile *	save (const SimulationContext &ctx, const runoff::RunoffSolver runoff, const groundwater::GWSolver gw, const std::string &path)
	Capture native engine state including optional infiltration and groundwater solvers.

static HotStartFile *	save_with_engine_checkpoint (const SimulationContext &ctx, const runoff::RunoffSolver runoff, const groundwater::GWSolver gw, const std::string &path, const std::string &engine_checkpoint)
	Capture a native hot start with an optional complete engine-session checkpoint.

static HotStartFile *	open (const std::string &path)
	Read and validate a hot start file.

static bool	is_native_file (const std::string &path) noexcept
	Probe the native hot-start magic without parsing records.

static int	apply (HotStartFile &hs, SimulationContext &ctx, std::function< void(const std::string &)> warn_cb={})
	Apply hot start records to a simulation context.

static int	apply (HotStartFile &hs, SimulationContext &ctx, runoff::RunoffSolver runoff, groundwater::GWSolver gw, std::function< void(const std::string &)> warn_cb={})
	Apply hot start records including infiltration and GW state.

static int	apply_legacy_routing (const std::string &path, SimulationContext &ctx, std::function< void(const std::string &)> warn_cb={}, std::vector< double > runoff=nullptr, LegacySpeciesTrailer species=nullptr)
	Read a legacy EPA SWMM5 `.hsf` (USE HOTSTART) file and apply its routing state to the context, BY OBJECT INDEX (the legacy format stores node/link state in object order, no IDs).

static bool	apply_species_surface (const LegacySpeciesTrailer &tr, SimulationContext &ctx, const std::function< void(const std::string &)> &warn)
	Apply a legacy trailer surface block by reaction-species name.

static std::size_t	legacy_runoff_size (const SimulationContext &ctx, int n_land)
	Number of doubles in legacy's runoff section (hotstart.c saveRunoff) for the current model with `n_land` land uses.

static int	save_legacy_routing (const std::string &path, const SimulationContext &ctx, const std::vector< double > *runoff=nullptr)
	Write the current routing state as a legacy EPA SWMM5 `.hsf` (SAVE HOTSTART), byte-format-compatible with legacy readRouting() and apply_legacy_routing() above.

static bool	flush (HotStartFile &hs)
	Rewrite a dirty native hot-start object to its stored path.

static const std::string &	last_io_error () noexcept
	Description of the most recent I/O error (empty = none).

Constructor & Destructor Documentation

◆ HotStartManager()

openswmm::HotStartManager::HotStartManager ( )

delete

Prevent instantiation of the static hot-start utility class.

Member Function Documentation

◆ apply() [1/2]

int openswmm::HotStartManager::apply	(	HotStartFile &	hs,
		SimulationContext &	ctx,
		runoff::RunoffSolver *	runoff,
		groundwater::GWSolver *	gw,
		std::function< void(const std::string &)>	warn_cb = {} )

static

Apply hot start records including infiltration and GW state.

Gap #54: extended apply that also restores infiltration model state and GW zone state when the file is V2 format.

Parameters

hs	Hot start file (from save() or open()).
ctx	Target simulation context (must be INITIALIZED).
runoff	RunoffSolver to restore infiltration state into (may be nullptr).
gw	GWSolver to restore GW zone state into (may be nullptr).
warn_cb	Optional callback for per-missing-object warnings.

Returns: Number of missing-object warnings generated.

Return values

-1	Qualified-restart or state-restore refusal; details in last_io_error() and/or hs.warnings.

Note: No whole-context rollback. A late failure can follow earlier state changes. Full embedded session checkpoints must restore through SWMMEngine start. Warning callback strings are borrowed for the synchronous call; callback exceptions propagate.

Here is the call graph for this function:

◆ apply() [2/2]

int openswmm::HotStartManager::apply	(	HotStartFile &	hs,
		SimulationContext &	ctx,
		std::function< void(const std::string &)>	warn_cb = {} )

static

Apply hot start records to a simulation context.

For each record in the hot start file, the matching object (by string ID) in ctx is updated. Objects in the hot start that are absent from ctx generate warnings — they do not fail.

Parameters

hs	Hot start file (from save() or open()).
ctx	Target simulation context (must be INITIALIZED).
warn_cb	Optional callback for per-missing-object warnings.

Returns: Number of missing-object warnings generated (0 = perfect match).

Return values

-1	Qualified-restart or state-restore refusal; details in last_io_error() and/or hs.warnings.

Note: No whole-context rollback. A late failure can follow earlier state changes. Full embedded session checkpoints must restore through SWMMEngine start. Warning callback strings are borrowed for the synchronous call; callback exceptions propagate.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ apply_legacy_routing()

int openswmm::HotStartManager::apply_legacy_routing	(	const std::string &	path,
		SimulationContext &	ctx,
		std::function< void(const std::string &)>	warn_cb = {},
		std::vector< double > *	runoff = nullptr,
		LegacySpeciesTrailer *	species = nullptr )

static

Read a legacy EPA SWMM5 .hsf (USE HOTSTART) file and apply its routing state to the context, BY OBJECT INDEX (the legacy format stores node/link state in object order, no IDs).

Mirrors legacy hotstart.c readRouting(): sets each node's depth + lateral inflow and each link's flow + depth + setting, all stored as float in internal units (ft, cfs). Also restores node/link pollutant concentrations (current and old) and v4 storage HRT. Supports legacy versions 1–4. Subcatchment state is skipped with a warning; this is a routing-only restore. Derived hydraulic state (head, volumes, old-step values) is recomputed by the caller. Cold quality seeds must not overwrite the restored concentrations.

Parameters

path	Absolute path to the legacy `.hsf` file.
ctx	Allocated target context; node/link/pollutant counts must match the file.
warn_cb	Optional warning callback.
runoff	When given, receives the file's runoff section (legacy_runoff_size() doubles) for the caller to apply once the hydrology and quality state exist; when null the section is skipped with a warning.

Returns: 0 on success; non-zero error code otherwise (description in last_io_error()).

Parameters

[out] species Optional trailer destination for deferred surface-species application; NULL discards it.

Note: Parsing applies records incrementally; later failure does not roll back earlier context mutations.

Here is the call graph for this function:

◆ apply_species_surface()

bool openswmm::HotStartManager::apply_species_surface	(	const LegacySpeciesTrailer &	tr,
		SimulationContext &	ctx,
		const std::function< void(const std::string &)> &	warn )

static

Apply a legacy trailer surface block by reaction-species name.

Mismatch emits one warning without surface mutation; unknown species are silently skipped and matching uses exact-case ReactionData names. Destination entries are bounds-tested independently, so true does not guarantee every expected destination was populated. Does not reset ledgers or initialize absent species.

Parameters

[in]	tr	Borrowed trailer with correctly shaped washoff/ponded/buildup arrays for its counts; source payload lengths are unchecked.
[in,out]	ctx	Allocated/resolved MSX surface state. Receives matching species current/old washoff, ponded mass and buildup.
[in]	warn	Optional synchronous warning callback; borrowed message string is valid only during the call.

Returns: False if trailer has no surface block, surface state inactive, or subcatchment/land-use counts differ; true otherwise.

Here is the call graph for this function:

◆ flush()

bool openswmm::HotStartManager::flush ( HotStartFile & hs )

static

Rewrite a dirty native hot-start object to its stored path.

On success clears dirty. Failure leaves dirty set and generally updates thread-local error; a direct truncated write may have partially replaced the destination. Does not apply edits to a live simulation or update embedded engine-session bytes.

Parameters

[in,out] hs Caller-owned coherent file representation; path must be nonempty when dirty.

Returns: True for an already clean object or successful write; false for empty path/write failure.

Here is the caller graph for this function:

◆ is_native_file()

bool openswmm::HotStartManager::is_native_file ( const std::string & path )

staticnoexcept

Probe the native hot-start magic without parsing records.

Does not validate version, checksum or trailing records. Declared noexcept; exceptions during path/stream construction therefore terminate.

Parameters

[in] path Borrowed UTF-8 input path.

Returns: True when 16 bytes can be read and the first 15 match the native stamp including its NUL; false for missing/short/legacy files.

Here is the call graph for this function:

◆ last_io_error()

const std::string & openswmm::HotStartManager::last_io_error ( )

staticnoexcept

Description of the most recent I/O error (empty = none).

Here is the caller graph for this function:

◆ legacy_runoff_size()

std::size_t openswmm::HotStartManager::legacy_runoff_size	(	const SimulationContext &	ctx,
		int	n_land )

static

Number of doubles in legacy's runoff section (hotstart.c saveRunoff) for the current model with n_land land uses.

Per subcatchment: 3 sub-area ponded depths + runoff (4), infiltration state (6), +4 with groundwater, +15 with a snowpack, and when pollutants exist runoff and ponded quality (2 per pollutant) plus per land use the buildup of each pollutant and the date it was last swept.

Parameters

[in]	ctx	Borrowed model counts and subcatchment aquifer/snowpack references.
[in]	n_land	Land-use count; negative treated as zero.

Returns: Number of native double slots, not bytes; caller ensures size_t arithmetic does not overflow.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ open()

HotStartFile * openswmm::HotStartManager::open ( const std::string & path )

static

Read and validate a hot start file.

Validates magic, version, and CRC32. Loads all records into memory.

Parameters

path	File path.

Returns: Heap-allocated HotStartFile* on success, nullptr on error.

Here is the caller graph for this function:

◆ save() [1/2]

HotStartFile * openswmm::HotStartManager::save	(	const SimulationContext &	ctx,
		const runoff::RunoffSolver *	runoff,
		const groundwater::GWSolver *	gw,
		const std::string &	path )

static

Capture native engine state including optional infiltration and groundwater solvers.

Gap #54: extends V1 save with per-subcatchment infiltration model state (6-element flat array) and GW zone state (theta, lower_depth). Uses at least version 2 and promotes for the captured feature blocks.

Parameters

ctx	Simulation context (must be RUNNING or ENDED).
runoff	RunoffSolver providing infiltration state (may be nullptr).
gw	GWSolver providing GW zone state (may be nullptr).
path	Output file path.

Returns: Owned heap file on success (caller deletes), NULL on handled refusal/IO failure with last_io_error().

Note: Delegates to save_with_engine_checkpoint with an empty payload; feature-dependent full-restart requirements can refuse this partial capture. Destination is directly overwritten; exceptions outside capture guards can propagate.

Here is the call graph for this function:

◆ save() [2/2]

HotStartFile * openswmm::HotStartManager::save	(	const SimulationContext &	ctx,
		const std::string &	path )

static

Capture current engine state and write a feature-dependent native hot start.

Parameters

ctx	Simulation context (must be RUNNING or ENDED).
path	Output file path.

Returns: Heap-allocated HotStartFile* on success (caller owns), or nullptr on I/O error (error description in last_io_error).

Note: Caller deletes the returned object. Source context must be coherent at an accepted boundary; this helper does not enforce the engine lifecycle itself. Destination is directly overwritten. Advanced features can require full session checkpoint capture instead; allocation exceptions may propagate.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ save_legacy_routing()

int openswmm::HotStartManager::save_legacy_routing	(	const std::string &	path,
		const SimulationContext &	ctx,
		const std::vector< double > *	runoff = nullptr )

static

Write the current routing state as a legacy EPA SWMM5 .hsf (SAVE HOTSTART), byte-format-compatible with legacy readRouting() and apply_legacy_routing() above.

Mirrors legacy hotstart.c saveHotstart()+saveRunoff()+ saveRouting() for the "SWMM5-HOTSTART4" version: 15-char stamp + object counts (nSub, nLand, nNodes, nLinks, nPollut, flowUnits as int32), then one double record per subcatchment (ponded depths, runoff, infiltration, groundwater, snowpack, quality, buildup — the runoff argument), then per node depth, latFlow[, storage hrt], qual[] and per link flow, depth, setting, qual[] — all float, internal units (ft, cfs). Storage residence time is preserved when quality state is allocated, and otherwise written as zero.

Parameters

path	Absolute path for the `.hsf` file.
ctx	Source context (final routing state).
runoff	Legacy runoff section (legacy_runoff_size() doubles for the model's land uses), written between the header and the routing records. Null writes no runoff section and zero land uses, which only a model without subcatchments can read back.

Returns: 0 on success; non-zero on file-open/write error (description in last_io_error()).

Here is the call graph for this function:

◆ save_with_engine_checkpoint()

HotStartFile * openswmm::HotStartManager::save_with_engine_checkpoint	(	const SimulationContext &	ctx,
		const runoff::RunoffSolver *	runoff,
		const groundwater::GWSolver *	gw,
		const std::string &	path,
		const std::string &	engine_checkpoint )

static

Capture a native hot start with an optional complete engine-session checkpoint.

Chooses feature-dependent versions through V18; nonempty engine payload promotes at least V15 and is limited to 512 MiB. Payload must come from the matching initialized model and qualified session snapshot, not arbitrary bytes. Empty payload refuses configurations needing full restart state. Native file write is direct truncation, without atomic staging. Allocation/other exceptions outside capture guards can propagate.

Parameters

[in]	ctx	Borrowed coherent model state at an accepted save boundary; lifecycle qualification is enforced by SWMMEngine callers.
[in]	runoff	Borrowed runoff solver for infiltration capture, may be NULL.
[in]	gw	Borrowed groundwater solver for zone-state capture, may be NULL.
[in]	path	UTF-8 destination path overwritten by native binary serialization.
[in]	engine_checkpoint	Owned-by-caller opaque accepted-boundary SWMMEngine checkpoint bytes copied into the file; empty requests a partial native save.

Returns: Heap-allocated file on success, caller deletes it; NULL on handled refusal/IO failure with last_io_error().

Here is the call graph for this function:

Here is the caller graph for this function:

The documentation for this class was generated from the following files:

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/core/HotStartManager.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/core/HotStartManager.cpp

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ HotStartManager()

Member Function Documentation

◆ apply() [1/2]

◆ apply() [2/2]

◆ apply_legacy_routing()

◆ apply_species_surface()

◆ flush()

◆ is_native_file()

◆ last_io_error()

◆ legacy_runoff_size()

◆ open()

◆ save() [1/2]

◆ save() [2/2]

◆ save_legacy_routing()

◆ save_with_engine_checkpoint()