openswmm_hotstart.h File Reference

Hot start file management — transparent C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_hotstart.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	OPENSWMM_HOTSTART_MAGIC   "OPENSWMM_HS_V1\0"
	Magic string written at the start of every OPENSWMM_HS_V1 file.
#define	OPENSWMM_HOTSTART_VERSION   1
	Current hot start format version number.

Typedefs
typedef void *	SWMM_HotStart
	Opaque handle to an open hot start file.

Functions
SWMM_ENGINE_API int	swmm_hotstart_saves_count (SWMM_Engine engine, int *count)
	Get the number of SAVE HOTSTART entries currently in [FILES].
SWMM_ENGINE_API int	swmm_hotstart_saves_get_path (SWMM_Engine engine, int idx, char *buf, int buflen)
	Get the path of the i-th SAVE HOTSTART entry.
SWMM_ENGINE_API int	swmm_hotstart_saves_get_datetime (SWMM_Engine engine, int idx, double *datetime)
	Get the datetime (decimal day; 0.0 = "end of run") of the i-th SAVE HOTSTART entry.
SWMM_ENGINE_API int	swmm_hotstart_saves_set_path (SWMM_Engine engine, int idx, const char *path)
	Replace the path of an existing SAVE HOTSTART entry.
SWMM_ENGINE_API int	swmm_hotstart_saves_set_datetime (SWMM_Engine engine, int idx, double datetime)
	Replace the datetime of an existing SAVE HOTSTART entry.
SWMM_ENGINE_API int	swmm_hotstart_saves_add (SWMM_Engine engine, const char *path, double datetime)
	Append a new SAVE HOTSTART entry.
SWMM_ENGINE_API int	swmm_hotstart_saves_remove (SWMM_Engine engine, int idx)
	Remove the i-th SAVE HOTSTART entry; subsequent slots shift down.
SWMM_ENGINE_API int	swmm_hotstart_saves_clear (SWMM_Engine engine)
	Remove all SAVE HOTSTART entries.
SWMM_ENGINE_API int	swmm_hotstart_save (SWMM_Engine engine, const char *path)
	Save the current engine state to a new hot start file.
SWMM_ENGINE_API int	swmm_hotstart_open (const char *path, SWMM_HotStart *hs)
	Open an existing hot start file for reading.
SWMM_ENGINE_API int	swmm_hotstart_apply (SWMM_Engine engine, SWMM_HotStart hs)
	Apply hot start state to an engine.
SWMM_ENGINE_API int	swmm_hotstart_set_node_depth (SWMM_HotStart hs, const char *node_id, double depth)
	Modify the stored depth for a node in the hot start file.
SWMM_ENGINE_API int	swmm_hotstart_set_node_head (SWMM_HotStart hs, const char *node_id, double head)
	Modify the stored head for a node.
SWMM_ENGINE_API int	swmm_hotstart_set_link_flow (SWMM_HotStart hs, const char *link_id, double flow)
	Modify the stored flow for a link.
SWMM_ENGINE_API int	swmm_hotstart_set_link_depth (SWMM_HotStart hs, const char *link_id, double depth)
	Modify the stored depth for a link.
SWMM_ENGINE_API int	swmm_hotstart_set_subcatch_runoff (SWMM_HotStart hs, const char *subcatch_id, double runoff)
	Modify the stored runoff for a subcatchment.
SWMM_ENGINE_API int	swmm_hotstart_get_sim_time (SWMM_HotStart hs, double *sim_time)
	Get the simulation timestamp stored in the hot start file.
SWMM_ENGINE_API int	swmm_hotstart_get_crs (SWMM_HotStart hs, char *buf, int buflen)
	Get the CRS string stored in the hot start file.
SWMM_ENGINE_API int	swmm_hotstart_node_count (SWMM_HotStart hs)
	Get the number of nodes stored in the hot start file.
SWMM_ENGINE_API int	swmm_hotstart_link_count (SWMM_HotStart hs)
	Get the number of links stored in the hot start file.
SWMM_ENGINE_API int	swmm_hotstart_warning_count (SWMM_HotStart hs)
	Get the number of warnings generated by the last swmm_hotstart_apply().
SWMM_ENGINE_API const char *	swmm_hotstart_warning (SWMM_HotStart hs, int index)
	Get the i-th warning message from the last swmm_hotstart_apply().
