ApiInfil2D.cpp File Reference

C API implementation for 2D per-cell infiltration (plan §5.5.6, I6). More...

#include <openswmm/engine/openswmm_engine.h>
#include <openswmm/engine/openswmm_infil2d.h>
#include "../../core/SWMMEngine.hpp"
#include <cmath>
#include <cstring>
#include <string>
#include <vector>
#include <unordered_map>
#include <unordered_set>

Include dependency graph for ApiInfil2D.cpp:

Macros
#define	GET_ENGINE(engine)
#define	CHECK_2D_MESH(eng)
#define	CHECK_TRI_IDX(idx, router2d)
#define	CHECK_EDITABLE(eng)

Functions
int	swmm_infil2d_get_options (SWMM_Engine engine, SWMM_Infil2DOptions *options)
	Get the 2D infiltration options (INFIL_STEP).
int	swmm_infil2d_set_options (SWMM_Engine engine, const SWMM_Infil2DOptions *options)
	Set the 2D infiltration options (INFIL_STEP, seconds).
int	swmm_infil2d_defaults_count (SWMM_Engine engine, int *count)
	Number of authored tag-default rows, including the ‘’*'` row.
int	swmm_infil2d_get_default (SWMM_Engine engine, int idx, SWMM_Infil2DRow *row)
	Read one tag-default row by index.
int	swmm_infil2d_get_default_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read the TAG of one default row by index.
int	swmm_infil2d_set_default (SWMM_Engine engine, const char *tag, const SWMM_Infil2DRow *row)
	Add or replace the default row for a tag.
int	swmm_infil2d_remove_default (SWMM_Engine engine, const char *tag)
	Remove every default row carrying a tag.
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.
int	swmm_infil2d_replace_authored_rows (SWMM_Engine engine, const SWMM_Infil2DAuthoredRow *rows, int count)
	Validate and replace infiltration authoring rows as one edit.
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.
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.
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.
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.
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.
int	swmm_infil2d_get_rate_bulk (SWMM_Engine engine, double *f, int n)
	Bulk get the held per-cell infiltration rate (m/s, >= 0).
int	swmm_infil2d_get_cum_bulk (SWMM_Engine engine, double *F, int n)
	Bulk get the cumulative infiltrated depth per cell (m).
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

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

Implements all functions declared in openswmm_infil2d.h. Follows Api2D.cpp exactly: the SWMMEngine is extracted from the opaque handle, the SurfaceRouter2D is reached through it, and the call is delegated — here to the twoD::Infil2D the router owns.

Two conventions are worth stating once, because both are load- bearing and neither is obvious from the signatures:

1. Staleness. Infil2D::resolve() is the only re-entry point that rebuilds kernel state, and it rebuilds it for the WHOLE mesh while zeroing cumulative(). Calling it mid-run would discard the Horton/Green-Ampt integration history of every cell the caller never touched and desynchronize cum_depth_ from MassBalance2D::infil_out. There is no per-cell re-init entry point and Infil2D.hpp is a frozen contract, so every parameter setter here is rejected once the engine has left OPENED — SWMM_ERR_LIFECYCLE, mirroring the guard the LID/inflow C API uses (openswmm_infrastructure_impl.cpp:581).
2. Empty-when-inactive. resolvedRows(), provenance() and cumulative() are EMPTY — not sized n_triangles — both before resolve() runs and after a resolve() that found no model (Infil2D.cpp:312-316, the I7 fast path). Every reader here therefore checks the container's own size before indexing and degrades to "no infiltration" / zero-fill rather than reading out of bounds.

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

CHECK_2D_MESH

#define CHECK_2D_MESH

(

eng

)

Value:

    auto& router2d = eng->surfaceRouter2D();                                                       \
    if (router2d.mesh().n_vertices() <= 0)                                                         \
    return SWMM_ERR_BADPARAM

CHECK_EDITABLE

#define CHECK_EDITABLE

(

eng

)

Value:

    if (eng->context().state != openswmm::EngineState::OPENED &&                                   \
        eng->context().state != openswmm::EngineState::BUILDING)                                   \
    return SWMM_ERR_LIFECYCLE

CHECK_TRI_IDX

#define CHECK_TRI_IDX	(		idx,
			router2d )

Value:

    if ((idx) < 0 || (idx) >= router2d.mesh().n_triangles())                                       \
    return SWMM_ERR_BADINDEX

GET_ENGINE

#define GET_ENGINE

(

engine

)

Value:

    auto* eng = reinterpret_cast<openswmm::SWMMEngine*>(engine);                                   \
    if (!eng)                                                                                      \
    return SWMM_ERR_BADHANDLE

Function Documentation

swmm_infil2d_get_authored_rows()

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

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

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

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.