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

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.

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

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.

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

Reserved — the two-zone 2D kernel.

SWMM_INFIL2D_DEST_LOST

#define SWMM_INFIL2D_DEST_LOST   0

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

D-I4: LOST is the only destination this release routes. The other two exist so the grammar is stable and are rejected at validation with a "not supported in this release" message. 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).