SWMM_ENGINE_API int	swmm_hotstart_close (SWMM_HotStart hs)
	Close and free the hot start handle.

Detailed Description

Hot start file management — transparent C API.

Hot start files capture the hydraulic and water quality state of a SWMM simulation so it can be resumed later without running a warm-up period from dry-weather initial conditions.

The new hot start format (OPENSWMM_HS_V1) extends the legacy SWMM binary hot start format with:

• An object UUID map for robust missing-object detection
• CRS string for spatial consistency checking
• User flag values
• A CRC32 integrity checksum

Workflow

// ---- Save a hot start ----
SWMM_Engine e = swmm_engine_create();
swmm_engine_open(e, "warmup.inp", "warmup.rpt", "warmup.out", NULL);
swmm_engine_initialize(e);
swmm_engine_start(e, 0);
double t = 0.0;
while (swmm_engine_step(e, &t) == SWMM_OK && t > 0.0) {}
swmm_hotstart_save(e, "warmup.hs");
swmm_engine_end(e);
swmm_engine_close(e);
swmm_engine_destroy(e);
 
// ---- Apply a hot start ----
SWMM_HotStart hs = NULL;
swmm_hotstart_open("warmup.hs", &hs);
 
SWMM_Engine e2 = swmm_engine_create();
swmm_engine_open(e2, "storm.inp", "storm.rpt", "storm.out", NULL);
swmm_engine_initialize(e2);
swmm_hotstart_apply(e2, hs);   // warnings issued for missing objects
 
int nwarn = swmm_hotstart_warning_count(hs);
for (int i = 0; i < nwarn; i++) {
    printf("Warning: %s\n", swmm_hotstart_warning(hs, i));
}
 
swmm_hotstart_close(hs);

Macro Definition Documentation

OPENSWMM_HOTSTART_MAGIC

#define OPENSWMM_HOTSTART_MAGIC   "OPENSWMM_HS_V1\0"

Magic string written at the start of every OPENSWMM_HS_V1 file.

OPENSWMM_HOTSTART_VERSION

#define OPENSWMM_HOTSTART_VERSION   1

Current hot start format version number.

Typedef Documentation

SWMM_HotStart

typedef void* SWMM_HotStart

Opaque handle to an open hot start file.

Function Documentation

swmm_hotstart_apply()

SWMM_ENGINE_API int swmm_hotstart_apply	(	SWMM_Engine	engine,
		SWMM_HotStart	hs
	)

Apply hot start state to an engine.

For each object in the hot start file, the engine's corresponding object (matched by string ID) is updated. Objects in the hot start that do not exist in the target engine generate warnings (not errors). Objects in the target engine that are absent from the hot start are left at their default initial conditions.

Parameters

engine	Engine handle (must be in SWMM_STATE_INITIALIZED).
hs	Hot start handle (from swmm_hotstart_open()).

Returns

SWMM_OK on success. Missing objects are warnings, not errors.

Note

Warnings are accessible via swmm_hotstart_warning_count() and swmm_hotstart_warning(). If a warning callback is registered, each missing object also fires SWMM_WARN_HOTSTART_MISSING.

Here is the call graph for this function:

swmm_hotstart_close()

SWMM_ENGINE_API int swmm_hotstart_close

(

SWMM_HotStart

hs

)

Close and free the hot start handle.

If any modifications were made via swmm_hotstart_set_*(), the changes are written back to the file before closing.

Parameters

hs	Hot start handle. Safe to call with NULL.

Returns

SWMM_OK, or SWMM_ERR_IO if write-back fails.

Here is the call graph for this function:

swmm_hotstart_get_crs()

SWMM_ENGINE_API int swmm_hotstart_get_crs	(	SWMM_HotStart	hs,
		char *	buf,
		int	buflen
	)

Get the CRS string stored in the hot start file.

Parameters

hs	Hot start handle.
buf	Caller-allocated buffer.
buflen	Buffer size.

Returns

SWMM_OK or SWMM_ERR_HOTSTART.

swmm_hotstart_get_sim_time()

SWMM_ENGINE_API int swmm_hotstart_get_sim_time	(	SWMM_HotStart	hs,
		double *	sim_time
	)

Get the simulation timestamp stored in the hot start file.

Parameters

hs	Hot start handle.
sim_time	[out] Simulation time (decimal days) at which state was saved.

Returns

SWMM_OK or SWMM_ERR_HOTSTART.

