2D Infiltration API

Collaboration diagram for 2D Infiltration API:

Files
file	ApiInfil2D.cpp
	C API implementation for 2D per-cell infiltration (plan §5.5.6, I6).

Classes
struct	SWMM_Infil2DOptions
	[2D_INFILTRATION_OPTIONS] — POD mirror of openswmm::twoD::Infil2DOptions. More...
struct	SWMM_Infil2DRow
	One infiltration specification — POD mirror of openswmm::twoD::Infil2DRow. More...

Macros
#define	SWMM_INFIL2D_MAX_PARAMS   5
	Number of positional parameter columns carried per row.

Typedefs
typedef struct SWMM_Infil2DOptions	SWMM_Infil2DOptions
	[2D_INFILTRATION_OPTIONS] — POD mirror of openswmm::twoD::Infil2DOptions.
typedef struct SWMM_Infil2DRow	SWMM_Infil2DRow
	One infiltration specification — POD mirror of openswmm::twoD::Infil2DRow.

Functions
SWMM_ENGINE_API int	swmm_infil2d_get_options (SWMM_Engine engine, SWMM_Infil2DOptions *options)
	Get the 2D infiltration options (INFIL_STEP).
SWMM_ENGINE_API int	swmm_infil2d_set_options (SWMM_Engine engine, const SWMM_Infil2DOptions *options)
	Set the 2D infiltration options (INFIL_STEP, seconds).
SWMM_ENGINE_API int	swmm_infil2d_defaults_count (SWMM_Engine engine, int *count)
	Number of authored tag-default rows, including the ‘’*'` row.
SWMM_ENGINE_API int	swmm_infil2d_get_default (SWMM_Engine engine, int idx, SWMM_Infil2DRow *row)
	Read one tag-default row by index.
SWMM_ENGINE_API int	swmm_infil2d_get_default_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read the TAG of one default row by index.
SWMM_ENGINE_API int	swmm_infil2d_set_default (SWMM_Engine engine, const char *tag, const SWMM_Infil2DRow *row)
	Add or replace the default row for a tag.
SWMM_ENGINE_API int	swmm_infil2d_remove_default (SWMM_Engine engine, const char *tag)
	Remove every default row carrying a tag.
SWMM_ENGINE_API int	swmm_infil2d_get_cell (SWMM_Engine engine, int tri, SWMM_Infil2DRow *row, int *is_override)
	Read the infiltration specification in force at one triangle.
SWMM_ENGINE_API int	swmm_infil2d_set_cell (SWMM_Engine engine, int tri, const SWMM_Infil2DRow *row)
	Set (or clear) the per-cell [2D_INFILTRATION] override of one triangle.
SWMM_ENGINE_API int	swmm_infil2d_set_cells (SWMM_Engine engine, const int *tris, int n, const SWMM_Infil2DRow *row)
	Assign one specification to many triangles in a single call.
SWMM_ENGINE_API int	swmm_infil2d_get_rate_bulk (SWMM_Engine engine, double *f, int n)
	Bulk get the held per-cell infiltration rate (m/s, >= 0).
SWMM_ENGINE_API int	swmm_infil2d_get_cum_bulk (SWMM_Engine engine, double *F, int n)
	Bulk get the cumulative infiltrated depth per cell (m).
SWMM_ENGINE_API int	swmm_infil2d_get_total_volume (SWMM_Engine engine, double *volume)
	Get the cumulative 2D infiltration loss (m³) — the infil_out mass-balance ledger row.

Detailed Description

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\n Apache-2.0

Macro Definition Documentation

SWMM_INFIL2D_MAX_PARAMS

#define SWMM_INFIL2D_MAX_PARAMS   5

Number of positional parameter columns carried per row.

Matches the widest legacy [INFILTRATION] method (Horton: f0 fmin decay dry_time Fmax). Mirrors openswmm::twoD::kInfil2DMaxParams.

Typedef Documentation

SWMM_Infil2DOptions

typedef struct SWMM_Infil2DOptions SWMM_Infil2DOptions

[2D_INFILTRATION_OPTIONS] — POD mirror of openswmm::twoD::Infil2DOptions.

SWMM_Infil2DRow

typedef struct SWMM_Infil2DRow SWMM_Infil2DRow

One infiltration specification — POD mirror of openswmm::twoD::Infil2DRow.

Parameters are POSITIONAL and in PROJECT UNITS, matching legacy [INFILTRATION] exactly:

method	p[0]	p[1]	p[2]	p[3]	p[4]
SWMM_INFIL2D_HORTON	f0	fmin	decay (1/hr)	dry_time (d)	Fmax
SWMM_INFIL2D_MOD_HORTON	f0	fmin	decay (1/hr)	dry_time (d)	Fmax
SWMM_INFIL2D_GREEN_AMPT	S suction	Ks	IMD	—	—
SWMM_INFIL2D_MOD_GREEN_AMPT	S suction	Ks	IMD	—	—
SWMM_INFIL2D_CURVE_NUMBER	CN	—	dry_time (d)	—	—
SWMM_INFIL2D_CONSTANT	rate	—	—	—	—

f0 / fmin / Ks / rate are in/hr (US) or mm/hr (SI); S and Fmax are in (US) or mm (SI). CURVE_NUMBER's p[1] is unused and ignored, matching the legacy column layout where the middle value is a no-op. Slots a method does not use are ignored; write 0.

Function Documentation

swmm_infil2d_defaults_count()

SWMM_ENGINE_API int swmm_infil2d_defaults_count	(	SWMM_Engine	engine,
		int *	count )

Number of authored tag-default rows, including the ‘’*'` row.

The *_count companion for swmm_infil2d_get_default / swmm_infil2d_get_default_tag.

Parameters

engine	Engine handle.
count	Output row count (0 when the model authors no defaults).

Returns

SWMM_OK; SWMM_ERR_BADHANDLE; SWMM_ERR_BADPARAM on NULL count or when no 2D mesh exists.

swmm_infil2d_get_cell()

SWMM_ENGINE_API int swmm_infil2d_get_cell	(	SWMM_Engine	engine,
		int	tri,
		SWMM_Infil2DRow *	row,
		int *	is_override )

Read the infiltration specification in force at one triangle.

Row parameters are in PROJECT UNITS — see SWMM_Infil2DRow.

Behaviour depends on whether the 2D surface has resolved yet:

• After initialize() the RESOLVED row is reported (D-I3 precedence already applied) and *is_override is 1 exactly when the resolved provenance is the per-cell [2D_INFILTRATION] layer.
• Before initialize() only the per-cell override layer is visible, so the authored override for tri is reported with *is_override == 1, and a cell with no override reports has_method == 0 with *is_override == 0 even when a tag or ‘’*'default would later apply. Combine with @ref swmm_infil2d_get_default and the triangle's tag (swmm_2d_get_triangle_tag`) to preview the resolution in that state.

Parameters

engine	Engine handle.
tri	Triangle index (0-based) in [0, triangle_count).
row	Output row; must not be NULL.
is_override	Output flag, 1 / 0. May be NULL.

Returns

SWMM_OK; SWMM_ERR_BADINDEX on an out-of-range triangle; SWMM_ERR_BADPARAM on NULL row or when no 2D mesh exists.

swmm_infil2d_get_cum_bulk()

SWMM_ENGINE_API int swmm_infil2d_get_cum_bulk	(	SWMM_Engine	engine,
		double *	F,
		int	n )

Bulk get the cumulative infiltrated depth per cell (m).

The infil_cum sidecar variable: the running time-integral of the loss the solver actually applied (the held rate after the wet/dry depth ramp), so sum(F[i] * cell_area[i]) equals swmm_infil2d_get_total_volume. Values are SI regardless of the project unit system.

Fills min(n, triangle_count) entries, and zero-fills + returns SWMM_OK when no infiltration model is resolved (same contract as swmm_infil2d_get_rate_bulk).

Parameters

engine	Engine handle.
F	Caller-allocated output buffer of at least n doubles.
n	Capacity of F; must be > 0.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE; SWMM_ERR_BADPARAM on a NULL buffer, n <= 0, or when no 2D mesh exists.

swmm_infil2d_get_default()

SWMM_ENGINE_API int swmm_infil2d_get_default	(	SWMM_Engine	engine,
		int	idx,
		SWMM_Infil2DRow *	row )

Read one tag-default row by index.

Row parameters are in PROJECT UNITS — see SWMM_Infil2DRow. Pair with swmm_infil2d_get_default_tag to learn which tag the row belongs to.

Parameters

engine	Engine handle.
idx	Row index in [0, swmm_infil2d_defaults_count).
row	Output row; must not be NULL.

Returns

SWMM_OK; SWMM_ERR_BADINDEX on an out-of-range index; SWMM_ERR_BADPARAM on NULL row or when no 2D mesh exists.

swmm_infil2d_get_default_tag()

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

Read the TAG of one default row by index.

Copies up to buflen-1 bytes into buf and always NUL-terminates (the swmm_2d_get_triangle_tag convention). "*" identifies the mesh-wide fallback row.

Parameters

engine	Engine handle.
idx	Row index in [0, swmm_infil2d_defaults_count).
buf	Caller-allocated output buffer.
buflen	Capacity of buf in bytes; must be > 0.

Returns

SWMM_OK; SWMM_ERR_BADINDEX; SWMM_ERR_BADPARAM.

swmm_infil2d_get_options()

SWMM_ENGINE_API int swmm_infil2d_get_options	(	SWMM_Engine	engine,
		SWMM_Infil2DOptions *	options )

Get the 2D infiltration options (INFIL_STEP).

Valid in any state once a 2D mesh is present. Reports the AUTHORED value, which may still be <= 0 ("use `WET_STEP`") — the cadence the solver actually resolved is not exposed here.

Parameters

engine	Engine handle.
options	Output; must not be NULL.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE on a bad handle; SWMM_ERR_BADPARAM on a NULL argument or when no 2D mesh exists.

swmm_infil2d_get_rate_bulk()

SWMM_ENGINE_API int swmm_infil2d_get_rate_bulk	(	SWMM_Engine	engine,
		double *	f,
		int	n )

Bulk get the held per-cell infiltration rate (m/s, >= 0).

This is the rate the marcher is consuming — recomputed on the INFIL_STEP cadence and held constant between updates (D-I1), NOT re-evaluated per sub-step. Values are SI regardless of the project unit system.

Fills min(n, triangle_count) entries. A mesh with no resolved infiltration model is a legitimate configuration, not an error: the buffer is zero-filled and SWMM_OK is returned.

Parameters

engine	Engine handle.
f	Caller-allocated output buffer of at least n doubles.
n	Capacity of f; must be > 0.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE; SWMM_ERR_BADPARAM on a NULL buffer, n <= 0, or when no 2D mesh exists.

swmm_infil2d_get_total_volume()

SWMM_ENGINE_API int swmm_infil2d_get_total_volume	(	SWMM_Engine	engine,
		double *	volume )

Get the cumulative 2D infiltration loss (m³) — the infil_out mass-balance ledger row.

The whole-domain companion to swmm_infil2d_get_cum_bulk, reported beside evap_out in the continuity report. Reads the same ledger as swmm_2d_get_mass_balance and, like it, requires the 2D mass balance to be live.

Parameters

engine	Engine handle.
volume	Output volume in m³; must not be NULL.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE; SWMM_ERR_BADPARAM on NULL volume or when the 2D mass balance is not active.

swmm_infil2d_remove_default()

SWMM_ENGINE_API int swmm_infil2d_remove_default	(	SWMM_Engine	engine,
		const char *	tag )

Remove every default row carrying a tag.

Removing the ‘’*'` row leaves cells with no tag row resolving to no infiltration. Subject to the staleness rule documented on swmm_infil2d_set_options.

Parameters

engine	Engine handle.
tag	Tag to remove; must be non-empty.

Returns

SWMM_OK (also when the tag was not present); SWMM_ERR_BADHANDLE; SWMM_ERR_BADPARAM on a NULL / empty tag or when no 2D mesh exists; SWMM_ERR_LIFECYCLE after initialize().

swmm_infil2d_set_cell()

SWMM_ENGINE_API int swmm_infil2d_set_cell	(	SWMM_Engine	engine,
		int	tri,
		const SWMM_Infil2DRow *	row )

Set (or clear) the per-cell [2D_INFILTRATION] override of one triangle.

Row parameters are in PROJECT UNITS — see SWMM_Infil2DRow. Passing row == NULL CLEARS the override, so the cell falls back to its tag row / the ‘’'row / no infiltration. Passing a row with has_method == 0is different: it stores an explicitNONEoverride, which suppresses the tag and''` defaults for that cell.

Persisted as one [2D_INFILTRATION] row on save. Subject to the staleness rule documented on swmm_infil2d_set_options.

Parameters

engine	Engine handle.
tri	Triangle index (0-based) in [0, triangle_count).
row	Row to store, or NULL to clear the override.

Returns

SWMM_OK; SWMM_ERR_BADINDEX on an out-of-range triangle; SWMM_ERR_BADPARAM on an invalid row or when no 2D mesh exists; SWMM_ERR_LIFECYCLE after initialize().

swmm_infil2d_set_cells()

SWMM_ENGINE_API int swmm_infil2d_set_cells	(	SWMM_Engine	engine,
		const int *	tris,
		int	n,
		const SWMM_Infil2DRow *	row )

Assign one specification to many triangles in a single call.

The GUI's select-many-cells-then-assign entry point: one validation pass, then one apply. All-or-nothing — the row and EVERY entry of tris are validated first, and if any triangle index is out of range (or the row is invalid) nothing at all is written. Duplicate indices are tolerated; the cell simply ends up with the one row.

Row parameters are in PROJECT UNITS — see SWMM_Infil2DRow. Passing row == NULL clears the override on every listed triangle, with the same all-or-nothing contract. Subject to the staleness rule documented on swmm_infil2d_set_options.

Parameters

engine	Engine handle.
tris	Caller-owned array of n 0-based triangle indices.
n	Number of entries in tris; must be > 0.
row	Row to store on every listed triangle, or NULL to clear.

Returns

SWMM_OK; SWMM_ERR_BADINDEX when any entry of tris is out of range (nothing applied); SWMM_ERR_BADPARAM on a NULL tris, n <= 0, an invalid row, or when no 2D mesh exists; SWMM_ERR_LIFECYCLE after initialize().

swmm_infil2d_set_default()

SWMM_ENGINE_API int swmm_infil2d_set_default	(	SWMM_Engine	engine,
		const char *	tag,
		const SWMM_Infil2DRow *	row )

Add or replace the default row for a tag.

Upsert semantics: any existing rows carrying tag are removed and one row is appended, so a tag never has two definitions. Pass "*" to set the mesh-wide fallback. A row with has_method == 0 (NONE) is meaningful and is stored — for a tag it deliberately CLEARS the ‘’*'` default for that tag's cells.

Row parameters are in PROJECT UNITS — see SWMM_Infil2DRow. Persisted in [2D_INFILTRATION_DEFAULTS] on save. Subject to the staleness rule documented on swmm_infil2d_set_options.

Parameters

engine	Engine handle.
tag	Tag to define; must be non-empty.
row	Row to store; must not be NULL.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE; SWMM_ERR_BADPARAM on a NULL / empty tag, a NULL row, an unknown method code, a destination other than SWMM_INFIL2D_DEST_LOST, an out-of-range parameter, or when no 2D mesh exists; SWMM_ERR_LIFECYCLE after initialize().

swmm_infil2d_set_options()

SWMM_ENGINE_API int swmm_infil2d_set_options	(	SWMM_Engine	engine,
		const SWMM_Infil2DOptions *	options )

Set the 2D infiltration options (INFIL_STEP, seconds).

Persisted in [2D_INFILTRATION_OPTIONS] on save.

Staleness (applies to every setter in this header). Infiltration parameters are baked into per-cell Horton / Green-Ampt / curve-number kernel state ONCE, when the 2D surface initializes. The only re-entry point rebuilds that state for the WHOLE mesh and zeroes the per-cell cumulative-depth array, which would discard the integration history of every cell the caller never touched and desynchronize the infil_out ledger row. Rather than corrupt a run, parameter setters are rejected after initialize(): they return SWMM_ERR_LIFECYCLE unless the engine is in SWMM_STATE_OPENED (the state the GUI edits in) or the programmatic BUILDING state. Re-open or re-initialize to apply a change.

Parameters

engine	Engine handle.
options	New options; must not be NULL. infil_step <= 0 selects the project WET_STEP; non-finite values are rejected.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE; SWMM_ERR_BADPARAM on a NULL / non-finite argument or when no 2D mesh exists; SWMM_ERR_LIFECYCLE when called after initialize().