U4 (2026-09-07) — C API for the [GW_*] subsurface-transport authoring sections. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_gw_transport.h:

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

Classes
struct	SWMM_GwParams

Macros
#define	SWMM_GW_SCOPE_GLOBAL 0

#define	SWMM_GW_SCOPE_TAG 1

#define	SWMM_GW_SCOPE_CELL 2

#define	SWMM_GW_ZONE_SAT 0

#define	SWMM_GW_ZONE_UNSAT 1

#define	SWMM_GW_ZONE_LAYER 2

Typedefs
typedef struct SWMM_GwParams	SWMM_GwParams

Functions
SWMM_ENGINE_API int	swmm_gw_transport_option_get (SWMM_Engine engine, const char key, char buf, int buflen)
	Serialize one groundwater transport option using its section spelling.

SWMM_ENGINE_API int	swmm_gw_transport_option_set (SWMM_Engine engine, const char key, const char value)
	Parse and atomically assign one groundwater transport option.

SWMM_ENGINE_API int	swmm_gw_transport_authored (SWMM_Engine engine)
	Test whether groundwater transport has any authored configuration.

SWMM_ENGINE_API int	swmm_gw_params_count (SWMM_Engine engine)
	Count authored groundwater physical-parameter rows.

SWMM_ENGINE_API int	swmm_gw_params_get (SWMM_Engine engine, int idx, SWMM_GwParams row, char tag_buf, int tag_len)
	Copy an authored porous-media parameter row and its optional tag.

SWMM_ENGINE_API int	swmm_gw_params_set (SWMM_Engine engine, const SWMM_GwParams row, const char tag)
	Upsert a raw porous-media parameter row keyed by scope/tag/cell.

SWMM_ENGINE_API int	swmm_gw_params_remove (SWMM_Engine engine, int idx)
	Remove one authored groundwater physical-parameter row.

SWMM_ENGINE_API int	swmm_gw_sorption_count (SWMM_Engine engine)
	Count authored groundwater species-sorption rows.

SWMM_ENGINE_API int	swmm_gw_sorption_get (SWMM_Engine engine, int idx, int scope, char tag_buf, int tag_len, int cell, char species_buf, int species_len, double kd, double decay)
	Read an authored scope/species sorption record.

SWMM_ENGINE_API int	swmm_gw_sorption_set (SWMM_Engine engine, int scope, const char tag, int cell, const char species, double kd, double decay)
	Upsert one scope/species partition coefficient and decay override.

SWMM_ENGINE_API int	swmm_gw_sorption_remove (SWMM_Engine engine, int idx)
	Remove one authored groundwater species-sorption row.

SWMM_ENGINE_API int	swmm_gw_init_quality_count (SWMM_Engine engine)
	Count authored groundwater initial-quality rows.

SWMM_ENGINE_API int	swmm_gw_init_quality_get (SWMM_Engine engine, int idx, int scope, char tag_buf, int tag_len, int cell, int zone, int layer, char species_buf, int species_len, double *value)
	Read an authored groundwater initial-quality record.

SWMM_ENGINE_API int	swmm_gw_init_quality_set (SWMM_Engine engine, int scope, const char tag, int cell, int zone, int layer, const char species, double value)
	Upsert initial quality keyed by scope, zone/layer and species.

SWMM_ENGINE_API int	swmm_gw_init_quality_remove (SWMM_Engine engine, int idx)
	Remove one authored groundwater initial-quality row.

SWMM_ENGINE_API int	swmm_gw_init_quality_file_get (SWMM_Engine engine, char *buf, int buflen)
	Read the initial-quality CSV sidecar reference.

SWMM_ENGINE_API int	swmm_gw_init_quality_file_set (SWMM_Engine engine, const char *path)
	Assign the initial-quality CSV sidecar reference.

SWMM_ENGINE_API int	swmm_gw_boundary_quality_count (SWMM_Engine engine)
	Count authored groundwater exterior-quality rows.

SWMM_ENGINE_API int	swmm_gw_boundary_quality_get (SWMM_Engine engine, int idx, int cell, int edge, char species_buf, int species_len, char kind_buf, int kind_len, double value, char ts_buf, int ts_len)
	Read an authored groundwater edge-quality record.

SWMM_ENGINE_API int	swmm_gw_boundary_quality_set (SWMM_Engine engine, int cell, int edge, const char species, const char kind, double value, const char *ts_name)
	Upsert groundwater edge quality for a species and concentration/flux category.

SWMM_ENGINE_API int	swmm_gw_boundary_quality_remove (SWMM_Engine engine, int idx)
	Remove one authored groundwater exterior-quality row.

SWMM_ENGINE_API int	swmm_gw_source_count (SWMM_Engine engine)
	Count authored groundwater named-source rows.

SWMM_ENGINE_API int	swmm_gw_source_get (SWMM_Engine engine, int idx, char name_buf, int name_len, int scope, char tag_buf, int tag_len, int cell, double flow, char flow_ts_buf, int flow_ts_len)
	Read an authored named groundwater source and its scope.

SWMM_ENGINE_API int	swmm_gw_source_set (SWMM_Engine engine, const char name, int scope, const char tag, int cell, double flow, const char *flow_ts)
	Upsert a named groundwater water source and its scope.

SWMM_ENGINE_API int	swmm_gw_source_scale_get (SWMM_Engine engine, int idx, double *value)
	Read the multiplier for a named source's flow and MASS terms.

SWMM_ENGINE_API int	swmm_gw_source_scale_set (SWMM_Engine engine, int idx, double value)
	Set the multiplier for a named source's flow and MASS terms.

SWMM_ENGINE_API int	swmm_gw_source_remove (SWMM_Engine engine, int idx)
	Remove one authored groundwater named-source row.

SWMM_ENGINE_API int	swmm_gw_source_species_count (SWMM_Engine engine, int src_idx)
	Count species terms carried by one named groundwater source.

SWMM_ENGINE_API int	swmm_gw_source_species_get (SWMM_Engine engine, int src_idx, int term_idx, char species_buf, int species_len, char kind_buf, int kind_len, double value, char ts_buf, int ts_len)
	Read a named groundwater source species term.

SWMM_ENGINE_API int	swmm_gw_source_species_set (SWMM_Engine engine, int src_idx, const char species, const char kind, double value, const char *ts_name)
	Upsert a named source's species term by species name.

SWMM_ENGINE_API int	swmm_gw_source_species_remove (SWMM_Engine engine, int src_idx, int term_idx)
	Remove one species term from a named source.

Detailed Description

U4 (2026-09-07) — C API for the [GW_*] subsurface-transport authoring sections.

These sections round-trip authored subsurface transport inputs. The integrated two-zone groundwater kernel consumes them at initialization. Runtime availability depends on the model and enabled transport classes; query swmm_get_transport_matrix() for capabilities and openswmm_gw2d.h for runtime state and ledgers.

Cell-generic. Every index is a CELL (0 .. swmm_2d_cell_count-1 through this API; 1-based in the .inp), and an edge is the LOCAL edge 0 .. nv-1 of ITS cell — 3 for a triangle, 4 for a quad.

Editing state. Setters require BUILDING or OPENED, the same contract as the 2D boundary API: the rows seed the kernel at initialize, so a mid-run edit would silently no-op.

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_GW_SCOPE_CELL

#define SWMM_GW_SCOPE_CELL 2

one cell, 0-based here

◆ SWMM_GW_SCOPE_GLOBAL

#define SWMM_GW_SCOPE_GLOBAL 0

the * row

◆ SWMM_GW_SCOPE_TAG

#define SWMM_GW_SCOPE_TAG 1

every cell carrying a tag

◆ SWMM_GW_ZONE_LAYER

#define SWMM_GW_ZONE_LAYER 2

with an explicit 1-based layer index

◆ SWMM_GW_ZONE_SAT

#define SWMM_GW_ZONE_SAT 0

◆ SWMM_GW_ZONE_UNSAT

#define SWMM_GW_ZONE_UNSAT 1

Typedef Documentation

◆ SWMM_GwParams

typedef struct SWMM_GwParams SWMM_GwParams

Function Documentation

◆ swmm_gw_boundary_quality_count()

SWMM_ENGINE_API int swmm_gw_boundary_quality_count ( SWMM_Engine engine )

Count authored groundwater exterior-quality rows.

Parameters

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

Returns: Nonnegative row count, or -1 for a null engine handle. This is a count-returning function, not a SWMM status-returning function.

Note: No initialized mesh or active groundwater runtime is required.

◆ swmm_gw_boundary_quality_get()

SWMM_ENGINE_API int swmm_gw_boundary_quality_get	(	SWMM_Engine	engine,
		int	idx,
		int *	cell,
		int *	edge,
		char *	species_buf,
		int	species_len,
		char *	kind_buf,
		int	kind_len,
		double *	value,
		char *	ts_buf,
		int	ts_len )

Read an authored groundwater edge-quality record.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based boundary-quality row index.
[out]	cell	Optional zero-based cell index slot.
[out]	edge	Optional local edge slot, 0..cell vertex count - 1.
[out]	species_buf	Optional species-name buffer.
[in]	species_len	Species-buffer byte capacity.
[out]	kind_buf	Optional kind buffer: CONC, TS, MASSFLUX or HEATFLUX.
[in]	kind_len	Kind-buffer byte capacity.
[out]	value	Optional raw constant concentration/flux field in the kind's section units.
[out]	ts_buf	Optional series-name buffer, empty when not authored.
[in]	ts_len	Time-series-buffer byte capacity.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/invalid arguments.

Note: Optional output pointers may be NULL. String capacities <= 0 skip copying; positive capacities truncate safely with a terminal NUL. No storage is retained.

◆ swmm_gw_boundary_quality_remove()

SWMM_ENGINE_API int swmm_gw_boundary_quality_remove	(	SWMM_Engine	engine,
		int	idx )

Remove one authored groundwater exterior-quality row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based current row index; later indices shift on removal.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.; Edits authoring only; removal does not clear every other authored option.

◆ swmm_gw_boundary_quality_set()

SWMM_ENGINE_API int swmm_gw_boundary_quality_set	(	SWMM_Engine	engine,
		int	cell,
		int	edge,
		const char *	species,
		const char *	kind,
		double	value,
		const char *	ts_name )

Upsert groundwater edge quality for a species and concentration/flux category.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	cell	Nonnegative zero-based cell index; checked against an available mesh.
[in]	edge	Nonnegative local edge, below the cell's vertex count when a mesh exists.
[in]	species	Non-null nonempty species name, copied for later resolution.
[in]	kind	Exact CONC, TS, MASSFLUX or HEATFLUX string.
[in]	value	Finite raw constant in the chosen concentration/flux section units, also required finite for TS mode even though a series supplies runtime values.
[in]	ts_name	Nonempty series name for TS, optional/NULL otherwise.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/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.; Concentration and imposed-flux rows are distinct categories for upsert. Hydraulic edge bindings are required before active groundwater initialization; name resolution and runtime compatibility are deferred to that stage.

◆ swmm_gw_init_quality_count()

SWMM_ENGINE_API int swmm_gw_init_quality_count ( SWMM_Engine engine )

Count authored groundwater initial-quality rows.

Parameters

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

Returns: Nonnegative row count, or -1 for a null engine handle. This is a count-returning function, not a SWMM status-returning function.

Note: No initialized mesh or active groundwater runtime is required.

◆ swmm_gw_init_quality_file_get()

SWMM_ENGINE_API int swmm_gw_init_quality_file_get	(	SWMM_Engine	engine,
		char *	buf,
		int	buflen )

Read the initial-quality CSV sidecar reference.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	buf	Non-null writable path buffer.
[in]	buflen	Positive byte capacity; long paths are truncated with NUL.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Returns stored authoring text without opening the file.

◆ swmm_gw_init_quality_file_set()

SWMM_ENGINE_API int swmm_gw_init_quality_file_set	(	SWMM_Engine	engine,
		const char *	path )

Assign the initial-quality CSV sidecar reference.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	path	Null-terminated path copied as given; NULL or empty clears the reference.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.; A nonempty reference marks configuration authored; clearing it does not reset other authored flags.

◆ swmm_gw_init_quality_get()