swmm_hotstart_link_count()

SWMM_ENGINE_API int swmm_hotstart_link_count

(

SWMM_HotStart

hs

)

Get the number of links stored in the hot start file.

Parameters

hs	Hot start handle.

Returns

Link count, or -1 on error.

swmm_hotstart_node_count()

SWMM_ENGINE_API int swmm_hotstart_node_count

(

SWMM_HotStart

hs

)

Get the number of nodes stored in the hot start file.

Parameters

hs	Hot start handle.

Returns

Node count, or -1 on error.

swmm_hotstart_open()

SWMM_ENGINE_API int swmm_hotstart_open	(	const char *	path,
		SWMM_HotStart *	hs
	)

Open an existing hot start file for reading.

Validates the magic number, version, and CRC32 checksum. Loads the full object UUID map into memory.

Parameters

path	Path to an existing OPENSWMM_HS_V1 hot start file.
hs	[out] Handle to the opened hot start.

Returns

SWMM_OK on success; SWMM_ERR_HOTSTART if file is invalid.

Here is the call graph for this function:

swmm_hotstart_save()

SWMM_ENGINE_API int swmm_hotstart_save	(	SWMM_Engine	engine,
		const char *	path
	)

Save the current engine state to a new hot start file.

Captures the full hydraulic state (node depths, heads, volumes; link flows, depths; subcatchment runoff and groundwater depths; user flag values) and writes it to the OPENSWMM_HS_V1 binary format.

Parameters

engine	Engine handle (must be in SWMM_STATE_STARTED or SWMM_STATE_RUNNING).
path	File path for the new hot start file.

Returns

SWMM_OK on success; SWMM_ERR_HOTSTART or SWMM_ERR_IO on failure.

Note

The saved file can be applied to a different model as long as the object IDs overlap. Missing objects are handled gracefully.

Here is the call graph for this function:

swmm_hotstart_saves_add()

SWMM_ENGINE_API int swmm_hotstart_saves_add	(	SWMM_Engine	engine,
		const char *	path,
		double	datetime
	)

Append a new SAVE HOTSTART entry.

Parameters

engine	Engine handle.
path	File path (must be non-NULL; may be empty for a placeholder row to be filled in later).
datetime	Decimal day (0.0 = "save at end of run").

Returns

SWMM_OK; SWMM_ERR_BADPARAM if path is NULL.

swmm_hotstart_saves_clear()

SWMM_ENGINE_API int swmm_hotstart_saves_clear

(

SWMM_Engine

engine

)

Remove all SAVE HOTSTART entries.

Parameters

engine

Engine handle.

Returns

SWMM_OK or SWMM_ERR_BADHANDLE.

swmm_hotstart_saves_count()

SWMM_ENGINE_API int swmm_hotstart_saves_count	(	SWMM_Engine	engine,
		int *	count
	)

Get the number of SAVE HOTSTART entries currently in [FILES].

Parameters

engine	Engine handle.
count	[out] Vector size (>= 0).

Returns

SWMM_OK or SWMM_ERR_BADHANDLE / SWMM_ERR_BADPARAM.

swmm_hotstart_saves_get_datetime()

SWMM_ENGINE_API int swmm_hotstart_saves_get_datetime	(	SWMM_Engine	engine,
		int	idx,
		double *	datetime
	)

Get the datetime (decimal day; 0.0 = "end of run") of the i-th SAVE HOTSTART entry.

Parameters

engine	Engine handle.
idx	Slot index.
datetime	[out] Decimal day.

Returns

SWMM_OK; SWMM_ERR_BADPARAM if idx is out of range.

swmm_hotstart_saves_get_path()

SWMM_ENGINE_API int swmm_hotstart_saves_get_path	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen
	)

Get the path of the i-th SAVE HOTSTART entry.

Parameters

engine	Engine handle.
idx	Slot index in [0, swmm_hotstart_saves_count).
buf	Caller-allocated buffer.
buflen	Buffer size (NUL-terminated, truncated at buflen - 1).

Returns

SWMM_OK; SWMM_ERR_BADPARAM if idx is out of range.

swmm_hotstart_saves_remove()

SWMM_ENGINE_API int swmm_hotstart_saves_remove	(	SWMM_Engine	engine,
		int	idx
	)

Remove the i-th SAVE HOTSTART entry; subsequent slots shift down.

Parameters

engine	Engine handle.
idx	Slot index.

