Public C API for runtime coupling prescriptions and exchanges. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_coupling.h:

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

Classes
struct	SWMM_CouplingSource

struct	SWMM_CouplingReceipt

struct	SWMM_CouplingBoundary

struct	SWMM_CouplingForcing

struct	SWMM_CouplingClear

struct	SWMM_CouplingFrame

Macros
#define	SWMM_COUPLING_SURFACE 0

#define	SWMM_COUPLING_GROUNDWATER 1

#define	SWMM_COUPLING_FRAME_VERSION 1

#define	SWMM_COUPLING_RAINFALL 1

#define	SWMM_COUPLING_EVAPORATION 2

#define	SWMM_COUPLING_INFILTRATION 3

#define	SWMM_COUPLING_RAIN_QUALITY 4

Typedefs
typedef struct SWMM_CouplingSource	SWMM_CouplingSource

typedef struct SWMM_CouplingReceipt	SWMM_CouplingReceipt

typedef struct SWMM_CouplingBoundary	SWMM_CouplingBoundary

typedef struct SWMM_CouplingForcing	SWMM_CouplingForcing

typedef struct SWMM_CouplingClear	SWMM_CouplingClear

typedef struct SWMM_CouplingFrame	SWMM_CouplingFrame

Functions
SWMM_ENGINE_API int	swmm_coupling_apply_frame (SWMM_Engine engine, const SWMM_CouplingFrame *frame)
	Atomically apply copied cross-domain sources, boundaries, forcings and clears.

SWMM_ENGINE_API int	swmm_coupling_clear_source_cell (SWMM_Engine engine, int domain, const char *id, int cell)
	Disable a legacy source in one cell or all of its cells while retaining receipts.

SWMM_ENGINE_API int	swmm_coupling_get_receipts (SWMM_Engine engine, int domain, const char id, const int cells, int count, SWMM_CouplingReceipt out, double requested_species, double *applied_species, int species_count)
	Read several source receipts after validating the entire request.

SWMM_ENGINE_API int	swmm_coupling_get_boundary_receipt (SWMM_Engine engine, int domain, int cell, int edge, SWMM_CouplingReceipt out, double requested_species, double *applied_species, int species_count)
	Read signed cumulative hydraulic and advective exchange for a perimeter edge.

SWMM_ENGINE_API int	swmm_coupling_get_infiltration_receipt (SWMM_Engine engine, int cell, SWMM_CouplingReceipt out, double requested_species, double *applied_species, int species_count)
	Read the paired surface-to-groundwater infiltration receipt for one cell.

SWMM_ENGINE_API int	swmm_2d_get_species_ledger (SWMM_Engine engine, int species, int term, double *value)
	Read a surface species storage or cumulative balance term.

SWMM_ENGINE_API int	swmm_coupling_set_source (SWMM_Engine engine, const char id, int domain, int cell, double flow_m3_s, double heat_w, const double concentrations, const double *rates, int species_count, double until_seconds)
	Replace one copied legacy source prescription without altering species topology.

SWMM_ENGINE_API int	swmm_gw2d_set_runtime_boundary (SWMM_Engine engine, int cell, int edge, int kind, double value, const double *concentrations, int species_count)
	Install or clear a saturated groundwater perimeter head or outward flow.

SWMM_ENGINE_API int	swmm_gw2d_clear_runtime_boundary (SWMM_Engine engine, int cell, int edge)
	Restore native no-flow on a legacy-owned groundwater perimeter edge.

SWMM_ENGINE_API int	swmm_gw2d_get_runtime_boundary_flow (SWMM_Engine engine, int cell, int edge, double *flow_m3_s)
	Read the last accepted outward groundwater boundary discharge.

SWMM_ENGINE_API int	swmm_2d_set_runtime_boundary (SWMM_Engine engine, int cell, int edge, int kind, double value, const double *concentrations, int species_count)
	Install or clear a surface perimeter stage or total outward flow.

SWMM_ENGINE_API int	swmm_coupling_set_sources (SWMM_Engine engine, const SWMM_CouplingSource *sources, int count)
	Atomically replace a batch of legacy source ID/cell prescriptions.

SWMM_ENGINE_API int	swmm_coupling_clear_source (SWMM_Engine engine, int domain, const char *id)
	Disable all legacy source cells for one ID and preserve their receipts.

SWMM_ENGINE_API int	swmm_coupling_get_receipt (SWMM_Engine engine, int domain, const char id, int cell, SWMM_CouplingReceipt out, double requested_species, double applied_species, int capacity)
	Read one stored source receipt, including retained cleared/expired history.

SWMM_ENGINE_API int	swmm_coupling_get_water_totals (SWMM_Engine engine, int domain, double incoming_m3, double outgoing_m3)
	Sum gross cumulative external source inflow and outflow for a domain.

SWMM_ENGINE_API int	swmm_coupling_advance_to (SWMM_Engine engine, double target_seconds, double *actual_seconds)
	Advance synchronously to an elapsed-second exchange time without overshoot.

SWMM_ENGINE_API int	swmm_coupling_capabilities (SWMM_Engine engine, unsigned *flags)
	Query runtime coupling features currently available in this engine.

Detailed Description

Public C API for runtime coupling prescriptions and exchanges.

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_COUPLING_EVAPORATION

#define SWMM_COUPLING_EVAPORATION 2

◆ SWMM_COUPLING_FRAME_VERSION

#define SWMM_COUPLING_FRAME_VERSION 1

◆ SWMM_COUPLING_GROUNDWATER

#define SWMM_COUPLING_GROUNDWATER 1

◆ SWMM_COUPLING_INFILTRATION

#define SWMM_COUPLING_INFILTRATION 3

◆ SWMM_COUPLING_RAIN_QUALITY

#define SWMM_COUPLING_RAIN_QUALITY 4

◆ SWMM_COUPLING_RAINFALL

#define SWMM_COUPLING_RAINFALL 1

◆ SWMM_COUPLING_SURFACE

#define SWMM_COUPLING_SURFACE 0

Typedef Documentation

◆ SWMM_CouplingBoundary

typedef struct SWMM_CouplingBoundary SWMM_CouplingBoundary

Boundary kind: 0 restores authored/native, 1 datum head in m, 2 outward m3/s.

◆ SWMM_CouplingClear

typedef struct SWMM_CouplingClear SWMM_CouplingClear

◆ SWMM_CouplingForcing

typedef struct SWMM_CouplingForcing SWMM_CouplingForcing

Forcing rate in m/s. mode: 0 clear, 1 replace, 2 add (rain/evap only). cell=-1 addresses all cells for rain/evap/quality; infiltration is per-cell, replaces native infiltration and transfers donor water/quality to GW once. species_count=0 keeps authored rainfall quality; a full tuple overrides it. until_seconds=0 holds until clear. Quality-only channel ignores rate.

◆ SWMM_CouplingFrame

typedef struct SWMM_CouplingFrame SWMM_CouplingFrame

Copied, atomic cross-domain transaction. provider=NULL/empty denotes legacy ownership. Named providers namespace source IDs as provider/<provider>/<id> and exclusively own each boundary/forcing until clear/expiry. Provider names cannot contain '/'. Rejections leave clock and all prescriptions unchanged. Native authored boundaries/forcing resume after clear.

◆ SWMM_CouplingReceipt

typedef struct SWMM_CouplingReceipt SWMM_CouplingReceipt

Signed cumulative receipt. Rejected=requested-applied; heat is J. Species arrays are retrieved separately, in concentration-unit*m3. Clearing/replacing preserves cumulative receipts for the same id/cell. A groundwater ID matching an authored well overrides it in that cell; clear/expiry resumes the authored prescription. Different IDs add.

◆ SWMM_CouplingSource

typedef struct SWMM_CouplingSource SWMM_CouplingSource

Version 1: per-cell sources. Arrays follow the target domain's species order. Concentrations use the same units as its concentration getter; rates use signed concentration-unit*m3/s (negative removes available mass). Reserved age is seconds and temperature is degrees C. Reserved-row rates must be zero: use heat_w for energy. flow_m3_s is positive INTO the domain; negative extracts donor quality. Groundwater sources address the saturated zone. Heat is water sensible heat, NOT soil conduction or heat storage. until_seconds=0 holds until clear. All pointers are copied; caller retains ownership.

Function Documentation

◆ swmm_2d_get_species_ledger()

