openswmm_engine.h File Reference

OpenSWMM Engine — primary transparent C API (master header). More...

#include "openswmm_callbacks.h"
#include "openswmm_model.h"
#include "openswmm_nodes.h"
#include "openswmm_links.h"
#include "openswmm_subcatchments.h"
#include "openswmm_gages.h"
#include "openswmm_massbalance.h"
#include "openswmm_hotstart.h"
#include "openswmm_spatial.h"
#include "openswmm_pollutants.h"
#include "openswmm_tables.h"
#include "openswmm_inflows.h"
#include "openswmm_controls.h"
#include "openswmm_infrastructure.h"
#include "openswmm_quality.h"
#include "openswmm_statistics.h"
#include "openswmm_output.h"
#include "openswmm_forcing.h"

Include dependency graph for openswmm_engine.h:

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

Go to the source code of this file.

Macros
#define	SWMM_ENGINE_API   __attribute__((visibility("default")))

Typedefs
typedef enum SWMM_ErrorCode	SWMM_ErrorCode
typedef enum SWMM_WarnCode	SWMM_WarnCode
typedef enum SWMM_EngineState	SWMM_EngineState
typedef enum SWMM_ObjectType	SWMM_ObjectType

Enumerations
enum	SWMM_ErrorCode {   SWMM_OK = 0 ,   SWMM_ERR_NOMEM = 1 ,   SWMM_ERR_INPFILE = 2 ,   SWMM_ERR_RPTFILE = 3 ,   SWMM_ERR_OUTFILE = 4 ,   SWMM_ERR_PARSE = 5 ,   SWMM_ERR_LIFECYCLE = 6 ,   SWMM_ERR_BADHANDLE = 7 ,   SWMM_ERR_BADINDEX = 8 ,   SWMM_ERR_BADPARAM = 9 ,   SWMM_ERR_PLUGIN = 10 ,   SWMM_ERR_IO = 11 ,   SWMM_ERR_HOTSTART = 12 ,   SWMM_ERR_CRS = 13 ,   SWMM_ERR_NUMERICAL = 14 ,   SWMM_ERR_INTERNAL = 99 }
enum	SWMM_WarnCode {   SWMM_WARN_NONE = 0 ,   SWMM_WARN_HOTSTART_MISSING = 1 ,   SWMM_WARN_UNKNOWN_SECTION = 2 ,   SWMM_WARN_UNKNOWN_OPTION = 3 ,   SWMM_WARN_DEPRECATED_KW = 4 ,   SWMM_WARN_PLUGIN_INIT = 5 ,   SWMM_WARN_NUMERICAL = 6 ,   SWMM_WARN_STABILITY_LIMIT = 7 }
enum	SWMM_EngineState {   SWMM_STATE_NONE = 0 ,   SWMM_STATE_CREATED = 1 ,   SWMM_STATE_OPENED = 2 ,   SWMM_STATE_INITIALIZED = 3 ,   SWMM_STATE_STARTED = 4 ,   SWMM_STATE_RUNNING = 5 ,   SWMM_STATE_ENDED = 6 ,   SWMM_STATE_CLOSED = 7 ,   SWMM_STATE_BUILDING = 8 }
enum	SWMM_ObjectType {   SWMM_OBJ_GAGE = 0 ,   SWMM_OBJ_SUBCATCH = 1 ,   SWMM_OBJ_NODE = 2 ,   SWMM_OBJ_LINK = 3 ,   SWMM_OBJ_POLLUT = 4 ,   SWMM_OBJ_LANDUSE = 5 ,   SWMM_OBJ_TIMESER = 6 ,   SWMM_OBJ_TABLE = 7 ,   SWMM_OBJ_RDII = 8 ,   SWMM_OBJ_UNITHYD = 9 ,   SWMM_OBJ_SNOWMELT = 10 ,   SWMM_OBJ_SHAPE = 11 ,   SWMM_OBJ_LID = 12 }

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

Detailed Description

OpenSWMM Engine — primary transparent C API (master header).

This is the main public header for the openswmm.engine library (version 6.0.0-alpha.1). It defines:

• Error / warning / state enums
• Engine lifecycle functions (create, open, init, start, step, end, close, destroy)
• Callback registration
• Simulation timing
• Error reporting
• The SWMM_ENGINE_API export macro

Domain-specific APIs are in separate headers:

• openswmm_model.h — model building, validation, serialisation, options, user flags
• openswmm_nodes.h — node creation, properties, state, forcing, bulk
• openswmm_links.h — link creation, properties, cross-sections, state, bulk
• openswmm_subcatchments.h — subcatchment creation, properties, state, bulk
• openswmm_gages.h — rain gage creation, properties, rainfall
• openswmm_massbalance.h — continuity errors and flux totals
• openswmm_hotstart.h — hot start file management
• openswmm_callbacks.h — callback typedefs

Including this header pulls in ALL of the above (master include). To use a single domain, include just that domain header.

Lifecycle

