![]() |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
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>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. | |
Public C API implementation for LID node configuration.
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [out] | area | Non-null contact-area destination in project square-length units, ft2 or m2; may be zero. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [out] | out | Non-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. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| [in] | layers | Non-null borrowed array of count layers, copied synchronously. See SWMM_LidNodeLayerKind for parameter positions/units; unused params must be zero. |
| [in] | count | Positive authored layer count, including optional final BOTTOM. SURFACE may occur only first; at least one MEDIA/AGGREGATE is required. |
| [in] | treatment | Borrowed 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_count | Nonnegative number of treatment rows; zero clears treatment. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| [in] | layers | Non-null borrowed array of count layers, copied synchronously. See SWMM_LidNodeLayerKind for parameter positions/units; unused params must be zero. |
| [in] | count | Positive authored layer count, including optional final BOTTOM. SURFACE may occur only first; at least one MEDIA/AGGREGATE is required. |
| [in] | treatment | Borrowed 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_count | Nonnegative number of treatment rows; zero clears treatment. |
| [in] | options | Non-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] | material | Borrowed 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. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| [in] | row | Zero-based row index in the selected profile/table. |
| [out] | out | Non-null caller-owned output receiving kind and all seven input-unit parameters. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| [in] | rows | Non-null copied array of count layers; unused parameters must be zero. |
| [in] | count | Positive authored layer count, including optional final BOTTOM. SURFACE may occur only first; at least one MEDIA/AGGREGATE is required. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | link | Zero-based existing link index. |
| [out] | layer | Non-null output; zero when no anchor exists. |
| [out] | top | Non-null output: 0=BOTTOM, 1=TOP; zero when absent. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | link | Zero-based existing link index. |
| [in] | layer | Zero removes the anchor; otherwise one-based physical layer, top-to-bottom excluding BOTTOM. |
| [in] | top | 0=BOTTOM or 1=TOP, required even when removing. |
| SWMM_ENGINE_API int swmm_lid_node_state_count | ( | SWMM_Engine | engine, |
| int | node ) |
Count initialized runtime profile cells.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [in] | row | Zero-based row index in the selected profile/table. |
| [out] | layer | Non-null one-based physical layer identifier. |
| [out] | bottom | Non-null cell-bottom depth above node invert, ft/m. |
| [out] | top | Non-null cell-top depth above node invert, ft/m. |
| [out] | moisture | Non-null volumetric water fraction; Richards porous rows use theta, classical rows include mobile-head inundation. |
| SWMM_ENGINE_API int swmm_lid_node_treatment_count | ( | SWMM_Engine | engine, |
| int | control ) |
Count per-layer treatment rows flattened top-to-bottom.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| [in] | row | Zero-based flattened treatment index; negative/out-of-range rows return BADPARAM. |
| [out] | out | Non-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. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| [in] | row | Zero-based row index in the selected profile/table. |
| [out] | out | Non-null caller-owned output. alpha/specific_storage are inverse metres in both project unit systems; nonporous rows may contain unused defaults. |
| SWMM_ENGINE_API int swmm_lid_richards_options_get | ( | SWMM_Engine | engine, |
| int | control, | ||
| SWMM_LidRichardsOptions * | out ) |
Read a control's Richards options.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | control | Zero-based existing LID control index. |
| [out] | out | Non-null caller-owned output. Defaults are returned for an empty stack; model is 0 or 1. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [in] | row | Zero-based row index in the selected profile/table. |
| [out] | pressure | Non-null pressure head in project length units, ft/m. |
| [out] | head | Non-null total hydraulic head in ft/m, including node invert and cell elevation. |
| [out] | water | Non-null complete cell water in project volume units, ft3/m3; surface row uses node 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.
Returns BADPARAM unless the node uses Richards; does not advance/reset statistics.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [out] | out | Non-null caller-owned statistics: accepted/rejected steps, RHS evaluations, Newton iterations, min_step in seconds and balance_m3 in SI cubic metres. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [out] | control | Non-null control-index output; -1 for nonstorage/plain storage. |
| [out] | saturation | Non-null initial saturation output in percent; zero for nonstorage. |
| SWMM_ENGINE_API int swmm_node_get_lid_bottom | ( | SWMM_Engine | engine, |
| int | node, | ||
| int * | mode ) |
Read a node's bottom exchange ownership mode.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [out] | mode | Non-null SWMM_LID_BOTTOM_* destination; CURRENT for nodes without a LID assignment. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [in] | control | Existing control with a valid derived/authored stack, or -1 to clear the assignment. |
| [in] | saturation | Finite initial saturation in percent [0,100]; ignored/reset to zero when clearing. |
| 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.
| [in] | engine | Non-null live engine; caller serializes access. |
| [in] | node | Zero-based existing node index. |
| [in] | mode | SWMM_LID_BOTTOM_CURRENT, SEALED or MESH_AQUIFER. |