openswmm_gw_transport.h File Reference

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:

Go to the source code of 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)
	Read one option into buf. SWMM_ERR_BADPARAM on an unknown key.
SWMM_ENGINE_API int	swmm_gw_transport_option_set (SWMM_Engine engine, const char *key, const char *value)
	Set one option (BUILDING/OPENED).
SWMM_ENGINE_API int	swmm_gw_transport_authored (SWMM_Engine engine)
	1 when any [GW_*] row was authored, else 0.
SWMM_ENGINE_API int	swmm_gw_params_count (SWMM_Engine engine)
SWMM_ENGINE_API int	swmm_gw_params_get (SWMM_Engine engine, int idx, SWMM_GwParams *row, char *tag_buf, int tag_len)
	Read row idx; tag_buf receives the TAG (empty otherwise).
SWMM_ENGINE_API int	swmm_gw_params_set (SWMM_Engine engine, const SWMM_GwParams *row, const char *tag)
	Append or replace the row for (scope, tag/cell).
SWMM_ENGINE_API int	swmm_gw_params_remove (SWMM_Engine engine, int idx)
SWMM_ENGINE_API int	swmm_gw_sorption_count (SWMM_Engine engine)
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)
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)
SWMM_ENGINE_API int	swmm_gw_sorption_remove (SWMM_Engine engine, int idx)
SWMM_ENGINE_API int	swmm_gw_init_quality_count (SWMM_Engine engine)
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)
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)
SWMM_ENGINE_API int	swmm_gw_init_quality_remove (SWMM_Engine engine, int idx)
SWMM_ENGINE_API int	swmm_gw_init_quality_file_get (SWMM_Engine engine, char *buf, int buflen)
	The FILE <csv> sidecar reference ("" when none).
SWMM_ENGINE_API int	swmm_gw_init_quality_file_set (SWMM_Engine engine, const char *path)
SWMM_ENGINE_API int	swmm_gw_boundary_quality_count (SWMM_Engine engine)
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)
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)
SWMM_ENGINE_API int	swmm_gw_boundary_quality_remove (SWMM_Engine engine, int idx)
SWMM_ENGINE_API int	swmm_gw_source_count (SWMM_Engine engine)
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)
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)
	Append or replace the source named name.
SWMM_ENGINE_API int	swmm_gw_source_remove (SWMM_Engine engine, int idx)
SWMM_ENGINE_API int	swmm_gw_source_species_count (SWMM_Engine engine, int src_idx)
	Species terms carried by source src_idx.
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)
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)
SWMM_ENGINE_API int	swmm_gw_source_species_remove (SWMM_Engine engine, int src_idx, int term_idx)

Detailed Description

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

Authoring only in this release. The integrated two-zone groundwater kernel that consumes these rows does not exist yet; a run emits one warning and the rows change nothing. Everything here nevertheless round-trips: a host can build a complete subsurface-transport model, save it, reopen it and get the same file back, and nothing about that file changes when the kernel lands.

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

)

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 )

swmm_gw_boundary_quality_remove()

SWMM_ENGINE_API int swmm_gw_boundary_quality_remove	(	SWMM_Engine	engine,
		int	idx )

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 )

Parameters

edge	LOCAL edge 0..nv-1 of cell (3 for a triangle, 4 for a quad).

swmm_gw_init_quality_count()

SWMM_ENGINE_API int swmm_gw_init_quality_count

(

SWMM_Engine

engine

)

swmm_gw_init_quality_file_get()

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

The FILE <csv> sidecar reference ("" when none).

swmm_gw_init_quality_file_set()

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

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 )

Parameters

layer

1-based, meaningful only when zone is SWMM_GW_ZONE_LAYER.

swmm_gw_init_quality_remove()

SWMM_ENGINE_API int swmm_gw_init_quality_remove	(	SWMM_Engine	engine,
		int	idx )

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 )

swmm_gw_params_count()

SWMM_ENGINE_API int swmm_gw_params_count

(

SWMM_Engine

engine

)

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 )

Read row idx; tag_buf receives the TAG (empty otherwise).

swmm_gw_params_remove()

SWMM_ENGINE_API int swmm_gw_params_remove	(	SWMM_Engine	engine,
		int	idx )

swmm_gw_params_set()

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

Append or replace the row for (scope, tag/cell).

swmm_gw_sorption_count()

SWMM_ENGINE_API int swmm_gw_sorption_count

(

SWMM_Engine

engine

)

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 )

Parameters

decay

1/day; negative means "use the [POLLUTANTS] kdecay".

swmm_gw_sorption_remove()

SWMM_ENGINE_API int swmm_gw_sorption_remove	(	SWMM_Engine	engine,
		int	idx )

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 )

swmm_gw_source_count()

SWMM_ENGINE_API int swmm_gw_source_count

(

SWMM_Engine

engine

)

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 )

swmm_gw_source_remove()

SWMM_ENGINE_API int swmm_gw_source_remove	(	SWMM_Engine	engine,
		int	idx )

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 )

Append or replace the source named name.

swmm_gw_source_species_count()

SWMM_ENGINE_API int swmm_gw_source_species_count	(	SWMM_Engine	engine,
		int	src_idx )

Species terms carried by source src_idx.

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 )

swmm_gw_source_species_remove()

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

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 )

Parameters

kind	"CONC" or "MASS". Upserts on the species name.

swmm_gw_transport_authored()

SWMM_ENGINE_API int swmm_gw_transport_authored

(

SWMM_Engine

engine

)

1 when any [GW_*] row was authored, else 0.

swmm_gw_transport_option_get()

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

Read one option into buf. SWMM_ERR_BADPARAM on an unknown key.

swmm_gw_transport_option_set()

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

Set one option (BUILDING/OPENED).

Here is the call graph for this function: