G-step 19 — the two-zone groundwater kernel's C API: authoring the [2D_AQUIFER*] rows, and reading the state and ledger while a run is in flight. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_gw2d.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SWMM_GwBoundary

struct	SWMM_GwNodeBed

struct	SWMM_LidNodeBottomEdit

struct	SWMM_GwExecutionStatus

Macros
#define	SWMM_GW2D_SCOPE_GLOBAL 0

#define	SWMM_GW2D_SCOPE_TAG 1

#define	SWMM_GW2D_SCOPE_CELL 2

#define	SWMM_GW2D_SOIL_RUSSO 0

#define	SWMM_GW2D_SOIL_GARDNER 1

#define	SWMM_GW2D_SOIL_BROOKS_COREY 2

#define	SWMM_GW2D_SOIL_VAN_GENUCHTEN 3

#define	SWMM_GW2D_CLOSURE_AUTO (-1)

#define	SWMM_GW2D_CLOSURE_CLOSED_FORM 0

#define	SWMM_GW2D_CLOSURE_ENSLAVED 1

#define	SWMM_GW2D_CLOSURE_SIGMA 2

#define	SWMM_GW2D_BOUNDARY_HEAD 0

#define	SWMM_GW2D_BOUNDARY_FLOW 1

#define	SWMM_GW2D_VAR_HG 0

#define	SWMM_GW2D_VAR_HU 1

#define	SWMM_GW2D_VAR_TABLE_EL 2

#define	SWMM_GW2D_VAR_Q0 3

#define	SWMM_GW2D_VAR_QLAT 4

#define	SWMM_GW2D_VAR_QNODE 5

#define	SWMM_GW2D_VAR_QDEEP 6

#define	SWMM_GW2D_VAR_QET 7

#define	SWMM_GW2D_VAR_DUNNE 8

#define	SWMM_GW2D_VAR_QPLUS 9

#define	SWMM_GW2D_VAR_DT_CELL 10

#define	SWMM_GW2D_VAR_TIER 11

#define	SWMM_GW2D_VAR_CLOSURE 12

#define	SWMM_GW2D_VAR_QLINK 13

#define	SWMM_GW2D_VAR_INFIL_CAPACITY 14

#define	SWMM_GW2D_VAR_INFIL_REMAINING 15

#define	SWMM_GW2D_VAR_INFIL_REFRESH 16

#define	SWMM_GW2D_VAR_INFIL_PENDING 17

#define	SWMM_GW2D_VAR_REJECT 18

#define	SWMM_GW2D_VAR_REJECT_CUM 19

#define	SWMM_GW2D_VAR_DUNNE_CUM 20

#define	SWMM_GW2D_VAR_ET_PENDING 21

#define	SWMM_GW2D_VAR_ET_POTENTIAL_CUM 22

#define	SWMM_GW2D_VAR_ET_SURFACE_CUM 23

#define	SWMM_GW2D_VAR_ET_SOIL_CUM 24

#define	SWMM_GW2D_VAR_ET_UNUSED_CUM 25

#define	SWMM_GW2D_VAR_ET_SURFACE 26

#define	SWMM_GW2D_VAR_ET_POTENTIAL 27

#define	SWMM_GW2D_VAR_ET_STRESS 28

#define	SWMM_GW2D_VAR_ET_REFRESH 29

#define	SWMM_GW2D_LED_RECHARGE 0

#define	SWMM_GW2D_LED_LATERAL 1

#define	SWMM_GW2D_LED_DEEP 2

#define	SWMM_GW2D_LED_NODE 3

#define	SWMM_GW2D_LED_REJECT 13

#define	SWMM_GW2D_LED_DUNNE 4

#define	SWMM_GW2D_LED_CAPRISE 5

#define	SWMM_GW2D_LED_ET 6

#define	SWMM_GW2D_LED_INFIL_IN 7

#define	SWMM_GW2D_LED_INIT_STORAGE 8

#define	SWMM_GW2D_LED_STORAGE 9

#define	SWMM_GW2D_LED_SOURCE_IN 11

#define	SWMM_GW2D_LED_BOUNDARY_IN 14

#define	SWMM_GW2D_LED_BOUNDARY_OUT 15

#define	SWMM_GW2D_LED_SOURCE_OUT 12

#define	SWMM_GW2D_LED_LINK 10

#define	SWMM_GW2D_ZONE_SAT 0

#define	SWMM_GW2D_ZONE_UNSAT 1

#define	SWMM_GW2D_SPL_INIT 0

#define	SWMM_GW2D_SPL_STORAGE 1

#define	SWMM_GW2D_SPL_INFIL_IN 2

#define	SWMM_GW2D_SPL_NODE_IN 3

#define	SWMM_GW2D_SPL_LINK_IN 4

#define	SWMM_GW2D_SPL_LATERAL_NET 5

#define	SWMM_GW2D_SPL_DEEP_OUT 6

#define	SWMM_GW2D_SPL_NODE_OUT 7

#define	SWMM_GW2D_SPL_LINK_OUT 8

#define	SWMM_GW2D_SPL_DUNNE_OUT 9

#define	SWMM_GW2D_SPL_ET_OUT 10

#define	SWMM_GW2D_SPL_REACTED 11

#define	SWMM_GW2D_SPL_SOURCE_IN 13

#define	SWMM_GW2D_SPL_SOURCE_OUT 14

#define	SWMM_GW2D_SPL_BOUNDARY_IN 15

#define	SWMM_GW2D_SPL_BOUNDARY_OUT 16

#define	SWMM_GW2D_SPL_BOUNDARY_FLUX_IN 17

#define	SWMM_GW2D_SPL_BOUNDARY_FLUX_OUT 18

#define	SWMM_GW2D_SPL_AGE_GENERATED 19

#define	SWMM_GW2D_SPL_RESIDUAL 12

#define	SWMM_GW2D_OP_CLOSED_FORM_RECHARGE 1u

#define	SWMM_GW2D_HOST_WATER_AND_RECEIPTS 1u

#define	SWMM_GW2D_HOST_TRANSPORT 2u

#define	SWMM_GW2D_HOST_REACTIONS 4u

#define	SWMM_GW2D_HOST_THERMAL 8u

Typedefs
typedef struct SWMM_GwBoundary	SWMM_GwBoundary

typedef struct SWMM_GwNodeBed	SWMM_GwNodeBed

typedef struct SWMM_LidNodeBottomEdit	SWMM_LidNodeBottomEdit

typedef struct SWMM_GwExecutionStatus	SWMM_GwExecutionStatus

Functions
SWMM_ENGINE_API int	swmm_gw2d_boundary_count (SWMM_Engine engine)
	Read the authored exterior aquifer-boundary count.

SWMM_ENGINE_API int	swmm_gw2d_boundary_get (SWMM_Engine engine, int index, SWMM_GwBoundary row, char series, int series_len)
	Copy one authored exterior aquifer boundary and series name.

SWMM_ENGINE_API int	swmm_gw2d_boundary_set (SWMM_Engine engine, const SWMM_GwBoundary row, const char series)
	Upsert an authored exterior aquifer boundary by cell and edge.

SWMM_ENGINE_API int	swmm_gw2d_boundary_remove (SWMM_Engine engine, int index)
	Erase one authored exterior aquifer boundary.

SWMM_ENGINE_API int	swmm_gw2d_boundary_water (SWMM_Engine engine, int index, double requested_in, double requested_out, double applied_in, double applied_out)
	Runtime totals, in SI m3; getters leave outputs unchanged on error.

SWMM_ENGINE_API int	swmm_gw2d_boundary_species (SWMM_Engine engine, int index, int species, double advective_in, double advective_out, double imposed_in, double imposed_out)
	Runtime totals in native concentrationm3 (age sm3, temperature degC*m3). advective in/out and independently imposed flux in/out are separate.

SWMM_ENGINE_API int	swmm_gw2d_species_count (SWMM_Engine engine, int *count)
	How many species rows the aquifer transports (0 when it carries none).

SWMM_ENGINE_API int	swmm_gw2d_species_name (SWMM_Engine engine, int species, char *buf, int buflen)
	One species row's name (TransportPolicy order: pollutants, MSX, `__WATER_AGE__`, `__TEMPERATURE__`).

SWMM_ENGINE_API int	swmm_gw2d_get_cell_conc (SWMM_Engine engine, int zone, int species, double out, int len, int written)
	Per-cell CONCENTRATION of one species in one zone, in the species' own units. BULK retains total inventory / water volume (zero when dry). LAYERED uses aqueous plus sorption capacity for a dissolved equivalent. Writes at most `len` values and sets `written`.

SWMM_ENGINE_API int	swmm_gw2d_get_layer_quality (SWMM_Engine engine, int cell, int layer, int species, double water, double mass, double *concentration)
	Canonical SIGMA chemistry, zero-based layer and species. Outputs are unchanged on error; BULK chemistry returns SWMM_ERR_BADPARAM. Mass uses native concentration times m3, water uses m3, concentration is dissolved.

SWMM_ENGINE_API int	swmm_gw2d_get_species_ledger (SWMM_Engine engine, int species, int term, double *value)
	One term of one species' cumulative ledger — see SWMM_GW2D_SPL_*.

SWMM_ENGINE_API int	swmm_gw2d_option_get (SWMM_Engine engine, const char key, char buf, int buflen)
	Read one option as text. Keys: SOIL_CHAR, CLOSURE, M_LAYERS, CAPILLARY_DIFF, C_GW, C_COL, FORCE_CLOSED_FORM, MODE, DUNNE, GW_ET, NODE_ENROLMENT (AUTO \| ROWS), LINK_SEEPAGE (DEFAULT \| ONE_WAY \| TWO_WAY \| NONE), WILTING_SUCTION (AUTO \| positive project length). Read-only keys: GW_ET_EFFECTIVE, LINK_SEEPAGE_EFFECTIVE, WILTING_SUCTION_EFFECTIVE, CONFIGURED and OPTIONS_AUTHORED. Legacy LINK_SEEPAGE AUTO means ONE_WAY.

SWMM_ENGINE_API int	swmm_gw2d_process_options_set (SWMM_Engine engine, const char et, const char link, const char *wilting, int authored)
	Atomically replace GW_ET, LINK_SEEPAGE and WILTING_SUCTION before a run. GW_ET AUTO defaults to BOTH on a mesh, NONE in PER_SUBCATCH. LINK_SEEPAGE DEFAULT defaults to TWO_WAY on a mesh; ONE_WAY and legacy AUTO retain explicit one-way delivery. WILTING_SUCTION AUTO means 150 m; a custom positive number is in project length units. authored must be 0 or 1 and restores section provenance for atomic GUI Undo.

SWMM_ENGINE_API int	swmm_gw2d_option_set (SWMM_Engine engine, const char key, const char value)
	Set an authored option from text through the same parser as the file.

SWMM_ENGINE_API int	swmm_gw2d_row_count (SWMM_Engine engine, int *count)
	Number of authored rows.

SWMM_ENGINE_API int	swmm_gw2d_row_add (SWMM_Engine engine, int scope, const char *tag, int cell, double ks, double zs, double theta_s, double theta_r, double alpha)
	Append one row. Values are in the PROJECT's units.

SWMM_ENGINE_API int	swmm_gw2d_row_get (SWMM_Engine engine, int index, int scope, char tag, int taglen, int cell, double ks, double zs, double theta_s, double theta_r, double alpha)
	Read row `index` back, in the units it was authored in. Any out pointer may be NULL. `tag` needs `taglen` bytes.

SWMM_ENGINE_API int	swmm_gw2d_row_set_property (SWMM_Engine engine, int index, const char *key, double value)
	Set one of a row's optional properties. Keys: PSI_B, LAMBDA, N, L, C_LOSS, HG0, SOIL_CHAR, CLOSURE, M_LAYERS. The numeric-valued keys take `value`; SOIL_CHAR and CLOSURE take the SWMM_GW2D_SOIL_* / SWMM_GW2D_CLOSURE_* codes as a double, which keeps this one entry point instead of nine.

SWMM_ENGINE_API int	swmm_gw2d_row_get_property (SWMM_Engine engine, int index, const char key, double value)
	Read one optional property back.

SWMM_ENGINE_API int	swmm_gw2d_row_remove (SWMM_Engine engine, int index)
	Remove row `index`.

SWMM_ENGINE_API int	swmm_gw2d_node_count (SWMM_Engine engine, int *count)
	Read the current aquifer node-bed row count.

