openswmm_model_impl.cpp File Reference

C API implementation — model building, options, user flags, CRS. More...

#include "openswmm_api_common.hpp"
#include "InpWriter.hpp"
#include "../../../include/openswmm/engine/openswmm_model.h"

Include dependency graph for openswmm_model_impl.cpp:

Functions
SWMM_ENGINE_API SWMM_Engine	swmm_engine_new (void)
	Create an empty engine in BUILDING state (no .inp file required).
SWMM_ENGINE_API int	swmm_validate_model (SWMM_Engine engine)
	Validate model topology without changing state.
SWMM_ENGINE_API int	swmm_finalize_model (SWMM_Engine engine)
	Finalise a programmatically-built model.
SWMM_ENGINE_API int	swmm_model_write (SWMM_Engine engine, const char *new_inp_path)
	Write the current model state to a SWMM input (.inp) file.
SWMM_ENGINE_API int	swmm_options_get (SWMM_Engine engine, const char *key, char *buf, int buflen)
	Retrieve a standard OPTIONS value as a string.
SWMM_ENGINE_API int	swmm_options_set (SWMM_Engine engine, const char *key, const char *value)
	Set a standard OPTIONS value.
SWMM_ENGINE_API int	swmm_options_get_ext (SWMM_Engine engine, const char *key, char *buf, int buflen)
	Retrieve an extension OPTIONS value (keys unknown to standard SWMM).
SWMM_ENGINE_API int	swmm_options_set_ext (SWMM_Engine engine, const char *key, const char *value)
	Set (or create) an extension OPTIONS value.
SWMM_ENGINE_API int	swmm_get_crs (SWMM_Engine engine, char *buf, int buflen)
	Retrieve the CRS string (e.g., "EPSG:4326" or PROJ string).
SWMM_ENGINE_API int	swmm_userflag_get_bool (SWMM_Engine engine, const char *name, int *value)
	Get the value of a BOOLEAN user flag (schema-level).
SWMM_ENGINE_API int	swmm_userflag_get_int (SWMM_Engine engine, const char *name, int *value)
	Get the value of an INTEGER user flag.
SWMM_ENGINE_API int	swmm_userflag_get_real (SWMM_Engine engine, const char *name, double *value)
	Get the value of a REAL user flag.
SWMM_ENGINE_API int	swmm_userflag_set_bool (SWMM_Engine engine, const char *name, int value)
	Set a BOOLEAN user flag at runtime.
SWMM_ENGINE_API int	swmm_userflag_set_int (SWMM_Engine engine, const char *name, int value)
	Set an INTEGER user flag at runtime.
SWMM_ENGINE_API int	swmm_userflag_set_real (SWMM_Engine engine, const char *name, double value)
	Set a REAL user flag at runtime.

Detailed Description

C API implementation — model building, options, user flags, CRS.

See also

include/openswmm/engine/openswmm_model.h

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

Function Documentation

swmm_engine_new()

SWMM_ENGINE_API SWMM_Engine swmm_engine_new

(

void

)

Create an empty engine in BUILDING state (no .inp file required).

Use this instead of swmm_engine_create() + swmm_engine_open() when building a model entirely through the API. Objects may be added via swmm_node_add(), swmm_link_add(), etc. while in BUILDING state. Call swmm_finalize_model() to transition to INITIALIZED.

Returns

Opaque engine handle in SWMM_STATE_BUILDING, or NULL on failure.

swmm_finalize_model()

SWMM_ENGINE_API int swmm_finalize_model

(

SWMM_Engine

engine

)

Finalise a programmatically-built model.

Runs full topology validation, builds CSR connectivity arrays, allocates all SoA state arrays, and transitions the engine to SWMM_STATE_INITIALIZED. Equivalent to swmm_engine_open() + swmm_engine_initialize() for file-based models.

Parameters

engine

Engine handle (must be in SWMM_STATE_BUILDING).

Returns

SWMM_OK on success; SWMM_ERR_* on failure.

Here is the call graph for this function:

swmm_get_crs()

SWMM_ENGINE_API int swmm_get_crs	(	SWMM_Engine	engine,
		char *	buf,
		int	buflen
	)

Retrieve the CRS string (e.g., "EPSG:4326" or PROJ string).

Parameters

engine	Engine handle.
buf	Caller-allocated buffer.
buflen	Buffer size.

Returns

SWMM_OK; SWMM_ERR_CRS if no CRS was specified in [OPTIONS].

swmm_model_write()

SWMM_ENGINE_API int swmm_model_write	(	SWMM_Engine	engine,
		const char *	new_inp_path
	)

