Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

swmm5-cplus

EPA SWMM 5.2.4 restructured as C++17 so that each simulation is an object. Nothing it computes differs from EPA's engine. What changes is that a program can hold, step and couple any number of models at once: in one process, on one thread each, or inside one WebAssembly instance in a browser.

Ready to use: dist/swmm5-cplus.html is the browser app (download it and open it in a browser; it needs no server), dist/swmm5-cplus-doc.docx is its essay, Same Numbers, Different Bones, as a Word document (40 pages, 21 figures), including the comparison with SWMM6, and dist/swmm5-cplus.md is the technical summary for AI tools and engineers: what it computes, every check with its numbers, the limits and the provenance.

EPA 5.2.4 keeps 415 mutable variables at file or program scope, so a process can hold one model. Open a second one over the first and swmm_open() returns 0, the first model's report stays empty, and AddressSanitizer counts 361,322 bytes in 134 allocations that are never freed. In swmm5-cplus those 415 variables are fields of class Project. Stage 1 made all 967 engine functions its members; R2 and R3 moved 97 general-purpose ones (cross-section geometry, the expression parser, the integrator, the root finders) back out as code that needs no model, and 870 remain members.

The parity contract

swmm5-cplus is judged against EPA SWMM 5.2.4 built from the USEPA v5.2.4 tag:

  • the .out file byte for byte, and
  • the .rpt file byte for byte after removing the three wall-clock lines (Analysis begun on, Analysis ended on, Total elapsed time),
  • on the same compiler family: GCC 13.3 natively (EPA at -O2 with Ubuntu's default fortify, so the gate passes absolute paths, see S5CP-2; swmm5-cplus at -O2 -flto), and Clang 18 with wasi-libc for WebAssembly (EPA at -O2, swmm5-cplus at -O2 -flto).

A run that both engines end with the same signal (the crash decks from the OpenSWMM code review) is counted as "both crash", not as identical.

A run that both engines abandon at the same time or file-size limit counts as inconclusive, never as a match.

Gate Result
Smoke set, every commit 40 / 40 identical
Coverage set (all 26 shapes, every feature found, 36 error decks) 187 / 187 identical
Full corpus, native: every model under 125 KB of input, plus a seeded sample of 72 of the 853 larger (18 per size quartile, to 88 MB) 3,743 identical, 0 different, 4 inconclusive (time cap), 12 crash decks crash both alike; 3,759 of 4,540 run
WebAssembly, swmm5-cplus vs EPA C (smoke + coverage sets) 221 / 221 identical
Six models round-robin in one instance; six threads each identical to its solo EPA run (native, ASan, wasm)
Run time, both with LTO, 8 models × 5 interleaved reps 1.003 × EPA (noise floor ±4.6 %)

The corpus is SWMMBobSWMM6/1729-SWMM5-Models-2030 (4,540 .inp files). The other 781 large models have not been run; at the sample's average run time they need at least 8 more hours on a two-core machine. Of the identical runs, 435 stop on an input error and write no .out, so the report is the whole comparison for them. Raw rows are in results/.

The history is the method

Each commit is one gated step on top of EPA's pristine source:

Commit Step
34066dc EPA SWMM 5.2.4 solver, unmodified
8e0fa39 Stage 1. Mechanical lift by tools/make_cplus.py: class Project, per-module PIMPL state, handle API
795fd37 R1. Resource safety: idempotent close, bounded paths, no descriptor leak; ~Project closes
adbddee R2. Root finders as templates, OdeSolver object, one MathExprParser per formula
c97a83a R3. Cross-section geometry as 26 shape classes (tools/transpose_xsect.py)
be57fec R3b. Shape table at namespace scope; swmm::Simulation; two-model coupling example

Stage 1 is a program, not a hand edit. make_cplus.py parses EPA's C with libclang and makes 5,710 edits, each at a location the compiler reported: a reference is renamed only where libclang says it refers to that declaration. Inside a macro argument (1,707 references of all kinds) libclang reports the macro's name, and the generator finds the identifier in the argument text by spelling. It works because C++ looks up an unqualified name in the same order C does: locals, then (now) class members, then namespace scope. Function bodies keep their text and their meaning.

Defects found (register S5CP)

ID Finding Status
S5CP-1 swmm_close() leaves its FILE* pointers dangling; a second close is a double free fixed in R1
S5CP-2 getAbsolutePath() can overrun InpDir (260 bytes); realpath() needs PATH_MAX; glibc fortify aborts EPA's runswmm on relative paths fixed in R1
S5CP-3 mkstemp() descriptor discarded (one leak per scratch file); TEMPDIR ignored descriptor fixed; TEMPDIR open
S5CP-4 swmm_open() over an open project abandons it (361,322 B leak) legacy API unchanged; handles avoid it
S5CP-5 Two TINYs: 1.E-6 in consts.h, 1.0e-30 in odesolve.c neutralized in R2 (kTiny)
S5CP-6 xsect.dat defines 92 non-const variables (49 tables, 43 sizes) with external linkage open; single definition since R3
S5CP-7 infil.h declares HortInfil, GAInfil, CNInfil; nothing defines them noted
S5CP-8 odesolve.c work arrays (nmax, y, yscal, yerr, ytemp, dydx, ak) are linker-visible globals fixed in R2
S5CP-9 Twelve files reach other modules' variables through local extern declarations open (made explicit)
S5CP-10 report.c declares extern char ErrString[81]; error.c defines char ErrString[256] (found by link-time optimization's type check) gone in C++: one member, one type

Speed (R4)

Measured on 8 corpus models chosen to span big dynamic-wave networks, continuous runoff, LID, water quality and a short-conduit case; CPU time of the child process, three interleaved repetitions, a repeat of the reference build as noise floor (±7–11 % per model). Raw rows are in results/perf/, the scripts in tools/perf/.

Build CPU time vs EPA 5.2.4 (Ubuntu's default gcc -O2) Output
EPA C, -O3 + LTO + PGO 0.90 byte-identical 8/8
swmm5-cplus be57fec, -O2 -flto 0.89–0.93 (two runs) byte-identical 8/8
swmm5-cplus R4 (outfall memo), -O3 -flto + PGO (tools/build_pgo.sh) 0.79 (0.46 on the water-quality model) byte-identical 8/8; gate: 217 of 221 smoke and coverage models identical, 4 crash decks crash both alike
EPA C with OpenMP, 2 threads wall time slower on 6 of 8 models, up to 1.75× .out identical
EPA C, -march=native (FMA) / -ffast-math 0.96 / 0.91 changed; the largest link-peak change was 6 % (FMA) and 11 % (fast-math)

R4 adds one change to the engine: the outfall conduit's normal and critical depth are pure functions of its flow, so a repeated flow reuses the last answer instead of re-running the Newton solve. A sampling profile (gprof) put cross-section geometry plus the math library at 25–72 % of run time and pow alone at 10–39 % in four of the eight models; the outfall solve was up to half the time of short-step models.

C, with a handle:

swmm5cp_handle h = swmm5cp_create();
int rc = swmm5cp_run(h, "model.inp", "model.rpt", "model.out");
swmm5cp_destroy(h);

Every swmm_ function has a swmm5cp_ twin that takes the handle. EPA's handle-less functions are still exported, each driving one default project per thread, so programs that call swmm_run() link unchanged.

C++, header-only, closes and frees however it leaves scope:

swmm::Simulation up, dn;
up.open("upstream.inp", "up.rpt", "up.out"); up.start();
dn.open("downstream.inp", "dn.rpt", "dn.out"); dn.start();

examples/coupled.cpp runs two models in lock step and hands the flow at one model's outfall to the other's inlet node; examples/models/merged.inp is the same network as one model, for the check.

Compared with SWMM6

OpenSWMM's SWMM6 (github.com/HydroCouple/openswmm.engine, branch swmm6_rel, 6.0.0-alpha.4) is the other C++ SWMM. It was read and counted at commit c40580c (28 October 2026) and built and run beside EPA 5.2.4 and swmm5-cplus, Release with the optional GeoPackage, HDF5, 2D and GPU modules off. On 12 November the comparison was rerun on all 3,562 models with three SWMM6 builds: A, c40580c as first built; B, the same commit with -ffp-contract=off; C, db4634a, 94 commits later. The Doc essay has the full account; the raw rows are in results/swmm6/ and results/swmm6/db4634a/, the scripts in tools/swmm6/.

Correction. The first build (A) was described as using -ffp-contract=off. It did not: a plain CMake configure at c40580c leaves contraction on, and SWMM6's engine is compiled with -mavx2 -mfma, so its library held 2,665 fused multiply-add instructions and the legacy engine's none. SWMM6's own commit 7d7dcbc (29 October) turns contraction off when no preset does. The table below is build C.

Measured, build C (db4634a) Result
Models run 3,522 small corpus models (EPA under 5 s) plus a seeded sample of 40 larger
Controls swmm5-cplus = EPA on 3,133 of 3,133 that wrote results; each SWMM6 engine = its own rerun (3,314 of 3,314; 3,226 of 3,226)
SWMM6 legacy (5.3.0-beta.3) = EPA 5.2.4 1,449 of 3,092
SWMM6 new = SWMM6 legacy 3,034 of 3,148; of the 54 more than 10 % apart, 36 have a Type 1 pump drawing from a junction (none of 149 with Type 1 pumps on storage nodes differs) and 14 are code-review decks
SWMM6 new = EPA 5.2.4 1,327 of 2,979
Models SWMM6 new refuses that EPA runs 144 (72 ERROR 145, 25 ERROR 203, ...)
Why the legacy engine differs from 5.2.4 (at c40580c) its free/normal outfall depth rule alone explains 915 of 1,558; with its storage and conveyance changes, 956
The flag and the code Result
A to B, contraction off, same commit new engine's output changed on 700 models (221 by over 10 % of an element's peak); legacy unchanged; new = legacy 2,377 -> 3,031; new = EPA 1,095 -> 1,376; no model went the other way
B to C, 94 commits, no contraction legacy changed on 117 models, new on 138 (runs that hit the time limit left out); every legacy change also in the new engine, in the same direction; against EPA 5.2.4, 30 further and 5 closer
Commits that moved them (bisection, 23 builds over 72 commits, 121 models) 40f439a (conduit evaporation and seepage limited by node water) moved 107 models in both engines: 30 further from EPA, 5 closer, 72 same distance; all 107 have evaporation or seepage, none of 2,711 dynamic-wave models without either changed. Six more commits changed 2 to 6 models each: three LID fixes from the code review (a47a3dc, fe8f84f, ab1d439) and three new refusals (e5f96a4, 7bcb4f4, 79e8e34)
CPU time vs EPA, 8 speed-study models SWMM6 new 2.17 (by the clock 2.04); with contraction on (build A) 2.10, off (B) 2.09, per model 0.93–1.06 of A, inside the noise; legacy 1.17; swmm5-cplus R4 0.86 (0.78 with PGO); EPA against itself 0.96–1.04
CPU time vs EPA, 5 networks of 345–8,683 links SWMM6 new 1.20–1.37, and 0.83 on 8,683 links with EPA's average routing step (build A's smaller step there came from contraction); legacy 1.05; swmm5-cplus 0.97; EPA against itself 0.97–1.02
Instructions, continuous model (build A) EPA 5.4 billion, SWMM6 new 11.5 billion; output 0.37 vs 2.7, memory 0.03 vs 1.0
One fwrite per period (test patch on build A) byte-identical on 48 of 48; CPU down 10 % on the continuous model, clock time unchanged

A line count of the three engines by purpose, from a parallel session, is in tools/loc_buckets.py and docs/swmm6_loc.json.

Building

Native (tools/build_native.sh ENG API OUT [FLAGS]):

tools/build_native.sh src/engine src/api build/native "-O2 -flto"

compiles src/engine/*.cpp and src/api/api.cpp with g++ -std=c++17, links EPA's own src/run/main.c (from the EPA tag) as the runswmm_cp command line, and builds tests/multi_native. Set MAINC to EPA's main.c if your EPA checkout is not at ../epa524.

WebAssembly (Clang 18, wasi-libc, wasm32-wasi reactor):

./build_wasm.sh        # build/wasm/swmm5cplus.wasm
./build_wasm_epa.sh    # build/wasm/swmm524_epa.wasm, EPA's C for comparison
node tests/wasm_run.mjs single build/wasm/swmm5cplus.wasm model.inp outdir

Re-running the checks

python3 tools/gate.py REF_EXE TEST_EXE CORPUS_DIR out.jsonl --list list.txt --timeout 300 --jobs 2
python3 tools/wasm_gate.py REF_EXE swmm5cplus.wasm swmm524_epa.wasm tests/wasm_run.mjs list.txt out.jsonl
python3 tools/bench.py EPA_EXE CPLUS_EXE list.txt out.json --reps 5

gate.py streams the hashes (a 1,000-year simulation's output never has to fit in memory), caps each run at 3 GiB of address space and 2 GiB per file, deletes outputs as it goes, and resumes from its own .jsonl. It runs each model with its own folder as the working directory, so data files resolve; models that save files (hot starts, rainfall interface files) write them there, and EPA leaves its swmmXXXXXX scratch files there when it crashes. Run it on a copy of the corpus. The SWMM6 comparison's own tools and how to rerun them are in tools/swmm6/README.md. tools/census.py, hazards.py and localtypes.py are the libclang census that came before the lift; features.py is the corpus feature census used to choose the coverage set.

The app

app/ builds swmm5-cplus.html, a single-file browser app that runs EPA 5.2.4 and swmm5-cplus side by side in WebAssembly, opens many models in one instance, runs the coupling, and carries the essay Same Numbers, Different Bones in its Doc tab. app/build.py reads the gate and timing results from the paths at its top; app/doc/essay.py is the single source of the essay, and doc/prep_docx.py plus doc/build_docx.js render the same text and figures to Word. app/make_all.sh runs the two passes (page, then Word, then the page again so it embeds the .docx). app/app_md.tmpl is the technical summary, filled from the same numbers as the essay and written beside the page as swmm5-cplus.md and inside it. app/bisect_text.py turns the SWMM6 bisection into the essay's numbers and commit table. The built copies in dist/ were made that way from the sources in this commit.

What this does not show

  • It is not a new engine and not more accurate. Every number is EPA 5.2.4's, EPA's own numerical defects included.
  • It fixes none of EPA's crashes: the crash decks in the corpus crash it the same way.
  • The full gate has not run 781 of the 853 models over 125 KB of input.
  • It is not faster. With link-time optimization it costs nothing measurable; at plain -O2 it is about 6 % slower on the eight models timed. One machine, two cores.
  • Parity is per platform. EPA's own C source gives different bits natively and in WebAssembly on 24 of 221 models; both WebAssembly engines agree on all of them.
  • Thread safety was tested (six models on six threads, identical), not audited. OpenMP in dynamic wave is compiled out in every build tested.
  • The coupling is one-way and a demonstration, not a validated method.
  • Project is still one large class and the modules still share the big arrays.
  • The SWMM6 comparison reads one alpha commit (c40580c) and runs two (c40580c in two builds, db4634a), built without the optional modules, on SWMM5 models that barely touch its new physics; agreement is on the 32-bit .out values, and no field data were used. Speed was timed on 13 models on a two-core machine. The first SWMM6 build had floating-point contraction on and was first reported as if it had not; see the correction above. The commits were found by bisection with a build without link-time optimization that reproduced the gate's builds at both ends.

Licence and credit

EPA SWMM is a work of the U.S. Environmental Protection Agency and is in the public domain; its engine is Lewis Rossman's design, and swmm5-cplus keeps every algorithm as he wrote it. No licence has been chosen yet for the restructuring itself.

SWMM6 (OpenSWMM Engine) is Copyright 2026 HydroCouple Developers, licensed under the Apache License, Version 2.0, branch swmm6_rel, commits c40580c and db4634a (https://github.com/HydroCouple/openswmm.engine); Caleb Buahin is lead developer, with Corinne Wiesner-Friedman on development and documentation. No SWMM6 engine is bundled here. The one patch to its source (tools/swmm6/swmm6_output_one_fwrite_per_period.patch, marked as modified) and the short excerpts quoted in the essay come under that licence: see NOTICE-SWMM6 and LICENSE-APACHE-2.0. The USEPA does not endorse this project.

AI use

swmm5-cplus, its tools, its app and this README were made with Claude, Anthropic's AI model (Claude Opus 5.5), in one session on 27 and 28 October and 12 November 2026, at the request of Robert (Bob) Dickinson, who asked the question and supplied the model corpus. Responsibility for publishing the work is his. Claude ran the libclang census, wrote the two generators and every hand-written change after them, found and fixed the resource defects, wrote the C and C++ APIs, the coupling example, the WebAssembly builds, the gate and timing harnesses, the app and its essay. The checks are mechanical: byte comparison against EPA 5.2.4 built from the tag, AddressSanitizer, interleaved timing with a noise floor. That evening two Claude sessions worked on SWMM6: one read its source and wrote tools/loc_buckets.py; the other, with Bob's go-ahead to build and run SWMM6's code, wrote tools/swmm6/, ran the four-engine gate, the timing, the profile and the attribution patches, and wrote the measured sections of the essay. On 12 November, at Bob's request for a deeper look, the same session rebuilt SWMM6 three ways, reran the four-engine gate on all 3,562 models, found and corrected the essay's account of the first SWMM6 build, bisected the 94 commits between the two SWMM6 versions, retimed the engines, and wrote tools/swmm6/cmp6u.py and its companions, the essay's summaries and its section on the flag and the commits, and swmm5-cplus.md. No person has yet reviewed the generated C++ or the hand edits line by line, or rerun either gate on another machine, and nobody from the SWMM6 project has seen the comparison.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages