OpenSWMM Engine  6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
Loading...
Searching...
No Matches
openswmm_lid_nodes_impl.cpp File Reference

Public C API implementation for LID node configuration. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_infrastructure.h"
#include "../hydrology/LidNode.hpp"
#include "../hydraulics/Node.hpp"
#include "UnitConversion.hpp"
#include <algorithm>
#include <cmath>
Include dependency graph for openswmm_lid_nodes_impl.cpp:

Functions

SWMM_ENGINE_API int swmm_lid_node_layer_count (SWMM_Engine engine, int control)
 Count authored or derived stack layers, including a BOTTOM row when present.
 
SWMM_ENGINE_API int swmm_lid_node_layer_get (SWMM_Engine engine, int control, int row, SWMM_LidNodeLayer *out)
 Read one authored or derived NODE layer.
 
SWMM_ENGINE_API int swmm_lid_node_layers_set (SWMM_Engine engine, int control, const SWMM_LidNodeLayer *rows, int count)
 Replace NODE layers while preserving compatible treatment and flow settings.
 
SWMM_ENGINE_API int swmm_lid_node_treatment_count (SWMM_Engine engine, int control)
 Count per-layer treatment rows flattened top-to-bottom.
 
SWMM_ENGINE_API int swmm_lid_node_treatment_get (SWMM_Engine engine, int control, int row, SWMM_LidLayerTreatment *out)
 Read a flattened per-layer treatment row.
 
SWMM_ENGINE_API int swmm_lid_node_configure (SWMM_Engine engine, int control, const SWMM_LidNodeLayer *rows, int count, const SWMM_LidLayerTreatment *treatments, int nt)
 Atomically configure a NODE control stack and treatment.
 
SWMM_ENGINE_API int swmm_node_get_lid (SWMM_Engine engine, int node, int *control, double *saturation)
 Read a node LID-control assignment and initial saturation.
 
SWMM_ENGINE_API int swmm_lid_richards_options_get (SWMM_Engine engine, int control, SWMM_LidRichardsOptions *out)
 Read a control's Richards options.
 
SWMM_ENGINE_API int swmm_lid_richards_material_get (SWMM_Engine engine, int control, int row, SWMM_LidRichardsMaterial *out)
 Read a control's Richards material.
 
SWMM_ENGINE_API int swmm_lid_node_configure_flow (SWMM_Engine engine, int control, const SWMM_LidNodeLayer *rows, int count, const SWMM_LidLayerTreatment *treatment, int nt, const SWMM_LidRichardsOptions *options, const SWMM_LidRichardsMaterial *material)
 Atomically configure a NODE control stack, treatment and flow formulation.
 
SWMM_ENGINE_API int swmm_node_set_lid (SWMM_Engine engine, int node, int control, double saturation)
 Assign or clear a storage-node LID and synchronize its geometry.
 
SWMM_ENGINE_API int swmm_node_get_lid_bottom (SWMM_Engine engine, int node, int *mode)
 Read a node's bottom exchange ownership mode.
 
SWMM_ENGINE_API int swmm_node_set_lid_bottom (SWMM_Engine engine, int node, int mode)
 Select bottom ownership for one assigned storage LID.
 
SWMM_ENGINE_API int swmm_lid_node_base_area (SWMM_Engine engine, int node, double *area)
 Read the authored geometric area at a storage LID base.
 
SWMM_ENGINE_API int swmm_lid_node_outlet_get (SWMM_Engine engine, int link, int *layer, int *top)
 Read a link's LID layer anchor.
 
SWMM_ENGINE_API int swmm_lid_node_outlet_set (SWMM_Engine engine, int link, int layer, int top)
 Set or remove a link's LID layer anchor.
 
SWMM_ENGINE_API int swmm_lid_node_state_count (SWMM_Engine engine, int node)
 Count initialized runtime profile cells.
 
SWMM_ENGINE_API int swmm_lid_node_state_get (SWMM_Engine engine, int node, int row, int *layer, double *bottom, double *top, double *moisture)
 Read one initialized LID profile cell.
 
SWMM_ENGINE_API int swmm_lid_richards_state_get (SWMM_Engine engine, int node, int row, double *pressure, double *head, double *water)
 Read one Richards cell's pressure, total head and complete water volume.
 
SWMM_ENGINE_API int swmm_lid_richards_statistics_get (SWMM_Engine engine, int node, SWMM_LidRichardsStatistics *out)
 Read the last stored Richards adaptive-solver report.
 
SWMM_ENGINE_API int swmm_lid_node_bottom_state_get (SWMM_Engine engine, int node, SWMM_LidBottomState *out)
 Read the last accepted LID-to-mesh exchange diagnostics without advancing time.
 

Detailed Description

Public C API implementation for LID node configuration.

Author
Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com
License
Apache-2.0

Function Documentation

◆ swmm_lid_node_base_area()

SWMM_ENGINE_API int swmm_lid_node_base_area ( SWMM_Engine engine,
int node,
double * area )

Read the authored geometric area at a storage LID base.

Requires BUILDING/OPENED, assigned storage LID, and no initialized runtime cells. Uses geometry at depth zero without pore/retained-water factors; rejects nonfinite/negative computed area. Zero requires explicit positive area when creating a connection.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[out]areaNon-null contact-area destination in project square-length units, ft2 or m2; may be zero.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.
Here is the call graph for this function:

◆ swmm_lid_node_bottom_state_get()

SWMM_ENGINE_API int swmm_lid_node_bottom_state_get ( SWMM_Engine engine,
int node,
SWMM_LidBottomState * out )

Read the last accepted LID-to-mesh exchange diagnostics without advancing time.

Requires an initialized explicit MESH_AQUIFER bottom connection with receipts enabled and a 2D-enabled build; otherwise BADPARAM. Current aquifer and sample timestamps can differ. Classical samples use mobile LID head; Richards uses bottom porous total head. Pending gross up/down transfers remain separate.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[out]outNon-null caller-owned SI diagnostics struct; preserved on failure. Positive net volume/rate is LID to aquifer; valid_sample=0 before the first completed sample.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_lid_node_configure()

SWMM_ENGINE_API int swmm_lid_node_configure ( SWMM_Engine engine,
int control,
const SWMM_LidNodeLayer * layers,
int count,
const SWMM_LidLayerTreatment * treatment,
int treatment_count )

Atomically configure a NODE control stack and treatment.

Requires BUILDING/OPENED and a NODE control. Validates stack, treatment expressions and outlet anchors before retaining the edit; rejects edits that orphan an anchored layer. Synchronizes dependent MaxDepths/outlet offsets. Preserves existing flow/retention settings, requiring compatible layer count/kinds when those settings are active.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
[in]layersNon-null borrowed array of count layers, copied synchronously. See SWMM_LidNodeLayerKind for parameter positions/units; unused params must be zero.
[in]countPositive authored layer count, including optional final BOTTOM. SURFACE may occur only first; at least one MEDIA/AGGREGATE is required.
[in]treatmentBorrowed treatment_count rows, required if treatment_count>0; expressions are copied. Layer is one-based, cannot target BOTTOM; each layer/pollutant key must be unique.
[in]treatment_countNonnegative number of treatment rows; zero clears treatment.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.
Here is the call graph for this function:

◆ swmm_lid_node_configure_flow()

SWMM_ENGINE_API int swmm_lid_node_configure_flow ( SWMM_Engine engine,
int control,
const SWMM_LidNodeLayer * layers,
int count,
const SWMM_LidLayerTreatment * treatment,
int treatment_count,
const SWMM_LidRichardsOptions * options,
const SWMM_LidRichardsMaterial * material )

Atomically configure a NODE control stack, treatment and flow formulation.

Requires BUILDING/OPENED and a NODE control. Validates stack, treatment expressions and outlet anchors before retaining the edit; rejects edits that orphan an anchored layer. Synchronizes dependent MaxDepths/outlet offsets. Richards requires SURFACE first and valid retention on every porous layer; invalid configuration leaves stack and dependent geometry unchanged.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
[in]layersNon-null borrowed array of count layers, copied synchronously. See SWMM_LidNodeLayerKind for parameter positions/units; unused params must be zero.
[in]countPositive authored layer count, including optional final BOTTOM. SURFACE may occur only first; at least one MEDIA/AGGREGATE is required.
[in]treatmentBorrowed treatment_count rows, required if treatment_count>0; expressions are copied. Layer is one-based, cannot target BOTTOM; each layer/pollutant key must be unique.
[in]treatment_countNonnegative number of treatment rows; zero clears treatment.
[in]optionsNon-null flow options: model=0 classical/backwater, model=1 Richards. Richards requires finite positive tolerances/max_step and cells_per_layer in [1,256].
[in]materialBorrowed array with count entries; required for Richards. Porous rows use residual theta, inverse-metre alpha/specific-storage in BOTH unit systems, n>1 and l>=0; SURFACE/BOTTOM rows are ignored.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.
Here is the call graph for this function:

◆ swmm_lid_node_layer_count()

SWMM_ENGINE_API int swmm_lid_node_layer_count ( SWMM_Engine engine,
int control )

Count authored or derived stack layers, including a BOTTOM row when present.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
Returns
Nonnegative row count; -1 for null engine or invalid control.
Here is the call graph for this function:

◆ swmm_lid_node_layer_get()

SWMM_ENGINE_API int swmm_lid_node_layer_get ( SWMM_Engine engine,
int control,
int row,
SWMM_LidNodeLayer * out )

Read one authored or derived NODE layer.

No lifecycle check. Uses the derived stack for conventional controls as well as explicitly authored NODE stacks.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
[in]rowZero-based row index in the selected profile/table.
[out]outNon-null caller-owned output receiving kind and all seven input-unit parameters.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.
Here is the call graph for this function:

◆ swmm_lid_node_layers_set()

SWMM_ENGINE_API int swmm_lid_node_layers_set ( SWMM_Engine engine,
int control,
const SWMM_LidNodeLayer * rows,
int count )

Replace NODE layers while preserving compatible treatment and flow settings.

Requires BUILDING/OPENED and NODE type. Validates stack and existing anchor bounds. Existing Richards/retention configuration requires same layer count/kinds; treatment-bearing layers must retain their kind. Refusal preserves the authored stack. Success synchronizes dependent node MaxDepths/outlet offsets.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
[in]rowsNon-null copied array of count layers; unused parameters must be zero.
[in]countPositive authored layer count, including optional final BOTTOM. SURFACE may occur only first; at least one MEDIA/AGGREGATE is required.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ swmm_lid_node_outlet_get()

SWMM_ENGINE_API int swmm_lid_node_outlet_get ( SWMM_Engine engine,
int link,
int * layer,
int * top )

Read a link's LID layer anchor.

No lifecycle check.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]linkZero-based existing link index.
[out]layerNon-null output; zero when no anchor exists.
[out]topNon-null output: 0=BOTTOM, 1=TOP; zero when absent.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_lid_node_outlet_set()

SWMM_ENGINE_API int swmm_lid_node_outlet_set ( SWMM_Engine engine,
int link,
int layer,
int top )

Set or remove a link's LID layer anchor.

Requires BUILDING/OPENED. Nonzero layer requires exactly one LID endpoint and a valid layer index. Replaces any previous anchor, then synchronizes offsets; removal needs no LID endpoint.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]linkZero-based existing link index.
[in]layerZero removes the anchor; otherwise one-based physical layer, top-to-bottom excluding BOTTOM.
[in]top0=BOTTOM or 1=TOP, required even when removing.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.
Here is the call graph for this function:

◆ swmm_lid_node_state_count()

SWMM_ENGINE_API int swmm_lid_node_state_count ( SWMM_Engine engine,
int node )

Count initialized runtime profile cells.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
Returns
Nonnegative row count; -1 for null engine or invalid selected node/control. Runtime state count is zero for nonstorage/plain storage and before initialization.

◆ swmm_lid_node_state_get()

SWMM_ENGINE_API int swmm_lid_node_state_get ( SWMM_Engine engine,
int node,
int row,
int * layer,
double * bottom,
double * top,
double * moisture )

Read one initialized LID profile cell.

Runtime rows are top-to-bottom; porous layers may produce several cells. No lifecycle check, but node must be storage with an existing runtime row.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[in]rowZero-based row index in the selected profile/table.
[out]layerNon-null one-based physical layer identifier.
[out]bottomNon-null cell-bottom depth above node invert, ft/m.
[out]topNon-null cell-top depth above node invert, ft/m.
[out]moistureNon-null volumetric water fraction; Richards porous rows use theta, classical rows include mobile-head inundation.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.
Here is the call graph for this function:

◆ swmm_lid_node_treatment_count()

SWMM_ENGINE_API int swmm_lid_node_treatment_count ( SWMM_Engine engine,
int control )

Count per-layer treatment rows flattened top-to-bottom.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
Returns
Nonnegative row count; -1 for null engine or invalid control.
Here is the call graph for this function:

◆ swmm_lid_node_treatment_get()

SWMM_ENGINE_API int swmm_lid_node_treatment_get ( SWMM_Engine engine,
int control,
int row,
SWMM_LidLayerTreatment * out )

Read a flattened per-layer treatment row.