SWMM_ENGINE_API int swmm_2d_get_species_ledger	(	SWMM_Engine	engine,
		int	species,
		int	term,
		double *	value )

Read a surface species storage or cumulative balance term.

Storage sums the current per-cell masses; other selectors return accumulated ledger entries. Terms 10 and 11 return zero when their corresponding calculation is inactive.

Parameters

[in]	engine	Non-null live engine with the selected mesh domain active; exclusive access is required.
[in]	species	Zero-based surface transport row index.
[in]	term	Ledger selector: 0 storage, 1 external in, 2 external out, 3 boundary in, 4 boundary out, 5 rainfall in, 6 infiltration out, 7 native coupling in, 8 native coupling out, 9 exfiltration in, 10 generated age, 11 signed reaction loss.
[out]	value	Non-null destination in native concentration-unit*m3. Generated age is RK2 age-volume (otherwise zero); qualified coupled RK2 reaction production is negative loss.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for unavailable surface runtime access, or SWMM_ERR_BADPARAM for null value/invalid species/term.

◆ swmm_2d_set_runtime_boundary()

SWMM_ENGINE_API int swmm_2d_set_runtime_boundary	(	SWMM_Engine	engine,
		int	cell,
		int	edge,
		int	kind,
		double	value,
		const double *	concentrations,
		int	species_count )

Install or clear a surface perimeter stage or total outward flow.

Uses legacy provider ownership. Active prescriptions disconnect authored time-series/rating bindings; clearing restores them and preserves receipts. Incoming quality follows the supplied tuple; profile-specific checkpoint/transport guards are checked before publication.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[in]	edge	Zero-based local cell edge. Must be a perimeter edge with positive length and center distance.
[in]	kind	0 restores the authored/native boundary, 1 prescribes datum stage, 2 prescribes outward flow.
[in]	value	Finite stage in m for kind=1 or total outward m3/s for kind=2; ignored for kind=0. Flow is total discharge, unlike legacy per-width edge setters.
[in]	concentrations	Copied array of species_count concentrations in domain row order; required when the count is nonzero. Values must be finite and nonnegative except temperature, which may be negative. Age is seconds; temperature is degrees C; other rows match the domain concentration getter.
[in]	species_count	Exact surface transport row count for kind 1/2; zero for kind=0 (concentrations may then be NULL).

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

◆ swmm_coupling_advance_to()

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

Advance synchronously to an elapsed-second exchange time without overshoot.

Pending 2D work is flushed before successful return. Due external driver updates must be supplied first. The operation does not promise rollback or iterative coupling; inspect actual_seconds after a stepping failure.

Parameters

[in]	engine	Non-null RUNNING engine; cannot be called from within an active step/callback.
[in]	target_seconds	Finite absolute elapsed simulation time in seconds between the current coupling time and simulation end, inclusive.
[out]	actual_seconds	Non-null destination for the accepted coupling clock in seconds. With valid arguments it is set before lifecycle/target checks, and updated after stepping; on failure it may show partial advancement.

Returns: SWMM_OK on successful advancement; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null output/nonfinite or out-of-range target, SWMM_ERR_LIFECYCLE for a running/driver/boundary refusal, or an error from stepping.

◆ swmm_coupling_apply_frame()

SWMM_ENGINE_API int swmm_coupling_apply_frame	(	SWMM_Engine	engine,
		const SWMM_CouplingFrame *	frame )

Atomically apply copied cross-domain sources, boundaries, forcings and clears.

provider NULL/empty uses legacy ownership. A named provider cannot contain a slash; source IDs become provider/<provider>/<id>. Boundary/forcing ownership is exclusive until clear/expiry. Duplicate or conflicting entries are refused before publication. Accepted changes flush prior pending physics, preserve cumulative receipts and record the prescription; native authored settings resume after clear.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	frame	Non-null frame with struct_size=sizeof(SWMM_CouplingFrame), version=SWMM_COUPLING_FRAME_VERSION and nonnegative counts. Each nonempty array requires a valid pointer; nested pointers are copied before return.

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_coupling_capabilities()

SWMM_ENGINE_API int swmm_coupling_capabilities	(	SWMM_Engine	engine,
		unsigned *	flags )

Query runtime coupling features currently available in this engine.