CREATED → OPENED → INITIALIZED → STARTED → [RUNNING] → ENDED → CLOSED

Programmatic model building (no .inp):

[BUILDING] → INITIALIZED → STARTED → [RUNNING] → ENDED → CLOSED

Typical usage:

#include <openswmm/engine/openswmm_engine.h>
 
SWMM_Engine e = swmm_engine_create();
swmm_engine_open(e, "model.inp", "model.rpt", "model.out");
swmm_engine_initialize(e);
swmm_engine_start(e, 1);
 
double elapsed = 0.0;
while (swmm_engine_step(e, &elapsed) == SWMM_OK && elapsed > 0.0) {
    // read/write node depths, link flows, etc.
}
 
swmm_engine_end(e);
swmm_engine_report(e);
swmm_engine_close(e);
swmm_engine_destroy(e);

Note

This API maintains a C89-compatible ABI at the boundary.

Macro Definition Documentation

SWMM_ENGINE_API

#define SWMM_ENGINE_API   __attribute__((visibility("default")))

Typedef Documentation

SWMM_EngineState

typedef enum SWMM_EngineState SWMM_EngineState

SWMM_ErrorCode

typedef enum SWMM_ErrorCode SWMM_ErrorCode

SWMM_ObjectType

typedef enum SWMM_ObjectType SWMM_ObjectType

SWMM_WarnCode

typedef enum SWMM_WarnCode SWMM_WarnCode

Enumeration Type Documentation

SWMM_EngineState

enum SWMM_EngineState

Enumerator
SWMM_STATE_NONE
SWMM_STATE_CREATED
SWMM_STATE_OPENED
SWMM_STATE_INITIALIZED
SWMM_STATE_STARTED
SWMM_STATE_RUNNING
SWMM_STATE_ENDED
SWMM_STATE_CLOSED
SWMM_STATE_BUILDING	Programmatic model construction in progress

SWMM_ErrorCode

enum SWMM_ErrorCode

Enumerator
SWMM_OK
SWMM_ERR_NOMEM
SWMM_ERR_INPFILE
SWMM_ERR_RPTFILE
SWMM_ERR_OUTFILE
SWMM_ERR_PARSE
SWMM_ERR_LIFECYCLE
SWMM_ERR_BADHANDLE
SWMM_ERR_BADINDEX
SWMM_ERR_BADPARAM
SWMM_ERR_PLUGIN
SWMM_ERR_IO
SWMM_ERR_HOTSTART
SWMM_ERR_CRS
SWMM_ERR_NUMERICAL
SWMM_ERR_INTERNAL

SWMM_ObjectType

enum SWMM_ObjectType

Enumerator
SWMM_OBJ_GAGE
SWMM_OBJ_SUBCATCH
SWMM_OBJ_NODE
SWMM_OBJ_LINK
SWMM_OBJ_POLLUT
SWMM_OBJ_LANDUSE
SWMM_OBJ_TIMESER
SWMM_OBJ_TABLE
SWMM_OBJ_RDII
SWMM_OBJ_UNITHYD
SWMM_OBJ_SNOWMELT
SWMM_OBJ_SHAPE
SWMM_OBJ_LID

SWMM_WarnCode

enum SWMM_WarnCode

Enumerator
SWMM_WARN_NONE
SWMM_WARN_HOTSTART_MISSING
SWMM_WARN_UNKNOWN_SECTION
SWMM_WARN_UNKNOWN_OPTION
SWMM_WARN_DEPRECATED_KW
SWMM_WARN_PLUGIN_INIT
SWMM_WARN_NUMERICAL
SWMM_WARN_STABILITY_LIMIT

Function Documentation

swmm_engine_close()

SWMM_ENGINE_API int swmm_engine_close

(

SWMM_Engine

engine

)

Close all files → SWMM_STATE_CLOSED.

swmm_engine_create()

SWMM_ENGINE_API SWMM_Engine swmm_engine_create

(

void

)

Create a new engine instance (SWMM_STATE_CREATED).

swmm_engine_destroy()

SWMM_ENGINE_API void swmm_engine_destroy

(

SWMM_Engine

engine

)

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

swmm_engine_end()

SWMM_ENGINE_API int swmm_engine_end

(

SWMM_Engine

engine

)

End the simulation → SWMM_STATE_ENDED.

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.

swmm_engine_open()

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

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

swmm_engine_report()

SWMM_ENGINE_API int swmm_engine_report

(

SWMM_Engine

engine

)

Write summary report (SWMM_STATE_ENDED).

swmm_engine_start()

SWMM_ENGINE_API int swmm_engine_start	(	SWMM_Engine	engine,
		int	save_results
	)

Start the simulation → SWMM_STATE_STARTED.

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.

swmm_error_message()

SWMM_ENGINE_API const char * swmm_error_message

(

int

code

)

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

SWMM_ENGINE_API int swmm_get_last_error

(

SWMM_Engine

engine

)

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

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

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
	)