 |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
|
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
Nothing in this chapter is complete in this release. Planned The formulations below are recorded because a modeller will meet their traces — a section the parser accepts and warns about, an option key that is stored but reaches nothing, a component id the registry knows by name — and the manual should say plainly what each trace means. Where a design record exists it is cited; where only a roadmap entry exists, that is said too. Every statement of "parsed but inert" is made against the parser and the consumer that does not exist.
| Formulation | Status | What exists today | What is missing |
|---|---|---|---|
| Sediment transport (§11.1) | Planned | A roadmap scope statement | Design record, sections, kernel |
| Groundwater transport (§11.2) | Experimental | Bulk SAT/UNSAT transport, named sources, budgets, results and restart | Per-layer transport, boundary hydraulic bindings and the fuller thermal/reaction formulation |
Finite-volume species transport on [POLLUTANTS] (§11.3) | Planned | Contact-upwinded, flux-corrected species kernels verified on their own gates | The connection to the project's species; FV_DISPERSION is inert |
| Per-element heat attributes — constants per tag, link or node, and climate per element through the API (§11.4) | Implemented | Parsed, resolved, honoured by every flux evaluator, written back | — |
| Per-element heat attributes — time series, computed shading, scoped API and GUI (§11.4) | Planned | The identity plumbing the constants ride on | Series resolution, a shade model, the editor table |
The five later-phase [REACTION_*] sections (§11.5) | Planned | Recognised by name and refused with their phase | Sources, per-element parameters, patterns, report selection, subcatchment scope |
Sediment is a planned theme of the engine roadmap and nothing more yet: there is no design record in the transport plans and no code. The roadmap's scope, quoted so that the reader knows what "planned" covers, is overland erosion (USLE/RUSLE or physically based detachment driven by rainfall and runoff shear), bedload and suspended-load routing in channels and pipes by empirical or process-based closures, multi-fraction particle sizes including cohesive material, deposition in basins, ponds and low-velocity reaches, and coupling to the water-quality transport so that particle-bound constituents ride the sediment. None of those items has been scoped against the engine's transport representations — the tanks-in-series, Eulerian and Lagrangian engines of Chapters 5 and 7 or the mesh of Chapter 10 — and no section, key or warning refers to sediment in this release. The bed zone of §9.3.11 is a heat and solute exchange layer, not a sediment store, and should not be read as a first step toward this item.
The two-zone mesh aquifer now has operational bulk SAT/UNSAT species stores, hydraulic mass transfers, sorption, dispersion and first-order decay. The transport policy controls the enabled species classes; an active aquifer is not categorically unavailable. The legacy subcatchment aquifer's constant quality boundary remains a separate model.
Section: [GW_INITIAL_QUALITY] applies SAT and UNSAT seeds with GLOBAL < TAG < CELL precedence. Section: [GW_SOURCES] applies named total water flow, native CONC and independent pollutant MASS loading, with optional SCALE, chronological series changes, availability-limited extraction and separate continuity terms. Source MASS uses mg/s, ug/s or count/s for declared MG/L, UG/L or #/L. Groundwater age values are seconds and temperature is degrees C. HDF5 SAT/UNSAT concentration datasets now identify native units per species, including when surface transport is disabled. Native restart version 7 retains source-species ledgers; new readers retain version 1–6 support.
These implemented paths do not complete the original design. Explicit SIGMA LAYERED transport now owns layer quality; LAYER never aliases bulk UNSAT. Hydraulic HEAD/FLOW edges bind groundwater boundary quality. Selected layered/porous thermal and scoped reaction profiles are implemented; see docs/design/groundwater-transport.md for their qualification limits. Groundwater reactions and heat retain first-order coupling; the separate standalone CPU passive pollutant/age CLOSED_FORM/ENSLAVED/SIGMA profile supports RK2. The older design below does not establish additional runtime capability.
The design (2026-09-04, amended 2026-09-07 for the mixed triangle/quadrilateral mesh) is retained here as the broader design, not as a claim that every term is implemented. Its saturated zone carries mass \(M_s = n\,h_g\,A\,C\) and solves the retarded advection–dispersion equation on the kernel's own Darcy face fluxes,
\[R_f\,\frac{\partial (n h_g C)}{\partial t} = -\nabla\cdot(\mathbf{q}\,C) + \nabla\cdot(n h_g D\,\nabla C) + S_C - \lambda\, n h_g C, \qquad R_f = 1 + \frac{1-n}{n}\,\rho_s K_d\] | (11-1) |
with a hydrodynamic dispersion \(D = D_m + \alpha_L |v|\) and the sorbed phase folded into the retardation rather than carried as a second species. The unsaturated zone is a well-mixed store under the kernel's closure A and a column of \(\sigma\)-layers advected by the kernel's moving-grid fluxes under closure B. Heat uses effective properties from the actual moisture state, \((\rho c)_{\mathrm{eff}} = \theta \rho_w c_w + (1-n)\rho_s c_s\), with conduction, a geothermal boundary and latent removal at evapotranspiration; age is an ordinary species slot; reaction species run the shared integrator per aquifer cell under a new SUBSURFACE scope. Every water flux the kernel moves — infiltration, recharge, capillary rise, return flow, node and conduit exchange — carries the donor's tuple, which is the rule the surface coupling of §10.4 already follows. The degenerate PER_SUBCATCH mode, one column per subcatchment, is what would replace the constant groundwater columns above on a network-only model.
[POLLUTANTS]The finite-volume routing solver of the Hydraulics Reference Manual (Chapter 8, §8.8) carries a species transport layer at scheme level: the species flux is the same mass flux the water used, upwinded on the HLLC contact speed so that solute mass is conserved exactly and a uniform field stays uniform through reversal, wetting and drying; UPWIND, MUSCL and QUICKEST_ULTIMATE reconstructions are limited by Zalesak's flux-corrected transport so the discrete maximum principle holds; and longitudinal dispersion is treated implicitly, one tridiagonal solve per cell chain, so the parabolic step limit never binds. When species are carried the solver stands local time stepping down, because the limiter bounds a cell against the extrema of its whole neighbourhood in one synchronous sweep and a tiered correction would be a new scheme. The kernels live in src/engine/transport/fvkernels/ and are verified on the solver's own analytic gates.
What is missing is the wiring. The router sizes the finite-volume state with zero species rows — fv_state_.resize(nc, nn, 0) — so no [POLLUTANTS] row, land-use load, inflow or treatment ever reaches the mesh, and under FLOW_ROUTING FV water quality is routed by the QUALITY_SOLVER engines of Chapters 5 and 7 as it is under dynamic wave. Three consequences follow, and the engine states each of them at open rather than leaving a calibrated deck to discover them:
[OPTIONS] FV_DISPERSION is parsed and stored, converted to internal units exactly as the honoured FV_* lengths are, and then reaches nothing; a non-zero value raises the FV option inert warning naming the key.FV_SCALAR_SCHEME set to anything but its default raises the same warning.QUALITY_SOLVER EULERIAN_ARD a non-zero FV_DISPERSION additionally warns that the Eulerian engine reads its dispersion from the transport component ([TRANSPORT_OPTIONS] DISPERSION and [CONDUIT_DISPERSION], Chapter 7 §7.3.3) and applies nothing from this key.The open design questions the roadmap records are how QUALITY_SOLVER would select finite-volume transport beside the three engines that exist, how the species rows would take their loads through the loader seam every other engine shares, and how cell-resolved concentrations would be reported. Unifying the FV_* and transport-component option surfaces is the phase the warning above names.
Chapter 9 documents the radiative and bed-zone parameters as one number per model. Shading, sky view, land-cover emissivity and temperature, burial depth, ground temperature and hyporheic velocity are properties of a place, and collapsing them to a scalar removes the spatial signal a heat model exists to produce. The per-element program (2026-09-01) makes them specifiable per element, with the per-element value overriding the global.
Landed (PE1, PE2, PE4 — validated and committed 2026-09-01). Every flux evaluator takes an element identity, so the same physics can be handed a different configuration per call. In [RADIATIVE_FLUXES] the rows ALBEDO, SHADE_FACTOR, SKY_VIEW, EMISS_WATER, EMISS_LANDCOVER and LANDCOVER_TEMPERATURE accept the scopes GLOBAL, TAG name, LINK name and NODE name; SHORTWAVE, ATM_EMISS_COEFF and ATM_LW_REFLECTION stay GLOBAL because they describe the incident resource and the atmosphere, not the reach. In [SEDIMENT_EXCHANGE] the bed attributes accept GLOBAL, TAG and LINK; NODE is refused because the bed zone exists beneath conduits only, and INITIAL_TEMPERATURE is the bed's own seed and stays GLOBAL. Precedence is GLOBAL under TAG under the named element; two rows at the same scope for the same target are refused rather than letting one silently win; global and per-element values pass one validator. Air temperature, humidity, wind and incident shortwave remain global in the deck and can be pushed per element only through the runtime forcing API, which is where a coupled shade or atmospheric model belongs. A deck with no override rows is byte-identical to one written before the program.
Open (PE3, PE5, PE6). Per-element TIMESERIES spellings of the same attributes; computed shading from sun position and bank vegetation, for which the recommendation on record is not to build — a prescribed SHADE_FACTOR series covers the seasonal case at a fraction of the cost; the scoped C API getters and setters and the GUI's per-element table; per-element wind-function coefficients; and the CELL2D scope that would let the 2D surface of Chapter 10 take per-cell shading — the element token exists, the flux evaluation on cells does not (§10.11).
[REACTION_*] Sections[REACTION_SUBCATCHMENTS] now implements a conservative wet-pool scope on non-LID subcatchments. Dry land-use reactions, porous LID layers and a continuously fed reactor formulation remain future work. Unknown reaction section names are errors.
Four formerly reserved sections are implemented: [REACTION_SOURCES] for CONC/MASS node loads, [REACTION_PATTERNS] for cyclic source multipliers, [REACTION_PARAMETERS] for node/link PARAMETER overrides, and [REACTION_REPORT] for native species-column selection. Their limits are in the input reference. SETPOINT/FLOWPACED sources, geometry-dependent wall kinetics, porous LID-layer reaction adapters and exact checkpoint/output continuation still require implementation and qualification.
A related refusal belongs in the same list: a RATE, EQUIL or FORMULA expression on a pollutant in [REACTION_PIPES] or [REACTION_TANKS] is refused with the note that pollutant kinetics arrive with phase R4b. Pollutants may be referenced read-only in reaction-species expressions, and their first-order Kdecay applies under every engine.
1.13.2