An absent bit means unavailable in this run. Capability bits do not bypass model-specific owner, transport, FULL_SWE or checkpoint-profile validation performed before frame publication.

Parameters

[in]	engine	Non-null live engine; the returned mask depends on the active mesh backend and transport rows.
[out]	flags	Non-null destination for a bitmask: 1 surface sources, 2 saturated GW sources, 4 surface water heat, 8 surface boundaries, 16 GW water heat, 32 GW hydraulic/advective boundaries, 64 atomic frames, 128 rain quality, 256 paired infiltration, 512 boundary receipts.

Returns: SWMM_OK on success, including a zero mask for an unavailable CPU runtime backend; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null flags.

◆ swmm_coupling_clear_source()

SWMM_ENGINE_API int swmm_coupling_clear_source	(	SWMM_Engine	engine,
		int	domain,
		const char *	id )

Disable all legacy source cells for one ID and preserve their receipts.

Equivalent to swmm_coupling_clear_source_cell() with cell=-1. An absent ID returns SWMM_ERR_BADINDEX. Named-provider sources must be cleared through their provider frame.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	domain	SWMM_COUPLING_SURFACE (0) or SWMM_COUPLING_GROUNDWATER (1).
[in]	id	Non-null NUL-terminated source ID. Set/clear APIs refuse empty IDs and the reserved boundary/ and provider/ prefixes. Receipt reads use the full stored ID, including `provider/<provider>/` for named providers.

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

◆ swmm_coupling_clear_source_cell()

SWMM_ENGINE_API int swmm_coupling_clear_source_cell	(	SWMM_Engine	engine,
		int	domain,
		const char *	id,
		int	cell )

Disable a legacy source in one cell or all of its cells while retaining receipts.

An absent source returns SWMM_ERR_BADINDEX. Clearing a groundwater source that overrides an authored well resumes that well; other source IDs continue to add.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	domain	SWMM_COUPLING_SURFACE (0) or SWMM_COUPLING_GROUNDWATER (1).
[in]	id	Non-null NUL-terminated source ID. Set/clear APIs refuse empty IDs and the reserved boundary/ and provider/ prefixes. Receipt reads use the full stored ID, including `provider/<provider>/` for named providers.
[in]	cell	Zero-based target cell, or -1 to clear every cell for this ID.

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_coupling_get_boundary_receipt()

SWMM_ENGINE_API int swmm_coupling_get_boundary_receipt	(	SWMM_Engine	engine,
		int	domain,
		int	cell,
		int	edge,
		SWMM_CouplingReceipt *	out,
		double *	requested_species,
		double *	applied_species,
		int	species_count )

Read signed cumulative hydraulic and advective exchange for a perimeter edge.

Positive water is INTO the domain, heat is total advective J, and species amounts use native concentration-unit*m3. A valid native no-flow edge with no receipt returns zero-filled outputs. Clearing a runtime boundary preserves its cumulative history.

Parameters

[in]	engine	Non-null live engine with the selected mesh domain active; exclusive access is required.
[in]	domain	SWMM_COUPLING_SURFACE (0) or SWMM_COUPLING_GROUNDWATER (1).
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[in]	edge	Zero-based local cell edge. Must be a perimeter edge with positive length and center distance.
[out]	out	Non-null destination for signed cumulative water (m3), heat (J), and last accepted flow/interval (m3/s and s). Rejected equals requested minus applied.
[out]	requested_species	Caller-owned array of species_count cumulative requested amounts, in native concentration-unit*m3; may be NULL only when species_count=0.
[out]	applied_species	Caller-owned array of species_count cumulative applied amounts in the same order/units; may be NULL only when species_count=0.
[in]	species_count	Exact number of transport rows in the selected domain, including reserved temperature and age rows.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE when runtime reads are unavailable, SWMM_ERR_BADPARAM for invalid domain/output/species count, or SWMM_ERR_BADINDEX for an invalid cell or local edge.

Here is the call graph for this function:

◆ swmm_coupling_get_infiltration_receipt()

SWMM_ENGINE_API int swmm_coupling_get_infiltration_receipt	(	SWMM_Engine	engine,
		int	cell,
		SWMM_CouplingReceipt *	out,
		double *	requested_species,
		double *	applied_species,
		int	species_count )

Read the paired surface-to-groundwater infiltration receipt for one cell.

