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.

Bases: object

Parameters:
kc: float#
dc: float#
exchange: bool#
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#
class AquiferOptions(owner)#

Bases: MutableMapping[str, str]

Text options using the native INP key/value spellings.

Parameters:

owner (Any)

set_process_options(*, et, link, wilting=Ellipsis, authored=Ellipsis)#
Parameters:
Return type:

None

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#
class Groundwater(owner)#

Bases: object

Parameters:

owner (Any)

property active: bool#
Parameters:
Return type:

None

add_node(node, cell, kc, dc, area=Ellipsis)#
Parameters:
Return type:

None

add_row(scope, ks, zs, theta_s, theta_r, alpha, *, tag=Ellipsis, cell=Ellipsis)#
Parameters:
Return type:

None

property authored_boundaries: tuple[dict[str, Any], ...]#
authored_boundary_receipt(index, species=Ellipsis)#
Parameters:
  • index (int)

  • species (int | None)

Return type:

dict[str, float]

boundary_flow(cell, edge)#
Parameters:
Return type:

float

boundary_receipt(cell, edge)#
Parameters:
Return type:

SourceReceipt

cell(cell, variable)#
Parameters:
  • cell (int)

  • variable (GroundwaterVariable)

Return type:

float

cells(variable)#
Parameters:

variable (GroundwaterVariable)

Return type:

NDArray[float64]

clear_boundary(cell, edge)#
Parameters:
Return type:

None

clear_source(source_id=Ellipsis, cell=Ellipsis)#
Parameters:
  • source_id (str)

  • cell (int | None)

Return type:

None

property clock_stats: dict[str, Any]#
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]#
property execution_status: dict[str, Any]#
layer_quality(cell, layer, species)#
Parameters:
Return type:

dict[str, float]

ledger(term)#
Parameters:

term (GroundwaterLedger)

Return type:

float

property nodes: tuple[AquiferNode, ...]#
property options: AquiferOptions#
remove_authored_boundary(index)#
Parameters:

index (int)

Return type:

None

Parameters:

index (int)

Return type:

None

remove_node(index)#
Parameters:

index (int)

Return type:

None

remove_row(index)#
Parameters:

index (int)

Return type:

None

replace_nodes(expected, replacement, *, bottoms=(), apply=True)#
Parameters:
Return type:

None

row_property(index, key)#
Parameters:
Return type:

float

property rows: tuple[AquiferRow, ...]#
set_authored_boundary(cell, edge, kind, value=Ellipsis, series=Ellipsis)#
Parameters:
Return type:

None

set_flow_boundary(cell, edge, flow_m3_s, concentrations=Ellipsis)#
Parameters:
Return type:

None

set_head_boundary(cell, edge, head_m, concentrations=Ellipsis)#
Parameters:
Return type:

None

set_heat_source(cells, heat_w, *, source_id=Ellipsis, until_seconds=Ellipsis)#
Parameters:
  • cells (Any)

  • heat_w (Any)

  • source_id (str)

  • until_seconds (float | None)

Return type:

None

set_node_exchange(index, enabled)#
Parameters:
Return type:

None

set_row_property(index, key, value)#
Parameters:
Return type:

None

set_species_source(cells, species_rates, *, source_id=Ellipsis, until_seconds=Ellipsis)#
Parameters:
Return type:

None

set_water_source(cells, flow_m3_s, **kwargs)#
Parameters:
Return type:

None

source_receipt(source_id=Ellipsis, cell=Ellipsis)#
Parameters:
Return type:

SourceReceipt

property sources: DomainSources#
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 = 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:
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:
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='', by_xy=False, x=0.0, y=0.0)#

Bases: object

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

Parameters:
by_xy: bool = False#
cell: int = 0#
flow: float = 0.0#
flow_timeseries: str = ''#
name: str = ''#
scope: CellScope = 2#
tag: str = ''#
x: float = 0.0#
y: float = 0.0#
class GroundwaterSourceTerm(species='', kind='CONC', value=0.0, timeseries='')#

Bases: object

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

Parameters:
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:
Return type:

None

set_source_species(source_index, row)#
Parameters:
Return type:

None