SWMM_ENGINE_API int swmm_gw_init_quality_get	(	SWMM_Engine	engine,
		int	idx,
		int *	scope,
		char *	tag_buf,
		int	tag_len,
		int *	cell,
		int *	zone,
		int *	layer,
		char *	species_buf,
		int	species_len,
		double *	value )

Read an authored groundwater initial-quality record.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based row index.
[out]	scope	Optional SWMM_GW_SCOPE_* slot.
[out]	tag_buf	Optional scope-tag buffer.
[in]	tag_len	Tag-buffer byte capacity.
[out]	cell	Optional zero-based CELL slot or -1.
[out]	zone	Optional SWMM_GW_ZONE_* selector.
[out]	layer	Optional one-based layer index, meaningful only for LAYER scope.
[out]	species_buf	Optional species-name buffer.
[in]	species_len	Species-buffer byte capacity.
[out]	value	Optional raw initial concentration in species units; reserved temperature/age fields use their respective degrees-C/seconds conventions.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/invalid arguments.

Note: Optional output pointers may be NULL. String capacities <= 0 skip copying; positive capacities truncate safely with a terminal NUL. No storage is retained.

◆ swmm_gw_init_quality_remove()

SWMM_ENGINE_API int swmm_gw_init_quality_remove	(	SWMM_Engine	engine,
		int	idx )

Remove one authored groundwater initial-quality row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based current row index; later indices shift on removal.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.; Edits authoring only; removal does not clear every other authored option.

◆ swmm_gw_init_quality_set()

SWMM_ENGINE_API int swmm_gw_init_quality_set	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		int	zone,
		int	layer,
		const char *	species,
		double	value )

Upsert initial quality keyed by scope, zone/layer and species.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	scope	SWMM_GW_SCOPE_GLOBAL, TAG or CELL; the legacy scope conversion treats other codes as GLOBAL unless this setter states otherwise.
[in]	tag	Required nonempty text for TAG; otherwise ignored and may be NULL.
[in]	cell	Nonnegative zero-based cell for CELL; otherwise ignored.
[in]	zone	SAT, UNSAT or LAYER; unrecognized codes convert to SAT.
[in]	layer	Positive one-based layer for LAYER, ignored and stored -1 otherwise.
[in]	species	Non-null nonempty species name; reserved TEMPERATURE and WATER_AGE permit signed authored values where ordinary concentrations do not.
[in]	value	Raw species concentration or reserved temperature/age value. Negative ordinary-species values are rejected; finite/range checks are not comprehensive.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/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.; Active bulk groundwater rejects LAYER quality at initialization; drafts can still be authored and saved. No source text pointer is retained.

◆ swmm_gw_params_count()

SWMM_ENGINE_API int swmm_gw_params_count ( SWMM_Engine engine )

Count authored groundwater physical-parameter rows.

Parameters

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

Returns: Nonnegative row count, or -1 for a null engine handle. This is a count-returning function, not a SWMM status-returning function.

Note: No initialized mesh or active groundwater runtime is required.

◆ swmm_gw_params_get()

SWMM_ENGINE_API int swmm_gw_params_get	(	SWMM_Engine	engine,
		int	idx,
		SWMM_GwParams *	row,
		char *	tag_buf,
		int	tag_len )

Copy an authored porous-media parameter row and its optional tag.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based parameter-row index.
[out]	row	Non-null structure receiving scope/cell and raw physical properties; SI units are stated on SWMM_GwParams fields, with geo_flux depending on the deep thermal mode.
[out]	tag_buf	Optional writable tag-name buffer; NULL skips it.
[in]	tag_len	Byte capacity; <= 0 skips copying, otherwise truncates with NUL.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/invalid arguments.

Note: No resolution, conversion or storage retention occurs.

◆ swmm_gw_params_remove()

SWMM_ENGINE_API int swmm_gw_params_remove	(	SWMM_Engine	engine,
		int	idx )

Remove one authored groundwater physical-parameter row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based current row index; later indices shift on removal.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.; Edits authoring only; removal does not clear every other authored option.

◆ swmm_gw_params_set()

SWMM_ENGINE_API int swmm_gw_params_set	(	SWMM_Engine	engine,
		const SWMM_GwParams *	row,
		const char *	tag )