SWMM_ENGINE_API int	swmm_gw2d_node_add (SWMM_Engine engine, const char *node, int cell, double kc, double dc, double area)
	Add a node bed. `kc` in in/hr \| mm/hr, `dc` in ft \| m, `area` in ft2 \| m2 (0 = the cell's own area). `kc` == 0 means direct Darcy.

SWMM_ENGINE_API int	swmm_gw2d_node_get (SWMM_Engine engine, int index, char node, int nodelen, int cell, double kc, double dc, double *area)
	Read one authored/resolved aquifer node-bed row.

SWMM_ENGINE_API int	swmm_gw2d_node_remove (SWMM_Engine engine, int index)
	Erase one aquifer node-bed row and its stored node name.

SWMM_ENGINE_API int	swmm_gw2d_node_get_flags (SWMM_Engine engine, int index, int locate, int exchange, int *automatic)
	G-X2 (2026-09-19): a bed's enrolment state. `locate` — the cell is found from the node's [COORDINATES] at initialize (`CELL AUTO`; pass cell −1 to swmm_gw2d_node_add); `exchange` — 0 when the row opts the node OUT (`EXCHANGE NO`); `automatic` — enrolled by NODE_ENROLMENT AUTO rather than authored (present after initialize only; not written back). Any pointer may be NULL.

SWMM_ENGINE_API int	swmm_gw2d_node_set_exchange (SWMM_Engine engine, int index, int exchange)
	G-X2: set a row's EXCHANGE flag (0 = the node exchanges with nothing).

SWMM_ENGINE_API int	swmm_gw2d_node_replace (SWMM_Engine engine, const SWMM_GwNodeBed expected, int expected_count, const SWMM_GwNodeBed replacement, int count, const SWMM_LidNodeBottomEdit *bottoms, int bottom_count, int apply)
	BUILDING/OPENED only. Compares the entire current bed list with expected, validates every replacement and owner edit, then publishes once. Stale, duplicate, unknown, nonfinite or contradictory input returns BADPARAM and changes nothing. Mesh ownership requires an enabled MESH aquifer and an enabled authored bed with positive AREA; mapping is checked at initialize. Mesh execution remains gated until R5 numerical/restart qualification. Existing AREA=0 retains whole-cell semantics. NULL arrays require count=0. apply=0 validates a private draft only; apply=1 publishes it.

SWMM_ENGINE_API int	swmm_gw2d_link_count (SWMM_Engine engine, int *count)
	Read the authored conduit-bed row count.

SWMM_ENGINE_API int	swmm_gw2d_link_add (SWMM_Engine engine, const char *link, double kc, double dc, int exchange)
	Add a conduit bed row. `kc` in the [LOSSES] seepage units (0 = the conduit's own seep rate), `dc` in ft \| m (0 = the conduit's full depth); both >= 0. `exchange` 0 keeps the conduit a legacy loss (EXCHANGE NO). The link name resolves at initialize, as for node beds.

SWMM_ENGINE_API int	swmm_gw2d_link_get (SWMM_Engine engine, int index, char link, int linklen, double kc, double dc, int exchange)
	Read one authored aquifer conduit-bed row.

SWMM_ENGINE_API int	swmm_gw2d_link_remove (SWMM_Engine engine, int index)
	Erase one authored aquifer conduit-bed row.

SWMM_ENGINE_API int	swmm_gw2d_is_active (SWMM_Engine engine, int *active)
	Non-zero once a `[2D_AQUIFER]` row has resolved and the kernel is live.

SWMM_ENGINE_API int	swmm_gw2d_get_dimensions (SWMM_Engine engine, int n_cells, int m_layers)
	Cells the kernel covers, and the sigma layer count (1 when no cell uses closure B). Either pointer may be NULL.

SWMM_ENGINE_API int	swmm_gw2d_get_cell (SWMM_Engine engine, int cell, int var, double *value)
	One cell, one variable — see SWMM_GW2D_VAR_*.

SWMM_ENGINE_API int	swmm_gw2d_get_cell_bulk (SWMM_Engine engine, int var, double out, int len, int written)
	Bulk read of one variable over `[0, n_cells)`. `len` must be at least the cell count; the number written is returned through `written`.

SWMM_ENGINE_API int	swmm_gw2d_get_column (SWMM_Engine engine, int cell, double theta, int len, int written)
	The sigma column of one cell: `m_layers` water contents, layer 0 at the ground surface. Refused with SWMM_ERR_BADPARAM when the cell's closure is not SIGMA — an all-zero buffer would read as a bone-dry column.

SWMM_ENGINE_API int	swmm_gw2d_get_ledger (SWMM_Engine engine, int term, double *value)
	One ledger term — see SWMM_GW2D_LED_*.

SWMM_ENGINE_API int	swmm_gw2d_get_continuity_error (SWMM_Engine engine, double *value)
	Continuity residual (m3): `storage_now − storage_init − (in − out)`.

SWMM_ENGINE_API int	swmm_gw2d_get_tier_histogram (SWMM_Engine engine, long out, int len, int written)
	Cumulative firings per LTS tier — the G-A telemetry. Writes `min(len, tier_count)` entries.

SWMM_ENGINE_API int	swmm_gw2d_get_execution_status (SWMM_Engine engine, SWMM_GwExecutionStatus *status)
	Runtime after initialization. Availability is distinct from actual use; surface backend selection is reported separately by swmm_2d_get_run_stats. Invalid size/handle/state leaves the caller's record unchanged.

Detailed Description

G-step 19 — the two-zone groundwater kernel's C API: authoring the [2D_AQUIFER*] rows, and reading the state and ledger while a run is in flight.

The API has two halves and they obey different rules.

     **Authoring** (`swmm_gw2d_option_*`, `swmm_gw2d_row_*`,
     `swmm_gw2d_node_*`) edits the rows the kernel is built from, so it
     requires BUILDING or OPENED — exactly like the 2D boundary and
     infiltration APIs. A mid-run edit would be silently ignored, which
     is worse than being refused. Values are in the PROJECT's units
     (see SubsurfaceSections.hpp's table); the API does not convert,
     because a host that sets what it read back must get the same
     number.

     **State** (`swmm_gw2d_get_*`) reads the running kernel and is
     available whenever a run has started. Everything it returns is
     **SI** — metres, seconds, m³ — because that is what the kernel
     holds and converting on the way out would make a reader's units
     depend on the project's, which is precisely the bug class the
     engine's 1D↔2D seam already had once.

     **Cell-generic.** Every index is a CELL (`0 .. cell_count−1` here;
     1-based in the `.inp`). Nothing assumes three edges.

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

◆ SWMM_GW2D_BOUNDARY_FLOW

#define SWMM_GW2D_BOUNDARY_FLOW 1

◆ SWMM_GW2D_BOUNDARY_HEAD

#define SWMM_GW2D_BOUNDARY_HEAD 0

◆ SWMM_GW2D_CLOSURE_AUTO

#define SWMM_GW2D_CLOSURE_AUTO (-1)

◆ SWMM_GW2D_CLOSURE_CLOSED_FORM

#define SWMM_GW2D_CLOSURE_CLOSED_FORM 0

◆ SWMM_GW2D_CLOSURE_ENSLAVED

#define SWMM_GW2D_CLOSURE_ENSLAVED 1

◆ SWMM_GW2D_CLOSURE_SIGMA

#define SWMM_GW2D_CLOSURE_SIGMA 2

◆ SWMM_GW2D_HOST_REACTIONS

#define SWMM_GW2D_HOST_REACTIONS 4u

◆ SWMM_GW2D_HOST_THERMAL

#define SWMM_GW2D_HOST_THERMAL 8u

◆ SWMM_GW2D_HOST_TRANSPORT

#define SWMM_GW2D_HOST_TRANSPORT 2u

◆ SWMM_GW2D_HOST_WATER_AND_RECEIPTS

#define SWMM_GW2D_HOST_WATER_AND_RECEIPTS 1u

◆ SWMM_GW2D_LED_BOUNDARY_IN

#define SWMM_GW2D_LED_BOUNDARY_IN 14

Gross boundary inflow; included in LATERAL.

◆ SWMM_GW2D_LED_BOUNDARY_OUT

#define SWMM_GW2D_LED_BOUNDARY_OUT 15

Gross boundary outflow; included in LATERAL.

◆ SWMM_GW2D_LED_CAPRISE

#define SWMM_GW2D_LED_CAPRISE 5

◆ SWMM_GW2D_LED_DEEP

#define SWMM_GW2D_LED_DEEP 2

◆ SWMM_GW2D_LED_DUNNE

#define SWMM_GW2D_LED_DUNNE 4

◆ SWMM_GW2D_LED_ET

#define SWMM_GW2D_LED_ET 6

◆ SWMM_GW2D_LED_INFIL_IN

#define SWMM_GW2D_LED_INFIL_IN 7

◆ SWMM_GW2D_LED_INIT_STORAGE

#define SWMM_GW2D_LED_INIT_STORAGE 8

◆ SWMM_GW2D_LED_LATERAL

#define SWMM_GW2D_LED_LATERAL 1

◆ SWMM_GW2D_LED_LINK

#define SWMM_GW2D_LED_LINK 10

G-X3: conduit seepage delivered in

◆ SWMM_GW2D_LED_NODE

#define SWMM_GW2D_LED_NODE 3

◆ SWMM_GW2D_LED_RECHARGE

#define SWMM_GW2D_LED_RECHARGE 0

◆ SWMM_GW2D_LED_REJECT

#define SWMM_GW2D_LED_REJECT 13

rejected infiltration only (m3)

◆ SWMM_GW2D_LED_SOURCE_IN

#define SWMM_GW2D_LED_SOURCE_IN 11

Named source injection, m3.

◆ SWMM_GW2D_LED_SOURCE_OUT

#define SWMM_GW2D_LED_SOURCE_OUT 12

Actual availability-limited extraction, m3.

◆ SWMM_GW2D_LED_STORAGE

#define SWMM_GW2D_LED_STORAGE 9

storage NOW, incl. accumulators

◆ SWMM_GW2D_OP_CLOSED_FORM_RECHARGE

#define SWMM_GW2D_OP_CLOSED_FORM_RECHARGE 1u

◆ SWMM_GW2D_SCOPE_CELL

#define SWMM_GW2D_SCOPE_CELL 2

one cell, 0-based here

◆ SWMM_GW2D_SCOPE_GLOBAL

#define SWMM_GW2D_SCOPE_GLOBAL 0

the * row

◆ SWMM_GW2D_SCOPE_TAG

#define SWMM_GW2D_SCOPE_TAG 1

every cell carrying a tag

◆ SWMM_GW2D_SOIL_BROOKS_COREY

#define SWMM_GW2D_SOIL_BROOKS_COREY 2

◆ SWMM_GW2D_SOIL_GARDNER

#define SWMM_GW2D_SOIL_GARDNER 1

◆ SWMM_GW2D_SOIL_RUSSO

#define SWMM_GW2D_SOIL_RUSSO 0

◆ SWMM_GW2D_SOIL_VAN_GENUCHTEN

#define SWMM_GW2D_SOIL_VAN_GENUCHTEN 3

◆ SWMM_GW2D_SPL_AGE_GENERATED

#define SWMM_GW2D_SPL_AGE_GENERATED 19

◆ SWMM_GW2D_SPL_BOUNDARY_FLUX_IN

#define SWMM_GW2D_SPL_BOUNDARY_FLUX_IN 17

◆ SWMM_GW2D_SPL_BOUNDARY_FLUX_OUT

#define SWMM_GW2D_SPL_BOUNDARY_FLUX_OUT 18

◆ SWMM_GW2D_SPL_BOUNDARY_IN

#define SWMM_GW2D_SPL_BOUNDARY_IN 15

◆ SWMM_GW2D_SPL_BOUNDARY_OUT

#define SWMM_GW2D_SPL_BOUNDARY_OUT 16

◆ SWMM_GW2D_SPL_DEEP_OUT

#define SWMM_GW2D_SPL_DEEP_OUT 6

◆ SWMM_GW2D_SPL_DUNNE_OUT

#define SWMM_GW2D_SPL_DUNNE_OUT 9

◆ SWMM_GW2D_SPL_ET_OUT

#define SWMM_GW2D_SPL_ET_OUT 10

◆ SWMM_GW2D_SPL_INFIL_IN

#define SWMM_GW2D_SPL_INFIL_IN 2

◆ SWMM_GW2D_SPL_INIT

#define SWMM_GW2D_SPL_INIT 0

Species ledger terms — the groundwater_species_ledger order.

◆ SWMM_GW2D_SPL_LATERAL_NET

#define SWMM_GW2D_SPL_LATERAL_NET 5

◆ SWMM_GW2D_SPL_LINK_IN

#define SWMM_GW2D_SPL_LINK_IN 4

◆ SWMM_GW2D_SPL_LINK_OUT

#define SWMM_GW2D_SPL_LINK_OUT 8

◆ SWMM_GW2D_SPL_NODE_IN

#define SWMM_GW2D_SPL_NODE_IN 3

◆ SWMM_GW2D_SPL_NODE_OUT

#define SWMM_GW2D_SPL_NODE_OUT 7

◆ SWMM_GW2D_SPL_REACTED

#define SWMM_GW2D_SPL_REACTED 11

◆ SWMM_GW2D_SPL_RESIDUAL

#define SWMM_GW2D_SPL_RESIDUAL 12

storage + out - in - init

◆ SWMM_GW2D_SPL_SOURCE_IN

#define SWMM_GW2D_SPL_SOURCE_IN 13

Native concentration times m3.

◆ SWMM_GW2D_SPL_SOURCE_OUT

#define SWMM_GW2D_SPL_SOURCE_OUT 14

Extracted dissolved species.

◆ SWMM_GW2D_SPL_STORAGE

#define SWMM_GW2D_SPL_STORAGE 1

ledgered storage NOW

◆ SWMM_GW2D_VAR_CLOSURE

#define SWMM_GW2D_VAR_CLOSURE 12

resolved closure (AUTO already gone)

◆ SWMM_GW2D_VAR_DT_CELL

#define SWMM_GW2D_VAR_DT_CELL 10

min(dt_g, dt_u) (s)

◆ SWMM_GW2D_VAR_DUNNE

#define SWMM_GW2D_VAR_DUNNE 8

saturation excess to surface (m3/s)

◆ SWMM_GW2D_VAR_DUNNE_CUM

#define SWMM_GW2D_VAR_DUNNE_CUM 20

Cumulative physical saturation excess (m3)

◆ SWMM_GW2D_VAR_ET_PENDING

#define SWMM_GW2D_VAR_ET_PENDING 21

Pending past atmospheric demand after actual surface evaporation (m3)

◆ SWMM_GW2D_VAR_ET_POTENTIAL

#define SWMM_GW2D_VAR_ET_POTENTIAL 27

Potential demand at last surface interval (m s-1)

◆ SWMM_GW2D_VAR_ET_POTENTIAL_CUM

#define SWMM_GW2D_VAR_ET_POTENTIAL_CUM 22

Cumulative single mesh-area potential atmospheric demand (m3)

◆ SWMM_GW2D_VAR_ET_REFRESH

#define SWMM_GW2D_VAR_ET_REFRESH 29

Last completed demand interval end since start (s)

◆ SWMM_GW2D_VAR_ET_SOIL_CUM

#define SWMM_GW2D_VAR_ET_SOIL_CUM 24

Cumulative actual soil ET (m3)

◆ SWMM_GW2D_VAR_ET_STRESS

#define SWMM_GW2D_VAR_ET_STRESS 28

Single extraction-site moisture stress factor (1)

◆ SWMM_GW2D_VAR_ET_SURFACE

#define SWMM_GW2D_VAR_ET_SURFACE 26

Actual surface evaporation at last surface interval (m s-1)

◆ SWMM_GW2D_VAR_ET_SURFACE_CUM

#define SWMM_GW2D_VAR_ET_SURFACE_CUM 23

Cumulative actual surface evaporation (m3)

◆ SWMM_GW2D_VAR_ET_UNUSED_CUM

#define SWMM_GW2D_VAR_ET_UNUSED_CUM 25

Cumulative expired unused soil demand (m3)

◆ SWMM_GW2D_VAR_HG

#define SWMM_GW2D_VAR_HG 0

saturated thickness (m)

◆ SWMM_GW2D_VAR_HU

#define SWMM_GW2D_VAR_HU 1

unsaturated storage (m of water)

◆ SWMM_GW2D_VAR_INFIL_CAPACITY

#define SWMM_GW2D_VAR_INFIL_CAPACITY 14

Aquifer top-interface receiving capacity (m s-1)

◆ SWMM_GW2D_VAR_INFIL_PENDING

#define SWMM_GW2D_VAR_INFIL_PENDING 17

Reserved surface water pending aquifer firing (m3)

◆ SWMM_GW2D_VAR_INFIL_REFRESH

#define SWMM_GW2D_VAR_INFIL_REFRESH 16

Capacity refresh time since simulation start (s)

◆ SWMM_GW2D_VAR_INFIL_REMAINING

#define SWMM_GW2D_VAR_INFIL_REMAINING 15

Remaining receiving allowance after pending receipts (m3)

◆ SWMM_GW2D_VAR_Q0

#define SWMM_GW2D_VAR_Q0 3

recharge (m/s), + down

◆ SWMM_GW2D_VAR_QDEEP

#define SWMM_GW2D_VAR_QDEEP 6

deep loss (m/s)

◆ SWMM_GW2D_VAR_QET

#define SWMM_GW2D_VAR_QET 7

subsurface ET (m/s)

◆ SWMM_GW2D_VAR_QLAT

#define SWMM_GW2D_VAR_QLAT 4

net lateral Darcy in (m3/s)

◆ SWMM_GW2D_VAR_QLINK

#define SWMM_GW2D_VAR_QLINK 13

G-X3: conduit seepage delivered in (m3/s)

◆ SWMM_GW2D_VAR_QNODE

#define SWMM_GW2D_VAR_QNODE 5

node exchange (m3/s), + out

◆ SWMM_GW2D_VAR_QPLUS

#define SWMM_GW2D_VAR_QPLUS 9

infiltration delivered in (m/s)

◆ SWMM_GW2D_VAR_REJECT

#define SWMM_GW2D_VAR_REJECT 18

Rejected top-interface delivery returned to surface (m3 s-1)

◆ SWMM_GW2D_VAR_REJECT_CUM

#define SWMM_GW2D_VAR_REJECT_CUM 19

Cumulative rejected top-interface delivery (m3)

◆ SWMM_GW2D_VAR_TABLE_EL

#define SWMM_GW2D_VAR_TABLE_EL 2

water-table elevation (m)

◆ SWMM_GW2D_VAR_TIER

#define SWMM_GW2D_VAR_TIER 11

assigned LTS tier

◆ SWMM_GW2D_ZONE_SAT

#define SWMM_GW2D_ZONE_SAT 0

Zone selector for the species accessors. the saturated zone

◆ SWMM_GW2D_ZONE_UNSAT

#define SWMM_GW2D_ZONE_UNSAT 1

the unsaturated column store

Typedef Documentation

◆ SWMM_GwBoundary

typedef struct SWMM_GwBoundary SWMM_GwBoundary

Authored HEAD is project-length elevation; FLOW is total signed m3/s, positive into the aquifer. cell/edge are zero-based. A nonempty series supplied to set/get replaces the constant value. Edits require BUILDING/OPENED.

◆ SWMM_GwExecutionStatus

typedef struct SWMM_GwExecutionStatus SWMM_GwExecutionStatus

◆ SWMM_GwNodeBed

typedef struct SWMM_GwNodeBed SWMM_GwNodeBed

Complete authored/resolved bed snapshot in project units. locate preserves CELL AUTO even after it has resolved to a nonnegative cell. automatic rows may be retained unchanged; they cannot be fabricated by this edit API.

◆ SWMM_LidNodeBottomEdit

typedef struct SWMM_LidNodeBottomEdit SWMM_LidNodeBottomEdit

Compare-and-replace a per-node owner as part of the same bed transaction. Modes are SWMM_LID_BOTTOM_* from openswmm_infrastructure.h.

Function Documentation

◆ swmm_gw2d_boundary_count()

SWMM_ENGINE_API int swmm_gw2d_boundary_count ( SWMM_Engine engine )

Read the authored exterior aquifer-boundary count.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Returns: Number of authored boundaries, or SWMM_ERR_BADHANDLE for a null engine.

◆ swmm_gw2d_boundary_get()

SWMM_ENGINE_API int swmm_gw2d_boundary_get	(	SWMM_Engine	engine,
		int	index,
		SWMM_GwBoundary *	row,
		char *	series,
		int	series_len )

Copy one authored exterior aquifer boundary and series name.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based authored boundary index.
[out]	row	Required destination for the complete boundary row in authored units.
[out]	series	Required destination for the complete series name, including NUL.
[in]	series_len	Positive byte capacity; a short buffer returns SWMM_ERR_BUFSIZE without truncation.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, SWMM_ERR_BUFSIZE for a short series buffer, or SWMM_ERR_BADPARAM for invalid arguments. Invalid boundary indices return SWMM_ERR_BADINDEX; outputs remain unchanged on error.

◆ swmm_gw2d_boundary_remove()

SWMM_ENGINE_API int swmm_gw2d_boundary_remove	(	SWMM_Engine	engine,
		int	index )

Erase one authored exterior aquifer boundary.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based authored boundary to erase; later indices shift down.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments. Out-of-range indices return SWMM_ERR_BADINDEX.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_boundary_set()

SWMM_ENGINE_API int swmm_gw2d_boundary_set	(	SWMM_Engine	engine,
		const SWMM_GwBoundary *	row,
		const char *	series )

Upsert an authored exterior aquifer boundary by cell and edge.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	row	Required row; cell >= 0, edge in [0,3], kind HEAD or FLOW, and finite value. Mesh-local edge existence is resolved when initialized.
[in]	series	Optional copied series name; NULL means constant forcing. Newlines, carriage returns and quote characters are rejected.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_boundary_species()

SWMM_ENGINE_API int swmm_gw2d_boundary_species	(	SWMM_Engine	engine,
		int	index,
		int	species,
		double *	advective_in,
		double *	advective_out,
		double *	imposed_in,
		double *	imposed_out )

Runtime totals in native concentration*m3 (age s*m3, temperature degC*m3). advective in/out and independently imposed flux in/out are separate.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based resolved runtime boundary index.
[in]	species	Zero-based transported species index.
[out]	advective_in	Required destination for the cumulative advective in total.
[out]	advective_out	Required destination for the cumulative advective out total.
[out]	imposed_in	Required destination for the cumulative imposed in total.
[out]	imposed_out	Required destination for the cumulative imposed out total.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments. Invalid boundary/species indices return SWMM_ERR_BADINDEX; all outputs remain unchanged on error.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_boundary_water()

SWMM_ENGINE_API int swmm_gw2d_boundary_water	(	SWMM_Engine	engine,
		int	index,
		double *	requested_in,
		double *	requested_out,
		double *	applied_in,
		double *	applied_out )

Runtime totals, in SI m3; getters leave outputs unchanged on error.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based resolved runtime boundary index.
[out]	requested_in	Required destination for the cumulative requested in total.
[out]	requested_out	Required destination for the cumulative requested out total.
[out]	applied_in	Required destination for the cumulative applied in total.
[out]	applied_out	Required destination for the cumulative applied out total.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments. Invalid boundary/species indices return SWMM_ERR_BADINDEX; all outputs remain unchanged on error.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_cell()

SWMM_ENGINE_API int swmm_gw2d_get_cell	(	SWMM_Engine	engine,
		int	cell,
		int	var,
		double *	value )

One cell, one variable — see SWMM_GW2D_VAR_*.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	cell	Zero-based covered cell index.
[in]	var	SWMM_GW2D_VAR_* selector; units are declared with each selector.
[out]	value	Required destination; unchanged on failure. A nonfinite state value returns SWMM_ERR_LIFECYCLE rather than publishing it.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_cell_bulk()

SWMM_ENGINE_API int swmm_gw2d_get_cell_bulk	(	SWMM_Engine	engine,
		int	var,
		double *	out,
		int	len,
		int *	written )

Bulk read of one variable over [0, n_cells). len must be at least the cell count; the number written is returned through written.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	var	SWMM_GW2D_VAR_* selector; units follow that selector.
[out]	out	Required array with room for every covered cell; native state values, including nonfinite values, are copied without the scalar getter's finite check.
[in]	len	Array capacity in doubles, at least n_cells.
[out]	written	Optional count destination, updated after successful completion.

Note: An invalid selector can modify the first output slot before returning an error.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_cell_conc()

SWMM_ENGINE_API int swmm_gw2d_get_cell_conc	(	SWMM_Engine	engine,
		int	zone,
		int	species,
		double *	out,
		int	len,
		int *	written )

Per-cell CONCENTRATION of one species in one zone, in the species' own units. BULK retains total inventory / water volume (zero when dry). LAYERED uses aqueous plus sorption capacity for a dissolved equivalent. Writes at most len values and sets written.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	zone	SWMM_GW2D_ZONE_SAT or SWMM_GW2D_ZONE_UNSAT.
[in]	species	Zero-based transported species index.
[out]	out	Required writable array, in the species native concentration units.
[in]	len	Positive capacity in doubles; partial cell reads are permitted.
[out]	written	Optional count destination, min(len, transport cell count).

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments. Inactive transport or invalid species returns SWMM_ERR_BADINDEX.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

Here is the call graph for this function:

◆ swmm_gw2d_get_column()

SWMM_ENGINE_API int swmm_gw2d_get_column	(	SWMM_Engine	engine,
		int	cell,
		double *	theta,
		int	len,
		int *	written )

The sigma column of one cell: m_layers water contents, layer 0 at the ground surface. Refused with SWMM_ERR_BADPARAM when the cell's closure is not SIGMA — an all-zero buffer would read as a bone-dry column.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	cell	Zero-based covered SIGMA cell index.
[out]	theta	Required array receiving dimensionless water content, surface layer first.
[in]	len	Capacity in doubles, at least m_layers.
[out]	written	Optional successful result count.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_continuity_error()

SWMM_ENGINE_API int swmm_gw2d_get_continuity_error	(	SWMM_Engine	engine,
		double *	value )

Continuity residual (m3): storage_now − storage_init − (in − out).

The single number that says whether the kernel is conserving. storage_now includes anything still parked in a side accumulator, because between firings that water is real and is simply not on a cell yet — a residual computed without it reports a leak that is not there. See SubsurfaceSolver::settle.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	value	Required destination for the signed conservation residual in m3.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_dimensions()

SWMM_ENGINE_API int swmm_gw2d_get_dimensions	(	SWMM_Engine	engine,
		int *	n_cells,
		int *	m_layers )

Cells the kernel covers, and the sigma layer count (1 when no cell uses closure B). Either pointer may be NULL.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	n_cells	Optional destination for the covered cell count.
[out]	m_layers	Optional destination for sigma layer count, or 1 without SIGMA.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_execution_status()

SWMM_ENGINE_API int swmm_gw2d_get_execution_status	(	SWMM_Engine	engine,
		SWMM_GwExecutionStatus *	status )

Runtime after initialization. Availability is distinct from actual use; surface backend selection is reported separately by swmm_2d_get_run_stats. Invalid size/handle/state leaves the caller's record unchanged.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in,out]	status	Required caller-owned record with struct_size initialized to sizeof(SWMM_GwExecutionStatus); completely replaced only on success.

Note: Backend/status strings are fixed-size NUL-terminated copies. The record reports host-owned work separately from recharge operator availability and use.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_layer_quality()

SWMM_ENGINE_API int swmm_gw2d_get_layer_quality	(	SWMM_Engine	engine,
		int	cell,
		int	layer,
		int	species,
		double *	water,
		double *	mass,
		double *	concentration )

Canonical SIGMA chemistry, zero-based layer and species. Outputs are unchanged on error; BULK chemistry returns SWMM_ERR_BADPARAM. Mass uses native concentration times m3, water uses m3, concentration is dissolved.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	cell	Zero-based covered cell index.
[in]	layer	Zero-based unsaturated chemistry layer, surface first.
[in]	species	Zero-based transported species index.
[out]	water	Required layer-water destination, m3.
[out]	mass	Required total inventory destination, native concentration times m3.
[out]	concentration	Required dissolved equivalent concentration destination; uses water plus sorption capacity, or zero if that capacity is nonpositive.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments. Invalid cell/layer/species returns SWMM_ERR_BADINDEX.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_ledger()

SWMM_ENGINE_API int swmm_gw2d_get_ledger	(	SWMM_Engine	engine,
		int	term,
		double *	value )

One ledger term — see SWMM_GW2D_LED_*.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	term	SWMM_GW2D_LED_* selector.
[out]	value	Required destination in m3. STORAGE is current live holdings, including accumulators; other terms are cumulative accepted ledger entries.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_species_ledger()

SWMM_ENGINE_API int swmm_gw2d_get_species_ledger	(	SWMM_Engine	engine,
		int	species,
		int	term,
		double *	value )

One term of one species' cumulative ledger — see SWMM_GW2D_SPL_*.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	species	Zero-based active transported species index.
[in]	term	SWMM_GW2D_SPL_* selector.
[out]	value	Required destination, native concentration times m3; water-age uses sm3 and temperature uses degrees Cm3.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments. Inactive transport or an invalid species returns SWMM_ERR_BADINDEX.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_get_tier_histogram()

SWMM_ENGINE_API int swmm_gw2d_get_tier_histogram	(	SWMM_Engine	engine,
		long *	out,
		int	len,
		int *	written )

Cumulative firings per LTS tier — the G-A telemetry. Writes min(len, tier_count) entries.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	out	Required writable counter array.
[in]	len	Positive capacity in long counters; partial reads are permitted.
[out]	written	Optional destination for min(len, tier_count).

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_is_active()

SWMM_ENGINE_API int swmm_gw2d_is_active	(	SWMM_Engine	engine,
		int *	active )

Non-zero once a [2D_AQUIFER] row has resolved and the kernel is live.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	active	Required result, 1 for a live aquifer kernel or 0 otherwise.

Note: Safe before initialization; does not require an active runtime.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_link_add()

SWMM_ENGINE_API int swmm_gw2d_link_add	(	SWMM_Engine	engine,
		const char *	link,
		double	kc,
		double	dc,
		int	exchange )

Add a conduit bed row. kc in the [LOSSES] seepage units (0 = the conduit's own seep rate), dc in ft | m (0 = the conduit's full depth); both >= 0. exchange 0 keeps the conduit a legacy loss (EXCHANGE NO). The link name resolves at initialize, as for node beds.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	link	Required nonempty copied conduit name, resolved at initialize.
[in]	kc	Nonnegative seepage conductivity in project LOSSES units; zero inherits the conduit.
[in]	dc	Nonnegative thickness in ft or m; zero inherits full conduit depth.
[in]	exchange	Zero disables aquifer exchange; nonzero enables it.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_link_count()

SWMM_ENGINE_API int swmm_gw2d_link_count	(	SWMM_Engine	engine,
		int *	count )

Read the authored conduit-bed row count.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Required destination for the current row count.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_link_get()

SWMM_ENGINE_API int swmm_gw2d_link_get	(	SWMM_Engine	engine,
		int	index,
		char *	link,
		int	linklen,
		double *	kc,
		double *	dc,
		int *	exchange )

Read one authored aquifer conduit-bed row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based conduit-bed row index.
[out]	link	Optional name destination; positive capacity truncates safely with NUL.
[in]	linklen	Name capacity in bytes; nonpositive capacity skips the string.
[out]	kc	Optional conductivity in authored project LOSSES units.
[out]	dc	Optional thickness in authored project length units.
[out]	exchange	Optional enabled-exchange flag, 0 or 1.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_link_remove()

SWMM_ENGINE_API int swmm_gw2d_link_remove	(	SWMM_Engine	engine,
		int	index )

Erase one authored aquifer conduit-bed row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based link row to erase; later rows shift down.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_node_add()

SWMM_ENGINE_API int swmm_gw2d_node_add	(	SWMM_Engine	engine,
		const char *	node,
		int	cell,
		double	kc,
		double	dc,
		double	area )

Add a node bed. kc in in/hr | mm/hr, dc in ft | m, area in ft2 | m2 (0 = the cell's own area). kc == 0 means direct Darcy.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	node	Required nonempty copied node name; resolved at initialize.
[in]	cell	Nonnegative cell index, or -1 to locate from node coordinates.
[in]	kc	Finite nonnegative bed conductivity; zero selects direct Darcy.
[in]	dc	Finite nonnegative bed thickness; positive when kc > 0.
[in]	area	Finite nonnegative contact area; zero means the entire cell.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_node_count()

SWMM_ENGINE_API int swmm_gw2d_node_count	(	SWMM_Engine	engine,
		int *	count )

Read the current aquifer node-bed row count.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Required destination for the current row count.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_node_get()

SWMM_ENGINE_API int swmm_gw2d_node_get	(	SWMM_Engine	engine,
		int	index,
		char *	node,
		int	nodelen,
		int *	cell,
		double *	kc,
		double *	dc,
		double *	area )

Read one authored/resolved aquifer node-bed row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based node-bed row index.
[out]	node	Optional destination for the node name; positive capacity safely truncates with NUL.
[in]	nodelen	Name capacity in bytes; nonpositive capacity skips the copy.
[out]	cell	Optional authored/resolved cell index; -1 denotes unresolved AUTO.
[out]	kc	Optional conductivity in project infiltration units, in/hr or mm/hr.
[out]	dc	Optional thickness in ft or m.
[out]	area	Optional area in ft2 or m2; zero means whole cell.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_node_get_flags()

SWMM_ENGINE_API int swmm_gw2d_node_get_flags	(	SWMM_Engine	engine,
		int	index,
		int *	locate,
		int *	exchange,
		int *	automatic )

G-X2 (2026-09-19): a bed's enrolment state. locate — the cell is found from the node's [COORDINATES] at initialize (CELL AUTO; pass cell −1 to swmm_gw2d_node_add); exchange — 0 when the row opts the node OUT (EXCHANGE NO); automatic — enrolled by NODE_ENROLMENT AUTO rather than authored (present after initialize only; not written back). Any pointer may be NULL.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based node-bed row index.
[out]	locate	Optional 0/1 destination for coordinate-based cell location.
[out]	exchange	Optional 0/1 destination for enabled exchange.
[out]	automatic	Optional 0/1 destination for runtime automatic enrollment.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_node_remove()

SWMM_ENGINE_API int swmm_gw2d_node_remove	(	SWMM_Engine	engine,
		int	index )

Erase one aquifer node-bed row and its stored node name.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based node row to erase; later rows shift down.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_node_replace()

SWMM_ENGINE_API int swmm_gw2d_node_replace	(	SWMM_Engine	engine,
		const SWMM_GwNodeBed *	expected,
		int	expected_count,
		const SWMM_GwNodeBed *	replacement,
		int	count,
		const SWMM_LidNodeBottomEdit *	bottoms,
		int	bottom_count,
		int	apply )

BUILDING/OPENED only. Compares the entire current bed list with expected, validates every replacement and owner edit, then publishes once. Stale, duplicate, unknown, nonfinite or contradictory input returns BADPARAM and changes nothing. Mesh ownership requires an enabled MESH aquifer and an enabled authored bed with positive AREA; mapping is checked at initialize. Mesh execution remains gated until R5 numerical/restart qualification. Existing AREA=0 retains whole-cell semantics. NULL arrays require count=0. apply=0 validates a private draft only; apply=1 publishes it.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	expected	Borrowed expected_count-element exact snapshot of the current ordered beds.
[in]	expected_count	Nonnegative expected row count; must match current configuration.
[in]	replacement	Borrowed count-element replacement list; names must resolve uniquely.
[in]	count	Nonnegative replacement row count.
[in]	bottoms	Borrowed bottom_count-element LID owner edit array; expected modes must match.
[in]	bottom_count	Nonnegative number of unique storage-node owner edits.
[in]	apply	0 validates only; 1 atomically publishes the draft.

Note: Inputs are not retained. Automatic beds must remain exact existing snapshots. Allocation failures return SWMM_ERR_INTERNAL before publication.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_node_set_exchange()

SWMM_ENGINE_API int swmm_gw2d_node_set_exchange	(	SWMM_Engine	engine,
		int	index,
		int	exchange )

G-X2: set a row's EXCHANGE flag (0 = the node exchanges with nothing).

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based node-bed row index.
[in]	exchange	Zero disables exchange; every nonzero value enables it.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_option_get()

SWMM_ENGINE_API int swmm_gw2d_option_get	(	SWMM_Engine	engine,
		const char *	key,
		char *	buf,
		int	buflen )

Read one option as text. Keys: SOIL_CHAR, CLOSURE, M_LAYERS, CAPILLARY_DIFF, C_GW, C_COL, FORCE_CLOSED_FORM, MODE, DUNNE, GW_ET, NODE_ENROLMENT (AUTO | ROWS), LINK_SEEPAGE (DEFAULT | ONE_WAY | TWO_WAY | NONE), WILTING_SUCTION (AUTO | positive project length). Read-only keys: GW_ET_EFFECTIVE, LINK_SEEPAGE_EFFECTIVE, WILTING_SUCTION_EFFECTIVE, CONFIGURED and OPTIONS_AUTHORED. Legacy LINK_SEEPAGE AUTO means ONE_WAY.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	key	Required case-insensitive null-terminated option key from the list above.
[out]	buf	Required destination; positive capacity is NUL-terminated and may truncate.
[in]	buflen	Positive destination capacity in bytes, including NUL.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Here is the call graph for this function:

◆ swmm_gw2d_option_set()

SWMM_ENGINE_API int swmm_gw2d_option_set	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value )

Set an authored option from text through the same parser as the file.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	key	Required case-insensitive writable option key.
[in]	value	Required null-terminated input-file value; invalid key/value text is refused.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_gw2d_process_options_set()

SWMM_ENGINE_API int swmm_gw2d_process_options_set	(	SWMM_Engine	engine,
		const char *	et,
		const char *	link,
		const char *	wilting,
		int	authored )

Atomically replace GW_ET, LINK_SEEPAGE and WILTING_SUCTION before a run. GW_ET AUTO defaults to BOTH on a mesh, NONE in PER_SUBCATCH. LINK_SEEPAGE DEFAULT defaults to TWO_WAY on a mesh; ONE_WAY and legacy AUTO retain explicit one-way delivery. WILTING_SUCTION AUTO means 150 m; a custom positive number is in project length units. authored must be 0 or 1 and restores section provenance for atomic GUI Undo.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	et	Required GW_ET parser value: AUTO, NONE, CAPILLARY_RISE, BOUNDARY_ET or BOTH.
[in]	link	Required LINK_SEEPAGE parser value: DEFAULT, NONE, ONE_WAY, TWO_WAY or legacy AUTO.
[in]	wilting	Required AUTO or a positive project-length suction string.
[in]	authored	Exactly 0 or 1, restoring whether the options section was authored.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_gw2d_row_add()

SWMM_ENGINE_API int swmm_gw2d_row_add	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		double	ks,
		double	zs,
		double	theta_s,
		double	theta_r,
		double	alpha )

Append one row. Values are in the PROJECT's units.

Parameters

[in]	scope	SWMM_GW2D_SCOPE_*
[in]	tag	tag name for SCOPE_TAG, else ignored (may be NULL)
[in]	cell	0-based cell for SCOPE_CELL, else ignored
[in]	ks	saturated conductivity (in/hr \| mm/hr)
[in]	zs	soil column thickness (ft \| m)
[in]	theta_s	porosity
[in]	theta_r	residual water content
[in]	alpha	sorptive number (1/ft \| 1/m)
[in]	engine	Borrowed live engine handle; not retained by this call.

Note: ks, zs and alpha must be positive; 0 < theta_s <= 1 and 0 <= theta_r < theta_s. TAG requires a nonempty tag; CELL requires cell >= 0. Appends a row and marks aquifer options authored.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_row_count()

SWMM_ENGINE_API int swmm_gw2d_row_count	(	SWMM_Engine	engine,
		int *	count )

Number of authored rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Required destination for the current row count.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Here is the caller graph for this function:

◆ swmm_gw2d_row_get()

SWMM_ENGINE_API int swmm_gw2d_row_get	(	SWMM_Engine	engine,
		int	index,
		int *	scope,
		char *	tag,
		int	taglen,
		int *	cell,
		double *	ks,
		double *	zs,
		double *	theta_s,
		double *	theta_r,
		double *	alpha )

Read row index back, in the units it was authored in. Any out pointer may be NULL. tag needs taglen bytes.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based authored aquifer row index.
[out]	scope	Optional scope-code destination.
[out]	tag	Optional tag string; positive capacity truncates safely with NUL.
[in]	taglen	Tag capacity in bytes; nonpositive capacity skips the string.
[out]	cell	Optional cell-index destination, -1 for non-CELL rows.
[out]	ks	Optional conductivity in in/hr or mm/hr.
[out]	zs	Optional soil thickness in ft or m.
[out]	theta_s	Optional dimensionless porosity.
[out]	theta_r	Optional dimensionless residual water content.
[out]	alpha	Optional sorptive number in inverse ft or inverse m.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_row_get_property()

SWMM_ENGINE_API int swmm_gw2d_row_get_property	(	SWMM_Engine	engine,
		int	index,
		const char *	key,
		double *	value )

Read one optional property back.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based authored aquifer row index.
[in]	key	Required case-insensitive property key (also SOIL_CHAR_SET and CLOSURE_SET for provenance).
[out]	value	Required result destination for the authored value. PSI_B and HG0 use project length; LAMBDA, N, L and C_LOSS are dimensionless; law/closure/layer selectors are numeric codes. Unset optional properties may contain their parser sentinel values.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

◆ swmm_gw2d_row_remove()

SWMM_ENGINE_API int swmm_gw2d_row_remove	(	SWMM_Engine	engine,
		int	index )

Remove row index.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based row row to erase; later rows shift down.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_row_set_property()

SWMM_ENGINE_API int swmm_gw2d_row_set_property	(	SWMM_Engine	engine,
		int	index,
		const char *	key,
		double	value )

Set one of a row's optional properties. Keys: PSI_B, LAMBDA, N, L, C_LOSS, HG0, SOIL_CHAR, CLOSURE, M_LAYERS. The numeric-valued keys take value; SOIL_CHAR and CLOSURE take the SWMM_GW2D_SOIL_* / SWMM_GW2D_CLOSURE_* codes as a double, which keeps this one entry point instead of nine.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based authored aquifer row index.
[in]	key	Required case-insensitive property key.
[in]	value	New authored value. PSI_B and HG0 use project length; LAMBDA, N, L and C_LOSS are dimensionless; law/closure/layer selectors are numeric codes. PSI_B and C_LOSS must be nonnegative, LAMBDA positive, N > 1; rounded M_LAYERS is [2,128], SOIL_CHAR [0,3], and CLOSURE [-1,2].

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_gw2d_species_count()

SWMM_ENGINE_API int swmm_gw2d_species_count	(	SWMM_Engine	engine,
		int *	count )

How many species rows the aquifer transports (0 when it carries none).

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Required species-count destination; zero when transport is inactive.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

◆ swmm_gw2d_species_name()

SWMM_ENGINE_API int swmm_gw2d_species_name	(	SWMM_Engine	engine,
		int	species,
		char *	buf,
		int	buflen )

One species row's name (TransportPolicy order: pollutants, MSX, __WATER_AGE__, __TEMPERATURE__).

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	species	Zero-based transported species index.
[out]	buf	Required writable name destination; safely truncated and NUL-terminated.
[in]	buflen	Positive byte capacity including the terminator.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid arguments. Invalid species indices return SWMM_ERR_BADINDEX.

Note: Requires an active aquifer runtime; otherwise returns SWMM_ERR_LIFECYCLE. Does not advance time.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SWMM_GW2D_BOUNDARY_FLOW

◆ SWMM_GW2D_BOUNDARY_HEAD

◆ SWMM_GW2D_CLOSURE_AUTO

◆ SWMM_GW2D_CLOSURE_CLOSED_FORM

◆ SWMM_GW2D_CLOSURE_ENSLAVED

◆ SWMM_GW2D_CLOSURE_SIGMA

◆ SWMM_GW2D_HOST_REACTIONS

◆ SWMM_GW2D_HOST_THERMAL

◆ SWMM_GW2D_HOST_TRANSPORT

◆ SWMM_GW2D_HOST_WATER_AND_RECEIPTS

◆ SWMM_GW2D_LED_BOUNDARY_IN

◆ SWMM_GW2D_LED_BOUNDARY_OUT

◆ SWMM_GW2D_LED_CAPRISE

◆ SWMM_GW2D_LED_DEEP

◆ SWMM_GW2D_LED_DUNNE

◆ SWMM_GW2D_LED_ET

◆ SWMM_GW2D_LED_INFIL_IN

◆ SWMM_GW2D_LED_INIT_STORAGE

◆ SWMM_GW2D_LED_LATERAL

◆ SWMM_GW2D_LED_LINK

◆ SWMM_GW2D_LED_NODE

◆ SWMM_GW2D_LED_RECHARGE

◆ SWMM_GW2D_LED_REJECT

◆ SWMM_GW2D_LED_SOURCE_IN

◆ SWMM_GW2D_LED_SOURCE_OUT

◆ SWMM_GW2D_LED_STORAGE

◆ SWMM_GW2D_OP_CLOSED_FORM_RECHARGE

◆ SWMM_GW2D_SCOPE_CELL

◆ SWMM_GW2D_SCOPE_GLOBAL

◆ SWMM_GW2D_SCOPE_TAG

◆ SWMM_GW2D_SOIL_BROOKS_COREY

◆ SWMM_GW2D_SOIL_GARDNER

◆ SWMM_GW2D_SOIL_RUSSO

◆ SWMM_GW2D_SOIL_VAN_GENUCHTEN

◆ SWMM_GW2D_SPL_AGE_GENERATED

◆ SWMM_GW2D_SPL_BOUNDARY_FLUX_IN

◆ SWMM_GW2D_SPL_BOUNDARY_FLUX_OUT

◆ SWMM_GW2D_SPL_BOUNDARY_IN

◆ SWMM_GW2D_SPL_BOUNDARY_OUT

◆ SWMM_GW2D_SPL_DEEP_OUT

◆ SWMM_GW2D_SPL_DUNNE_OUT

◆ SWMM_GW2D_SPL_ET_OUT

◆ SWMM_GW2D_SPL_INFIL_IN

◆ SWMM_GW2D_SPL_INIT

◆ SWMM_GW2D_SPL_LATERAL_NET

◆ SWMM_GW2D_SPL_LINK_IN

◆ SWMM_GW2D_SPL_LINK_OUT

◆ SWMM_GW2D_SPL_NODE_IN

◆ SWMM_GW2D_SPL_NODE_OUT

◆ SWMM_GW2D_SPL_REACTED

◆ SWMM_GW2D_SPL_RESIDUAL

◆ SWMM_GW2D_SPL_SOURCE_IN

◆ SWMM_GW2D_SPL_SOURCE_OUT

◆ SWMM_GW2D_SPL_STORAGE

◆ SWMM_GW2D_VAR_CLOSURE

◆ SWMM_GW2D_VAR_DT_CELL

◆ SWMM_GW2D_VAR_DUNNE

◆ SWMM_GW2D_VAR_DUNNE_CUM

◆ SWMM_GW2D_VAR_ET_PENDING

◆ SWMM_GW2D_VAR_ET_POTENTIAL

◆ SWMM_GW2D_VAR_ET_POTENTIAL_CUM

◆ SWMM_GW2D_VAR_ET_REFRESH

◆ SWMM_GW2D_VAR_ET_SOIL_CUM

◆ SWMM_GW2D_VAR_ET_STRESS

◆ SWMM_GW2D_VAR_ET_SURFACE

◆ SWMM_GW2D_VAR_ET_SURFACE_CUM

◆ SWMM_GW2D_VAR_ET_UNUSED_CUM

◆ SWMM_GW2D_VAR_HG

◆ SWMM_GW2D_VAR_HU

◆ SWMM_GW2D_VAR_INFIL_CAPACITY

◆ SWMM_GW2D_VAR_INFIL_PENDING

◆ SWMM_GW2D_VAR_INFIL_REFRESH

◆ SWMM_GW2D_VAR_INFIL_REMAINING

◆ SWMM_GW2D_VAR_Q0