Hot start C API implementation — thin wrappers around HotStartManager. More...

#include "SWMMEngine.hpp"
#include "HotStartManager.hpp"
#include "../../../include/openswmm/engine/openswmm_hotstart.h"
#include <cstring>

Include dependency graph for openswmm_hotstart_impl.cpp:

Macros
#define	CHECK_ENGINE(e) do { if (!(e)) return SWMM_ERR_BADHANDLE; } while(0)

#define	CHECK_HS(hs) do { if (!(hs)) return SWMM_ERR_BADHANDLE; } while(0)

Functions
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 C API implementation — thin wrappers around HotStartManager.

Every function declared in include/openswmm/engine/openswmm_hotstart.h is implemented here.

Pattern:

Validate handle (non-null, correct type).
Cast opaque void* → HotStartFile* or SWMMEngine*.
Delegate to HotStartManager static methods.
Return SWMM_OK or an error code.

Note: Must be compiled as C++ (pulls in C++ headers), but exported symbols use C linkage via extern "C".

See also: include/openswmm/engine/openswmm_hotstart.h; HotStartManager.hpp; SWMMEngine.hpp

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright: Copyright (c) 2026 HydroCouple. All rights reserved.

License\n MIT License

Macro Definition Documentation

◆ CHECK_ENGINE

#define CHECK_ENGINE ( e ) do { if (!(e)) return SWMM_ERR_BADHANDLE; } while(0)

◆ CHECK_HS

#define CHECK_HS ( hs ) do { if (!(hs)) return SWMM_ERR_BADHANDLE; } while(0)

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_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).

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CHECK_ENGINE

◆ CHECK_HS

Function Documentation

◆ swmm_hotstart_apply()

◆ swmm_hotstart_close()

◆ swmm_hotstart_get_crs()

◆ swmm_hotstart_get_sim_time()

◆ swmm_hotstart_link_count()

◆ swmm_hotstart_node_count()

◆ swmm_hotstart_open()

◆ swmm_hotstart_save()

◆ swmm_hotstart_set_link_depth()

◆ swmm_hotstart_set_link_flow()

◆ swmm_hotstart_set_node_depth()

◆ swmm_hotstart_set_node_head()

◆ swmm_hotstart_set_subcatch_runoff()

◆ swmm_hotstart_warning()

◆ swmm_hotstart_warning_count()