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

#include "openswmm_callbacks.h"
#include "openswmm_datetime.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_initial_quality.h"
#include "openswmm_reactions.h"
#include "openswmm_process_components.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_forcing.h"
#include "openswmm_climate.h"
#include "openswmm_edit.h"
#include "openswmm_checkpoint.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.

Classes
struct	SWMM_ThreadInfo

struct	SWMM_TransportCell

struct	SWMM_TransportMatrix

struct	SWMM_TransportDraft

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

#define	SWMM_TRANSPORT_DOMAIN_RUNOFF 0

#define	SWMM_TRANSPORT_DOMAIN_GROUNDWATER 1

#define	SWMM_TRANSPORT_DOMAIN_NETWORK_1D 2

#define	SWMM_TRANSPORT_DOMAIN_SURFACE_2D 3

#define	SWMM_TRANSPORT_DOMAIN_COUNT 4

#define	SWMM_TRANSPORT_CLASS_POLLUTANTS 0

#define	SWMM_TRANSPORT_CLASS_MSX 1

#define	SWMM_TRANSPORT_CLASS_AGE 2

#define	SWMM_TRANSPORT_CLASS_TEMPERATURE 3

#define	SWMM_TRANSPORT_CLASS_COUNT 4

#define	SWMM_TRANSPORT_ENABLED 0

#define	SWMM_TRANSPORT_DISABLED_BY_USER 1

#define	SWMM_TRANSPORT_UNAVAILABLE 2

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

typedef struct SWMM_TransportCell	SWMM_TransportCell

typedef struct SWMM_TransportMatrix	SWMM_TransportMatrix

typedef struct SWMM_TransportDraft	SWMM_TransportDraft

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_DEPENDENCY = 15 , SWMM_ERR_CANCELLED = 16 , SWMM_ERR_BUFSIZE = 17 , 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)
	Allocate an independent engine in SWMM_STATE_CREATED.

SWMM_ENGINE_API const char *	swmm_engine_abi_tag (void)
	Identify the public C ABI compiled into the running engine image.

SWMM_ENGINE_API int	swmm_engine_open (SWMM_Engine engine, const char inp, const char rpt, const char out, const char input_plugin_lib)
	Load a model and prepare its plugin configuration in SWMM_STATE_OPENED.

SWMM_ENGINE_API int	swmm_engine_open_metadata (SWMM_Engine engine, const char *inp)
	Open a model for configured metadata without preparing simulation plugins.

SWMM_ENGINE_API int	swmm_engine_initialize (SWMM_Engine engine)
	Allocate simulation modules and initial state, entering SWMM_STATE_INITIALIZED.

SWMM_ENGINE_API int	swmm_engine_start (SWMM_Engine engine, int save_results)
	Start an initialized simulation, entering SWMM_STATE_RUNNING.

SWMM_ENGINE_API int	swmm_engine_advance_to (SWMM_Engine engine, double target_seconds, double *actual_seconds)
	Advance to a specified elapsed-second exchange boundary without overshooting.

SWMM_ENGINE_API int	swmm_engine_get_elapsed_seconds (SWMM_Engine engine, double *seconds)
	Read the routing elapsed clock, including during step callbacks.

SWMM_ENGINE_API int	swmm_engine_step (SWMM_Engine engine, double *elapsed_time)
	Advance one physical simulation step and report elapsed days.

SWMM_ENGINE_API int	swmm_engine_stride (SWMM_Engine engine, int n_steps, double *elapsed_time)
	Perform up to a requested number of physical steps synchronously.

SWMM_ENGINE_API int	swmm_engine_end (SWMM_Engine engine)
	Finalize a running or completed simulation and enter SWMM_STATE_ENDED.

SWMM_ENGINE_API int	swmm_engine_report (SWMM_Engine engine)
	Write final model/simulation reports after ending the simulation.

SWMM_ENGINE_API int	swmm_engine_close (SWMM_Engine engine)
	Stop IO and release active model files, plugins and checkpoint attachments.

SWMM_ENGINE_API void	swmm_engine_destroy (SWMM_Engine engine)
	Delete an engine and all resources it owns.

SWMM_ENGINE_API int	swmm_engine_get_state (SWMM_Engine engine, int *state)
	Read the public lifecycle state of a live engine.

SWMM_ENGINE_API int	swmm_engine_run (const char inp, const char rpt, const char out, const char input_plugin_lib)
	Create an engine, run the full lifecycle synchronously, and destroy it.

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 the full synchronous lifecycle with a borrowed progress callback.

SWMM_ENGINE_API int	swmm_set_progress_callback (SWMM_Engine engine, SWMM_ProgressCallback callback, void *user_data)
	Register, replace or disable pre-step progress.

SWMM_ENGINE_API int	swmm_set_warning_callback (SWMM_Engine engine, SWMM_WarningCallback callback, void *user_data)
	Register, replace or disable diagnostics.

SWMM_ENGINE_API int	swmm_set_step_begin_callback (SWMM_Engine engine, SWMM_StepBeginCallback callback, void *user_data)
	Register, replace or disable pre-physics step notifications.

SWMM_ENGINE_API int	swmm_set_step_end_callback (SWMM_Engine engine, SWMM_StepEndCallback callback, void *user_data)
	Register, replace or disable post-physics step notifications.

SWMM_ENGINE_API int	swmm_get_last_error (SWMM_Engine engine)
	Read the stored simulation error code without clearing it.

SWMM_ENGINE_API const char *	swmm_get_last_error_msg (SWMM_Engine engine)
	Borrow the stored simulation error text.

SWMM_ENGINE_API const char *	swmm_error_message (int code)
	Translate a known public error code to a static English description.

SWMM_ENGINE_API void	swmm_engine_set_lenient_open (SWMM_Engine engine, int on)
	Select permissive model validation for subsequent editor loads.

SWMM_ENGINE_API int	swmm_get_error_count (SWMM_Engine engine)
	Count accumulated error messages.

SWMM_ENGINE_API const char *	swmm_get_error_at (SWMM_Engine engine, int index)
	Borrow one accumulated error message.

SWMM_ENGINE_API int	swmm_get_warning_count (SWMM_Engine engine)
	Count accumulated warning messages.

SWMM_ENGINE_API const char *	swmm_get_warning_at (SWMM_Engine engine, int index)
	Borrow one accumulated warning message.

SWMM_ENGINE_API int	swmm_get_thread_info (SWMM_ThreadInfo *out)
	Query hardware and parallel-runtime limits without an engine.

SWMM_ENGINE_API int	swmm_get_effective_threads (SWMM_Engine engine, int threads_option, int global_threads, int dw_threads, int *twod_threads)
	Preview thread-team sizes for a request and the current model.

SWMM_ENGINE_API int	swmm_get_transport_matrix (SWMM_Engine engine, SWMM_TransportMatrix *out)
	Resolve planned transport classes for each configured model domain.

SWMM_ENGINE_API int	swmm_preview_transport_matrix (SWMM_Engine engine, const SWMM_TransportDraft draft, SWMM_TransportMatrix out)
	Resolve transport for a temporary draft without mutating the model.

SWMM_ENGINE_API const char *	swmm_transport_domain_name (int domain)
	Get the display name of a transport-domain axis value.

SWMM_ENGINE_API const char *	swmm_transport_class_name (int species_class)
	Get the display name of a transport-species class.

SWMM_ENGINE_API int	swmm_get_start_time (SWMM_Engine engine, double *start)
	Read the configured simulation start calendar date.

SWMM_ENGINE_API int	swmm_get_end_time (SWMM_Engine engine, double *end)
	Read the configured simulation end calendar date.

SWMM_ENGINE_API int	swmm_get_current_time (SWMM_Engine engine, double *current)
	Read the current elapsed physics time.

SWMM_ENGINE_API int	swmm_get_routing_step (SWMM_Engine engine, double *dt)
	Read the configured routing timestep limit.

SWMM_ENGINE_API int	swmm_get_flow_units (SWMM_Engine engine, int *flow_units)
	Read the project display-flow unit code.

SWMM_ENGINE_API int	swmm_get_unit_system (SWMM_Engine engine, int *unit_system)
	Read the unit system implied by project flow units.

SWMM_ENGINE_API int	swmm_is_between_events (SWMM_Engine engine, int *is_between)
	Read the current implementation event-list presence flag.

SWMM_ENGINE_API int	swmm_get_event_count (SWMM_Engine engine, int *count)
	Count configured routing-event entries.

SWMM_ENGINE_API int	swmm_events_count (SWMM_Engine engine, int *count)
	Count configured routing-event entries.

SWMM_ENGINE_API int	swmm_events_get (SWMM_Engine engine, int idx, double start, double end)
	Read the calendar window of a configured routing event.

SWMM_ENGINE_API int	swmm_events_set (SWMM_Engine engine, int idx, double start, double end)
	Replace one event calendar window in place.

SWMM_ENGINE_API int	swmm_events_add (SWMM_Engine engine, double start, double end, int *out_idx)
	Append a routing-event window in insertion order.

SWMM_ENGINE_API int	swmm_events_remove (SWMM_Engine engine, int idx)
	Remove one configured event and shift later indices down.

SWMM_ENGINE_API int	swmm_events_clear (SWMM_Engine engine)
	Remove all configured routing events.

SWMM_ENGINE_API int	swmm_get_steady_state_skip (SWMM_Engine engine, int *enabled)
	Read the stored steady-state routing-skip option.

SWMM_ENGINE_API int	swmm_set_steady_state_skip (SWMM_Engine engine, int enabled)
	Set the stored steady-state routing-skip option.

SWMM_ENGINE_API int	swmm_runoff_iface_open_write (SWMM_Engine engine, const char *path)
	Open a runoff cache for SAVE records using the current model schema.

SWMM_ENGINE_API int	swmm_runoff_iface_open_read (SWMM_Engine engine, const char *path)
	Open a compatible runoff cache for USE-mode record reads.

SWMM_ENGINE_API int	swmm_runoff_iface_save_step (SWMM_Engine engine, double dt)
	Request a manual runoff-cache snapshot.

SWMM_ENGINE_API int	swmm_runoff_iface_read_step (SWMM_Engine engine, int *has_data)
	Read one available runoff record into the current subcatchment state.

SWMM_ENGINE_API int	swmm_runoff_iface_close (SWMM_Engine engine)
	Close and release the runoff-cache file if present.

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_datetime.h — SWMM DateTime encode/decode utilities
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", NULL);
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.

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: Apache-2.0