Positive exchange is surface-to-groundwater; heat is advective J. The groundwater domain must cover the cell. A cell without an infiltration forcing record returns SWMM_ERR_BADINDEX.

Parameters

[in]	engine	Non-null live engine with the selected mesh domain active; exclusive access is required.
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[out]	out	Non-null destination for signed cumulative water (m3), heat (J), and last accepted flow/interval (m3/s and s). Rejected equals requested minus applied.
[out]	requested_species	Caller-owned array of species_count cumulative requested amounts, in native concentration-unit*m3; may be NULL only when species_count=0.
[out]	applied_species	Caller-owned array of species_count cumulative applied amounts in the same order/units; may be NULL only when species_count=0.
[in]	species_count	Exact surface-domain transport row count; output species follow the surface row order.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE when runtime reads are unavailable, SWMM_ERR_BADPARAM for invalid domain/output/species count, or SWMM_ERR_BADINDEX for a missing record.

◆ swmm_coupling_get_receipt()

SWMM_ENGINE_API int swmm_coupling_get_receipt	(	SWMM_Engine	engine,
		int	domain,
		const char *	id,
		int	cell,
		SWMM_CouplingReceipt *	out,
		double *	requested_species,
		double *	applied_species,
		int	capacity )

Read one stored source receipt, including retained cleared/expired history.

Species rows follow the selected domain order. The record must already exist; validation errors leave the outputs unchanged.

Parameters

[in]	engine	Non-null live engine with the selected mesh domain active; exclusive access is required.
[in]	domain	SWMM_COUPLING_SURFACE (0) or SWMM_COUPLING_GROUNDWATER (1).
[in]	id	Non-null NUL-terminated source ID. Set/clear APIs refuse empty IDs and the reserved boundary/ and provider/ prefixes. Receipt reads use the full stored ID, including `provider/<provider>/` for named providers.
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[out]	out	Non-null destination for signed cumulative water (m3), heat (J), and last accepted flow/interval (m3/s and s). Rejected equals requested minus applied.
[out]	requested_species	Caller-owned array of species_count cumulative requested amounts, in native concentration-unit*m3; may be NULL only when species_count=0.
[out]	applied_species	Caller-owned array of species_count cumulative applied amounts in the same order/units; may be NULL only when species_count=0.
[in]	capacity	Must equal the selected domain species count exactly; it is not a minimum buffer capacity. Both species arrays require this many elements.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE when runtime reads are unavailable, SWMM_ERR_BADPARAM for invalid domain/output/species count, or SWMM_ERR_BADINDEX for a missing record.

◆ swmm_coupling_get_receipts()

SWMM_ENGINE_API int swmm_coupling_get_receipts	(	SWMM_Engine	engine,
		int	domain,
		const char *	id,
		const int *	cells,
		int	count,
		SWMM_CouplingReceipt *	out,
		double *	requested_species,
		double *	applied_species,
		int	species_count )

Read several source receipts after validating the entire request.

No outputs are written if any requested record is missing or any argument fails validation. Records remain readable after source clear/expiry while the domain is active and runtime access is permitted.

Parameters

[in]	engine	Non-null live engine with the selected mesh domain active; exclusive access is required.
[in]	domain	SWMM_COUPLING_SURFACE (0) or SWMM_COUPLING_GROUNDWATER (1).
[in]	id	Non-null NUL-terminated source ID. Set/clear APIs refuse empty IDs and the reserved boundary/ and provider/ prefixes. Receipt reads use the full stored ID, including `provider/<provider>/` for named providers.
[in]	cells	Array of count target cells; may be NULL when count=0.
[in]	count	Nonnegative number of receipt records to retrieve.
[out]	out	Caller-owned array of count receipts; may be NULL when count=0.
[out]	requested_species	Row-major [count][species_count] requested amounts in native concentration-unit*m3; may be NULL when either dimension is zero.
[out]	applied_species	Row-major [count][species_count] applied amounts in the same order/units; may be NULL when either dimension is zero.
[in]	species_count	Exact number of transport rows in the selected domain, including reserved temperature and age rows.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE when runtime reads are unavailable, SWMM_ERR_BADPARAM for invalid domain/output/species count, or SWMM_ERR_BADINDEX for a missing record.

◆ swmm_coupling_get_water_totals()

SWMM_ENGINE_API int swmm_coupling_get_water_totals	(	SWMM_Engine	engine,
		int	domain,
		double *	incoming_m3,
		double *	outgoing_m3 )

Sum gross cumulative external source inflow and outflow for a domain.

Sums stored source receipt rows, including their retained history. Surface hydraulic boundary exchange has a separate boundary ledger and is excluded.

Parameters

[in]	engine	Non-null live engine with the selected mesh domain active; exclusive access is required.
[in]	domain	SWMM_COUPLING_SURFACE (0) or SWMM_COUPLING_GROUNDWATER (1).
[out]	incoming_m3	Non-null destination for cumulative gross incoming water in m3.
[out]	outgoing_m3	Non-null destination for cumulative gross outgoing water in m3.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for unavailable domain/runtime access, or SWMM_ERR_BADPARAM for invalid domain/null outputs.

◆ swmm_coupling_set_source()

SWMM_ENGINE_API int swmm_coupling_set_source	(	SWMM_Engine	engine,
		const char *	id,
		int	domain,
		int	cell,
		double	flow_m3_s,
		double	heat_w,
		const double *	concentrations,
		const double *	rates,
		int	species_count,
		double	until_seconds )

Replace one copied legacy source prescription without altering species topology.

Equivalent to swmm_coupling_set_sources() with one row. Replacing the same ID/cell retains its cumulative receipts. Groundwater addresses the saturated zone; matching an authored well ID overrides that well in this cell, while distinct IDs add.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	id	Non-null NUL-terminated source ID. Set/clear APIs refuse empty IDs and the reserved boundary/ and provider/ prefixes. Receipt reads use the full stored ID, including `provider/<provider>/` for named providers.
[in]	domain	SWMM_COUPLING_SURFACE (0) or SWMM_COUPLING_GROUNDWATER (1).
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[in]	flow_m3_s	Finite signed water rate in m3/s, positive INTO the domain. Negative flow extracts donor water quality.
[in]	heat_w	Finite signed water sensible-heat rate in W; nonzero requires a temperature row. Does not prescribe soil conduction or storage.
[in]	concentrations	Copied array of species_count concentrations in domain row order; required when the count is nonzero. Values must be finite and nonnegative except temperature, which may be negative. Age is seconds; temperature is degrees C; other rows match the domain concentration getter.
[in]	rates	Copied array of species_count finite signed concentration-unit*m3/s rates. Negative removes available mass. Reserved temperature/age rates must be zero; required when count is nonzero.
[in]	species_count	Exact number of transport rows in the selected domain, including reserved temperature and age rows.
[in]	until_seconds	Finite absolute elapsed simulation expiry time in seconds, strictly later than the current coupling time; zero holds until clear.

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

◆ swmm_coupling_set_sources()

SWMM_ENGINE_API int swmm_coupling_set_sources	(	SWMM_Engine	engine,
		const SWMM_CouplingSource *	sources,
		int	count )

Atomically replace a batch of legacy source ID/cell prescriptions.

No cell/species topology changes are permitted. All rows are validated before pending old physics is flushed and the batch is published. Unlisted sources remain active; receipts for replaced rows are retained. Uses an unnamed-provider frame.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	sources	Copied array of count rows with struct_size=sizeof(SWMM_CouplingSource); may be NULL only when count=0.
[in]	count	Nonnegative row count. Duplicate (domain,id,cell) entries are refused.

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_gw2d_clear_runtime_boundary()

SWMM_ENGINE_API int swmm_gw2d_clear_runtime_boundary	(	SWMM_Engine	engine,
		int	cell,
		int	edge )

Restore native no-flow on a legacy-owned groundwater perimeter edge.

Equivalent to kind=0 in swmm_gw2d_set_runtime_boundary(). Preserves accumulated receipts; clearing an already native edge succeeds unless an authored/other-provider boundary prevents the operation.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[in]	edge	Zero-based local cell edge. Must be a perimeter edge with positive length and center distance.

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

◆ swmm_gw2d_get_runtime_boundary_flow()

SWMM_ENGINE_API int swmm_gw2d_get_runtime_boundary_flow	(	SWMM_Engine	engine,
		int	cell,
		int	edge,
		double *	flow_m3_s )

Read the last accepted outward groundwater boundary discharge.

Cumulative history is retained separately by swmm_coupling_get_boundary_receipt(). The groundwater domain must be active and cover the cell.

Parameters

[in]	engine	Non-null live engine with the selected mesh domain active; exclusive access is required.
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[in]	edge	Zero-based local cell edge. Must be a perimeter edge with positive length and center distance.
[out]	flow_m3_s	Non-null destination in outward m3/s; zero for native no-flow or a cleared boundary.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE when runtime reads are unavailable, SWMM_ERR_BADPARAM for invalid domain/output/species count, or SWMM_ERR_BADINDEX for an invalid cell or local edge.

◆ swmm_gw2d_set_runtime_boundary()

SWMM_ENGINE_API int swmm_gw2d_set_runtime_boundary	(	SWMM_Engine	engine,
		int	cell,
		int	edge,
		int	kind,
		double	value,
		const double *	concentrations,
		int	species_count )

Install or clear a saturated groundwater perimeter head or outward flow.

A head prescription uses a one-sided unconfined Darcy face. Incoming water carries the supplied quality; outgoing water uses donor quality. No solute diffusion or soil thermal boundary is implied. Authored aquifer boundary entries on the same edge are refused. Receipt ID is boundary/<cell>/<edge>; a different provider owning this edge prevents replacement.

Parameters

[in]	engine	Non-null RUNNING engine with a supported CPU mesh backend. Call between steps or from a permitted step callback.
[in]	cell	Zero-based mesh cell index; groundwater must cover this cell with positive saturated thickness.
[in]	edge	Zero-based local cell edge. Must be a perimeter edge with positive length and center distance.
[in]	kind	0 restores native no-flow, 1 prescribes datum head, 2 prescribes outward flow.
[in]	value	Finite datum head in m for kind=1 or total outward m3/s for kind=2; ignored for kind=0.
[in]	concentrations	Copied array of species_count concentrations in domain row order; required when the count is nonzero. Values must be finite and nonnegative except temperature, which may be negative. Age is seconds; temperature is degrees C; other rows match the domain concentration getter.
[in]	species_count	Exact groundwater transport row count for kind 1/2; must be zero for kind=0 (concentrations may then be NULL).

Returns: SWMM_OK on acceptance; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE for an unavailable state/domain, SWMM_ERR_PLUGIN for an unsupported runtime profile, SWMM_ERR_BADPARAM for invalid tuples/ownership conflicts, SWMM_ERR_BADINDEX for invalid cells/edges or a missing clear target, or SWMM_ERR_NOMEM/SWMM_ERR_INTERNAL for exceptions. Refusal preserves prescriptions and clocks.

Here is the call graph for this function:

Here is the caller graph for this function:

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SWMM_COUPLING_EVAPORATION

◆ SWMM_COUPLING_FRAME_VERSION

◆ SWMM_COUPLING_GROUNDWATER

◆ SWMM_COUPLING_INFILTRATION

◆ SWMM_COUPLING_RAIN_QUALITY

◆ SWMM_COUPLING_RAINFALL

◆ SWMM_COUPLING_SURFACE

Typedef Documentation

◆ SWMM_CouplingBoundary

◆ SWMM_CouplingClear

◆ SWMM_CouplingForcing

◆ SWMM_CouplingFrame

◆ SWMM_CouplingReceipt

◆ SWMM_CouplingSource

Function Documentation

◆ swmm_2d_get_species_ledger()

◆ swmm_2d_set_runtime_boundary()

◆ swmm_coupling_advance_to()

◆ swmm_coupling_apply_frame()

◆ swmm_coupling_capabilities()

◆ swmm_coupling_clear_source()

◆ swmm_coupling_clear_source_cell()

◆ swmm_coupling_get_boundary_receipt()

◆ swmm_coupling_get_infiltration_receipt()

◆ swmm_coupling_get_receipt()

◆ swmm_coupling_get_receipts()

◆ swmm_coupling_get_water_totals()

◆ swmm_coupling_set_source()

◆ swmm_coupling_set_sources()

◆ swmm_gw2d_clear_runtime_boundary()

◆ swmm_gw2d_get_runtime_boundary_flow()

◆ swmm_gw2d_set_runtime_boundary()