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

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