OpenSWMM Engine — Mass Balance / Continuity C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_massbalance.h:

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

Typedefs
typedef enum SWMM_RunoffTotal	SWMM_RunoffTotal
	Runoff mass balance component codes.

typedef enum SWMM_RoutingTotal	SWMM_RoutingTotal
	Routing mass balance component codes.

Enumerations
enum	SWMM_RunoffTotal { SWMM_RUNOFF_RAINFALL = 0 , SWMM_RUNOFF_EVAP = 1 , SWMM_RUNOFF_INFIL = 2 , SWMM_RUNOFF_RUNOFF = 3 , SWMM_RUNOFF_SNOWREMOV = 4 , SWMM_RUNOFF_INITSTORE = 5 , SWMM_RUNOFF_FINALSTORE = 6 , SWMM_RUNOFF_INITSNOW = 7 , SWMM_RUNOFF_FINALSNOW = 8 }
	Runoff mass balance component codes. More...

enum	SWMM_RoutingTotal { SWMM_ROUTING_DRY_WEATHER = 0 , SWMM_ROUTING_WET_WEATHER = 1 , SWMM_ROUTING_GW_INFLOW = 2 , SWMM_ROUTING_RDII = 3 , SWMM_ROUTING_EXTERNAL = 4 , SWMM_ROUTING_FLOODING = 5 , SWMM_ROUTING_OUTFLOW = 6 , SWMM_ROUTING_EVAP_LOSS = 7 , SWMM_ROUTING_SEEP_LOSS = 8 , SWMM_ROUTING_INIT_STORAGE = 9 , SWMM_ROUTING_FINAL_STORAGE = 10 , SWMM_ROUTING_FORCING_INFLOW = 11 , SWMM_ROUTING_LINK_GW_INFLOW = 13 , SWMM_ROUTING_COUPLING_OUT = 12 }
	Routing mass balance component codes. More...

Functions
SWMM_ENGINE_API int	swmm_get_runoff_continuity_error (SWMM_Engine engine, double *error)
	Compute the signed runoff water-continuity residual fraction.

SWMM_ENGINE_API int	swmm_get_routing_continuity_error (SWMM_Engine engine, double *error)
	Compute the signed routing water-continuity residual fraction.

SWMM_ENGINE_API int	swmm_get_quality_continuity_error (SWMM_Engine engine, int pollutant_idx, double *error)
	Compute a pollutant routing-continuity residual from stored mass totals.

SWMM_ENGINE_API int	swmm_get_runoff_total (SWMM_Engine engine, int component, double *volume)
	Read a stored runoff water-balance volume.

SWMM_ENGINE_API int	swmm_get_routing_total (SWMM_Engine engine, int component, double *volume)
	Read a stored routing water-balance volume.

SWMM_ENGINE_API int	swmm_get_routing_stats (SWMM_Engine engine, double avg_step, double min_step, double max_step, int n_steps, double pct_non_converged, double avg_iterations, double *max_courant)
	Read accumulated routing timestep and convergence diagnostics.

SWMM_ENGINE_API int	swmm_get_max_courant (SWMM_Engine engine, double *max_courant)
	Read the largest recorded routing Courant number.

SWMM_ENGINE_API int	swmm_get_quality_seep_loss (SWMM_Engine engine, int pollutant_idx, double *mass)
	Read cumulative pollutant amount booked to seepage.

SWMM_ENGINE_API int	swmm_get_quality_evap_loss (SWMM_Engine engine, int pollutant_idx, double *mass)
	Read cumulative pollutant amount booked to evaporation.

Detailed Description

OpenSWMM Engine — Mass Balance / Continuity C API.

Query continuity errors and cumulative flux totals for runoff, routing, and water quality. Finalized after SWMM_STATE_ENDED; getters also permit intermediate reads.

See also: openswmm_engine.h

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

Copyright: Copyright (c) 2026 Caleb Buahin. All rights reserved.

License: Apache-2.0

Typedef Documentation

◆ SWMM_RoutingTotal

typedef enum SWMM_RoutingTotal SWMM_RoutingTotal

Routing mass balance component codes.

◆ SWMM_RunoffTotal

typedef enum SWMM_RunoffTotal SWMM_RunoffTotal

Runoff mass balance component codes.

Enumeration Type Documentation

◆ SWMM_RoutingTotal

enum SWMM_RoutingTotal

Routing mass balance component codes.