Upsert a raw porous-media parameter row keyed by scope/tag/cell.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	row	Non-null borrowed physical-property record in the SI units specified on SWMM_GwParams. CELL indices must be nonnegative; TAG needs a name.
[in]	tag	Nonempty for TAG scope, ignored otherwise and may be NULL.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/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.; Unknown scope codes convert to GLOBAL. This authoring setter copies physical coefficients without comprehensive range/finite checks; initialization provides the runtime validity gate. Successful writes mark configuration authored.

◆ swmm_gw_sorption_count()

SWMM_ENGINE_API int swmm_gw_sorption_count ( SWMM_Engine engine )

Count authored groundwater species-sorption rows.

Parameters

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

Returns: Nonnegative row count, or -1 for a null engine handle. This is a count-returning function, not a SWMM status-returning function.

Note: No initialized mesh or active groundwater runtime is required.

◆ swmm_gw_sorption_get()

SWMM_ENGINE_API int swmm_gw_sorption_get	(	SWMM_Engine	engine,
		int	idx,
		int *	scope,
		char *	tag_buf,
		int	tag_len,
		int *	cell,
		char *	species_buf,
		int	species_len,
		double *	kd,
		double *	decay )

Read an authored scope/species sorption record.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based sorption row index.
[out]	scope	Optional SWMM_GW_SCOPE_* slot.
[out]	tag_buf	Optional tag-name buffer.
[in]	tag_len	Tag buffer byte capacity.
[out]	cell	Optional zero-based cell slot, -1 outside CELL scope.
[out]	species_buf	Optional species-name buffer.
[in]	species_len	Species-buffer byte capacity.
[out]	kd	Optional partition-coefficient slot in L/kg.
[out]	decay	Optional 1/day decay slot; negative means inherit the pollutant decay.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/invalid arguments.

Note: Optional output pointers may be NULL. String capacities <= 0 skip copying; positive capacities truncate safely with a terminal NUL. No storage is retained.

◆ swmm_gw_sorption_remove()

SWMM_ENGINE_API int swmm_gw_sorption_remove	(	SWMM_Engine	engine,
		int	idx )

Remove one authored groundwater species-sorption row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based current row index; later indices shift on removal.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.; Edits authoring only; removal does not clear every other authored option.

◆ swmm_gw_sorption_set()

SWMM_ENGINE_API int swmm_gw_sorption_set	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		const char *	species,
		double	kd,
		double	decay )

Upsert one scope/species partition coefficient and decay override.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	scope	SWMM_GW_SCOPE_GLOBAL, TAG or CELL; the legacy scope conversion treats other codes as GLOBAL unless this setter states otherwise.
[in]	tag	Required nonempty text for TAG; otherwise ignored and may be NULL.
[in]	cell	Nonnegative zero-based cell for CELL; otherwise ignored.
[in]	species	Non-null nonempty species name, copied without eager name resolution.
[in]	kd	Partition coefficient in L/kg; negative values are rejected.
[in]	decay	Decay in 1/day; negative inherits the pollutant's kDecay.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/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.; Physical finite/domain validation is not comprehensive here. Successful writes mark groundwater configuration authored; a negative CELL index is BADINDEX.

◆ swmm_gw_source_count()

SWMM_ENGINE_API int swmm_gw_source_count ( SWMM_Engine engine )

Count authored groundwater named-source rows.

Parameters

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

Returns: Nonnegative row count, or -1 for a null engine handle. This is a count-returning function, not a SWMM status-returning function.

Note: No initialized mesh or active groundwater runtime is required.

◆ swmm_gw_source_get()

SWMM_ENGINE_API int swmm_gw_source_get	(	SWMM_Engine	engine,
		int	idx,
		char *	name_buf,
		int	name_len,
		int *	scope,
		char *	tag_buf,
		int	tag_len,
		int *	cell,
		double *	flow,
		char *	flow_ts_buf,
		int	flow_ts_len )

Read an authored named groundwater source and its scope.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based source row index.
[out]	name_buf	Optional source-name buffer.
[in]	name_len	Name-buffer byte capacity.
[out]	scope	Optional GLOBAL/TAG/CELL scope slot.
[out]	tag_buf	Optional tag-name buffer.
[in]	tag_len	Tag-buffer byte capacity.
[out]	cell	Optional zero-based cell slot, -1 outside CELL scope.
[out]	flow	Optional total source discharge in m3/s, signed positive into groundwater.
[out]	flow_ts_buf	Optional flow time-series-name buffer.
[in]	flow_ts_len	Flow-series buffer byte capacity.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/invalid arguments.

Note: Optional output pointers may be NULL. String capacities <= 0 skip copying; positive capacities truncate safely with a terminal NUL. No storage is retained.

◆ swmm_gw_source_remove()

SWMM_ENGINE_API int swmm_gw_source_remove	(	SWMM_Engine	engine,
		int	idx )

Remove one authored groundwater named-source row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based current row index; later indices shift on removal.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.; Edits authoring only; removal does not clear every other authored option.

◆ swmm_gw_source_scale_get()

SWMM_ENGINE_API int swmm_gw_source_scale_get	(	SWMM_Engine	engine,
		int	idx,
		double *	value )

Read the multiplier for a named source's flow and MASS terms.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based source row index.
[out]	value	Non-null slot for dimensionless source multiplier; CONC terms remain unchanged by the multiplier.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/invalid arguments.

Note: Does not sample or change source time series.

◆ swmm_gw_source_scale_set()

SWMM_ENGINE_API int swmm_gw_source_scale_set	(	SWMM_Engine	engine,
		int	idx,
		double	value )

Set the multiplier for a named source's flow and MASS terms.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	idx	Zero-based source row index.
[in]	value	Finite nonnegative dimensionless source multiplier; CONC terms remain unchanged by the multiplier.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/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_gw_source_set()

SWMM_ENGINE_API int swmm_gw_source_set	(	SWMM_Engine	engine,
		const char *	name,
		int	scope,
		const char *	tag,
		int	cell,
		double	flow,
		const char *	flow_ts )

Upsert a named groundwater water source and its scope.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	name	Non-null nonempty source name, used as the replacement key.
[in]	scope	Exactly GLOBAL (0), TAG (1) or CELL (2); other codes are rejected.
[in]	tag	Non-null nonempty for TAG; ignored otherwise and may be NULL.
[in]	cell	Nonnegative zero-based index for CELL; ignored otherwise.
[in]	flow	Finite signed total discharge in m3/s over all active matching cells; GLOBAL/TAG distribution is area-weighted and negative discharge extracts water.
[in]	flow_ts	Optional time-series name; NULL stores empty text.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/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.; Updates preserve existing species terms and scale, and clear XY-based location on replacement. Source/name/series resolution is deferred; successful writes mark options authored. Extraction is later bounded by drainable water.

◆ swmm_gw_source_species_count()

SWMM_ENGINE_API int swmm_gw_source_species_count	(	SWMM_Engine	engine,
		int	src_idx )

Count species terms carried by one named groundwater source.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	src_idx	Zero-based source row index.

Returns: Nonnegative species-term count, or -1 for a null handle or invalid source row. This returns a count rather than a SWMM status code.

◆ swmm_gw_source_species_get()

SWMM_ENGINE_API int swmm_gw_source_species_get	(	SWMM_Engine	engine,
		int	src_idx,
		int	term_idx,
		char *	species_buf,
		int	species_len,
		char *	kind_buf,
		int	kind_len,
		double *	value,
		char *	ts_buf,
		int	ts_len )

Read a named groundwater source species term.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	src_idx	Zero-based source row index.
[in]	term_idx	Zero-based term index within that source.
[out]	species_buf	Optional species-name buffer.
[in]	species_len	Species-buffer byte capacity.
[out]	kind_buf	Optional CONC/MASS kind buffer.
[in]	kind_len	Kind-buffer byte capacity.
[out]	value	Optional constant concentration or species-native mass/s field.
[out]	ts_buf	Optional time-series-name buffer.
[in]	ts_len	Series-buffer byte capacity.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/invalid arguments.

Note: Optional output pointers may be NULL. String capacities <= 0 skip copying; positive capacities truncate safely with a terminal NUL. No storage is retained.

◆ swmm_gw_source_species_remove()

