How SWMM6 Works

Take the cover off

A good engineer does not trust a machine until the cover has come off it. You want to see which shaft turns which gear, where the heat goes, and what happens when the load comes on. A computer program deserves the same treatment, and it rarely gets it.

For most of its life SWMM has had one answer to the question of how it really computes something: read the code. The program came out of an EPA contract in 1971. Its dynamic wave solver descends from EXTRAN, the Extended Transport block that joined SWMM in the 1970s. Lewis Rossman rewrote the whole program in C as SWMM 5. Generations of modelers learned it the hard way, one routine at a time.

Now there is a second machine in the shop. The OpenSWMM Engine lives in the HydroCouple/openswmm.engine repository on GitHub. Caleb Buahin and the OpenSWMM team are building it in C++20; it stands at version 6.0.0-alpha.4, with the EPA-lineage engine kept alongside it in the same repository as a 5.3.0-beta.3 wrapper. The new engine adds a finite-volume pipe solver, a two-dimensional surface and an aquifer under that surface.

This page takes the new machine apart in the order it runs. Every default, keyword and line number here was read off the swmm6_rel branch at commit 93421ef, pushed on October 20, 2026. When the film cites a line, the line is real, and the link takes you to it.

What the film is

The Film tab is eleven short scenes, a little over two minutes end to end. Each scene is one assembly of the machine, drawn as a working diagram: the two engines, the run’s lifecycle, input becoming arrays, picking the time step, runoff on its own clock, the routing step in order, the dynamic wave loop, finite-volume cells, the 2D surface, the aquifer under it, and closing the books. Under each scene sit the narration and the source lines it describes. Numbers taken from the source are real. Numbers that only make a diagram move, such as a residual shrinking pass by pass, are tagged example or illustrative on the stage.

Weigh it first

Before you take a machine apart, weigh it. The weight tells you where the work went.

The legacy engine in src/legacy is 82 files and 60,304 lines of C. The new engine in src/engine is 596 files and 231,919 lines of C++, 3.8 times the size.

Look where the mass sits. The engine shell, its C API and the checkpoint machinery run to 49,268 lines. The 2D surface and the aquifer under it take 48,235. Hydraulics is 35,791, and 13,368 of that is the finite-volume solver alone. Together the mesh, the aquifer and the finite-volume solver are 27 percent of the new engine. The old program never had any of that machinery, and it is where much of the new code has gone.

The life of a run

The engine is a state machine, and it is strict about it. A handle starts out CREATED. swmm_engine_open parses the input and leaves it OPENED. initialize applies the initial conditions, and start sets it RUNNING. Then you call swmm_engine_step as many times as it takes. Each call advances one routing step and reports the elapsed time in days. When the clock passes the end date, step marks the run ENDED by itself. report writes the summary and close releases everything.

Call a function out of turn and you get an error code back instead of a crash. There is a BUILDING state for a model put together through the API with no input file at all, and an ERROR_STATE that tells you to ask swmm_engine_last_error what happened.

Here is why a modeler should care. The step belongs to the caller. Between any two steps a program can read a depth, push an inflow, change a pump setting or save a checkpoint. The state lives in the handle instead of in global variables, so two models can run in one program without fouling each other. The public C API is split into 42 headers, one per subject: nodes, links, gages, the 2D surface, hot starts and so on.

From text to columns

An input file is a stack of bracketed sections. The engine keeps a SectionRegistry, a table that maps each section name to a handler, the code that knows how to read that one section. OptionsHandler takes [OPTIONS], NodesHandler the junctions, outfalls and storage units, LinksHandler the conduits, pumps and regulators. The 2D model registers its own: [2D_OPTIONS], [2D_VERTICES], [2D_TRIANGLES], [2D_QUADS] and the rest. A plugin can register a section of its own, and the model need not come from text at all: there are GeoPackage and HDF5 input plugins.

The handlers do not build one object per junction. They fill columns. Every node’s invert elevation goes in one array, every node’s depth in another, every link’s flow in a third. The name for this is structure-of-arrays. It sounds like clerk’s work, and it is. It also means that when a solver sweeps ten thousand conduits, the numbers it needs next lie side by side in memory, where the processor can reach them fast.

One turn of the crank

step() runs 419 lines, 1834 to 2252 of SWMMEngine.cpp. Strip off the guard rails and it does eight things, always in this order:

1. Pick the time step.
2. Apply any forcings a calling program injected.
3. Run runoff, which catches up on its own clock.
4. Run routing.
5. Book the routing mass balance.
6. Compute final storage and advance the clock.
7. Post a snapshot of the results for output.
8. Fire the step-end callback, and save a hot start or checkpoint if one is due.

