openswmm_engine_impl.cpp File Reference

C API implementation — engine lifecycle, callbacks, errors, timing. More...

#include "openswmm_api_common.hpp"

Include dependency graph for openswmm_engine_impl.cpp:

Functions
SWMM_ENGINE_API SWMM_Engine	swmm_engine_create (void)
	Create a new engine instance (SWMM_STATE_CREATED).
SWMM_ENGINE_API int	swmm_engine_open (SWMM_Engine engine, const char *inp, const char *rpt, const char *out, const char *input_plugin_lib)
	Open and parse a SWMM input file; load plugins → SWMM_STATE_OPENED.
SWMM_ENGINE_API int	swmm_engine_initialize (SWMM_Engine engine)
	Initialize the simulation → SWMM_STATE_INITIALIZED.
SWMM_ENGINE_API int	swmm_engine_start (SWMM_Engine engine, int save_results)
	Start the simulation → SWMM_STATE_STARTED.
SWMM_ENGINE_API int	swmm_engine_step (SWMM_Engine engine, double *elapsed_time)
	Advance one explicit timestep. elapsed_time==0 when done.
SWMM_ENGINE_API int	swmm_engine_stride (SWMM_Engine engine, int n_steps, double *elapsed_time)
	Advance up to n_steps routing steps in one call (Gap #50 — swmm_stride equivalent).
SWMM_ENGINE_API int	swmm_engine_end (SWMM_Engine engine)
	End the simulation → SWMM_STATE_ENDED.
SWMM_ENGINE_API int	swmm_engine_report (SWMM_Engine engine)
	Write summary report (SWMM_STATE_ENDED).
SWMM_ENGINE_API int	swmm_engine_close (SWMM_Engine engine)
	Close all files → SWMM_STATE_CLOSED.
SWMM_ENGINE_API void	swmm_engine_destroy (SWMM_Engine engine)
	Destroy the engine handle (any state, NULL safe).
SWMM_ENGINE_API int	swmm_engine_get_state (SWMM_Engine engine, int *state)
	Query the current engine lifecycle state.
SWMM_ENGINE_API int	swmm_engine_run_with_callback (const char *inp, const char *rpt, const char *out, const char *input_plugin_lib, SWMM_ProgressCallback callback, void *user_data)
	Run a complete simulation with a progress callback.
SWMM_ENGINE_API int	swmm_engine_run (const char *inp, const char *rpt, const char *out, const char *input_plugin_lib)
	Run a complete simulation to completion.
SWMM_ENGINE_API int	swmm_set_progress_callback (SWMM_Engine engine, SWMM_ProgressCallback callback, void *user_data)
SWMM_ENGINE_API int	swmm_set_warning_callback (SWMM_Engine engine, SWMM_WarningCallback callback, void *user_data)
SWMM_ENGINE_API int	swmm_set_step_begin_callback (SWMM_Engine engine, SWMM_StepBeginCallback callback, void *user_data)
SWMM_ENGINE_API int	swmm_set_step_end_callback (SWMM_Engine engine, SWMM_StepEndCallback callback, void *user_data)
SWMM_ENGINE_API int	swmm_get_last_error (SWMM_Engine engine)
SWMM_ENGINE_API const char *	swmm_get_last_error_msg (SWMM_Engine engine)
SWMM_ENGINE_API const char *	swmm_error_message (int code)
SWMM_ENGINE_API int	swmm_get_start_time (SWMM_Engine engine, double *start)
SWMM_ENGINE_API int	swmm_get_end_time (SWMM_Engine engine, double *end)
SWMM_ENGINE_API int	swmm_get_current_time (SWMM_Engine engine, double *current)
SWMM_ENGINE_API int	swmm_get_routing_step (SWMM_Engine engine, double *dt)
SWMM_ENGINE_API int	swmm_is_between_events (SWMM_Engine engine, int *is_between)
	Check if simulation is currently between routing events.
SWMM_ENGINE_API int	swmm_get_event_count (SWMM_Engine engine, int *count)
	Get number of routing events defined.
SWMM_ENGINE_API int	swmm_events_count (SWMM_Engine engine, int *count)
	Number of [EVENTS] entries. Alias of swmm_get_event_count.
SWMM_ENGINE_API int	swmm_events_get (SWMM_Engine engine, int idx, double *start, double *end)
	Get the start/end DateTime of the idx-th event.
SWMM_ENGINE_API int	swmm_events_set (SWMM_Engine engine, int idx, double start, double end)
	Overwrite the idx-th event's window.
SWMM_ENGINE_API int	swmm_events_add (SWMM_Engine engine, double start, double end, int *out_idx)
	Append a new event window.
SWMM_ENGINE_API int	swmm_events_remove (SWMM_Engine engine, int idx)
	Remove the idx-th event. Trailing entries shift down by one.
SWMM_ENGINE_API int	swmm_events_clear (SWMM_Engine engine)
	Remove all events.
SWMM_ENGINE_API int	swmm_get_steady_state_skip (SWMM_Engine engine, int *enabled)
	Get/set steady-state skip flag.
SWMM_ENGINE_API int	swmm_set_steady_state_skip (SWMM_Engine engine, int enabled)
SWMM_ENGINE_API int	swmm_runoff_iface_open_write (SWMM_Engine engine, const char *path)
	Open the runoff interface file for writing (SAVE mode).
SWMM_ENGINE_API int	swmm_runoff_iface_open_read (SWMM_Engine engine, const char *path)
	Open the runoff interface file for reading (USE mode).
SWMM_ENGINE_API int	swmm_runoff_iface_save_step (SWMM_Engine engine, double dt)
	Manually emit one runoff substep record to the open SAVE file.
SWMM_ENGINE_API int	swmm_runoff_iface_read_step (SWMM_Engine engine, int *has_data)
	Read one runoff substep record from the open USE file into the current subcatchment state.
SWMM_ENGINE_API int	swmm_runoff_iface_close (SWMM_Engine engine)
	Close the runoff interface file.

Detailed Description

C API implementation — engine lifecycle, callbacks, errors, timing.

See also

include/openswmm/engine/openswmm_engine.h

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

SWMM_ENGINE_API int swmm_engine_close

(

SWMM_Engine

engine

)

Close all files → SWMM_STATE_CLOSED.

Here is the caller graph for this function:

swmm_engine_create()

SWMM_ENGINE_API SWMM_Engine swmm_engine_create

(

void

)

Create a new engine instance (SWMM_STATE_CREATED).

Here is the caller graph for this function:

swmm_engine_destroy()

SWMM_ENGINE_API void swmm_engine_destroy

(

SWMM_Engine

engine

)

Destroy the engine handle (any state, NULL safe).

Here is the caller graph for this function:

swmm_engine_end()

SWMM_ENGINE_API int swmm_engine_end

(

SWMM_Engine

engine

)

End the simulation → SWMM_STATE_ENDED.

Here is the caller graph for this function:

swmm_engine_get_state()

SWMM_ENGINE_API int swmm_engine_get_state	(	SWMM_Engine	engine,
		int *	state
	)

Query the current engine lifecycle state.

swmm_engine_initialize()

SWMM_ENGINE_API int swmm_engine_initialize

(

SWMM_Engine

engine

)

Initialize the simulation → SWMM_STATE_INITIALIZED.

Here is the caller graph for this function:

swmm_engine_open()

SWMM_ENGINE_API int swmm_engine_open	(	SWMM_Engine	engine,
		const char *	inp,
		const char *	rpt,
		const char *	out,
		const char *	input_plugin_lib
	)

Open and parse a SWMM input file; load plugins → SWMM_STATE_OPENED.

Parameters

engine	Engine handle.
inp	Path to the input file.
rpt	Path to the report file, or NULL.
out	Path to the binary output file, or NULL.
input_plugin_lib	Path to a shared library (.so/.dylib/.dll) that provides an IInputPlugin via openswmm_plugin_info(). Pass NULL to use the built-in .inp reader.

Here is the caller graph for this function:

swmm_engine_report()

SWMM_ENGINE_API int swmm_engine_report

(

SWMM_Engine

engine

)

Write summary report (SWMM_STATE_ENDED).

Here is the caller graph for this function:

swmm_engine_run()

SWMM_ENGINE_API int swmm_engine_run	(	const char *	inp,
		const char *	rpt,
		const char *	out,
		const char *	input_plugin_lib
	)

Run a complete simulation to completion.

Creates an engine, then chains: open → initialize → start → step loop → end → report → close → destroy. Mirrors the legacy swmm_run() function.

Parameters

inp	Path to SWMM input file (.inp).
rpt	Path to report file (.rpt), or NULL to skip reporting.
out	Path to binary output file (.out), or NULL.
input_plugin_lib	Path to input plugin library, or NULL for built-in .inp reader.

Returns

SWMM_OK (0) on success, or an error code.

Here is the call graph for this function:

swmm_engine_run_with_callback()

SWMM_ENGINE_API int swmm_engine_run_with_callback	(	const char *	inp,
		const char *	rpt,
		const char *	out,
		const char *	input_plugin_lib,
		SWMM_ProgressCallback	callback,
		void *	user_data
	)

Run a complete simulation with a progress callback.

Same as swmm_engine_run() but registers a progress callback before starting the simulation loop.

Parameters

inp	Path to SWMM input file (.inp).
rpt	Path to report file (.rpt), or NULL to skip reporting.
out	Path to binary output file (.out), or NULL.
input_plugin_lib	Path to input plugin library, or NULL for built-in .inp reader.
callback	Progress callback (may be NULL).
user_data	Opaque pointer passed through to the callback.

Returns

SWMM_OK (0) on success, or an error code.

Here is the call graph for this function:

Here is the caller graph for this function:

swmm_engine_start()

SWMM_ENGINE_API int swmm_engine_start	(	SWMM_Engine	engine,
		int	save_results
	)

Start the simulation → SWMM_STATE_STARTED.

Here is the caller graph for this function:

swmm_engine_step()

SWMM_ENGINE_API int swmm_engine_step	(	SWMM_Engine	engine,
		double *	elapsed_time
	)

Advance one explicit timestep. elapsed_time==0 when done.

Here is the caller graph for this function:

swmm_engine_stride()

SWMM_ENGINE_API int swmm_engine_stride	(	SWMM_Engine	engine,
		int	n_steps,
		double *	elapsed_time
	)

Advance up to n_steps routing steps in one call (Gap #50 — swmm_stride equivalent).

Calls step() n_steps times and stops early on error or when the simulation ends (elapsed_time == 0). elapsed_time receives the last non-zero elapsed value, or 0.0 when the simulation has ended. Passing n_steps <= 0 is a no-op (returns SWMM_OK).

Parameters

engine	Engine handle.
n_steps	Maximum number of routing steps to advance.
elapsed_time	Receives elapsed time (decimal days) after the last step.

Returns

SWMM_OK on success; first non-OK error code encountered otherwise.

swmm_error_message()

SWMM_ENGINE_API const char * swmm_error_message

(

int

code

)

swmm_events_add()

SWMM_ENGINE_API int swmm_events_add	(	SWMM_Engine	engine,
		double	start,
		double	end,
		int *	out_idx
	)

Append a new event window.

Parameters

out_idx

Receives the new event's index (optional, may be NULL).

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM if start >= end.

swmm_events_clear()

SWMM_ENGINE_API int swmm_events_clear

(

SWMM_Engine

engine

)

Remove all events.

swmm_events_count()

SWMM_ENGINE_API int swmm_events_count	(	SWMM_Engine	engine,
		int *	count
	)

Number of [EVENTS] entries. Alias of swmm_get_event_count.

Here is the call graph for this function:

swmm_events_get()

SWMM_ENGINE_API int swmm_events_get	(	SWMM_Engine	engine,
		int	idx,
		double *	start,
		double *	end
	)

Get the start/end DateTime of the idx-th event.

Returns

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

swmm_events_remove()

SWMM_ENGINE_API int swmm_events_remove	(	SWMM_Engine	engine,
		int	idx
	)

Remove the idx-th event. Trailing entries shift down by one.

Returns

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

swmm_events_set()

SWMM_ENGINE_API int swmm_events_set	(	SWMM_Engine	engine,
		int	idx,
		double	start,
		double	end
	)

Overwrite the idx-th event's window.

Returns

SWMM_OK on success; SWMM_ERR_BADINDEX if idx out of range; SWMM_ERR_BADPARAM if start >= end.

swmm_get_current_time()

SWMM_ENGINE_API int swmm_get_current_time	(	SWMM_Engine	engine,
		double *	current
	)

swmm_get_end_time()

SWMM_ENGINE_API int swmm_get_end_time	(	SWMM_Engine	engine,
		double *	end
	)

swmm_get_event_count()

SWMM_ENGINE_API int swmm_get_event_count	(	SWMM_Engine	engine,
		int *	count
	)

Get number of routing events defined.

Note

Synonymous with swmm_events_count (Slice CW).

Here is the caller graph for this function:

swmm_get_last_error()

SWMM_ENGINE_API int swmm_get_last_error

(

SWMM_Engine

engine

)

Here is the caller graph for this function:

swmm_get_last_error_msg()

SWMM_ENGINE_API const char * swmm_get_last_error_msg

(

SWMM_Engine

engine

)

swmm_get_routing_step()

SWMM_ENGINE_API int swmm_get_routing_step	(	SWMM_Engine	engine,
		double *	dt
	)

swmm_get_start_time()

SWMM_ENGINE_API int swmm_get_start_time	(	SWMM_Engine	engine,
		double *	start
	)

swmm_get_steady_state_skip()

SWMM_ENGINE_API int swmm_get_steady_state_skip	(	SWMM_Engine	engine,
		int *	enabled
	)

Get/set steady-state skip flag.

swmm_is_between_events()

SWMM_ENGINE_API int swmm_is_between_events	(	SWMM_Engine	engine,
		int *	is_between
	)

Check if simulation is currently between routing events.

swmm_runoff_iface_close()

SWMM_ENGINE_API int swmm_runoff_iface_close

(

SWMM_Engine

engine

)

Close the runoff interface file.

Safe to call multiple times; safe to call when no file was opened. Also called automatically as part of swmm_engine_close.

swmm_runoff_iface_open_read()

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

Open the runoff interface file for reading (USE mode).

Parameters

engine	Engine handle.
path	Path to an existing runoff interface file.

Returns

SWMM_OK on success; non-zero on file-open failure or header mismatch (subcatchment count, pollutant count, or flow units differ from the current model).

swmm_runoff_iface_open_write()

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

Open the runoff interface file for writing (SAVE mode).

Parameters

engine	Engine handle (any state).
path	Output file path. Existing file is truncated.

Returns

SWMM_OK on success. Non-zero error codes include SWMM_ERR_BADHANDLE (invalid engine), SWMM_ERR_BADPARAM (null path), and a non-zero file-I/O error code when the file could not be opened or a runoff file is already open.

swmm_runoff_iface_read_step()

SWMM_ENGINE_API int swmm_runoff_iface_read_step	(	SWMM_Engine	engine,
		int *	has_data
	)

Read one runoff substep record from the open USE file into the current subcatchment state.

Parameters

	engine	Engine handle.
[out]	has_data	Set to 1 when a record was successfully read, 0 on EOF. May be NULL.

Returns

SWMM_OK in either case (use has_data to tell EOF apart from a successful read). Returns SWMM_ERR_BADHANDLE on null engine; SWMM_ERR_BADPARAM if no USE-mode file is open.

swmm_runoff_iface_save_step()

SWMM_ENGINE_API int swmm_runoff_iface_save_step	(	SWMM_Engine	engine,
		double	dt
	)

Manually emit one runoff substep record to the open SAVE file.

Normally the engine emits records automatically inside stepRunoff(). This entry point is exposed so plugin authors and tests can force a snapshot at well-defined times; it is a no-op when no file is open or the file is in USE mode.

Parameters

engine	Engine handle.
dt	Substep duration (seconds) to record in the file for this snapshot.

swmm_set_progress_callback()

SWMM_ENGINE_API int swmm_set_progress_callback	(	SWMM_Engine	engine,
		SWMM_ProgressCallback	callback,
		void *	user_data
	)

Here is the caller graph for this function:

swmm_set_steady_state_skip()

SWMM_ENGINE_API int swmm_set_steady_state_skip	(	SWMM_Engine	engine,
		int	enabled
	)

swmm_set_step_begin_callback()

SWMM_ENGINE_API int swmm_set_step_begin_callback	(	SWMM_Engine	engine,
		SWMM_StepBeginCallback	callback,
		void *	user_data
	)

swmm_set_step_end_callback()

SWMM_ENGINE_API int swmm_set_step_end_callback	(	SWMM_Engine	engine,
		SWMM_StepEndCallback	callback,
		void *	user_data
	)

swmm_set_warning_callback()

SWMM_ENGINE_API int swmm_set_warning_callback	(	SWMM_Engine	engine,
		SWMM_WarningCallback	callback,
		void *	user_data
	)