Returns

SWMM_OK; SWMM_ERR_BADPARAM if idx is out of range.

swmm_hotstart_saves_set_datetime()

SWMM_ENGINE_API int swmm_hotstart_saves_set_datetime	(	SWMM_Engine	engine,
		int	idx,
		double	datetime
	)

Replace the datetime of an existing SAVE HOTSTART entry.

Parameters

engine	Engine handle.
idx	Slot index.
datetime	Decimal day (0.0 = "save at end of run").

Returns

SWMM_OK; SWMM_ERR_BADPARAM if idx is out of range.

swmm_hotstart_saves_set_path()

SWMM_ENGINE_API int swmm_hotstart_saves_set_path	(	SWMM_Engine	engine,
		int	idx,
		const char *	path
	)

Replace the path of an existing SAVE HOTSTART entry.

Multi-slot generalization of swmm_files_set("HOTSTART_SAVE_PATH", …) (which only addresses slot 0). Empty path + zero datetime does not auto-remove the row here — the caller is expected to manage row lifecycle explicitly via _remove() / _clear().

Parameters

engine	Engine handle.
idx	Slot index.
path	New path (may be empty).

Returns

SWMM_OK; SWMM_ERR_BADPARAM if idx is out of range.

swmm_hotstart_set_link_depth()

SWMM_ENGINE_API int swmm_hotstart_set_link_depth	(	SWMM_HotStart	hs,
		const char *	link_id,
		double	depth
	)

Modify the stored depth for a link.

Parameters

hs	Hot start handle.
link_id	Link identifier.
depth	New depth value.

Returns

SWMM_OK or SWMM_ERR_BADPARAM.

Here is the call graph for this function:

swmm_hotstart_set_link_flow()

SWMM_ENGINE_API int swmm_hotstart_set_link_flow	(	SWMM_HotStart	hs,
		const char *	link_id,
		double	flow
	)

Modify the stored flow for a link.

Parameters

hs	Hot start handle.
link_id	Link identifier.
flow	New flow value.

Returns

SWMM_OK or SWMM_ERR_BADPARAM.

Here is the call graph for this function:

swmm_hotstart_set_node_depth()

SWMM_ENGINE_API int swmm_hotstart_set_node_depth	(	SWMM_HotStart	hs,
		const char *	node_id,
		double	depth
	)

Modify the stored depth for a node in the hot start file.

This allows adjusting initial conditions before applying a hot start. Changes are written back to the file when the handle is closed.

Parameters

hs	Hot start handle.
node_id	Node identifier string.
depth	New depth in the original project length units.

Returns

SWMM_OK, or SWMM_ERR_BADPARAM if node_id not found in hot start.

Here is the call graph for this function:

swmm_hotstart_set_node_head()

SWMM_ENGINE_API int swmm_hotstart_set_node_head	(	SWMM_HotStart	hs,
		const char *	node_id,
		double	head
	)

Modify the stored head for a node.

Parameters

hs	Hot start handle.
node_id	Node identifier.
head	New head value.

Returns

SWMM_OK or SWMM_ERR_BADPARAM.

Here is the call graph for this function:

swmm_hotstart_set_subcatch_runoff()

SWMM_ENGINE_API int swmm_hotstart_set_subcatch_runoff	(	SWMM_HotStart	hs,
		const char *	subcatch_id,
		double	runoff
	)

Modify the stored runoff for a subcatchment.

Parameters

hs	Hot start handle.
subcatch_id	Subcatchment identifier.
runoff	New runoff value.

Returns

SWMM_OK or SWMM_ERR_BADPARAM.

Here is the call graph for this function:

swmm_hotstart_warning()

SWMM_ENGINE_API const char * swmm_hotstart_warning	(	SWMM_HotStart	hs,
		int	index
	)

Get the i-th warning message from the last swmm_hotstart_apply().

Parameters

hs	Hot start handle.
index	Warning index [0, count-1].

Returns

Null-terminated warning string (owned by hs handle), or NULL.

swmm_hotstart_warning_count()

SWMM_ENGINE_API int swmm_hotstart_warning_count

(

SWMM_HotStart

hs

)

Get the number of warnings generated by the last swmm_hotstart_apply().

Warnings are issued for objects that were in the hot start file but not found in the target engine model.

Parameters

hs	Hot start handle.

Returns

Warning count (0 if no apply was called, or all objects matched).