The step length is the smallest of several limits. ROUTING_STEP, 20 s by default, is the ceiling. With VARIABLE_STEP set, 0.75 by default, the router works out a Courant-limited step from the conduits. RULE_STEP trims the step so it lands exactly on the next control-rule boundary, and the end of the run clamps the last step. Between storm events the engine can jump straight to the next runoff or report time.

One limit is missing, and on purpose. The 2D surface never shortens the pipe step. The source says so in a comment: the 2D marcher owns its own stability by subcycling. Each part of the machine keeps its own governor.

Runoff keeps its own clock

Here is a design decision from the old program that the new engine keeps to the letter. Runoff does not run every routing step. It runs on its own clock: WET_STEP, 300 s by default while it rains, and DRY_STEP, 3,600 s when it does not. Inside each runoff step the order is rain gages, climate, snowmelt, subcatchment runoff and infiltration, surface water quality, LID units and groundwater.

Routing comes around far more often. At each routing step the engine does not recompute runoff. It interpolates between the last two runoff results:

The comment above that code gives the reason in one sentence: computing runoff at every 5-second routing step produces peak rates 15 to 18 percent higher, with the same volume and sharper peaks. That figure is the source’s own, and this page did not re-run it. Two clocks with a straight line between them cost less than one fast clock, and they keep the new engine’s hydrographs in step with SWMM 5’s.

The routing step, and the loop at its heart

The routing phase works in a fixed order: pump targets, control rules, inflows (dry weather, direct, RDII and interface files), 2D outfall preparation, LID storage nodes, saving the old hydraulic state, 2D coupling conductances, exfiltration, and then the router. After the router come the 2D surface and water quality. The order is engineering. Controls act before the inflows are summed. Exfiltration rates are fixed before the router runs, so the router sees them. The surface moves only after the pipes have settled.

The router dispatches to one of four solvers: STEADY, KINWAVE, DYNWAVE or FV. Dynamic wave is the one most of us lean on, and its heart is a Picard iteration: guess the heads, compute the flows, use the flows to correct the heads, and go around again until the answer stops moving.

Each pass computes conduit geometry, solves momentum in every conduit, scatters the conduit flows onto their nodes, evaluates pumps, orifices, weirs and outlets, sets the outfall depths from the current flows, and updates every node depth. Then comes the test. HEAD_TOLERANCE is 0.005 ft unless you set it, and MAX_TRIALS is 8. The node update defaults to NODE_CONTINUITY EXPLICIT, the classic two-branch form, with SEMI_IMPLICIT available. ANDERSON_ACCEL, which blends earlier iterates to speed convergence, defaults to off.

The threading is worth a look. The whole loop runs inside one OpenMP team, forked once per routing step instead of once per phase per pass. Every parallel loop writes only its own elements, and on that basis the source states the results are bit-identical at any thread count. That is a strong claim, the kind you test before you lean on it. This page reports it and did not measure it.

Cells inside the pipe

Dynamic wave carries one flow per conduit, computed at its middle. The finite-volume router, FLOW_ROUTING FV, cuts every conduit into cells and solves the Saint-Venant equations in conservation form, one cell at a time. At each face between two cells an approximate Riemann solver, HLLC by default, decides how much water and momentum cross. The number of cells is max(FV_MIN_CELLS, ceil(L / FV_CELL_LENGTH)). The floor is 4, and there is no length target unless you set one.

Why four and not one? The authors measured it on Example1 and left the numbers in the source, which is exactly where numbers like that belong.

One cell per conduit gives a mean peak-flow deviation from dynamic wave of 37.1 percent. Four cells give 15.3 percent at 2.2 times the run time of one; eight give 7.6 percent at 5.4 times. The comment calls four the knee and says one cell was a known-wrong setting, not a cheap approximation. Keep in mind that deviation from dynamic wave is not error, because dynamic wave is not the truth either. The trend is what tells you when a mesh is too coarse.

The FV router substeps on its own to fill each routing step, at FV_CFL 0.5. Local time stepping, FV_LTS, on by default, lets short conduits take small steps while long ones take big ones, so the shortest pipe no longer sets the pace for the whole network. The October 20 push added a native implicit, backward-Euler FV prototype with its own GMRES linear solver. It has no input keyword yet, and its commit message names a known failure that holds back its promotion.

Water on the ground

Turn on the 2D surface and the ground becomes a mesh of triangles; quads are accepted as well. The default momentum equation is LOCAL_INERTIAL, the de Almeida and Bates face-flow update, with FULL_SWE and DIFFUSIVE_WAVE on the shelf. A coupled junction trades water with the cells around it through an orifice law by default. COUPLING_LAW WEIR_ORIFICE switches to a regime-aware law with free and submerged weir and orifice forms.

