openswmm_gw2d.h File Reference

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.

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

Functions
SWMM_ENGINE_API int	swmm_gw2d_option_get (SWMM_Engine engine, const char *key, char *buf, int buflen)
SWMM_ENGINE_API int	swmm_gw2d_option_set (SWMM_Engine engine, const char *key, const char *value)
SWMM_ENGINE_API int	swmm_gw2d_row_count (SWMM_Engine engine, int *count)
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)
SWMM_ENGINE_API int	swmm_gw2d_row_set_property (SWMM_Engine engine, int index, const char *key, double value)
SWMM_ENGINE_API int	swmm_gw2d_row_get_property (SWMM_Engine engine, int index, const char *key, double *value)
SWMM_ENGINE_API int	swmm_gw2d_row_remove (SWMM_Engine engine, int index)
SWMM_ENGINE_API int	swmm_gw2d_node_count (SWMM_Engine engine, int *count)
SWMM_ENGINE_API int	swmm_gw2d_node_add (SWMM_Engine engine, const char *node, int cell, double kc, double dc, double area)
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)
SWMM_ENGINE_API int	swmm_gw2d_node_remove (SWMM_Engine engine, int index)
SWMM_ENGINE_API int	swmm_gw2d_is_active (SWMM_Engine engine, int *active)
SWMM_ENGINE_API int	swmm_gw2d_get_dimensions (SWMM_Engine engine, int *n_cells, int *m_layers)
SWMM_ENGINE_API int	swmm_gw2d_get_cell (SWMM_Engine engine, int cell, int var, double *value)
SWMM_ENGINE_API int	swmm_gw2d_get_cell_bulk (SWMM_Engine engine, int var, double *out, int len, int *written)
SWMM_ENGINE_API int	swmm_gw2d_get_column (SWMM_Engine engine, int cell, double *theta, int len, int *written)
SWMM_ENGINE_API int	swmm_gw2d_get_ledger (SWMM_Engine engine, int term, double *value)
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)

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\n Apache-2.0

Macro Definition Documentation

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

#define SWMM_GW2D_LED_NODE   3

SWMM_GW2D_LED_RECHARGE

#define SWMM_GW2D_LED_RECHARGE   0

SWMM_GW2D_LED_STORAGE

#define SWMM_GW2D_LED_STORAGE   9

storage NOW, incl. accumulators

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

Function Documentation

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

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.

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.

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.

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.

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

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.

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.

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.

swmm_gw2d_node_count()

SWMM_ENGINE_API int swmm_gw2d_node_count	(	SWMM_Engine	engine,
		int *	count )

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 )

swmm_gw2d_node_remove()

SWMM_ENGINE_API int swmm_gw2d_node_remove	(	SWMM_Engine	engine,
		int	index )

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.

swmm_gw2d_option_set()

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

Set one option from text. Same keys and the same token spellings the .inp accepts — one parser, so the file and the API cannot drift.

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

scope	SWMM_GW2D_SCOPE_*
tag	tag name for SCOPE_TAG, else ignored (may be NULL)
cell	0-based cell for SCOPE_CELL, else ignored
ks	saturated conductivity (in/hr | mm/hr)
zs	soil column thickness (ft | m)
theta_s	porosity
theta_r	residual water content
alpha	sorptive number (1/ft | 1/m)

swmm_gw2d_row_count()

SWMM_ENGINE_API int swmm_gw2d_row_count	(	SWMM_Engine	engine,
		int *	count )

Number of authored rows.

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.

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.

swmm_gw2d_row_remove()

SWMM_ENGINE_API int swmm_gw2d_row_remove	(	SWMM_Engine	engine,
		int	index )

Remove row index.

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.