Macro Definition Documentation

◆ SWMM_ENGINE_API

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

◆ SWMM_TRANSPORT_CLASS_AGE

#define SWMM_TRANSPORT_CLASS_AGE 2

◆ SWMM_TRANSPORT_CLASS_COUNT

#define SWMM_TRANSPORT_CLASS_COUNT 4

◆ SWMM_TRANSPORT_CLASS_MSX

#define SWMM_TRANSPORT_CLASS_MSX 1

◆ SWMM_TRANSPORT_CLASS_POLLUTANTS

#define SWMM_TRANSPORT_CLASS_POLLUTANTS 0

◆ SWMM_TRANSPORT_CLASS_TEMPERATURE

#define SWMM_TRANSPORT_CLASS_TEMPERATURE 3

◆ SWMM_TRANSPORT_DISABLED_BY_USER

#define SWMM_TRANSPORT_DISABLED_BY_USER 1

reason = the option key

◆ SWMM_TRANSPORT_DOMAIN_COUNT

#define SWMM_TRANSPORT_DOMAIN_COUNT 4

◆ SWMM_TRANSPORT_DOMAIN_GROUNDWATER

#define SWMM_TRANSPORT_DOMAIN_GROUNDWATER 1

◆ SWMM_TRANSPORT_DOMAIN_NETWORK_1D

#define SWMM_TRANSPORT_DOMAIN_NETWORK_1D 2

◆ SWMM_TRANSPORT_DOMAIN_RUNOFF

#define SWMM_TRANSPORT_DOMAIN_RUNOFF 0

◆ SWMM_TRANSPORT_DOMAIN_SURFACE_2D

#define SWMM_TRANSPORT_DOMAIN_SURFACE_2D 3

◆ SWMM_TRANSPORT_ENABLED

#define SWMM_TRANSPORT_ENABLED 0

◆ SWMM_TRANSPORT_UNAVAILABLE

#define SWMM_TRANSPORT_UNAVAILABLE 2

reason = why nothing is carried

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_TransportCell

typedef struct SWMM_TransportCell SWMM_TransportCell

◆ SWMM_TransportDraft

typedef struct SWMM_TransportDraft SWMM_TransportDraft

Side-effect-free pre-run preview. Boolean fields must be 0 or 1; groundwater is -1 (Automatic), 0 (Off), 1 (On). This is planned transport, not proof of initialized runtime activity or local heat-flux support.

◆ SWMM_TransportMatrix

typedef struct SWMM_TransportMatrix SWMM_TransportMatrix

◆ 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_DEPENDENCY	Object has dependents that would be affected by deletion.
SWMM_ERR_CANCELLED	A caller cancelled a cancellable read-only operation.
SWMM_ERR_BUFSIZE	A caller's output buffer is too small for the value; nothing was written. Retry with a larger buffer.
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_abi_tag()

SWMM_ENGINE_API const char * swmm_engine_abi_tag ( void )

Identify the public C ABI compiled into the running engine image.

Returns: Borrowed immutable UTF-8 tag, valid while the library remains loaded; never free it.

Note: Thread-safe, requires no engine handle and performs no allocation or file IO. Compare with OPENSWMM_ENGINE_ABI_TAG from the installed openswmm_abi_tag.h before passing native engine handles across a GUI/plugin/Python boundary. Public-header, optional-module or build-ABI changes automatically change the tag. Comment-only header changes may conservatively change it too.

◆ swmm_engine_advance_to()

SWMM_ENGINE_API int swmm_engine_advance_to	(	SWMM_Engine	engine,
		double	target_seconds,
		double *	actual_seconds )

Advance to a specified elapsed-second exchange boundary without overshooting.

Flushes pending 2D work before successful return. Due external driver updates must be supplied first. Does not provide rollback or iterative coupling; inspect actual_seconds after errors.

Parameters

[in]	engine	Non-null RUNNING engine; cannot be invoked recursively from a step or its callbacks.
[in]	target_seconds	Finite absolute elapsed simulation time in seconds, at least the current coupling clock and no later than simulation end.
[out]	actual_seconds	Non-null accepted coupling-time output in seconds. With valid arguments, set before lifecycle/target checks and updated after advancement; may report partial progress on stepping failure.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for invalid target/output, SWMM_ERR_LIFECYCLE for a running/driver/boundary refusal, or the first step error.

◆ swmm_engine_close()

SWMM_ENGINE_API int swmm_engine_close ( SWMM_Engine engine )

Stop IO and release active model files, plugins and checkpoint attachments.

May be called during teardown from any live engine state. Enters CLOSED and permits a fresh open; it does not free the handle. Flushes recorded fatal diagnostics on failed runs. Engine-owned pointers to mutable model data must not be retained across close/reopen.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

Here is the caller graph for this function:

◆ swmm_engine_create()

SWMM_ENGINE_API SWMM_Engine swmm_engine_create ( void )

Allocate an independent engine in SWMM_STATE_CREATED.

Returns: Caller-owned opaque engine handle, or NULL when construction fails. Release with swmm_engine_destroy(); close active resources first when explicit teardown is needed.

Here is the caller graph for this function:

◆ swmm_engine_destroy()

SWMM_ENGINE_API void swmm_engine_destroy ( SWMM_Engine engine )