SWMM_ENGINE_API int swmm_gw_source_species_remove	(	SWMM_Engine	engine,
		int	src_idx,
		int	term_idx )

Remove one species term from a named source.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	src_idx	Zero-based source row index.
[in]	term_idx	Zero-based term index, shifting later term positions on success.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

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_gw_source_species_set()

SWMM_ENGINE_API int swmm_gw_source_species_set	(	SWMM_Engine	engine,
		int	src_idx,
		const char *	species,
		const char *	kind,
		double	value,
		const char *	ts_name )

Upsert a named source's species term by species name.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	src_idx	Zero-based source row index.
[in]	species	Non-null nonempty species name.
[in]	kind	Exact CONC or MASS text; other spellings are rejected.
[in]	value	Raw concentration or native species mass/s field; this setter stores it without finite/range validation, so meaningful physical values remain required.
[in]	ts_name	Optional series name; NULL stores empty text. Series are sampled linearly with held endpoint values on the absolute simulation clock.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX for an invalid row, or SWMM_ERR_BADPARAM for required missing/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.; MASS is supported for pollutant-native mg, ug or count rates; age, temperature and unresolved MSX MASS are rejected by active runtime validation. Updates preserve other terms; no borrowed strings are retained.

◆ swmm_gw_transport_authored()

SWMM_ENGINE_API int swmm_gw_transport_authored ( SWMM_Engine engine )

Test whether groundwater transport has any authored configuration.

Parameters

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

Returns: One when any options/rows make the configuration nonempty, zero otherwise, including for a null engine handle. No runtime is required.

◆ swmm_gw_transport_option_get()

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

Serialize one groundwater transport option using its section spelling.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	key	Non-null case-sensitive recognized uppercase option key.
[out]	buf	Non-null writable value buffer; multi-token boundary values include their arguments.
[in]	buflen	Positive byte capacity; values are truncated safely to len - 1 plus NUL.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Unknown keys return SWMM_ERR_BADPARAM. Units follow the key: seconds, W/m/K conductivity, m2 K/W resistance, or the documented thermal-BC units.

◆ swmm_gw_transport_option_set()

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

Parse and atomically assign one groundwater transport option.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	key	Non-null input-section key, passed to the shared parser.
[in]	value	Non-null textual value; whitespace splits multi-token arguments.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.; Parses a temporary options copy and publishes only on success; success sets its authored flag. No mesh is required.

Here is the call graph for this function:

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SWMM_GW_SCOPE_CELL

◆ SWMM_GW_SCOPE_GLOBAL

◆ SWMM_GW_SCOPE_TAG

◆ SWMM_GW_ZONE_LAYER

◆ SWMM_GW_ZONE_SAT

◆ SWMM_GW_ZONE_UNSAT

Typedef Documentation

◆ SWMM_GwParams

Function Documentation

◆ swmm_gw_boundary_quality_count()

◆ swmm_gw_boundary_quality_get()

◆ swmm_gw_boundary_quality_remove()

◆ swmm_gw_boundary_quality_set()

◆ swmm_gw_init_quality_count()

◆ swmm_gw_init_quality_file_get()

◆ swmm_gw_init_quality_file_set()

◆ swmm_gw_init_quality_get()

◆ swmm_gw_init_quality_remove()

◆ swmm_gw_init_quality_set()

◆ swmm_gw_params_count()

◆ swmm_gw_params_get()

◆ swmm_gw_params_remove()

◆ swmm_gw_params_set()

◆ swmm_gw_sorption_count()

◆ swmm_gw_sorption_get()

◆ swmm_gw_sorption_remove()

◆ swmm_gw_sorption_set()

◆ swmm_gw_source_count()

◆ swmm_gw_source_get()

◆ swmm_gw_source_remove()

◆ swmm_gw_source_scale_get()

◆ swmm_gw_source_scale_set()

◆ swmm_gw_source_set()

◆ swmm_gw_source_species_count()

◆ swmm_gw_source_species_get()

◆ swmm_gw_source_species_remove()

◆ swmm_gw_source_species_set()

◆ swmm_gw_transport_authored()

◆ swmm_gw_transport_option_get()

◆ swmm_gw_transport_option_set()