ApiGw2D.cpp File Reference

G-step 19 — implementation of openswmm_gw2d.h. More...

#include <openswmm/engine/openswmm_engine.h>
#include <openswmm/engine/openswmm_gw2d.h>
#include "../../core/SWMMEngine.hpp"
#include "../subsurface/SubsurfaceSections.hpp"
#include "../subsurface/SubsurfaceSolver.hpp"
#include <algorithm>
#include <cmath>
#include <cstring>
#include <string>
#include <vector>

Include dependency graph for ApiGw2D.cpp:

Macros
#define	AQ_CFG(engine)
#define	AQ_EDITABLE(eng)
#define	AQ_SOLVER(engine)

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 — implementation of openswmm_gw2d.h.

The authoring half edits SubsurfaceConfig (project units, never converted); the state half reads SubsurfaceState (SI). Keeping the two apart in the header is what keeps them apart here: there is no place in this file where a project-unit number and an SI one could be added together.

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

AQ_CFG

#define AQ_CFG

(

engine

)

Value:

    auto* eng = reinterpret_cast<openswmm::SWMMEngine*>(engine); \
    if (!eng) return SWMM_ERR_BADHANDLE; \
    SubsurfaceConfig& cfg = eng->surfaceRouter2D().aquiferConfig()

AQ_EDITABLE

#define AQ_EDITABLE

(

eng

)

Value:

    if (eng->context().state != openswmm::EngineState::OPENED && \
        eng->context().state != openswmm::EngineState::BUILDING) \
        return SWMM_ERR_LIFECYCLE

AQ_SOLVER

#define AQ_SOLVER

(

engine

)

Value:

    auto* eng = reinterpret_cast<openswmm::SWMMEngine*>(engine); \
    if (!eng) return SWMM_ERR_BADHANDLE; \
    const SubsurfaceSolver& gw = eng->surfaceRouter2D().subsurface(); \
    if (!gw.active()) return SWMM_ERR_LIFECYCLE

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.