The surface runs at its own stability limit, CFL_NUMBER 0.7, and it advances in sync batches covering several routing steps, because a routing step of a second or so is shorter than one of its local-time-step cycles. Water exchanged during a batch flows back to the pipes as a uniform rate across the batch. BACKEND AUTO hands a big mesh to a Kokkos plugin for OpenMP, CUDA, HIP or SYCL, and keeps a small one on the CPU.

The October 20 push fixed an outfall bug worth knowing about. A flap-gated outfall under a flooded surface used to discharge as if its outlet were free, because the code skipped the 2D tailwater whenever the gate was present and the surface stood above the free stage. Now the tailwater applies to every coupled outfall, and the gate does the one thing a flap gate does: it stops reverse flow.

Water under the ground

Below the mesh the engine can carry a two-zone aquifer, an unsaturated zone over a saturated one. It has no time loop of its own. The surface marcher calls four hooks. assignTiers gives each cell its time-step tier. fireGwFaces moves water sideways between cells by Darcy’s law. fireGwCells gathers every flow into a cell and updates it. settle flushes the accumulators before any re-tiering. Each exchange is booked as plus-or-minus volume at the pace of the part that produced it and collected at the pace of the part that owns it. That is the same bookkeeping that lets the surface conserve mass across tiers, borrowed instead of derived a second time.

Seepage out of a conduit goes to the aquifer cells the pipe crosses, split by length. Three closures describe the unsaturated zone: CLOSED_FORM, ENSLAVED, and SIGMA, an explicit column of layers. AUTO, the default, picks one at start-up. In the 25 commits of October 19 and 20, wells, flow edges, head boundaries, equilibrium and SIGMA chemistry, solute transport and water age were all moved onto one shared, conservative, second-order Runge-Kutta step.

Closing the books

When routing is done, the engine closes the books. Each routing mass-balance term is booked by the trapezoid rule: half of last step’s rate times dt, plus half of this step’s. Final storage is computed, the clock advances, and a snapshot of the result arrays goes to the output side.

Output runs on its own thread. The main thread posts each snapshot into a bounded queue and goes straight back to computing. The IO thread takes the snapshots off the queue and hands them to every output plugin: the binary .out file, the .rpt report, GeoPackage, and a CF/UGRID HDF5 file for 2D results. Hot starts and checkpoints are written last, after the step has been accepted. Then the crank turns again.

What was checked

Every default, option keyword and line number in the film and in this essay was read from the source at commit 93421ef. The script that built this page opens each cited file again and confirms the cited line still contains the text it is cited for: 89 of 89 passed. The option keywords were confirmed against the parsers that read them, OptionsHandler.cpp and SectionHandlers2D.cpp. The line counts were made by a script over every .c, .h, .cpp and .hpp file under the two source trees. The GIF recorder’s encoder was checked by decoding a test file with Pillow: 345,600 pixels, no mismatches.

One check was not made. The engine was not compiled or run for this page. Statements about behavior, such as the 15 to 18 percent peak figure, the cell-count table and bit-identical threading, come from the authors’ comments in the source and are labeled that way.

What this does not show

A film about a machine is not the machine. Know where this one stops.

• The moving numbers on the stage are illustrative: the Courant step, the runoff values, the dynamic wave residuals, the 2D spread and the water table. They show how each part behaves, not what any particular model computes.
• Large parts of the engine get a sentence or nothing: control rules, water quality and its reaction chemistry, LID internals, the UEB and degree-day snow models, heat transport and the Lagrangian quality solver.
• The 2D surface and the aquifer are compiled in only when the build turns them on; in the source they sit behind OPENSWMM_HAS_2D.
• This is alpha software on a branch that moved 25 commits in two days. Line numbers drift. The links are pinned to commit 93421ef so they keep pointing at what was read.

How to use the film

1. Press Play, or tap a numbered scene chip to jump to that scene.
2. Drag the scrubber to hold a moment. Space plays and pauses; the left and right arrow keys step between scenes.
3. Read the narration under the stage, then follow the links under In the source to the exact lines on GitHub.
4. Use Make a GIF to record the current scene, or the whole film, as a captioned animated GIF.
5. Use the phase table under the film to copy or save the step’s phases, with their line numbers, as CSV.
6. Switch Dark, Light or Auto at the top right. Dark is the default.

Use of AI

This page was built with Claude, Anthropic’s AI model, in a Claude session on October 20, 2026, at the request of Robert (Bob) Dickinson, who asked for an animation of how SWMM6 works based on Caleb Buahin’s GitHub repository. Bob chose the subject, and responsibility for publishing the page is his.

Claude read the source at commit 93421ef, chose what to show, and wrote the film’s drawing code, the narration, this essay, the GIF encoder, the build script that re-checks every cited line, and the Word version of this essay. The checks listed under What was checked are mechanical. No person has yet reviewed the narration or this essay against the source line by line, and nobody from the OpenSWMM team has reviewed it.