C API implementation — continuity errors and flux totals. More...

#include <cmath>
#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_massbalance.h"

Include dependency graph for openswmm_massbalance_impl.cpp:

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

C API implementation — continuity errors and flux totals.

See also: include/openswmm/engine/openswmm_massbalance.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

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.

Functions

Detailed Description

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