Reads explicitly authored node_layers storage; a control lacking that storage can return BADINDEX. removal_percent is 0..100; decay_per_day is per day.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
[in]rowZero-based flattened treatment index; negative/out-of-range rows return BADPARAM.
[out]outNon-null struct. expression borrows engine storage; do not free and copy before editing/destroying the control/engine. layer is one-based and pollutant is an engine pollutant index.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_lid_richards_material_get()

SWMM_ENGINE_API int swmm_lid_richards_material_get ( SWMM_Engine engine,
int control,
int row,
SWMM_LidRichardsMaterial * out )

Read a control's Richards material.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
[in]rowZero-based row index in the selected profile/table.
[out]outNon-null caller-owned output. alpha/specific_storage are inverse metres in both project unit systems; nonporous rows may contain unused defaults.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.
Here is the call graph for this function:

◆ swmm_lid_richards_options_get()

SWMM_ENGINE_API int swmm_lid_richards_options_get ( SWMM_Engine engine,
int control,
SWMM_LidRichardsOptions * out )

Read a control's Richards options.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]controlZero-based existing LID control index.
[out]outNon-null caller-owned output. Defaults are returned for an empty stack; model is 0 or 1.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.
Here is the call graph for this function:

◆ swmm_lid_richards_state_get()

SWMM_ENGINE_API int swmm_lid_richards_state_get ( SWMM_Engine engine,
int node,
int row,
double * pressure,
double * head,
double * water )

Read one Richards cell's pressure, total head and complete water volume.

Requires an initialized Richards storage profile; classical formulation returns BADPARAM. No state is advanced.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[in]rowZero-based row index in the selected profile/table.
[out]pressureNon-null pressure head in project length units, ft/m.
[out]headNon-null total hydraulic head in ft/m, including node invert and cell elevation.
[out]waterNon-null complete cell water in project volume units, ft3/m3; surface row uses node volume.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.
Here is the call graph for this function:

◆ swmm_lid_richards_statistics_get()

SWMM_ENGINE_API int swmm_lid_richards_statistics_get ( SWMM_Engine engine,
int node,
SWMM_LidRichardsStatistics * out )

Read the last stored Richards adaptive-solver report.

Returns BADPARAM unless the node uses Richards; does not advance/reset statistics.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[out]outNon-null caller-owned statistics: accepted/rejected steps, RHS evaluations, Newton iterations, min_step in seconds and balance_m3 in SI cubic metres.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.
Here is the call graph for this function:

◆ swmm_node_get_lid()

SWMM_ENGINE_API int swmm_node_get_lid ( SWMM_Engine engine,
int node,
int * control,
double * saturation )

Read a node LID-control assignment and initial saturation.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[out]controlNon-null control-index output; -1 for nonstorage/plain storage.
[out]saturationNon-null initial saturation output in percent; zero for nonstorage.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_node_get_lid_bottom()

SWMM_ENGINE_API int swmm_node_get_lid_bottom ( SWMM_Engine engine,
int node,
int * mode )

Read a node's bottom exchange ownership mode.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[out]modeNon-null SWMM_LID_BOTTOM_* destination; CURRENT for nodes without a LID assignment.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.
Here is the call graph for this function:

◆ swmm_node_set_lid()

SWMM_ENGINE_API int swmm_node_set_lid ( SWMM_Engine engine,
int node,
int control,
double saturation )

Assign or clear a storage-node LID and synchronize its geometry.

Requires BUILDING/OPENED and storage node. Checks existing outlet anchors and refuses a second LID endpoint. Clears node runtime LID state and cached full volume. Assignment preserves bottom mode; clearing resets CURRENT and removes attached outlet anchors.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[in]controlExisting control with a valid derived/authored stack, or -1 to clear the assignment.
[in]saturationFinite initial saturation in percent [0,100]; ignored/reset to zero when clearing.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.
Here is the call graph for this function:

◆ swmm_node_set_lid_bottom()

SWMM_ENGINE_API int swmm_node_set_lid_bottom ( SWMM_Engine engine,
int node,
int mode )

Select bottom ownership for one assigned storage LID.

Requires BUILDING/OPENED and an assigned storage LID. Authoring MESH_AQUIFER does not by itself establish a qualified executable mesh connection.

Parameters
[in]engineNon-null live engine; caller serializes access.
[in]nodeZero-based existing node index.
[in]modeSWMM_LID_BOTTOM_CURRENT, SEALED or MESH_AQUIFER.
Returns
SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.