Write the current model state to a SWMM input (.inp) file.

Serializes the entire SimulationContext back to SWMM .inp format. The output is a valid SWMM input file that can be re-opened. Includes all modified objects, user flags, CRS, plugin specs, and extension options.

Parameters

engine	Engine handle (SWMM_STATE_OPENED or later).
new_inp_path	Path where the new .inp file should be written.

Returns

SWMM_OK on success; SWMM_ERR_* on failure.

Here is the call graph for this function:

swmm_options_get()

SWMM_ENGINE_API int swmm_options_get	(	SWMM_Engine	engine,
		const char *	key,
		char *	buf,
		int	buflen
	)

Retrieve a standard OPTIONS value as a string.

Parameters

engine	Engine handle.
key	Option name (e.g., "FLOW_UNITS", "ROUTING_MODEL", "CRS").
buf	Caller-allocated buffer for the value string.
buflen	Size of buf in bytes.

Returns

SWMM_OK if key found; SWMM_ERR_BADPARAM if not a standard key.

swmm_options_get_ext()

SWMM_ENGINE_API int swmm_options_get_ext	(	SWMM_Engine	engine,
		const char *	key,
		char *	buf,
		int	buflen
	)

Retrieve an extension OPTIONS value (keys unknown to standard SWMM).

Parameters

engine	Engine handle.
key	Extension option key.
buf	Caller-allocated buffer.
buflen	Buffer size.

Returns

SWMM_OK or SWMM_ERR_BADPARAM if key not found.

swmm_options_set()

SWMM_ENGINE_API int swmm_options_set	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value
	)

Set a standard OPTIONS value.

Parameters

engine	Engine handle (valid before swmm_engine_start()).
key	Option name.
value	New value string (parsed by the engine).

Returns

SWMM_OK or SWMM_ERR_BADPARAM.

swmm_options_set_ext()

SWMM_ENGINE_API int swmm_options_set_ext	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value
	)

Set (or create) an extension OPTIONS value.

Parameters

engine	Engine handle.
key	Extension option key.
value	New value string.

Returns

SWMM_OK or error code.

swmm_userflag_get_bool()

SWMM_ENGINE_API int swmm_userflag_get_bool	(	SWMM_Engine	engine,
		const char *	name,
		int *	value
	)

Get the value of a BOOLEAN user flag (schema-level).

Parameters

engine	Engine handle.
name	Flag name (as defined in [USER_FLAGS]).
value	[out] 1 = YES/TRUE, 0 = NO/FALSE.

Returns

SWMM_OK; SWMM_ERR_BADPARAM if flag not found or wrong type.

swmm_userflag_get_int()

SWMM_ENGINE_API int swmm_userflag_get_int	(	SWMM_Engine	engine,
		const char *	name,
		int *	value
	)

Get the value of an INTEGER user flag.

Parameters

engine	Engine handle.
name	Flag name.
value	[out] Integer value.

Returns

SWMM_OK; SWMM_ERR_BADPARAM if not found or wrong type.

swmm_userflag_get_real()

SWMM_ENGINE_API int swmm_userflag_get_real	(	SWMM_Engine	engine,
		const char *	name,
		double *	value
	)

Get the value of a REAL user flag.

Parameters

engine	Engine handle.
name	Flag name.
value	[out] Double value.

Returns

SWMM_OK; SWMM_ERR_BADPARAM if not found or wrong type.

swmm_userflag_set_bool()

SWMM_ENGINE_API int swmm_userflag_set_bool	(	SWMM_Engine	engine,
		const char *	name,
		int	value
	)

Set a BOOLEAN user flag at runtime.

swmm_userflag_set_int()

SWMM_ENGINE_API int swmm_userflag_set_int	(	SWMM_Engine	engine,
		const char *	name,
		int	value
	)

Set an INTEGER user flag at runtime.

swmm_userflag_set_real()

SWMM_ENGINE_API int swmm_userflag_set_real	(	SWMM_Engine	engine,
		const char *	name,
		double	value
	)

Set a REAL user flag at runtime.

swmm_validate_model()

SWMM_ENGINE_API int swmm_validate_model

(

SWMM_Engine

engine

)

Validate model topology without changing state.

Checks connectivity (no orphaned links, at least one outfall, no duplicate IDs). Emits warnings via the registered warning callback. Does NOT change state — safe to call multiple times.

Parameters

engine

Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).

Returns

SWMM_OK if validation passes; SWMM_ERR_* on fatal topology error.

Here is the caller graph for this function: