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 AquiferLink(link: 'str', kc: 'float', dc: 'float', exchange: 'bool')
Bases: object
- Parameters:
-
-
link: str
-
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
-
add_link(link, kc=Ellipsis, dc=Ellipsis, exchange=Ellipsis)
- 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:
-
- 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 links: tuple[AquiferLink, ...]
-
property nodes: tuple[AquiferNode, ...]
-
property options: AquiferOptions
-
remove_authored_boundary(index)
- Parameters:
index (int)
- Return type:
None
-
remove_link(index)
- 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:
-
- 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:
-
- 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:
-
-
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.