Two-zone groundwater

solver.surface2d.groundwater exposes aquifer authoring and runtime results. The view retains its solver and is invalidated when the solver closes or its structure changes. Edits require BUILDING or OPENED. Use an explicit solver.open() before editing; the solver context manager starts the run.

Authoring units and precedence

add_row(scope, ks, zs, theta_s, theta_r, alpha, tag="", cell=-1) appends an aquifer row. CellScope selects GLOBAL, TAG or CELL. Runtime resolution uses the more specific row; cells are zero-based in Python on both triangular and quadrilateral meshes.

• ks uses project rainfall-rate units (in/hr or mm/hr).

• zs uses project length (ft or m), and alpha inverse length.

• theta_s and theta_r are dimensionless water contents.

• Optional row properties include HG0, PSI_B, LAMBDA, N, L, C_LOSS, SOIL_CHAR, CLOSURE and M_LAYERS. Use GroundwaterSoil and GroundwaterClosure for their numeric selectors.

options is a text mapping using native INP keys and values. rows and nodes are immutable snapshots. Removing a row shifts subsequent indices. add_node accepts a zero-based cell or -1 for coordinate-based location; its conductivity is in/hr or mm/hr, thickness is ft or m, and area is ft² or m². Zero area uses cell area, and zero conductivity requests direct Darcy exchange. Node snapshots distinguish authored, located and automatically enrolled beds and expose the exchange opt-out flag.

Runtime units

After initialization/start, active indicates that the kernel is available. Runtime hydrology uses SI regardless of the input project’s unit system. dimensions returns cell and sigma-layer counts. cell(index, variable) reads one value and cells(variable) returns an owned float64 NumPy snapshot. GroundwaterVariable selectors distinguish thickness/elevation (m), flux rates (m/s or m³/s), timestep (s), tier and closure codes.

column(cell) returns water contents from the surface down and requires a SIGMA closure; the engine refuses other closures instead of returning a misleading zero-filled array. ledger(term) returns m³. The continuity_error is a residual in m³, not a percentage. tier_histogram uses the platform’s C-long dtype, including on Windows.

species lists the transported names in native policy order. concentrations(zone, species_index) returns per-cell concentrations in the species’ own mass units per m³ of zone water; dry zones report zero. species_ledger exposes the corresponding cumulative native ledger.

class AquiferNode(node: 'str', cell: 'int', kc: 'float', dc: 'float', area: 'float', locate: 'bool', exchange: 'bool', automatic: 'bool')

Bases: object

Parameters:

• node (str)

• cell (int)

• kc (float)

• dc (float)

• area (float)

• locate (bool)

• exchange (bool)

• automatic (bool)

node: str

cell: int

kc: float

dc: float

area: float

locate: bool

exchange: bool

automatic: bool

class AquiferOptions(owner)

Bases: MutableMapping[str, str]

Text options using the native INP key/value spellings.

Parameters:

owner (Any)

class AquiferRow(scope: 'CellScope', tag: 'str', cell: 'int', ks: 'float', zs: 'float', theta_s: 'float', theta_r: 'float', alpha: 'float')

Bases: object

Parameters:

• scope (CellScope)

• tag (str)

• cell (int)

• ks (float)

• zs (float)

• theta_s (float)

• theta_r (float)

• alpha (float)

scope: CellScope

tag: str

cell: int

ks: float

zs: float

theta_s: float

theta_r: float

alpha: float

class Groundwater(owner)

Bases: object

Parameters:

owner (Any)

property active: bool

add_node(node, cell, kc, dc, area=Ellipsis)

Parameters:

• node (str)

• cell (int)

• kc (float)

• dc (float)

• area (float)

Return type:

None

add_row(scope, ks, zs, theta_s, theta_r, alpha, *, tag=Ellipsis, cell=Ellipsis)

Parameters:

• scope (CellScope)

• ks (float)

• zs (float)

• theta_s (float)

• theta_r (float)

• alpha (float)

• tag (str)

• cell (int)

Return type:

None

cell(cell, variable)

Parameters:

• cell (int)

• variable (GroundwaterVariable)

Return type:

float

cells(variable)

Parameters:

variable (GroundwaterVariable)