Delete an engine and all resources it owns.

Do not call concurrently with any operation or from inside a callback. Callback user_data remains caller-owned and is never freed by this function.

Parameters

[in] engine Caller-owned engine handle, or NULL for a no-op. Do not use a non-null handle afterward or destroy it twice.

Here is the caller graph for this function:

◆ swmm_engine_end()

SWMM_ENGINE_API int swmm_engine_end ( SWMM_Engine engine )

Finalize a running or completed simulation and enter SWMM_STATE_ENDED.

Requires RUNNING or ENDED. Finalizes balances, pending IO and end-of-run output/hotstarts. If a prior error has placed the engine in an error state, preserves and returns the existing root-cause error instead of replacing it with a teardown-state complaint.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an invalid lifecycle state, or the underlying initialization/IO/plugin error.

Here is the caller graph for this function:

◆ swmm_engine_get_elapsed_seconds()

SWMM_ENGINE_API int swmm_engine_get_elapsed_seconds	(	SWMM_Engine	engine,
		double *	seconds )

Read the routing elapsed clock, including during step callbacks.

No lifecycle guard is applied. This getter uses the context routing clock; swmm_engine_advance_to() reports the runtime coupling clock used for exchange boundaries.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	seconds	Non-null destination for context elapsed_ms/1000 in seconds since simulation start.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null seconds.

◆ swmm_engine_get_state()

SWMM_ENGINE_API int swmm_engine_get_state	(	SWMM_Engine	engine,
		int *	state )

Read the public lifecycle state of a live engine.

Internal PAUSED maps to RUNNING, REPORTED maps to ENDED, and the internal error state maps to SWMM_STATE_NONE.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	state	Optional destination for an SWMM_EngineState integer. NULL performs only the handle check.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

Here is the caller graph for this function:

◆ swmm_engine_initialize()

SWMM_ENGINE_API int swmm_engine_initialize ( SWMM_Engine engine )

Allocate simulation modules and initial state, entering SWMM_STATE_INITIALIZED.

Requires OPENED, or INITIALIZED for a pre-start rebuild. Resolves runtime physics/transport guards, initializes forcing arrays and compiles stored control rules. Metadata-only handles are refused. Reinitializing after a run requires a fresh open; initialization may change state to an error state on failure.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an invalid lifecycle state, or the underlying initialization/IO/plugin error.

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 )

Load a model and prepare its plugin configuration in SWMM_STATE_OPENED.

Requires CREATED or CLOSED and resets the model context for a fresh load. Ordinary open resolves and validates model references and may load configured plugins. Paths are consumed synchronously; the engine keeps its own copies as needed. Query swmm_get_last_error_msg() and accumulated errors/warnings after refusal. Existing report/output destinations can be written during the lifecycle; use separate private paths for staged work.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	inp	Borrowed NUL-terminated input-model path.
[in]	rpt	Borrowed report destination path, or NULL to omit it.
[in]	out	Borrowed binary-results destination path, or NULL to omit it.
[in]	input_plugin_lib	Borrowed input plugin library path, component ID or id:version; NULL/empty selects the built-in INP reader when no input plugin is already registered.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an invalid lifecycle state, or the underlying initialization/IO/plugin error.

Here is the caller graph for this function:

◆ swmm_engine_open_metadata()

SWMM_ENGINE_API int swmm_engine_open_metadata	(	SWMM_Engine	engine,
		const char *	inp )

Open a model for configured metadata without preparing simulation plugins.

Uses normal strict model validation and no report/result destinations. The returned OPENED model supports metadata getters; initialize/start are refused until the engine is closed and reopened normally. Model-declared SAVE paths are not opened by this metadata load.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	inp	Borrowed NUL-terminated input-model path.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null/empty inp, or an open/parse/validation error.

◆ swmm_engine_report()

SWMM_ENGINE_API int swmm_engine_report ( SWMM_Engine engine )

Write final model/simulation reports after ending the simulation.

Requires the internal ENDED state and transitions to REPORTED (publicly exposed as SWMM_STATE_ENDED). Preserves the root-cause error for failed runs. Report plugins/configuration determine the destinations and content.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an invalid lifecycle state, or the underlying initialization/IO/plugin error.

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 )

Create an engine, run the full lifecycle synchronously, and destroy it.

Chains open, initialize, start(save_results=1), step loop, end, report, close and destroy. Early failures close/destroy as appropriate; the temporary engine and its detailed diagnostics are not available after return. All input strings remain caller-owned.

Parameters

[in]	inp	Borrowed NUL-terminated input-model path.
[in]	rpt	Borrowed report destination path, or NULL to omit it.
[in]	out	Borrowed binary-results destination path, or NULL to omit it.
[in]	input_plugin_lib	Borrowed input plugin library path, component ID or id:version; NULL/empty selects the built-in INP reader when no input plugin is already registered.

Returns: SWMM_OK on success; SWMM_ERR_NOMEM when engine creation fails, otherwise an open/initialize/start/step or recorded engine error.

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 the full synchronous lifecycle with a borrowed progress callback.

Uses a temporary engine and destroys it before returning, as swmm_engine_run() does. Callbacks must not throw, close/destroy the temporary engine or recursively advance it; progress notifications cannot cancel the run.

Parameters

[in]	inp	Borrowed NUL-terminated input-model path.
[in]	rpt	Borrowed report destination path, or NULL to omit it.
[in]	out	Borrowed binary-results destination path, or NULL to omit it.
[in]	input_plugin_lib	Borrowed input plugin library path, component ID or id:version; NULL/empty selects the built-in INP reader when no input plugin is already registered.
[in]	callback	Optional progress function, invoked on the calling thread before each physical step; NULL disables progress notifications.
[in]	user_data	Borrowed opaque context passed unchanged to callback; may be NULL and must remain valid throughout this call.

Returns: SWMM_OK on success, SWMM_ERR_NOMEM when engine creation fails, or the lifecycle/recorded error.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_engine_set_lenient_open()

SWMM_ENGINE_API void swmm_engine_set_lenient_open	(	SWMM_Engine	engine,
		int	on )

Select permissive model validation for subsequent editor loads.

Lenient open keeps parsed objects editable in OPENED despite post-parse reference/validation errors, which remain available through swmm_get_error_count()/swmm_get_error_at(). Hard input-reader failures still fail. Running the repaired model requires a fresh strict open.

Parameters

[in]	engine	Live engine handle; NULL is a no-op.
[in]	on	0 selects strict validation (default); nonzero enables lenient open.

◆ swmm_engine_start()

SWMM_ENGINE_API int swmm_engine_start	(	SWMM_Engine	engine,
		int	save_results )

Start an initialized simulation, entering SWMM_STATE_RUNNING.

Requires INITIALIZED. Opens configured interface files and prepares run-time plugins/outputs before stepping. Failure may leave partially prepared resources that must be closed; read the last error before teardown.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	save_results	0 disables regular result saving; nonzero enables it through the configured output path/plugins.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an invalid lifecycle state, or the underlying initialization/IO/plugin error.

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 physical simulation step and report elapsed days.

Requires RUNNING and refuses recursive stepping or a due external driver update. Invokes progress and begin callbacks before physics and the end callback after physics/output. Runtime source expiries may shorten the proposed step. A failure after accepted physics or output recording does not promise rollback; query state and diagnostics.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	elapsed_time	Optional destination for elapsed simulation DAYS after the accepted step; 0 when the simulation is complete. NULL suppresses this output. Some early refusals leave it unchanged.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an invalid lifecycle state, or the underlying initialization/IO/plugin error.

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 )

Perform up to a requested number of physical steps synchronously.

Stops early on an error or a step result <=0. A failed early step can overwrite the output with zero even when prior physics remains accepted. Each individual step performs its usual callbacks and lifecycle checks.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	n_steps	Maximum step count; nonpositive values are a successful no-op after checking the handle.
[out]	elapsed_time	Optional elapsed-days output, initially set to zero and then to each step result; zero denotes completion.

Returns: SWMM_OK on success/no-op, SWMM_ERR_BADHANDLE for null engine, or the first error returned by swmm_engine_step().

◆ swmm_error_message()

SWMM_ENGINE_API const char * swmm_error_message ( int code )

Translate a known public error code to a static English description.

Does not require an engine or include operation-specific context; use swmm_get_last_error_msg() for the recorded diagnostic.

Parameters

[in] code SWMM_OK, an SWMM_ERR_* code, or a supported validation code.

Returns: Pointer to immutable static NUL-terminated storage; Unknown error for an unrecognized code. Never free it.

◆ swmm_events_add()

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

Append a routing-event window in insertion order.

Does not sort, merge overlaps or validate finite values. Caller retains no references into the internal event vector.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	start	Start as SWMM DateTime decimal days since 1899-12-30; must compare less than end.
[in]	end	End in the same calendar-day units.
[out]	out_idx	Optional destination for the appended zero-based index, written on success.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM when start>=end.

◆ swmm_events_clear()

SWMM_ENGINE_API int swmm_events_clear ( SWMM_Engine engine )

Remove all configured routing events.

No lifecycle guard is applied; configure the event list before running.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_events_count()

SWMM_ENGINE_API int swmm_events_count	(	SWMM_Engine	engine,
		int *	count )

Count configured routing-event entries.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	count	Optional destination. Nonnegative number of stored event windows; alias of swmm_get_event_count().

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

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 )

Read the calendar window of a configured routing event.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	idx	Zero-based event index in [0,event count).
[out]	start	Optional destination for event start as SWMM DateTime decimal days since 1899-12-30.
[out]	end	Optional destination for event end in the same calendar-day units.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid idx.

◆ swmm_events_remove()

SWMM_ENGINE_API int swmm_events_remove	(	SWMM_Engine	engine,
		int	idx )

Remove one configured event and shift later indices down.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	idx	Zero-based event index to remove.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid idx.

◆ swmm_events_set()

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

Replace one event calendar window in place.

Applies no lifecycle, overlap, sorting or finite-value validation; configure valid ordered event data before running.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	idx	Zero-based event index.
[in]	start	Start as SWMM DateTime decimal days since 1899-12-30; must compare less than end.
[in]	end	End in the same calendar-day units.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid idx, or SWMM_ERR_BADPARAM when start>=end.

◆ swmm_get_current_time()

SWMM_ENGINE_API int swmm_get_current_time	(	SWMM_Engine	engine,
		double *	current )

Read the current elapsed physics time.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	current	Optional destination. Elapsed seconds since simulation start (context current_time), NOT a DateTime calendar value.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_effective_threads()

SWMM_ENGINE_API int swmm_get_effective_threads	(	SWMM_Engine	engine,
		int	threads_option,
		int *	global_threads,
		int *	dw_threads,
		int *	twod_threads )

Preview thread-team sizes for a request and the current model.

Read-only resolution using the same policy helpers as run setup. Model-size gates may reduce even an explicit request; automatic requests also apply applicable performance-core policy. Does not change the stored THREADS option or initialize a parallel backend.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	threads_option	[OPTIONS] THREADS request: 0 is automatic; positive requests are resolved against model-size/runtime policies.
[out]	global_threads	Optional general OpenMP team-size destination.
[out]	dw_threads	Optional dynamic-wave team-size destination; zero when routing is not DYNWAVE.
[out]	twod_threads	Optional 2D CPU team-size destination; zero without an enabled nonempty mesh or 2D build support.

Returns: SWMM_OK, or SWMM_ERR_BADPARAM for null engine (this query uses BADPARAM rather than BADHANDLE).

◆ swmm_get_end_time()

SWMM_ENGINE_API int swmm_get_end_time	(	SWMM_Engine	engine,
		double *	end )

Read the configured simulation end calendar date.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	end	Optional destination. SWMM DateTime decimal days since 1899-12-30.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_error_at()

SWMM_ENGINE_API const char * swmm_get_error_at	(	SWMM_Engine	engine,
		int	index )

Borrow one accumulated error message.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	index	Zero-based message index.

Returns: Engine-owned NUL-terminated message, or an empty string for null engine/out-of-range index. Never free; copy before operations that change the list or destroy the engine.

◆ swmm_get_error_count()

SWMM_ENGINE_API int swmm_get_error_count ( SWMM_Engine engine )

Count accumulated error messages.

This getter does not clear the list and is distinct from the stored last-error code.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: Number of accumulated messages; 0 for null engine.

◆ swmm_get_event_count()

SWMM_ENGINE_API int swmm_get_event_count	(	SWMM_Engine	engine,
		int *	count )

Count configured routing-event entries.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	count	Optional destination. Nonnegative number of stored event windows; alias of swmm_events_count().

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

Here is the caller graph for this function:

◆ swmm_get_flow_units()

SWMM_ENGINE_API int swmm_get_flow_units	(	SWMM_Engine	engine,
		int *	flow_units )

Read the project display-flow unit code.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	flow_units	Optional destination. 0=CFS, 1=GPM, 2=MGD, 3=CMS, 4=LPS, 5=MLD.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_last_error()

SWMM_ENGINE_API int swmm_get_last_error ( SWMM_Engine engine )

Read the stored simulation error code without clearing it.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: Stored error code (SWMM_OK if no error), or SWMM_ERR_BADHANDLE for null 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 )

Borrow the stored simulation error text.

Reading does not clear the error. Diagnostic lifetime is tied to the underlying stored string, which subsequent operations can replace.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: Engine-owned NUL-terminated string, or the static string invalid engine handle for NULL. Never free it; copy before another error/model operation or engine destruction.

◆ swmm_get_routing_step()

SWMM_ENGINE_API int swmm_get_routing_step	(	SWMM_Engine	engine,
		double *	dt )

Read the configured routing timestep limit.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	dt	Optional destination. Configured routing-step seconds, not the last adaptive step duration.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_start_time()

SWMM_ENGINE_API int swmm_get_start_time	(	SWMM_Engine	engine,
		double *	start )

Read the configured simulation start calendar date.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	start	Optional destination. SWMM DateTime decimal days since 1899-12-30.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_steady_state_skip()

SWMM_ENGINE_API int swmm_get_steady_state_skip	(	SWMM_Engine	engine,
		int *	enabled )

Read the stored steady-state routing-skip option.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	enabled	Optional destination. 1 when skipping is enabled, otherwise 0.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_thread_info()

SWMM_ENGINE_API int swmm_get_thread_info ( SWMM_ThreadInfo * out )

Query hardware and parallel-runtime limits without an engine.

Reports process-visible logical CPUs, OpenMP limits/availability, macOS performance-cluster CPUs and initialized Kokkos OpenMP team size. Zero indicates unavailable/unknown for fields whose struct comments permit it.

Parameters

[out] out Non-null caller-owned SWMM_ThreadInfo destination; all fields are filled on success.

Returns: SWMM_OK, or SWMM_ERR_BADPARAM for null out.

◆ swmm_get_transport_matrix()

SWMM_ENGINE_API int swmm_get_transport_matrix	(	SWMM_Engine	engine,
		SWMM_TransportMatrix *	out )

Resolve planned transport classes for each configured model domain.

Read after open and again after relevant option edits. An unopened/unavailable domain reports unavailable cells. This is configured transport resolution, not proof of runtime initialization or local heat-flux availability.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	out	Non-null caller-owned matrix indexed [SWMM_TRANSPORT_DOMAIN_][SWMM_TRANSPORT_CLASS_]; reasons are NUL-terminated and truncated to their fixed capacity.

Returns: SWMM_OK, or SWMM_ERR_BADPARAM for null engine/out.

◆ swmm_get_unit_system()

SWMM_ENGINE_API int swmm_get_unit_system	(	SWMM_Engine	engine,
		int *	unit_system )

Read the unit system implied by project flow units.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	unit_system	Optional destination. 0=US/imperial or 1=SI/metric; CMS/LPS/MLD select SI.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

Here is the call graph for this function:

◆ swmm_get_warning_at()

SWMM_ENGINE_API const char * swmm_get_warning_at	(	SWMM_Engine	engine,
		int	index )

Borrow one accumulated warning message.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	index	Zero-based message index.

Returns: Engine-owned NUL-terminated message, or an empty string for null engine/out-of-range index. Never free; copy before operations that change the list or destroy the engine.

◆ swmm_get_warning_count()

SWMM_ENGINE_API int swmm_get_warning_count ( SWMM_Engine engine )

Count accumulated warning messages.

This getter does not clear the list and is distinct from the stored last-error code.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: Number of accumulated messages; 0 for null engine.

◆ swmm_is_between_events()

SWMM_ENGINE_API int swmm_is_between_events	(	SWMM_Engine	engine,
		int *	is_between )

Read the current implementation event-list presence flag.

Despite the historical function name, the implementation does not compare the simulation clock with event windows; it reports only whether the event list is nonempty.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	is_between	Optional destination: 1 when at least one event entry is configured, 0 for an empty event list.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_preview_transport_matrix()

SWMM_ENGINE_API int swmm_preview_transport_matrix	(	SWMM_Engine	engine,
		const SWMM_TransportDraft *	draft,
		SWMM_TransportMatrix *	out )

Resolve transport for a temporary draft without mutating the model.

Uses existing mesh/aquifer authoring and a temporary options overlay. Does not initialize transport, validate runtime support, or persist the draft.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	draft	Non-null borrowed draft: Boolean fields and surface_class entries must be 0/1; groundwater must be -1 (automatic), 0 (off), or 1 (on).
[out]	out	Non-null caller-owned resolved matrix with bounded NUL-terminated reasons; unchanged on argument refusal.

Returns: SWMM_OK, or SWMM_ERR_BADPARAM for null arguments or invalid draft flags.

◆ swmm_runoff_iface_close()

SWMM_ENGINE_API int swmm_runoff_iface_close ( SWMM_Engine engine )

Close and release the runoff-cache file if present.

Idempotent for a live engine; engine close also invokes this cleanup. Does not destroy the engine.

Parameters

[in] engine Non-null live engine handle; caller provides exclusive access on the owning thread.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_runoff_iface_open_read()

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

Open a compatible runoff cache for USE-mode record reads.

Header subcatchment count, pollutant count and flow units must match the current model. USE does not automatically suppress native runoff computation; manually loaded states can be overwritten by subsequent runoff work.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	path	Non-null, nonempty NUL-terminated existing runoff-cache path; borrowed for the call.

Returns: 0 on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null/empty path, -10 when a runoff file is already open, or a file/header compatibility error.

◆ swmm_runoff_iface_open_write()

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

Open a runoff cache for SAVE records using the current model schema.

Call after configuring the model dimensions/units and before stepping. Automatic SAVE records are emitted by runoff substeps; close with swmm_runoff_iface_close() or engine close.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	path	Non-null, nonempty NUL-terminated output path. Existing contents are truncated; string is borrowed for the call.

Returns: 0 on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null/empty path, -10 when another runoff file is already open, or a runoff-interface file error.

◆ swmm_runoff_iface_read_step()

SWMM_ENGINE_API int swmm_runoff_iface_read_step	(	SWMM_Engine	engine,
		int *	has_data )

Read one available runoff record into the current subcatchment state.

Returns SWMM_OK even when the underlying read returns false; has_data is the only per-call availability signal. The next native runoff calculation may overwrite the imported state.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[out]	has_data	Optional destination: 1 when a record was read, 0 when no record is available (including EOF, no open file or an unsuitable read state).

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_runoff_iface_save_step()

SWMM_ENGINE_API int swmm_runoff_iface_save_step	(	SWMM_Engine	engine,
		double	dt )

Request a manual runoff-cache snapshot.

Normally SAVE records are emitted automatically. With no open SAVE file this is a no-op; this wrapper does not report a write/flush error from the underlying void save operation.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	dt	Snapshot runoff substep duration in seconds, passed through without validation.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_set_progress_callback()

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

Register, replace or disable pre-step progress.

No lifecycle guard is applied. Callbacks run synchronously on the thread making the triggering engine call; they must not throw or recursively step/close/destroy the engine. See the callback typedef for timing and permitted updates.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	callback	SWMM_ProgressCallback function pointer, or NULL to unregister. Borrowed until replaced/unregistered or engine destruction.
[in]	user_data	Borrowed opaque pointer passed through unchanged; may be NULL. Keep the context alive for every callback invocation.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

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 )

Set the stored steady-state routing-skip option.

Sets the option directly without a lifecycle guard. Routing logic determines whether individual steps can be skipped.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	enabled	0 disables skipping; any nonzero value enables it.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_set_step_begin_callback()

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

Register, replace or disable pre-physics step notifications.