set_source_xy(source_index, x, y)#

Set finite map coordinates before initialization; retain XY on save.

Resolves the nearest cell centroid without changing flow, scale or species terms. Requires a mesh with cells.

Parameters:
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, …]

source_xy(source_index)#

Authored X/Y in project map units, or None for a non-XY source.

The source table separately reports CELL scope and the resolved cell.

Parameters:

source_index (int)

Return type:

tuple[float, float] | None

property sources: tuple[GroundwaterSource, ...]#
class GroundwaterTransportOptions(owner)#

Bases: MutableMapping[str, str]

Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling.

Parameters:

owner (Any)

Execution profiles#

Groundwater reactions and porous heat require the CPU first-order coupling profile. A standalone CLOSED_FORM/ENSLAVED/SIGMA mesh can use FULL_SWE with RECONSTRUCTION_ORDER 2 for water, passive pollutants and age, including SIGMA LAYERED chemistry. Active surface rows must match groundwater rows. Decay, heat, surface MSX and network/catchment owners remain guarded. Authored wells and HEAD/FLOW quality edges are supported: shared surface/groundwater stages split at knots and sign reversals. HEAD uses absolute elevation; FLOW is inward-positive m³/s. Quality knots split the shared stages. Runtime providers remain guarded. ENSLAVED stages average conserved total water and recover their equilibrium table/column state. SIGMA stages hold starting-state ALE velocity and average conserved layer water, deriving moisture and bulk UNSAT storage afterward. All three closures may share a mesh. Smooth SIGMA drainage and capillary tests retain second temporal order; collapse/rewet and donor switching have separate bounds/conservation checks without an order claim. Passive stage transport averages canonical mass, pending receipts and ledgers; UNSAT layer totals are derived. Explicit age production advances once per accepted interval. Reactions and heat require their separate qualification.

Surface age production is reported by surface2d.species_ledger("__WATER_AGE__")["age_generated"]. Rebuild surface plugins for ABI 6; older layouts fall back to CPU.

This profile has an internal numerical component checkpoint, not managed engine-calendar or output continuation. Requests for accelerated backends retain observable CPU fallback; they do not qualify device groundwater. See docs/design/groundwater-transport.md in the engine source for the activation and qualification boundaries.

Mesh chemistry checkpoint sessions#

A qualified first-order or RK2 mesh-only model with matching surface/groundwater transport rows can use solver.checkpoints.start_session(0) for numerical state or start_session(1) for native binary output, start_session(2) for mesh HDF5 output, or start_session(3) for both. The qualified profile requires matching species layouts and either WATER_ONLY with heat disabled, or POROUS_EQUILIBRIUM groundwater heat paired with coupled surface heat and a GROUND_COLUMN bed. BULK MSX species, passive pollutants and water age are optional; age-only and heat-only models need no dummy pollutant. Bulk and SIGMA layer transport are supported. With porous heat, chemical and thermal layer counts are independent.

Start both engines from the same model before saving and restoring with solver.checkpoints.save(path) and target.checkpoints.restore(path). Canonical water, solute, age/contact and soil-energy state, accepted clocks, engine calendar and qualified report history continue together. A different reaction definition, species units, grid or authored edge forcing is refused before publication. Reactive HEAD/FLOW edge reversals, simultaneous well forcing, imposed species fluxes and their gross receipts also continue with exact groundwater report history in the named profile. Bulk finite-porewater sessions require their ledger payload. Shared-source transport sessions also require the accepted-cell-clock payload, including species-only bulk models. Older exact-session files cannot supply that omitted history; raw default bulk state carriers retain their existing behavior.

This mesh-only profile excludes private catchment owners, WALL species and surface-species/buildup report continuation. The separate native LEGACY network profile supports numerical/binary continuation, first-order matched conservative mesh exchange and an independent RK2 mesh, without catchments, LIDs, treatment expressions or reactions. Keep global HEAT_TRANSPORT NO and WATER_AGE OFF. Both sessions must use matching pollutant names/order, units, decay, defaults and initial quality. Shared RK2 network exchange and ARD/LARD continuation remain refused. See the native groundwater transport contracts for the full limits.