Return type:

NDArray[float64]

column(cell)

Parameters:

cell (int)

Return type:

NDArray[float64]

concentrations(zone, species)

Parameters:

• zone (GroundwaterZone)

• species (int)

Return type:

NDArray[float64]

property continuity_error: float

property dimensions: tuple[int, int]

ledger(term)

Parameters:

term (GroundwaterLedger)

Return type:

float

property nodes: tuple[AquiferNode, ...]

property options: AquiferOptions

remove_node(index)

Parameters:

index (int)

Return type:

None

remove_row(index)

Parameters:

index (int)

Return type:

None

row_property(index, key)

Parameters:

• index (int)

• key (str)

Return type:

float

property rows: tuple[AquiferRow, ...]

set_node_exchange(index, enabled)

Parameters:

• index (int)

• enabled (bool)

Return type:

None

set_row_property(index, key, value)

Parameters:

• index (int)

• key (str)

• value (float)

Return type:

None

property species: tuple[str, ...]

species_ledger(species, term)

Parameters:

• species (int)

• term (GroundwaterSpeciesLedger)

Return type:

float

property tier_histogram: NDArray[Any]

property transport: GroundwaterTransport

Transport authoring

groundwater.transport edits the groundwater transport tables before initialization. Its options mapping takes native text keys such as TRANSPORT_POLLUTANTS, TRANSPORT_MSX, TRANSPORT_AGE and TRANSPORT_TEMPERATURE. Use YES/NO for switches. authored distinguishes an authored transport configuration from an absent one; consult solver.transport_matrix for runtime availability.

The parameters, sorption, initial_quality, boundaries and sources properties return tuples of frozen records. Their set_* methods upsert by native row identity. Change a field with dataclasses.replace and submit the new record; modifying a snapshot does not mutate the model. remove_* takes a zero-based row index, and subsequent indices shift. Source-species terms have a separate table indexed by the source row.

from openswmm.engine import GroundwaterParameters, GroundwaterInitialQuality

transport = solver.surface2d.groundwater.transport  # after solver.open()
transport.options['TRANSPORT_POLLUTANTS'] = 'YES'
transport.set_parameters(GroundwaterParameters(rho_s=2700))
transport.set_initial_quality(
    GroundwaterInitialQuality(species='TSS', value=5)
)

Parameter records use SI: density kg/m³, heat capacity J/(kg K), conductivity W/(m K), dispersivity m, diffusivity m²/s and geothermal flux W/m². Source flow is m³/s regardless of project FLOW_UNITS. Sorption kd is L/kg and decay is 1/day; a negative decay inherits the pollutant value. Initial quality uses native species authoring units, which must not be confused with runtime mass-per-m³ arrays.

GroundwaterTransportZone selects SAT, UNSAT or LAYER. LAYER requires the native one-based layer number; cell, edge and table indices are zero-based. Boundary edge indices follow the cell geometry, including edge 3 of a quad. initial_quality_file accepts a path or None to clear the reference. The reference is authored metadata; it does not read or apply the file immediately.

class GroundwaterBoundary(cell=0, edge=0, species='', kind='CONC', value=0.0, timeseries='')

Bases: object

Immutable authored row; replace fields and submit it with the matching setter.

Parameters:

• cell (int)

• edge (int)

• species (str)

• kind (str)

• value (float)

• timeseries (str)

cell: int = 0

edge: int = 0

kind: str = 'CONC'

species: str = ''

timeseries: str = ''

value: float = 0.0

class GroundwaterInitialQuality(scope=CellScope.GLOBAL, tag='', cell=-1, zone=GroundwaterTransportZone.SAT, layer=-1, species='', value=0.0)

Bases: object

Immutable authored row; replace fields and submit it with the matching setter.

Parameters:

• scope (CellScope)

• tag (str)

• cell (int)

• zone (GroundwaterTransportZone)

• layer (int)

• species (str)

• value (float)

cell: int = -1

layer: int = -1

scope: CellScope = 0

species: str = ''

tag: str = ''

value: float = 0.0

zone: GroundwaterTransportZone = 0

