openswmm_model.h File Reference

OpenSWMM Engine — Model building and options C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_model.h:

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

Go to the source code of this file.

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_model_write_with_plugin (SWMM_Engine engine, const char *new_path, const char *output_plugin_id)
	Write the current model state via a named writer plugin.
SWMM_ENGINE_API int	swmm_plugins_count (SWMM_Engine engine, int *count)
	Number of [PLUGINS] entries currently registered on the engine.
SWMM_ENGINE_API int	swmm_plugin_get (SWMM_Engine engine, int idx, char *path_buf, int path_buf_sz, char *args_buf, int args_buf_sz)
	Read one [PLUGINS] row by index.
SWMM_ENGINE_API int	swmm_plugin_set (SWMM_Engine engine, const char *path_or_id, const char *args)
	Add or replace a [PLUGINS] row keyed by path_or_id.
SWMM_ENGINE_API int	swmm_plugin_remove (SWMM_Engine engine, const char *path_or_id)
	Remove the [PLUGINS] row matching path_or_id.
SWMM_ENGINE_API int	swmm_files_get (SWMM_Engine engine, const char *key, char *buf, int buflen)
	Read one [FILES] field by key.
SWMM_ENGINE_API int	swmm_files_set (SWMM_Engine engine, const char *key, const char *value)
	Write one [FILES] field by key.
SWMM_ENGINE_API int	swmm_title_get_count (SWMM_Engine engine, int *count)
	Get the number of title/note lines in the [TITLE] section.
SWMM_ENGINE_API int	swmm_title_get_line (SWMM_Engine engine, int index, char *buf, int buflen)
	Get a specific title/note line by index.
SWMM_ENGINE_API int	swmm_title_add_line (SWMM_Engine engine, const char *line)
	Add a new line to the end of the [TITLE] section.
SWMM_ENGINE_API int	swmm_title_set (SWMM_Engine engine, const char *text)
	Replace all title/note lines with a single block of text.
SWMM_ENGINE_API int	swmm_title_clear (SWMM_Engine engine)
	Remove all lines from the [TITLE] section.
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_options_get_start_date (SWMM_Engine engine, double *value)
	Retrieve the simulation start date/time as an OADate.
SWMM_ENGINE_API int	swmm_options_set_start_date (SWMM_Engine engine, double value)
	Set the simulation start date/time from an OADate.
SWMM_ENGINE_API int	swmm_options_get_end_date (SWMM_Engine engine, double *value)
	Retrieve the simulation end date/time as an OADate.
SWMM_ENGINE_API int	swmm_options_set_end_date (SWMM_Engine engine, double value)
	Set the simulation end date/time from an OADate.
SWMM_ENGINE_API int	swmm_options_get_report_start (SWMM_Engine engine, double *value)
	Retrieve the report start date/time as an OADate.
SWMM_ENGINE_API int	swmm_options_set_report_start (SWMM_Engine engine, double value)
	Set the report start date/time from an OADate.
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

OpenSWMM Engine — Model building and options C API.

Covers:

• Programmatic model construction (swmm_engine_new, object add)
• Model finalisation and validation
• Serialisation to .inp file
• Standard and extension OPTIONS
• CRS access
• User flags

Note

Include this header independently or get it via openswmm_engine.h.

See also

openswmm_engine.h — lifecycle and error codes

Author

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

Copyright

Copyright (c) 2026 Caleb Buahin. 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_files_get()

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

Read one [FILES] field by key.

Parameters

engine	Engine handle.
key	Field key (see header comment for recognised values).
buf	[out] UTF-8 result; NUL-terminated and truncated at buflen - 1 if too small.
buflen	Size of buf in bytes (including NUL).

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM when key is NULL, unknown, or buf args are invalid.

swmm_files_set()

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

Write one [FILES] field by key.

Pass an empty value to clear a path slot. Pass an empty value to a *_MODE key to clear the mode (slot becomes inactive). The engine re-emits [FILES] on the next swmm_model_write* call.

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM when key is NULL, unknown, or value is NULL.

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_model_write_with_plugin()