No lifecycle guard is applied. Callbacks run synchronously on the thread making the triggering engine call; they must not throw or recursively step/close/destroy the engine. See the callback typedef for timing and permitted updates.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	callback	SWMM_StepBeginCallback function pointer, or NULL to unregister. Borrowed until replaced/unregistered or engine destruction.
[in]	user_data	Borrowed opaque pointer passed through unchanged; may be NULL. Keep the context alive for every callback invocation.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_set_step_end_callback()

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

Register, replace or disable post-physics step notifications.

No lifecycle guard is applied. Callbacks run synchronously on the thread making the triggering engine call; they must not throw or recursively step/close/destroy the engine. See the callback typedef for timing and permitted updates.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	callback	SWMM_StepEndCallback function pointer, or NULL to unregister. Borrowed until replaced/unregistered or engine destruction.
[in]	user_data	Borrowed opaque pointer passed through unchanged; may be NULL. Keep the context alive for every callback invocation.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_set_warning_callback()

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

Register, replace or disable diagnostics.

No lifecycle guard is applied. Callbacks run synchronously on the thread making the triggering engine call; they must not throw or recursively step/close/destroy the engine. See the callback typedef for timing and permitted updates.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access on the owning thread.
[in]	callback	SWMM_WarningCallback function pointer, or NULL to unregister. Borrowed until replaced/unregistered or engine destruction.
[in]	user_data	Borrowed opaque pointer passed through unchanged; may be NULL. Keep the context alive for every callback invocation.

Returns: SWMM_OK on success, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_transport_class_name()

SWMM_ENGINE_API const char * swmm_transport_class_name ( int species_class )

Get the display name of a transport-species class.

Parameters

[in] species_class SWMM_TRANSPORT_CLASS_* integer in [0,SWMM_TRANSPORT_CLASS_COUNT).

Returns: Immutable static NUL-terminated name, or an empty static string when out of range; never free it.

Here is the call graph for this function:

◆ swmm_transport_domain_name()

SWMM_ENGINE_API const char * swmm_transport_domain_name ( int domain )

Get the display name of a transport-domain axis value.

Parameters

[in] domain SWMM_TRANSPORT_DOMAIN_* integer in [0,SWMM_TRANSPORT_DOMAIN_COUNT).

Returns: Immutable static NUL-terminated name, or an empty static string when out of range; never free it.

Here is the call graph for this function:

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Lifecycle

Macro Definition Documentation

◆ SWMM_ENGINE_API

◆ SWMM_TRANSPORT_CLASS_AGE

◆ SWMM_TRANSPORT_CLASS_COUNT

◆ SWMM_TRANSPORT_CLASS_MSX

◆ SWMM_TRANSPORT_CLASS_POLLUTANTS

◆ SWMM_TRANSPORT_CLASS_TEMPERATURE

◆ SWMM_TRANSPORT_DISABLED_BY_USER

◆ SWMM_TRANSPORT_DOMAIN_COUNT

◆ SWMM_TRANSPORT_DOMAIN_GROUNDWATER

◆ SWMM_TRANSPORT_DOMAIN_NETWORK_1D

◆ SWMM_TRANSPORT_DOMAIN_RUNOFF

◆ SWMM_TRANSPORT_DOMAIN_SURFACE_2D

◆ SWMM_TRANSPORT_ENABLED

◆ SWMM_TRANSPORT_UNAVAILABLE

Typedef Documentation

◆ SWMM_EngineState

◆ SWMM_ErrorCode

◆ SWMM_ObjectType

◆ SWMM_TransportCell

◆ SWMM_TransportDraft

◆ SWMM_TransportMatrix

◆ SWMM_WarnCode

Enumeration Type Documentation

◆ SWMM_EngineState

◆ SWMM_ErrorCode

◆ SWMM_ObjectType

◆ SWMM_WarnCode

Function Documentation

◆ swmm_engine_abi_tag()

◆ swmm_engine_advance_to()

◆ swmm_engine_close()

◆ swmm_engine_create()

◆ swmm_engine_destroy()

◆ swmm_engine_end()

◆ swmm_engine_get_elapsed_seconds()

◆ swmm_engine_get_state()

◆ swmm_engine_initialize()

◆ swmm_engine_open()

◆ swmm_engine_open_metadata()

◆ swmm_engine_report()

◆ swmm_engine_run()

◆ swmm_engine_run_with_callback()

◆ swmm_engine_set_lenient_open()

◆ swmm_engine_start()

◆ swmm_engine_step()

◆ swmm_engine_stride()

◆ swmm_error_message()

◆ swmm_events_add()

◆ swmm_events_clear()

◆ swmm_events_count()

◆ swmm_events_get()

◆ swmm_events_remove()

◆ swmm_events_set()

◆ swmm_get_current_time()

◆ swmm_get_effective_threads()

◆ swmm_get_end_time()

◆ swmm_get_error_at()

◆ swmm_get_error_count()

◆ swmm_get_event_count()

◆ swmm_get_flow_units()

◆ swmm_get_last_error()

◆ swmm_get_last_error_msg()

◆ swmm_get_routing_step()

◆ swmm_get_start_time()

◆ swmm_get_steady_state_skip()

◆ swmm_get_thread_info()

◆ swmm_get_transport_matrix()

◆ swmm_get_unit_system()

◆ swmm_get_warning_at()

◆ swmm_get_warning_count()

◆ swmm_is_between_events()

◆ swmm_preview_transport_matrix()