C API implementation — external inflows, DWF, RDII. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_inflows.h"
#include "../data/InflowData.hpp"
#include "../edit/ObjectDeleter.hpp"
#include <algorithm>
#include <cstring>
#include <string>
#include <vector>

Include dependency graph for openswmm_inflows_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_ext_inflow_add (SWMM_Engine engine, int node_idx, const char constituent, const char ts_name, const char type, double m_factor, double s_factor, double baseline, const char pattern)
	Add an external inflow to a node.

SWMM_ENGINE_API int	swmm_ext_inflow_set_scale (SWMM_Engine engine, int entry_idx, double scale)
	Replace an external-inflow timeseries scale factor.

SWMM_ENGINE_API int	swmm_ext_inflow_set_baseline (SWMM_Engine engine, int entry_idx, double baseline)
	Replace one external-inflow baseline.

SWMM_ENGINE_API int	swmm_ext_inflow_get (SWMM_Engine engine, int entry_idx, int node_idx, char constituent_buf, int constituent_buflen, char ts_buf, int ts_buflen, char type_buf, int type_buflen, double m_factor, double s_factor, double baseline, char pattern_buf, int pattern_buflen)
	Read back an external inflow entry by index.

SWMM_ENGINE_API int	swmm_ext_inflow_remove (SWMM_Engine engine, int entry_idx)
	Remove an external inflow entry by index.

SWMM_ENGINE_API int	swmm_dwf_add (SWMM_Engine engine, int node_idx, const char constituent, double avg_value, const char pat1, const char pat2, const char pat3, const char *pat4)
	Add a dry weather flow component to a node.

SWMM_ENGINE_API int	swmm_dwf_get (SWMM_Engine engine, int entry_idx, int node_idx, char constituent_buf, int constituent_buflen, double avg_value, char pat1_buf, int pat1_buflen, char pat2_buf, int pat2_buflen, char pat3_buf, int pat3_buflen, char *pat4_buf, int pat4_buflen)
	Read back a dry weather flow entry by index.

SWMM_ENGINE_API int	swmm_dwf_remove (SWMM_Engine engine, int entry_idx)
	Remove a DWF entry by index. Subsequent entries shift down.

SWMM_ENGINE_API int	swmm_dwf_set_baseline (SWMM_Engine engine, int entry_idx, double avg_value)
	Replace one dry-weather-flow average value.

SWMM_ENGINE_API int	swmm_rdii_add (SWMM_Engine engine, int node_idx, const char *uh_name, double area)
	Add RDII inflow to a node using a unit hydrograph.

SWMM_ENGINE_API int	swmm_rdii_get (SWMM_Engine engine, int entry_idx, int node_idx, char uh_buf, int buflen, double *area)
	Read back an RDII assignment by entry index.

SWMM_ENGINE_API int	swmm_rdii_remove (SWMM_Engine engine, int entry_idx)
	Remove an RDII entry by index. Subsequent entries shift down.

SWMM_ENGINE_API int	swmm_hydrograph_add (SWMM_Engine engine, const char *uh_name, int month, int response, double r, double t, double k, double dmax, double drecov, double dinit)
	Add a unit hydrograph parameter line.

SWMM_ENGINE_API int	swmm_hydrograph_get (SWMM_Engine engine, int entry_idx, char uh_buf, int buflen, int month, int response, double r, double t, double k, double dmax, double drecov, double *dinit)
	Read back a hydrograph parameter entry by index.

SWMM_ENGINE_API int	swmm_hydrograph_count (SWMM_Engine engine)
	Count stored hydrograph parameter rows, including duplicate keys.

SWMM_ENGINE_API int	swmm_hydrograph_add_gage (SWMM_Engine engine, const char uh_name, const char gage_name)
	Assign a rain gage to a unit hydrograph group.

SWMM_ENGINE_API int	swmm_hydrograph_get_gage (SWMM_Engine engine, int entry_idx, char uh_buf, int uh_buflen, char gage_buf, int gage_buflen)
	Read back a UH-to-gage assignment by index.

SWMM_ENGINE_API int	swmm_hydrograph_gage_count (SWMM_Engine engine)
	Count stored hydrograph-to-gage assignment rows.

SWMM_ENGINE_API int	swmm_hydrograph_group_count (SWMM_Engine engine)
	Count the unique unit-hydrograph group names defined.

SWMM_ENGINE_API int	swmm_hydrograph_group_id (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read back the name of a unit-hydrograph group by its zero-based index.

SWMM_ENGINE_API int	swmm_rdii_decay_add (SWMM_Engine engine, const char *uh_name, int response, double k_dep, double k_0, double k_T, double T_ref, double theta_rec, double T_freeze, int snow_on, double snow_T, double snow_ddf)
	Append an exponential-depletion and temperature-dependent IA-recovery row.

SWMM_ENGINE_API int	swmm_rdii_decay_get (SWMM_Engine engine, int entry_idx, char uh_buf, int buflen, int response, double k_dep, double k_0, double k_T, double T_ref, double theta_rec, double T_freeze, int snow_on, double snow_T, double *snow_ddf)
	Read back an exponential-decay parameter row by index.

SWMM_ENGINE_API int	swmm_rdii_decay_count (SWMM_Engine engine)
	Count stored exponential-decay rows.

SWMM_ENGINE_API int	swmm_hydrograph_set_rtk (SWMM_Engine engine, const char *uh_name, int month, int response, double r, double t, double k)
	Upsert R/T/K parameters for one (group, month, response) row.

SWMM_ENGINE_API int	swmm_hydrograph_set_ia (SWMM_Engine engine, const char *uh_name, int month, int response, double dmax, double drecov, double dinit)
	Upsert linear-IA parameters for one (group, month, response) row.

SWMM_ENGINE_API int	swmm_hydrograph_remove_entry (SWMM_Engine engine, const char *uh_name, int month, int response)
	Remove the first matching hydrograph parameter row.

SWMM_ENGINE_API int	swmm_hydrograph_remove_group (SWMM_Engine engine, const char *uh_name)
	Remove all authoring rows and RDII assignments for a hydrograph group.

SWMM_ENGINE_API int	swmm_hydrograph_clear_group_months (SWMM_Engine engine, const char *uh_name)
	Remove a group's month-specific parameter rows while retaining ALL rows.

SWMM_ENGINE_API int	swmm_hydrograph_set_gage (SWMM_Engine engine, const char uh_name, const char gage_name)
	Set, replace, or clear the rain gage assigned to a UH group.

SWMM_ENGINE_API int	swmm_hydrograph_group_rename (SWMM_Engine engine, int idx, const char *new_id)
	Rename a UH group, propagating the new name to parameter rows, gage assignments, [RDII_DECAY] rows, and [RDII] node assignments.

SWMM_ENGINE_API int	swmm_rdii_decay_set (SWMM_Engine engine, const char *uh_name, int response, double k_dep, double k_0, double k_T, double T_ref, double theta_rec, double T_freeze, int snow_on, double snow_T, double snow_ddf)
	Upsert an exponential-depletion and temperature-dependent IA-recovery row.

SWMM_ENGINE_API int	swmm_rdii_decay_remove (SWMM_Engine engine, const char *uh_name, int response)
	Remove the first exponential-decay row matching a group and response.

SWMM_ENGINE_API int	swmm_ext_inflow_count (SWMM_Engine engine)
	Get the total number of external inflows defined.

SWMM_ENGINE_API int	swmm_dwf_count (SWMM_Engine engine)
	Get the total number of dry weather flow entries defined.

SWMM_ENGINE_API int	swmm_rdii_count (SWMM_Engine engine)
	Get the total number of RDII entries defined.

Detailed Description

C API implementation — external inflows, DWF, RDII.

See also: include/openswmm/engine/openswmm_inflows.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_dwf_add()

SWMM_ENGINE_API int swmm_dwf_add	(	SWMM_Engine	engine,
		int	node_idx,
		const char *	constituent,
		double	avg_value,
		const char *	pat1,
		const char *	pat2,
		const char *	pat3,
		const char *	pat4 )

Add a dry weather flow component to a node.

Dry weather flow represents the base sanitary flow entering the system at a node, modulated by up to four time patterns.

Parameters

[in]	engine	Engine handle.
[in]	node_idx	Zero-based index of the receiving node.
[in]	constituent	Constituent name ("FLOW" or a pollutant name).
[in]	avg_value	Average DWF value.
[in]	pat1	Monthly time pattern name (NULL for none).
[in]	pat2	Daily time pattern name (NULL for none).
[in]	pat3	Hourly time pattern name (NULL for none).
[in]	pat4	Weekend time pattern name (NULL for none).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard; mutations rebuild the inflow cache outside BUILDING/OPENED. Input strings are copied; unresolved names and numeric values are stored without validation here.

Here is the call graph for this function:

◆ swmm_dwf_count()

SWMM_ENGINE_API int swmm_dwf_count ( SWMM_Engine engine )

Get the total number of dry weather flow entries defined.

Parameters

[in] engine Engine handle.

Returns: Number of DWF entries, or -1 on error.

◆ swmm_dwf_get()

SWMM_ENGINE_API int swmm_dwf_get	(	SWMM_Engine	engine,
		int	entry_idx,
		int *	node_idx,
		char *	constituent_buf,
		int	constituent_buflen,
		double *	avg_value,
		char *	pat1_buf,
		int	pat1_buflen,
		char *	pat2_buf,
		int	pat2_buflen,
		char *	pat3_buf,
		int	pat3_buflen,
		char *	pat4_buf,
		int	pat4_buflen )

Read back a dry weather flow entry by index.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based entry index (0..swmm_dwf_count()-1).
[out]	node_idx	Receiving node index.
[in]	constituent_buf	Constituent name (NUL-terminated).
[in]	constituent_buflen	Size of `constituent_buf`.
[out]	avg_value	Average value.
[out]	pat1_buf	Monthly pattern name (NUL-terminated; empty if none).
[in]	pat1_buflen	Size of `pat1_buf`.
[out]	pat2_buf	Daily pattern name.
[in]	pat2_buflen	Size of `pat2_buf`.
[out]	pat3_buf	Hourly pattern name.
[in]	pat3_buflen	Size of `pat3_buf`.
[out]	pat4_buf	Weekend pattern name.
[in]	pat4_buflen	Size of `pat4_buf`.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Every declared output pointer is required; every text capacity must be positive, otherwise SWMM_ERR_BADPARAM. Text is copied into caller-owned buffers, NUL-terminated and silently truncated to capacity minus one byte.

Here is the call graph for this function:

◆ swmm_dwf_remove()

SWMM_ENGINE_API int swmm_dwf_remove	(	SWMM_Engine	engine,
		int	entry_idx )

Remove a DWF entry by index. Subsequent entries shift down.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based entry index (0..swmm_dwf_count()-1).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard; mutations rebuild the inflow cache outside BUILDING/OPENED. Input strings are copied; unresolved names and numeric values are stored without validation here.

Here is the call graph for this function:

◆ swmm_dwf_set_baseline()

SWMM_ENGINE_API int swmm_dwf_set_baseline	(	SWMM_Engine	engine,
		int	entry_idx,
		double	avg_value )

Replace one dry-weather-flow average value.

Rebuilds the inflow cache in states other than BUILDING/OPENED; preserves all four pattern bindings.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	entry_idx	Zero-based existing row index in the corresponding flat entry list.
[in]	avg_value	Average constituent value in input/display units (project flow units for FLOW); no finite/range validation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_ext_inflow_add()

SWMM_ENGINE_API int swmm_ext_inflow_add	(	SWMM_Engine	engine,
		int	node_idx,
		const char *	constituent,
		const char *	ts_name,
		const char *	type,
		double	m_factor,
		double	s_factor,
		double	baseline,
		const char *	pattern )

Add an external inflow to a node.

External inflows define time-varying flows or pollutant loads applied at a node, optionally driven by a time series, with scaling, baseline, and pattern modifiers.

Parameters

[in]	engine	Engine handle.
[in]	node_idx	Zero-based index of the receiving node.
[in]	constituent	Constituent name ("FLOW" for flow, a pollutant name, or the reserved species "__WATER_AGE__" — such a row prescribes the AGE, in HOURS, carried by the node's external inflow water, and wins over the [WATER_AGE_SOURCES] EXTERNAL_INFLOW entry (Z1, amendment D-Y4). It adds no water and no mass.
[in]	ts_name	Time series name (NULL or "" for constant baseline only).
[in]	type	Inflow type: "FLOW", "CONCEN", or "MASS".
[in]	m_factor	Multiplier applied to the time series values.
[in]	s_factor	Scale factor (unit conversion).
[in]	baseline	Constant baseline value added to the time series.
[in]	pattern	Time pattern name (NULL or "" for none).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard; mutations rebuild the inflow cache outside BUILDING/OPENED. Input strings are copied; unresolved names and numeric values are stored without validation here. A null type defaults to FLOW; constituent must be non-null. Appends a row rather than replacing an existing constituent/node pair.

Here is the call graph for this function:

◆ swmm_ext_inflow_count()

SWMM_ENGINE_API int swmm_ext_inflow_count ( SWMM_Engine engine )

Get the total number of external inflows defined.

Parameters

[in] engine Engine handle.

Returns: Number of external inflows, or -1 on error.

◆ swmm_ext_inflow_get()

SWMM_ENGINE_API int swmm_ext_inflow_get	(	SWMM_Engine	engine,
		int	entry_idx,
		int *	node_idx,
		char *	constituent_buf,
		int	constituent_buflen,
		char *	ts_buf,
		int	ts_buflen,
		char *	type_buf,
		int	type_buflen,
		double *	m_factor,
		double *	s_factor,
		double *	baseline,
		char *	pattern_buf,
		int	pattern_buflen )

Read back an external inflow entry by index.

The model stores external inflows as a flat SoA, indexed 0..swmm_ext_inflow_count()-1. To list a single node's inflows, iterate all entries and filter by node_idx.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based entry index.
[out]	node_idx	Receiving node index.
[in]	constituent_buf	Constituent name buffer (NUL-terminated).
[in]	constituent_buflen	Size of `constituent_buf`.
[out]	ts_buf	Time series name buffer (NUL-terminated; empty if none).
[in]	ts_buflen	Size of `ts_buf`.
[out]	type_buf	Inflow type buffer (NUL-terminated; "FLOW"/"CONCEN"/"MASS").
[in]	type_buflen	Size of `type_buf`.
[out]	m_factor	Multiplier factor.
[out]	s_factor	Scale factor.
[out]	baseline	Baseline value.
[out]	pattern_buf	Pattern name buffer (NUL-terminated; empty if none).
[in]	pattern_buflen	Size of `pattern_buf`.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Every declared output pointer is required; every text capacity must be positive, otherwise SWMM_ERR_BADPARAM. Text is copied into caller-owned buffers, NUL-terminated and silently truncated to capacity minus one byte.

Here is the call graph for this function:

◆ swmm_ext_inflow_remove()

SWMM_ENGINE_API int swmm_ext_inflow_remove	(	SWMM_Engine	engine,
		int	entry_idx )

Remove an external inflow entry by index.

Entries with index > entry_idx shift down by one. Callers holding cached indices must re-resolve via swmm_ext_inflow_count() / iteration.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based entry index (0..swmm_ext_inflow_count()-1).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard; mutations rebuild the inflow cache outside BUILDING/OPENED. Input strings are copied; unresolved names and numeric values are stored without validation here.

Here is the call graph for this function:

◆ swmm_ext_inflow_set_baseline()

SWMM_ENGINE_API int swmm_ext_inflow_set_baseline	(	SWMM_Engine	engine,
		int	entry_idx,
		double	baseline )

Replace one external-inflow baseline.

Rebuilds the inflow cache in states other than BUILDING/OPENED. Does not change the timeseries, pattern or scale factors.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	entry_idx	Zero-based existing row index in the corresponding flat entry list.
[in]	baseline	Constant baseline in the constituent input/display units; no finite/range validation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_ext_inflow_set_scale()

SWMM_ENGINE_API int swmm_ext_inflow_set_scale	(	SWMM_Engine	engine,
		int	entry_idx,
		double	scale )

Replace an external-inflow timeseries scale factor.

Rebuilds the inflow cache in states other than BUILDING/OPENED so subsequent evaluation uses the new value. Does not change m_factor, baseline or other entries.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	entry_idx	Zero-based existing row index in the corresponding flat entry list.
[in]	scale	Stored s_factor, used in the constituent input-unit conversion; no finite/range validation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_hydrograph_add()

SWMM_ENGINE_API int swmm_hydrograph_add	(	SWMM_Engine	engine,
		const char *	uh_name,
		int	month,
		int	response,
		double	r,
		double	t,
		double	k,
		double	dmax,
		double	drecov,
		double	dinit )

Add a unit hydrograph parameter line.

Parameters

[in]	engine	Engine handle.
[in]	uh_name	Unit hydrograph group name.
[in]	month	0..11 = JAN..DEC, or -1 for ALL months.
[in]	response	0 = SHORT, 1 = MEDIUM, 2 = LONG.
[in]	r	Fraction of rainfall volume that becomes RDII.
[in]	t	Time to peak (hours).
[in]	k	Ratio of recession-limb time to time-to-peak (>= 0). Base time = t * (1 + k); the falling limb spans k * t hours.
[in]	dmax	Maximum initial-abstraction depth (project depth units; 0 if unused).
[in]	drecov	Linear-model IA recovery rate (project depth/day; 0 if unused or if [RDII_DECAY] is configured).
[in]	dinit	Initial IA already used at start of simulation (project depth units; 0 if unused).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. Always appends; duplicate keys are accepted. Required name pointers must be non-null, but empty/unresolved names are not rejected. No lifecycle guard or runtime RDII cache rebuild. Only month/response codes are range-checked; RTK and abstraction values are stored without finite/range validation.

Here is the call graph for this function:

◆ swmm_hydrograph_add_gage()

SWMM_ENGINE_API int swmm_hydrograph_add_gage	(	SWMM_Engine	engine,
		const char *	uh_name,
		const char *	gage_name )

Assign a rain gage to a unit hydrograph group.

Parameters

[in]	engine	Engine handle.
[in]	uh_name	Unit hydrograph group name.
[in]	gage_name	Rain gage name.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. Always appends; duplicate keys are accepted. Required name pointers must be non-null, but empty/unresolved names are not rejected. No lifecycle guard or runtime RDII cache rebuild.

Here is the call graph for this function:

◆ swmm_hydrograph_clear_group_months()

SWMM_ENGINE_API int swmm_hydrograph_clear_group_months	(	SWMM_Engine	engine,
		const char *	uh_name )

Remove a group's month-specific parameter rows while retaining ALL rows.

Case-insensitive name comparison; retains every month=-1 row, other groups, gage assignments and decay rows. Missing groups succeed. No lifecycle guard or runtime RDII cache rebuild.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	uh_name	Non-null, nonempty copied unit-hydrograph group name; matched case-insensitively for hydrograph rows.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_hydrograph_count()

SWMM_ENGINE_API int swmm_hydrograph_count ( SWMM_Engine engine )

Count stored hydrograph parameter rows, including duplicate keys.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative row count, or -1 for a null engine.

◆ swmm_hydrograph_gage_count()

SWMM_ENGINE_API int swmm_hydrograph_gage_count ( SWMM_Engine engine )

Count stored hydrograph-to-gage assignment rows.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative row count, or -1 for a null engine.

◆ swmm_hydrograph_get()

SWMM_ENGINE_API int swmm_hydrograph_get	(	SWMM_Engine	engine,
		int	entry_idx,
		char *	uh_buf,
		int	buflen,
		int *	month,
		int *	response,
		double *	r,
		double *	t,
		double *	k,
		double *	dmax,
		double *	drecov,
		double *	dinit )

Read back a hydrograph parameter entry by index.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based index (0..swmm_hydrograph_count()-1).
[out]	uh_buf	UH group name buffer (NUL-terminated).
[in]	buflen	Size of `uh_buf`.
[out]	month	Month code (-1, or 0..11).
[out]	response	Response code (0..2).
[out]	r	Rainfall fraction.
[out]	t	Time to peak (hours).
[out]	k	Recession ratio.
[out]	dmax	IA max depth.
[out]	drecov	Linear IA recovery rate.
[out]	dinit	Initial IA used.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Every declared output pointer is required; every text capacity must be positive, otherwise SWMM_ERR_BADPARAM. Text is copied into caller-owned buffers, NUL-terminated and silently truncated to capacity minus one byte.

Here is the call graph for this function:

◆ swmm_hydrograph_get_gage()

SWMM_ENGINE_API int swmm_hydrograph_get_gage	(	SWMM_Engine	engine,
		int	entry_idx,
		char *	uh_buf,
		int	uh_buflen,
		char *	gage_buf,
		int	gage_buflen )

Read back a UH-to-gage assignment by index.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based index (0..swmm_hydrograph_gage_count()-1).
[out]	uh_buf	UH group name (NUL-terminated).
[in]	uh_buflen	Size of `uh_buf`.
[out]	gage_buf	Rain gage name (NUL-terminated).
[in]	gage_buflen	Size of `gage_buf`.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Every declared output pointer is required; every text capacity must be positive, otherwise SWMM_ERR_BADPARAM. Text is copied into caller-owned buffers, NUL-terminated and silently truncated to capacity minus one byte.

◆ swmm_hydrograph_group_count()

SWMM_ENGINE_API int swmm_hydrograph_group_count ( SWMM_Engine engine )

Count the unique unit-hydrograph group names defined.

A unit-hydrograph "group" is identified by name; the engine stores one entry per (group, month, response). This count is the number of distinct nonempty group names across parameter entries and gage assignments, useful for enumerating groups in a UI without manually de-duplicating the per-entry list.

Parameters

[in] engine Engine handle.

Returns: Number of unique groups, or -1 on error.

◆ swmm_hydrograph_group_id()

SWMM_ENGINE_API int swmm_hydrograph_group_id	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen )

Read back the name of a unit-hydrograph group by its zero-based index.

Groups are enumerated in first-occurrence order across the parameter entry list, then gage assignments; names are deduplicated case-insensitively. Gage-only groups are included; decay-only names are not.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based group index (0..swmm_hydrograph_group_count()-1).
[out]	buf	Caller-allocated buffer to receive the group name.
[in]	buflen	Size of `buf` in bytes.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Every declared output pointer is required; every text capacity must be positive, otherwise SWMM_ERR_BADPARAM. Text is copied into caller-owned buffers, NUL-terminated and silently truncated to capacity minus one byte.

◆ swmm_hydrograph_group_rename()

SWMM_ENGINE_API int swmm_hydrograph_group_rename	(	SWMM_Engine	engine,
		int	idx,
		const char *	new_id )

Rename a UH group, propagating the new name to parameter rows, gage assignments, [RDII_DECAY] rows, and [RDII] node assignments.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based group index (0..swmm_hydrograph_group_count()-1).
[in]	new_id	New group name (non-null, non-empty, must not already exist).

Returns: SWMM_OK on success, SWMM_ERR_BADPARAM if new_id is invalid or duplicates an existing group, or another error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Unique names use case-insensitive identity across parameter rows followed by gage assignments. Case-only renaming is permitted. Rewrites parameter/gage/decay/RDII references case-insensitively. No lifecycle guard or runtime RDII cache rebuild.

Here is the call graph for this function:

◆ swmm_hydrograph_remove_entry()

SWMM_ENGINE_API int swmm_hydrograph_remove_entry	(	SWMM_Engine	engine,
		const char *	uh_name,
		int	month,
		int	response )

Remove the first matching hydrograph parameter row.

Case-insensitive group key; absent rows succeed without mutation. Later flat indices shift down. No lifecycle guard or runtime RDII cache rebuild.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	uh_name	Non-null, nonempty copied unit-hydrograph group name; matched case-insensitively for hydrograph rows.
[in]	month	-1 for ALL months or 0..11 for January..December.
[in]	response	0=SHORT, 1=MEDIUM or 2=LONG.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_hydrograph_remove_group()

SWMM_ENGINE_API int swmm_hydrograph_remove_group	(	SWMM_Engine	engine,
		const char *	uh_name )

Remove all authoring rows and RDII assignments for a hydrograph group.

Cascades through parameter rows, rain-gage assignments, exponential-decay rows and node RDII references using the edit deletion helper. Absent groups succeed. No lifecycle guard or runtime RDII cache rebuild.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	uh_name	Non-null, nonempty borrowed group name; all deletion matches use exact case.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_hydrograph_set_gage()

SWMM_ENGINE_API int swmm_hydrograph_set_gage	(	SWMM_Engine	engine,
		const char *	uh_name,
		const char *	gage_name )

Set, replace, or clear the rain gage assigned to a UH group.

Parameters

[in]	engine	Engine handle.
[in]	uh_name	Unit hydrograph group name (non-null, non-empty).
[in]	gage_name	Rain gage name, or NULL/empty to clear an existing assignment.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. Upserts the first case-insensitive group assignment; NULL/empty gage removes that first assignment if present. The referenced gage is not resolved here. No lifecycle guard or runtime RDII cache rebuild.

Here is the call graph for this function:

◆ swmm_hydrograph_set_ia()

SWMM_ENGINE_API int swmm_hydrograph_set_ia	(	SWMM_Engine	engine,
		const char *	uh_name,
		int	month,
		int	response,
		double	dmax,
		double	drecov,
		double	dinit )

Upsert linear-IA parameters for one (group, month, response) row.

Parameters

[in]	engine	Engine handle.
[in]	uh_name	Unit hydrograph group name (non-null, non-empty).
[in]	month	0..11 = JAN..DEC, or -1 for ALL.
[in]	response	0 = SHORT, 1 = MEDIUM, 2 = LONG.
[in]	dmax	Maximum initial-abstraction depth.
[in]	drecov	Linear IA recovery rate.
[in]	dinit	Initial IA already used.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. Matches the first case-insensitive (group,month,response) key; updates only the named fields, or appends with other numeric fields zero. Required names and month/response codes are checked, numeric values are not. No lifecycle guard or runtime RDII cache rebuild.

Here is the call graph for this function:

◆ swmm_hydrograph_set_rtk()

SWMM_ENGINE_API int swmm_hydrograph_set_rtk	(	SWMM_Engine	engine,
		const char *	uh_name,
		int	month,
		int	response,
		double	r,
		double	t,
		double	k )

Upsert R/T/K parameters for one (group, month, response) row.

Parameters

[in]	engine	Engine handle.
[in]	uh_name	Unit hydrograph group name (non-null, non-empty).
[in]	month	0..11 = JAN..DEC, or -1 for ALL.
[in]	response	0 = SHORT, 1 = MEDIUM, 2 = LONG.
[in]	r	Rainfall fraction.
[in]	t	Time to peak (hours).
[in]	k	Recession-limb-to-peak-time ratio (>= 0). Base time = t * (1 + k).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. Matches the first case-insensitive (group,month,response) key; updates only the named fields, or appends with other numeric fields zero. Required names and month/response codes are checked, numeric values are not. No lifecycle guard or runtime RDII cache rebuild.

Here is the call graph for this function:

◆ swmm_rdii_add()

SWMM_ENGINE_API int swmm_rdii_add	(	SWMM_Engine	engine,
		int	node_idx,
		const char *	uh_name,
		double	area )

Add RDII inflow to a node using a unit hydrograph.

Associates a node with a unit hydrograph group and its sewershed area to compute rainfall-dependent infiltration/inflow.

Parameters

[in]	engine	Engine handle.
[in]	node_idx	Zero-based index of the receiving node.
[in]	uh_name	Unit hydrograph group name.
[in]	area	Sewershed area in project area units.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Copies the group name and stores area verbatim; group existence, area range and lifecycle are not checked. Does not rebuild the running RDII cache.

Here is the call graph for this function:

◆ swmm_rdii_count()

SWMM_ENGINE_API int swmm_rdii_count ( SWMM_Engine engine )

Get the total number of RDII entries defined.

Parameters

[in] engine Engine handle.

Returns: Number of RDII entries, or -1 on error.

◆ swmm_rdii_decay_add()

SWMM_ENGINE_API int swmm_rdii_decay_add	(	SWMM_Engine	engine,
		const char *	uh_name,
		int	response,
		double	k_dep,
		double	k_0,
		double	k_T,
		double	T_ref,
		double	theta_rec,
		double	T_freeze,
		int	snow_on,
		double	snow_T,
		double	snow_ddf )

Append an exponential-depletion and temperature-dependent IA-recovery row.

Always appends; duplicate keys are permitted. Negative rate/melt-factor comparisons are checked; provide finite values because no independent finiteness guard exists. No lifecycle guard or runtime RDII cache rebuild.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	uh_name	Copied group name; non-null; empty names are not rejected. Group existence is not resolved here.
[in]	response	0=SHORT, 1=MEDIUM or 2=LONG.
[in]	k_dep	Nonnegative depletion rate, inverse project rainfall-depth units.
[in]	k_0	Nonnegative base recovery rate, per hour.
[in]	k_T	Nonnegative thermal recovery rate at T_ref, per hour.
[in]	T_ref	Reference temperature, degrees C.
[in]	theta_rec	Thermal recovery sensitivity, inverse degrees C.
[in]	T_freeze	Air-temperature threshold below which recovery is suppressed, degrees C.
[in]	snow_on	Zero disables; any nonzero value enables this row's degree-day snow model.
[in]	snow_T	Rain/snow partition and melt-base temperature, degrees C.
[in]	snow_ddf	Nonnegative melt factor, project rainfall-depth units per degree C per day.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_rdii_decay_count()

SWMM_ENGINE_API int swmm_rdii_decay_count ( SWMM_Engine engine )

Count stored exponential-decay rows.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative row count, or -1 for a null engine.

◆ swmm_rdii_decay_get()

SWMM_ENGINE_API int swmm_rdii_decay_get	(	SWMM_Engine	engine,
		int	entry_idx,
		char *	uh_buf,
		int	buflen,
		int *	response,
		double *	k_dep,
		double *	k_0,
		double *	k_T,
		double *	T_ref,
		double *	theta_rec,
		double *	T_freeze,
		int *	snow_on,
		double *	snow_T,
		double *	snow_ddf )

Read back an exponential-decay parameter row by index.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based index (0..swmm_rdii_decay_count()-1).
[out]	uh_buf	UH group name (NUL-terminated).
[in]	buflen	Size of `uh_buf`.
[out]	response	Response code (0..2).
[out]	k_dep	Depletion rate.
[out]	k_0	Base recovery rate.
[out]	k_T	Thermal recovery rate.
[out]	T_ref	Reference temperature.
[out]	theta_rec	Temperature sensitivity.
[out]	T_freeze	Frozen-ground threshold.
[out]	snow_on	Degree-day snow model flag (0/1).
[out]	snow_T	Rain/snow partition threshold & melt base (deg C).
[out]	snow_ddf	Degree-day melt factor.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Every declared output pointer is required; every text capacity must be positive, otherwise SWMM_ERR_BADPARAM. Text is copied into caller-owned buffers, NUL-terminated and silently truncated to capacity minus one byte.

Here is the call graph for this function:

◆ swmm_rdii_decay_remove()

SWMM_ENGINE_API int swmm_rdii_decay_remove	(	SWMM_Engine	engine,
		const char *	uh_name,
		int	response )

Remove the first exponential-decay row matching a group and response.

Absent keys succeed. Later flat row indices shift down. Does not remove hydrograph parameters or RDII node assignments; no runtime RDII cache rebuild.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	uh_name	Non-null, nonempty group name; this decay-row lookup is case-sensitive.
[in]	response	0=SHORT, 1=MEDIUM or 2=LONG.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_rdii_decay_set()

SWMM_ENGINE_API int swmm_rdii_decay_set	(	SWMM_Engine	engine,
		const char *	uh_name,
		int	response,
		double	k_dep,
		double	k_0,
		double	k_T,
		double	T_ref,
		double	theta_rec,
		double	T_freeze,
		int	snow_on,
		double	snow_T,
		double	snow_ddf )

Upsert an exponential-depletion and temperature-dependent IA-recovery row.

Updates the first exact-case (group,response) match or appends. Negative rate/melt-factor comparisons are checked; provide finite values because no independent finiteness guard exists. No lifecycle guard or runtime RDII cache rebuild.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	uh_name	Copied group name; non-null, nonempty, matched case-sensitively. Group existence is not resolved here.
[in]	response	0=SHORT, 1=MEDIUM or 2=LONG.
[in]	k_dep	Nonnegative depletion rate, inverse project rainfall-depth units.
[in]	k_0	Nonnegative base recovery rate, per hour.
[in]	k_T	Nonnegative thermal recovery rate at T_ref, per hour.
[in]	T_ref	Reference temperature, degrees C.
[in]	theta_rec	Thermal recovery sensitivity, inverse degrees C.
[in]	T_freeze	Air-temperature threshold below which recovery is suppressed, degrees C.
[in]	snow_on	Zero disables; any nonzero value enables this row's degree-day snow model.
[in]	snow_T	Rain/snow partition and melt-base temperature, degrees C.
[in]	snow_ddf	Nonnegative melt factor, project rainfall-depth units per degree C per day.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for an invalid row index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_rdii_get()

SWMM_ENGINE_API int swmm_rdii_get	(	SWMM_Engine	engine,
		int	entry_idx,
		int *	node_idx,
		char *	uh_buf,
		int	buflen,
		double *	area )

Read back an RDII assignment by entry index.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based index into the RDII assignment list (0..swmm_rdii_count()-1).
[out]	node_idx	Receiving node index.
[out]	uh_buf	Buffer to receive the unit hydrograph name (NUL-terminated, truncated if too small).
[in]	buflen	Size of `uh_buf` in bytes.
[out]	area	Sewershed area in project area units.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX. Every declared output pointer is required; every text capacity must be positive, otherwise SWMM_ERR_BADPARAM. Text is copied into caller-owned buffers, NUL-terminated and silently truncated to capacity minus one byte.

Here is the call graph for this function:

◆ swmm_rdii_remove()

SWMM_ENGINE_API int swmm_rdii_remove	(	SWMM_Engine	engine,
		int	entry_idx )

Remove an RDII entry by index. Subsequent entries shift down.

Parameters

[in]	engine	Engine handle.
[in]	entry_idx	Zero-based entry index (0..swmm_rdii_count()-1).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed inflow row/pollutant index check returns SWMM_ERR_BADINDEX.

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ swmm_dwf_add()

◆ swmm_dwf_count()

◆ swmm_dwf_get()

◆ swmm_dwf_remove()

◆ swmm_dwf_set_baseline()

◆ swmm_ext_inflow_add()

◆ swmm_ext_inflow_count()

◆ swmm_ext_inflow_get()

◆ swmm_ext_inflow_remove()

◆ swmm_ext_inflow_set_baseline()

◆ swmm_ext_inflow_set_scale()

◆ swmm_hydrograph_add()

◆ swmm_hydrograph_add_gage()

◆ swmm_hydrograph_clear_group_months()

◆ swmm_hydrograph_count()

◆ swmm_hydrograph_gage_count()

◆ swmm_hydrograph_get()

◆ swmm_hydrograph_get_gage()

◆ swmm_hydrograph_group_count()

◆ swmm_hydrograph_group_id()

◆ swmm_hydrograph_group_rename()

◆ swmm_hydrograph_remove_entry()

◆ swmm_hydrograph_remove_group()

◆ swmm_hydrograph_set_gage()

◆ swmm_hydrograph_set_ia()

◆ swmm_hydrograph_set_rtk()

◆ swmm_rdii_add()

◆ swmm_rdii_count()

◆ swmm_rdii_decay_add()

◆ swmm_rdii_decay_count()

◆ swmm_rdii_decay_get()

◆ swmm_rdii_decay_remove()

◆ swmm_rdii_decay_set()

◆ swmm_rdii_get()

◆ swmm_rdii_remove()