 |
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)
|
OpenSWMM offers more than one representation of nearly every process it models. This chapter is the map: six decision workflows that take a modelling question and end at the literal [OPTIONS] lines that answer it, and a closing table that names, for every formulation, the keys that select it, its status, the theory that describes it and the worked example that uses it.
The workflows are drawn as flowcharts you can pan, zoom and click: a terminal node opens the chapter that documents the formulation it names. Nothing here decides for you — each branch states the question a modeller has to answer about their own system, and the cost of the answer.
One principle runs through all six. A default is not a recommendation; it is the choice that reproduces earlier behaviour. FLOW_ROUTING DYNWAVE, SURCHARGE_METHOD EXTRAN, QUALITY_SOLVER LEGACY and MOMENTUM_EQUATION LOCAL_INERTIAL are all defaults because changing them would change existing models' answers, not because they are the best available representation of every system. A model that never sets a key is choosing the legacy formulation.
The router decides what the momentum equation keeps. Steady flow keeps nothing and translates hydrographs; kinematic wave keeps the friction balance and cannot propagate a backwater; dynamic wave keeps the full one-dimensional momentum equation between nodes; the finite-volume router discretises the conduit itself and resolves the profile inside it.
graph TD
A[How is the conveyance system driven] --> B{Backwater, surcharge or pressurisation anywhere in the network}
B -- no --> C{Is in-pipe attenuation part of the answer}
C -- no --> D[FLOW_ROUTING STEADY]
C -- yes --> E[FLOW_ROUTING KINWAVE]
B -- yes --> F{Do you need the profile inside the conduit: bores, hydraulic jumps, mixed flow}
F -- no --> G[FLOW_ROUTING DYNWAVE]
F -- yes --> H[FLOW_ROUTING FV with FV_CELL_LENGTH and FV_MIN_CELLS]
G --> I{Does the network surcharge against its crowns}
I -- yes --> J[Choose a pressurisation closure: section 1.2]
H --> J
Figure 1-1 Choosing a flow router
The cost ladder is real. Steady flow is free, kinematic wave is cheap, dynamic wave costs an iteration per node per step, and the finite-volume router costs a substep bounded by the Courant condition on the shortest cell. Chapter 2: a filling pipe under both routers runs the same filling pipe through the last two and shows what the extra cost buys.
A pipe that fills has no free surface, and the shallow-water equations need one. Every closure invents a narrow slot above the crown so the equations keep their form; they differ in what the slot remembers and whether the pressure may go negative.
graph TD
A[Pipes pressurise] --> B{Which router}
B -- dynamic wave --> C{Is sub-atmospheric pressure part of the question}
C -- no --> D[SURCHARGE_METHOD EXTRAN or SLOT]
C -- yes --> E[SURCHARGE_METHOD TPA with TPA_CELERITY]
B -- finite volume --> F{Is sub-atmospheric pressure part of the question}
F -- no --> G[FV_PRESSURE_CLOSURE SLOT with FV_SLOT_CELERITY]
F -- yes --> H[FV_PRESSURE_CLOSURE TPA]
D --> I{Is the surge history itself the answer}
I -- yes --> K[SURCHARGE_METHOD DYNAMIC_SLOT with the DPS keys]
G --> L[Check the slot's share of stored volume in the report]
H --> M[Experimental: read section 8.4.5 before trusting a number]
Figure 1-2 Choosing a pressurisation closure
A slot celerity is an accuracy-cost trade, not a physical constant: the explicit step is bounded by the celerity, so asking for the acoustic speed of water collapses the step size. The default of 100 ft/s is the order the dynamic wave solver's own slot produces. Chapter 3: a sub-atmospheric transient runs a siphon where the two closures disagree about the sign of the pressure.
A one-dimensional model reports water leaving a node as flooding and loses sight of it. A mesh keeps it: where it goes, how deep it gets and when it comes back. That is a different question from how much left, and it costs a mesh, a solver and a coupling.
graph TD
A[Does water leave the network and spread over the surface] --> B{Is where it goes part of the answer}
B -- no --> C[Stay one-dimensional: flooding is reported per node]
B -- yes --> D{What drives the mesh}
D -- rain on the grid --> E[RAINFALL_MODE NATURAL_NEIGHBOUR with 2D_INFILTRATION rows]
D -- spill from the network --> F[2D_VERTEX_NODE_MAP or 2D_TRIANGLE_NODE_MAP]
D -- both --> G[Both, with subcatchment coverage ownership checked]
E --> H{Which momentum closure}
F --> H
G --> H
H -- shallow and friction dominated --> I[MOMENTUM_EQUATION LOCAL_INERTIAL]
H -- transcritical flow or shocks --> J[MOMENTUM_EQUATION FULL_SWE]
H -- very flat and slow --> K[MOMENTUM_EQUATION DIFFUSIVE_WAVE]
Figure 1-3 Deciding whether to add the two-dimensional surface, and how to drive it
Chapter 6: building a coupled 1D-2D model builds a coupled model from an existing network; Chapter 7: rain, infiltration and groundwater on the mesh drives one with rain rather than spill. The GUI tutorials T3 — From a DTM to an Animated 2D Inundation Map and T4 — Capped Street Inlets Coupled to a 2D Surface walk the same ground with a mouse.
All three engines solve the same advection-reaction-dispersion problem and share the same loads, the same reactions and the same mass-balance ledger. They differ in how they represent a front.
graph TD
A[Are constituents carried] --> B{What has to be right}
B -- totals at the outfall only --> C[QUALITY_SOLVER LEGACY]
B -- the shape of a front --> D{Sharp front or long chain of storages}
D -- a sharp front, plug flow --> E[QUALITY_SOLVER LAGRANGIAN with MAX_SEGMENTS_PER_LINK]
D -- dispersion is the mechanism --> F[QUALITY_SOLVER EULERIAN_ARD with TARGET_DX]
F --> G[DISPERSION FISCHER, or a measured VALUE]
E --> H[DISPERSION RWPT with RWPT_SEED for a reproducible draw]
C --> I[Every engine shares the same loads, reactions and ledger]
Figure 1-4 Choosing a transport engine
Refining the Eulerian mesh is quadratic: halving TARGET_DX doubles both the cell count and the substep count. Chapter 8: the three transport engines puts a tracer pulse through all three.
These three ride on the transport engine rather than replacing it. Each is a separate process component with its own configuration file, and each adds its own reserved species row.
graph TD
A[Beyond pollutant concentrations] --> B{Which question}
B -- how long has this water been in the system --> C[WATER_AGE ON with a WATER_AGE_SOURCES section]
B -- what temperature is it --> D[HEAT_TRANSPORT ON with a heat configuration file]
B -- species that react with each other --> E[PROCESS_COMPONENTS reactions with a reaction file]
D --> F[TEMPERATURE with HUMIDITY, WIND and the radiative sections]
E --> G{Do the reactions depend on temperature}
G -- yes --> D
C --> H[The age row is carried by whichever transport engine is selected]
Figure 1-5 Water age, heat and reacting species
Chapter 9: multi-species reactions and Chapter 10: water age and heat configure all three on one deck.
The lumped two-zone aquifer belongs to a subcatchment and exchanges with one node. The mesh aquifer belongs to the cells and exchanges with every node standing in them. They are different models of the same water, and only one of them can own a given parcel of ground.
graph TD
A[Is subsurface exchange part of the question] --> B{Lumped or spatially explicit}
B -- one store per subcatchment --> C[AQUIFERS with GROUNDWATER rows]
B -- a store per mesh cell --> D[2D_AQUIFER_OPTIONS with 2D_AQUIFER rows]
C --> E{Do you need your own flow equation}
E -- yes --> F[A GWF section on the subcatchment]
D --> G{How thick is the unsaturated column in capillary lengths}
G -- thin or unknown --> H[CLOSURE AUTO chooses at initialisation]
G -- deep, with profile memory --> I[CLOSURE SIGMA integrates the column]
D --> J{Where does mesh infiltration go}
J -- to this aquifer --> K[INFIL_DESTINATION AQUIFER_2D]
Figure 1-6 Choosing a groundwater representation
The mesh aquifer's non-Gardner soil laws are Experimental: their equilibrium is right and their relaxation rate is the engine's own generalisation rather than a published result. Chapter 7: rain, infiltration and groundwater on the mesh runs one.
Table 1-1 Every formulation, the keys that select it, and where it is documented
Grammar for every key named here is in Chapter 2 of the Engine Manual; the GUI's own controls are in 18 — Simulation Options.
1.13.2