class GroundwaterParameters(scope=CellScope.GLOBAL, cell=-1, rho_s=2650.0, c_s=880.0, lambda_s=2.0, a_s=0.0, alpha_L=1.0, alpha_T=0.1, D_m=1e-09, D_v=1e-09, geo_flux=0.065, tag='')

Bases: object

Immutable authored row; replace fields and submit it with the matching setter.

Parameters:

• scope (CellScope)

• cell (int)

• rho_s (float)

• c_s (float)

• lambda_s (float)

• a_s (float)

• alpha_L (float)

• alpha_T (float)

• D_m (float)

• D_v (float)

• geo_flux (float)

• tag (str)

D_m: float = 1e-09

D_v: float = 1e-09

a_s: float = 0.0

alpha_L: float = 1.0

alpha_T: float = 0.1

c_s: float = 880.0

cell: int = -1

geo_flux: float = 0.065

lambda_s: float = 2.0

rho_s: float = 2650.0

scope: CellScope = 0

tag: str = ''

class GroundwaterSorption(scope=CellScope.GLOBAL, tag='', cell=-1, species='', kd=0.0, decay=-1.0)

Bases: object

Immutable authored row; replace fields and submit it with the matching setter.

Parameters:

• scope (CellScope)

• tag (str)

• cell (int)

• species (str)

• kd (float)

• decay (float)

cell: int = -1

decay: float = -1.0

kd: float = 0.0

scope: CellScope = 0

species: str = ''

tag: str = ''

class GroundwaterSource(name='', scope=CellScope.CELL, tag='', cell=0, flow=0.0, flow_timeseries='')

Bases: object

Immutable authored row; replace fields and submit it with the matching setter.

Parameters:

• name (str)

• scope (CellScope)

• tag (str)

• cell (int)

• flow (float)

• flow_timeseries (str)

cell: int = 0

flow: float = 0.0

flow_timeseries: str = ''

name: str = ''

scope: CellScope = 2

tag: str = ''

class GroundwaterSourceTerm(species='', kind='CONC', value=0.0, timeseries='')

Bases: object

Immutable authored row; replace fields and submit it with the matching setter.

Parameters:

• species (str)

• kind (str)

• value (float)

• timeseries (str)

kind: str = 'CONC'

species: str = ''

timeseries: str = ''

value: float = 0.0

class GroundwaterTransport(owner)

Bases: object

Parameters:

owner (Any)

property authored: bool

property boundaries: tuple[GroundwaterBoundary, ...]

property initial_quality: tuple[GroundwaterInitialQuality, ...]

property initial_quality_file: str

property options: GroundwaterTransportOptions

property parameters: tuple[GroundwaterParameters, ...]

remove_boundary(index)

Parameters:

index (int)

Return type:

None

remove_initial_quality(index)

Parameters:

index (int)

Return type:

None

remove_parameters(index)

Parameters:

index (int)

Return type:

None

remove_sorption(index)

Parameters:

index (int)

Return type:

None

remove_source(index)

Parameters:

index (int)

Return type:

None

remove_source_species(source_index, index)

Parameters:

• source_index (int)

• index (int)

Return type:

None

set_boundary(row)

Parameters:

row (GroundwaterBoundary)

Return type:

None

set_initial_quality(row)

Parameters:

row (GroundwaterInitialQuality)

Return type:

None

set_parameters(row)

Parameters:

row (GroundwaterParameters)

Return type:

None

set_sorption(row)

Parameters:

row (GroundwaterSorption)

Return type:

None

set_source(row)

Parameters:

row (GroundwaterSource)

Return type:

None

set_source_scale(source_index, value)

Parameters:

• source_index (int)

• value (float)

Return type:

None

set_source_species(source_index, row)

Parameters:

• source_index (int)

• row (GroundwaterSourceTerm)

Return type:

None

property sorption: tuple[GroundwaterSorption, ...]

source_scale(source_index)

Parameters:

source_index (int)

Return type:

float

source_species(source_index)

Parameters:

source_index (int)

Return type:

tuple[GroundwaterSourceTerm, …]

property sources: tuple[GroundwaterSource, ...]

class GroundwaterTransportOptions(owner)

Bases: MutableMapping[str, str]

Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling.

Parameters:

owner (Any)