Enumerator
SWMM_ROUTING_DRY_WEATHER	Cumulative dry weather inflow volume.
SWMM_ROUTING_WET_WEATHER	Cumulative wet weather (runoff) inflow volume.
SWMM_ROUTING_GW_INFLOW	Cumulative groundwater inflow volume.
SWMM_ROUTING_RDII	Cumulative rainfall-dependent I/I volume.
SWMM_ROUTING_EXTERNAL	Cumulative external (user-defined) inflow volume.
SWMM_ROUTING_FLOODING	Cumulative flooding (surcharge overflow) volume.
SWMM_ROUTING_OUTFLOW	Cumulative outfall discharge volume.
SWMM_ROUTING_EVAP_LOSS	Cumulative evaporation loss from conveyance.
SWMM_ROUTING_SEEP_LOSS	Cumulative seepage loss from conveyance.
SWMM_ROUTING_INIT_STORAGE	Initial in-system storage volume.
SWMM_ROUTING_FINAL_STORAGE	Final in-system storage volume.
SWMM_ROUTING_FORCING_INFLOW	Cumulative runtime-API forced lateral inflow volume (i.e. flow injected via `swmm_node_set_lateral_inflow` or transient ForcingData). A subset of `SWMM_ROUTING_EXTERNAL`, which also counts INP `[INFLOWS]`-derived, interface-file, and 2D-coupling inflow (issue #113).
SWMM_ROUTING_LINK_GW_INFLOW	G-X4 (2026-09-20): cumulative volume the two-zone [2D_AQUIFER] handed to conduits below the water table (gaining reaches). The negative half of the signed conduit seepage; the losing half stays SWMM_ROUTING_SEEP_LOSS.
SWMM_ROUTING_COUPLING_OUT	C2 (2026-09-07): cumulative volume the 1D→2D coupling spill removed from coupled nodes. Previously folded into `SWMM_ROUTING_FLOODING`, which reported a coupling TRANSFER as flooding. It is still an OUTFLOW of the 1D system and still enters the routing continuity error, so a host summing the outflow categories must now add this one too. Zero (and the volume stays in `SWMM_ROUTING_FLOODING`) under `[2D_OPTIONS] COUPLING_IN_FLOODING YES`.

◆ SWMM_RunoffTotal

enum SWMM_RunoffTotal

Runoff mass balance component codes.

Enumerator
SWMM_RUNOFF_RAINFALL	Cumulative rainfall volume.
SWMM_RUNOFF_EVAP	Cumulative evaporation loss.
SWMM_RUNOFF_INFIL	Cumulative infiltration loss.
SWMM_RUNOFF_RUNOFF	Cumulative surface runoff volume.
SWMM_RUNOFF_SNOWREMOV	Cumulative snow removal volume.
SWMM_RUNOFF_INITSTORE	Initial surface storage volume.
SWMM_RUNOFF_FINALSTORE	Final surface storage volume.
SWMM_RUNOFF_INITSNOW	Initial snow cover volume (SWE + free water).
SWMM_RUNOFF_FINALSNOW	Final snow cover volume (SWE + free water).

Function Documentation

◆ swmm_get_max_courant()

SWMM_ENGINE_API int swmm_get_max_courant	(	SWMM_Engine	engine,
		double *	max_courant )

Read the largest recorded routing Courant number.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[out]	max_courant	Optional destination for the dimensionless maximum; initialized value is zero.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_quality_continuity_error()

SWMM_ENGINE_API int swmm_get_quality_continuity_error	(	SWMM_Engine	engine,
		int	pollutant_idx,
		double *	error )

Compute a pollutant routing-continuity residual from stored mass totals.

Sums the implementation wet-deposition/runoff/wet/RDII/dry-weather/external inflow terms plus initial storage against outflow/flooding/reaction and final storage. Residuals below 0.001 native amount are zeroed; otherwise divides by input when positive, or output when only output is positive. This function does not apply a percent conversion.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[in]	pollutant_idx	Zero-based pollutant row; an unavailable/negative row writes zero and still succeeds.
[out]	error	Optional signed residual fraction; NULL returns success after checking the engine.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_quality_evap_loss()

SWMM_ENGINE_API int swmm_get_quality_evap_loss	(	SWMM_Engine	engine,
		int	pollutant_idx,
		double *	mass )

Read cumulative pollutant amount booked to evaporation.

Returns the stored loss entry only; does not infer additional losses from water fluxes or current concentrations.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[in]	pollutant_idx	Zero-based native pollutant-ledger row; out-of-range or negative rows return zero without an index error.
[out]	mass	Optional destination for the raw stored quality-ledger amount. Routing ledger amounts use internal water volume (ft3) times the concentration row unit; no pollutant/display-mass conversion is applied here.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_quality_seep_loss()

SWMM_ENGINE_API int swmm_get_quality_seep_loss	(	SWMM_Engine	engine,
		int	pollutant_idx,
		double *	mass )

Read cumulative pollutant amount booked to seepage.

Returns the stored loss entry only; does not infer additional losses from water fluxes or current concentrations.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[in]	pollutant_idx	Zero-based native pollutant-ledger row; out-of-range or negative rows return zero without an index error.
[out]	mass	Optional destination for the raw stored quality-ledger amount. Routing ledger amounts use internal water volume (ft3) times the concentration row unit; no pollutant/display-mass conversion is applied here.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_routing_continuity_error()

SWMM_ENGINE_API int swmm_get_routing_continuity_error	(	SWMM_Engine	engine,
		double *	error )

Compute the signed routing water-continuity residual fraction.

Uses the current stored balance totals without converting units or updating final storage. A running query may therefore differ from the finalized end-of-run balance.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[out]	error	Optional fraction output, e.g. 0.001 means 0.1%. Positive indicates accounted input exceeds output/storage; zero when total input including initial storage is nonpositive.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_routing_stats()

SWMM_ENGINE_API int swmm_get_routing_stats	(	SWMM_Engine	engine,
		double *	avg_step,
		double *	min_step,
		double *	max_step,
		int *	n_steps,
		double *	pct_non_converged,
		double *	avg_iterations,
		double *	max_courant )

Read accumulated routing timestep and convergence diagnostics.

All output pointers may be NULL independently; this getter does not advance or finalize the simulation.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[out]	avg_step	Optional mean physical routing step in seconds; zero when no steps are counted.
[out]	min_step	Optional minimum step in seconds; the uninitialized sentinel is returned as zero.
[out]	max_step	Optional maximum step in seconds.
[out]	n_steps	Optional number of counted routing steps, converted to int.
[out]	pct_non_converged	Optional percent of counted steps that did not converge, in [0,100] under normal accounting.
[out]	avg_iterations	Optional mean solver iterations per counted step.
[out]	max_courant	Optional maximum recorded Courant number (dimensionless).

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_routing_total()

SWMM_ENGINE_API int swmm_get_routing_total	(	SWMM_Engine	engine,
		int	component,
		double *	volume )

Read a stored routing water-balance volume.

Includes cumulative flux and initial/final storage selectors. The value is read directly from the current mass-balance accumulator; final storage is only as current as the last balance update.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[in]	component	SWMM_RoutingTotal selector declared in this header.
[out]	volume	Non-null destination in internal cubic feet (ft3), regardless of project display units. No display-volume conversion is performed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null volume/unknown component.

◆ swmm_get_runoff_continuity_error()

SWMM_ENGINE_API int swmm_get_runoff_continuity_error	(	SWMM_Engine	engine,
		double *	error )

Compute the signed runoff water-continuity residual fraction.

Uses the current stored balance totals without converting units or updating final storage. A running query may therefore differ from the finalized end-of-run balance.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[out]	error	Optional fraction output, e.g. 0.001 means 0.1%. Positive indicates accounted input exceeds output/storage; zero when total input including initial storage is nonpositive.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_get_runoff_total()

SWMM_ENGINE_API int swmm_get_runoff_total	(	SWMM_Engine	engine,
		int	component,
		double *	volume )

Read a stored runoff water-balance volume.

Includes cumulative flux and initial/final storage selectors. The value is read directly from the current mass-balance accumulator; final storage is only as current as the last balance update.

Parameters

[in]	engine	Non-null live engine. No lifecycle guard is imposed; final totals are available after end, and running reads reflect currently accumulated state.
[in]	component	SWMM_RunoffTotal selector declared in this header.
[out]	volume	Non-null destination in internal cubic feet (ft3), regardless of project display units. No display-volume conversion is performed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null volume/unknown component.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ SWMM_RoutingTotal

◆ SWMM_RunoffTotal

Enumeration Type Documentation

◆ SWMM_RoutingTotal

◆ SWMM_RunoffTotal

Function Documentation

◆ swmm_get_max_courant()

◆ swmm_get_quality_continuity_error()

◆ swmm_get_quality_evap_loss()

◆ swmm_get_quality_seep_loss()

◆ swmm_get_routing_continuity_error()

◆ swmm_get_routing_stats()

◆ swmm_get_routing_total()

◆ swmm_get_runoff_continuity_error()

◆ swmm_get_runoff_total()