openswmm_infil2d.h File Reference

Per-cell infiltration for the 2D overland-flow mesh — C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_infil2d.h:

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

Go to the source code of this file.

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...
struct	SWMM_Infil2DAuthoredRow

Macros
#define	SWMM_INFIL2D_MAX_PARAMS   5
	Number of positional parameter columns carried per row.
#define	SWMM_INFIL2D_HORTON   0
#define	SWMM_INFIL2D_MOD_HORTON   1
#define	SWMM_INFIL2D_GREEN_AMPT   2
#define	SWMM_INFIL2D_MOD_GREEN_AMPT   3
#define	SWMM_INFIL2D_CURVE_NUMBER   4
#define	SWMM_INFIL2D_CONSTANT   5
#define	SWMM_INFIL2D_DEST_LOST   0
#define	SWMM_INFIL2D_DEST_SUBCATCH_AQUIFER   1
#define	SWMM_INFIL2D_DEST_AQUIFER_2D   2

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.
typedef struct SWMM_Infil2DAuthoredRow	SWMM_Infil2DAuthoredRow

Functions
SWMM_ENGINE_API int	swmm_infil2d_get_authored_rows (SWMM_Engine engine, SWMM_Infil2DAuthoredRow *out, int len, int *written)
	Copy the complete ordered infiltration authoring records, including inheritance flags.
SWMM_ENGINE_API int	swmm_infil2d_replace_authored_rows (SWMM_Engine engine, const SWMM_Infil2DAuthoredRow *rows, int count)
	Validate and replace infiltration authoring rows as one edit.
SWMM_ENGINE_API int	swmm_infil2d_get_ownership_bulk (SWMM_Engine engine, int *owners, int *aq_rows, int *conflicts, int len, int *written)
	Preview infiltration/aquifer ownership and authoring conflicts for all triangles.
SWMM_ENGINE_API int	swmm_infil2d_get_ownership (SWMM_Engine engine, int cell, int *owner, int *aq_row, int *conflict)
	Preview one triangle's infiltration/aquifer ownership and conflict.
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

Per-cell infiltration for the 2D overland-flow mesh — C API.

Implements the API surface of plans/TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN_2026-08-15.md §5.5.6 (track I, step I6). This is the GROUNDWATER OFF infiltration path: a per-cell loss model so surface-only 2D runs do not overestimate pervious runoff. It supersedes the swmm_gw2d_infil_set/get sketch in §8.5 — the capability ships first and owns this header; openswmm_gw2d.h will refer to it rather than redeclare it.

Configuration mirrors the three input sections:

section	API
[2D_INFILTRATION_OPTIONS]	swmm_infil2d_get_options / set_options
[2D_INFILTRATION_DEFAULTS]	the *_default family (tag rows, incl. *)
[2D_INFILTRATION]	the *_cell family (sparse per-cell override)

Resolution order (D-I3), most specific wins: ‘per-cell override > tag row > ’*' row > no infiltration`. Resolution happens ONCE, when the 2D surface initializes; the solver never consults tags afterwards.

Units — read this before touching any row. Every value in SWMM_Infil2DRow::p is in PROJECT UNITS — the same number a user types into a legacy [INFILTRATION] row (in/hr and in on a US-FLOW_UNITS project, mm/hr and mm on an SI project). This deliberately differs from the SI convention of the rest of the 2D API, so that [INFILTRATION] and [2D_INFILTRATION*] cannot disagree. The readback channels are the exception and are SI, as the rest of the 2D API is: swmm_infil2d_get_rate_bulk is m/s, swmm_infil2d_get_cum_bulk is m, and swmm_infil2d_get_total_volume is m³.

Lifecycle. The readers work in any state (see each function). Every setter that changes parameters is rejected with SWMM_ERR_LIFECYCLE unless the engine is in SWMM_STATE_OPENED (or BUILDING) — see the "Staleness" note on swmm_infil2d_set_options.

All functions return SWMM_ERR_BADPARAM when the 2D module carries no mesh, and require the engine to have been compiled with OPENSWMM_BUILD_2D.

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_INFIL2D_CONSTANT

#define SWMM_INFIL2D_CONSTANT   5

Constant rate, capacity-bounded.

SWMM_INFIL2D_CURVE_NUMBER

#define SWMM_INFIL2D_CURVE_NUMBER   4

SCS curve number.

SWMM_INFIL2D_DEST_AQUIFER_2D

#define SWMM_INFIL2D_DEST_AQUIFER_2D   2

Obsolete; requires reviewed ownership migration.

SWMM_INFIL2D_DEST_LOST

#define SWMM_INFIL2D_DEST_LOST   0

Destination codes for infiltrated water. Mirror openswmm::twoD::Infil2DDest.

LOST and SUBCATCH_AQUIFER route ordinary bank cells. Aquifer-owned cells use their column capacity. AQUIFER_2D is retained for readable migration and is rejected at initialization. Leaves the domain; booked to the infil_out ledger row.

SWMM_INFIL2D_DEST_SUBCATCH_AQUIFER

#define SWMM_INFIL2D_DEST_SUBCATCH_AQUIFER   1

Reserved — legacy subcatchment aquifer.

SWMM_INFIL2D_GREEN_AMPT

#define SWMM_INFIL2D_GREEN_AMPT   2

Green-Ampt.

SWMM_INFIL2D_HORTON

#define SWMM_INFIL2D_HORTON   0

Infiltration method codes. Mirror openswmm::InfilModel value-for-value (D-I6: six methods). CONSTANT has no legacy [INFILTRATION] token — it is 2D-only. Horton.

SWMM_INFIL2D_MOD_GREEN_AMPT

#define SWMM_INFIL2D_MOD_GREEN_AMPT   3

Modified Green-Ampt (F not reset).

SWMM_INFIL2D_MOD_HORTON

#define SWMM_INFIL2D_MOD_HORTON   1

Modified Horton (linear decay).

Typedef Documentation

SWMM_Infil2DAuthoredRow

typedef struct SWMM_Infil2DAuthoredRow SWMM_Infil2DAuthoredRow

Ordered authoring record, including inheritance presence. cell=-1: default/tag. Fixed tag buffer matches the other authoring read APIs; oversized tags are refused rather than truncated. Replacement retains obsolete destination values for migration Undo; initialize still rejects them. It validates the entire batch before writing, retains duplicates/order, and is available only while editable.

Function Documentation

swmm_infil2d_get_authored_rows()

SWMM_ENGINE_API int swmm_infil2d_get_authored_rows	(	SWMM_Engine	engine,
		SWMM_Infil2DAuthoredRow *	out,
		int	len,
		int *	written )

Copy the complete ordered infiltration authoring records, including inheritance flags.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	out	Writable row array, or NULL with len == 0 for a count query. Defaults/tags are copied first with cell == -1, then explicit cell overrides; parameters remain in PROJECT UNITS and dest_explicit is preserved.
[in]	len	Nonnegative row capacity; a supplied array must fit every row.
[out]	written	Non-null slot set to the required total row count before capacity/tag-length validation; no partial prefix is returned as success.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

No initialized mesh is required. Oversized tags that cannot fit the 4096-byte row field are refused before writing, rather than truncated.

swmm_infil2d_get_ownership()

SWMM_ENGINE_API int swmm_infil2d_get_ownership	(	SWMM_Engine	engine,
		int	cell,
		int *	owner,
		int *	aq_row,
		int *	conflict )

Preview one triangle's infiltration/aquifer ownership and conflict.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	cell	Zero-based triangle index, within the current mesh.
[out]	owner	Non-null slot: 0 disabled, 1 surface bank, 2 aquifer.
[out]	aq_row	Non-null resolved aquifer-row slot; -1 for implicit/no explicit row.
[out]	conflict	Non-null slot: 0 none, 1 conflicting explicit cell model, 2 obsolete AQUIFER_2D routing destination.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_BADPARAM.

Note

Authoring-only preview before or after initialize; does not modify records.

swmm_infil2d_get_ownership_bulk()

SWMM_ENGINE_API int swmm_infil2d_get_ownership_bulk	(	SWMM_Engine	engine,
		int *	owners,
		int *	aq_rows,
		int *	conflicts,
		int	len,
		int *	written )

Preview infiltration/aquifer ownership and authoring conflicts for all triangles.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	owners	Non-null writable full-cell array: 0 disabled, 1 surface bank, 2 aquifer.
[out]	aq_rows	Non-null writable full-cell array of resolved aquifer-row indices; -1 denotes no explicit selected row/implicit whole-mesh default.
[out]	conflicts	Non-null writable full-cell array: 0 none, 1 explicit cell infiltration on an aquifer owner, 2 obsolete AQUIFER_2D destination.
[in]	len	Capacity of each output array, at least the triangle count.
[out]	written	Optional count slot; NULL skips it.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Requires a mesh, but can run before initialize. Uses authored options, GLOBAL/TAG/CELL precedence and infiltration records without modifying them.

swmm_infil2d_replace_authored_rows()

SWMM_ENGINE_API int swmm_infil2d_replace_authored_rows	(	SWMM_Engine	engine,
		const SWMM_Infil2DAuthoredRow *	rows,
		int	count )

Validate and replace infiltration authoring rows as one edit.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	rows	Borrowed count-element ordered array; NULL allowed only for zero count. cell == -1 requires a nonempty terminated tag; other cells use zero-based triangle indices. dest_explicit must be 0 or 1 and parameters finite.
[in]	count	Nonnegative number of rows; zero clears all defaults and overrides.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADPARAM, SWMM_ERR_BADINDEX for an invalid explicit cell, or SWMM_ERR_LIFECYCLE.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Keeps duplicate rows/order within each default/override collection. Obsolete destination codes are retained for migration/Undo authoring and may still be rejected at initialize. Entire input is checked before publication.