SWMM_ENGINE_API int swmm_model_write_with_plugin	(	SWMM_Engine	engine,
		const char *	new_path,
		const char *	output_plugin_id
	)

Write the current model state via a named writer plugin.

Routes the in-memory SimulationContext through the IInputPlugin::write() method of the plugin matching output_plugin_id. Lets a host (e.g., the GUI's Save As dialog) pick a non-.inp container — GeoPackage, HDF5, GeoJSON, …— at write time without touching the rest of the engine API.

Pass NULL or an empty string for output_plugin_id to use the built-in .inp writer (equivalent to swmm_model_write).

output_plugin_id is resolved via the engine's PluginFactory::find_component() — accepts a plugin id (e.g., "org.hydrocouple.openswmm.geopackage"), an id:version pair, or a shared-library path. The resolved plugin must advertise input capability (IPluginComponentInfo::has_input() returns true), since model write is delegated through IInputPlugin::write().

The chosen plugin is instantiated transiently for the call: create → initialize(args=empty) → write → finalize → delete. The engine's primary input plugin is not disturbed so the model can be re-saved later with a different writer.

Parameters

engine	Engine handle (SWMM_STATE_OPENED or later).
new_path	Path where the new model file should be written.
output_plugin_id	Writer plugin id, version pair, or library path; or NULL/empty for default .inp writer.

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM when new_path is NULL or the plugin id does not resolve; SWMM_ERR_PLUGIN when the resolved plugin has no input capability or its initialize/write/finalize fails.

See also

swmm_model_write — built-in .inp writer (this function with NULL plugin id is functionally equivalent).

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", "LINK_OFFSETS", "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.

Encoding is symmetric with swmm_options_set: the returned string is one that swmm_options_set accepts for the same key. Enum keys return their canonical token (e.g. "CMS", "DYNWAVE", "ELEVATION"), never the underlying int.

Here is the call graph for this function:

swmm_options_get_end_date()

SWMM_ENGINE_API int swmm_options_get_end_date	(	SWMM_Engine	engine,
		double *	value
	)

Retrieve the simulation end date/time as an OADate.

Parameters

engine	Engine handle.
value	[out] OADate (decimal days since 1899-12-30).

Returns

SWMM_OK; SWMM_ERR_BADPARAM on null engine/value.

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_get_report_start()

SWMM_ENGINE_API int swmm_options_get_report_start	(	SWMM_Engine	engine,
		double *	value
	)

Retrieve the report start date/time as an OADate.

Parameters

engine	Engine handle.
value	[out] OADate (decimal days since 1899-12-30).

Returns

SWMM_OK; SWMM_ERR_BADPARAM on null engine/value.

swmm_options_get_start_date()

SWMM_ENGINE_API int swmm_options_get_start_date	(	SWMM_Engine	engine,
		double *	value
	)

Retrieve the simulation start date/time as an OADate.

Parameters

engine	Engine handle.
value	[out] OADate (decimal days since 1899-12-30).

Returns

SWMM_OK; SWMM_ERR_BADPARAM on null engine/value.

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.

Here is the call graph for this function:

swmm_options_set_end_date()

SWMM_ENGINE_API int swmm_options_set_end_date	(	SWMM_Engine	engine,
		double	value
	)

Set the simulation end date/time from an OADate.

Parameters

engine	Engine handle.
value	OADate (decimal days since 1899-12-30).

Returns

SWMM_OK; SWMM_ERR_BADPARAM on null engine.

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_options_set_report_start()

SWMM_ENGINE_API int swmm_options_set_report_start	(	SWMM_Engine	engine,
		double	value
	)

Set the report start date/time from an OADate.

Parameters

engine	Engine handle.
value	OADate (decimal days since 1899-12-30).

Returns

SWMM_OK; SWMM_ERR_BADPARAM on null engine.

swmm_options_set_start_date()

SWMM_ENGINE_API int swmm_options_set_start_date	(	SWMM_Engine	engine,
		double	value
	)

Set the simulation start date/time from an OADate.

Parameters

engine	Engine handle.
value	OADate (decimal days since 1899-12-30).

Returns

SWMM_OK; SWMM_ERR_BADPARAM on null engine.

swmm_plugin_get()

SWMM_ENGINE_API int swmm_plugin_get	(	SWMM_Engine	engine,
		int	idx,
		char *	path_buf,
		int	path_buf_sz,
		char *	args_buf,
		int	args_buf_sz
	)

Read one [PLUGINS] row by index.

Either output buffer may be NULL (caller doesn't want that field). When non-NULL, the buffer is NUL-terminated and truncated at path_buf_sz - 1 / args_buf_sz - 1 if too small (no error returned). The args string is reconstructed by joining the row's init_args vector with single spaces.

Parameters

engine	Engine handle.
idx	Index in [0, count).
path_buf	[out] UTF-8 plugin path / id; may be NULL.
path_buf_sz	Size of path_buf in bytes (incl. NUL).
args_buf	[out] UTF-8 space-joined args; may be NULL.
args_buf_sz	Size of args_buf in bytes (incl. NUL).

Returns

SWMM_OK on success; SWMM_ERR_BADINDEX when idx is out of range.

swmm_plugin_remove()

SWMM_ENGINE_API int swmm_plugin_remove	(	SWMM_Engine	engine,
		const char *	path_or_id
	)

Remove the [PLUGINS] row matching path_or_id.

Idempotent: returns SWMM_OK even when no row matches.

Parameters

engine	Engine handle.
path_or_id	Library path, plugin id, or id:version string.

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM when path_or_id is NULL.

swmm_plugin_set()

SWMM_ENGINE_API int swmm_plugin_set	(	SWMM_Engine	engine,
		const char *	path_or_id,
		const char *	args
	)

Add or replace a [PLUGINS] row keyed by path_or_id.

If a row with the same path_or_id exists, its args are replaced. Otherwise a new row is appended. The engine re-serialises the [PLUGINS] section on the next swmm_model_write* call.

Parameters

engine	Engine handle.
path_or_id	Library path, plugin id, or id:version string.
args	Space-separated argument tokens; may be NULL or empty for "no arguments".

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM when path_or_id is NULL or empty.

swmm_plugins_count()

SWMM_ENGINE_API int swmm_plugins_count	(	SWMM_Engine	engine,
		int *	count
	)

Number of [PLUGINS] entries currently registered on the engine.

Parameters

count

[out] Number of entries. Always set on SWMM_OK return.

swmm_title_add_line()

SWMM_ENGINE_API int swmm_title_add_line	(	SWMM_Engine	engine,
		const char *	line
	)

Add a new line to the end of the [TITLE] section.

Parameters

engine	Engine handle.
line	Null-terminated string to append.

Returns

SWMM_OK on success.

swmm_title_clear()

SWMM_ENGINE_API int swmm_title_clear

(

SWMM_Engine

engine

)

Remove all lines from the [TITLE] section.

Parameters

engine

Engine handle.

Returns

SWMM_OK on success.

swmm_title_get_count()

SWMM_ENGINE_API int swmm_title_get_count	(	SWMM_Engine	engine,
		int *	count
	)

Get the number of title/note lines in the [TITLE] section.

Parameters

engine	Engine handle.
count	[out] Number of title lines.

Returns

SWMM_OK on success.

swmm_title_get_line()

SWMM_ENGINE_API int swmm_title_get_line	(	SWMM_Engine	engine,
		int	index,
		char *	buf,
		int	buflen
	)

Get a specific title/note line by index.

Parameters

engine	Engine handle.
index	Zero-based line index.
buf	Caller-allocated buffer for the line text.
buflen	Size of buf in bytes.

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM if index out of range.

swmm_title_set()

SWMM_ENGINE_API int swmm_title_set	(	SWMM_Engine	engine,
		const char *	text
	)

Replace all title/note lines with a single block of text.

The text is split on newline characters ('\n') to form individual title lines. Any existing title lines are cleared.

Parameters

engine	Engine handle.
text	Null-terminated text (may contain '\n' separators).

Returns

SWMM_OK on success.

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: