Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

swmm6-perl: the OpenSWMM 6 1D engine in Perl, byte for byte

A translation of the 1D engine of OpenSWMM 6 (HydroCouple/openswmm.engine, branch swmm6_rel, commit 88329d6) into Perl, held to the same output as the C++ engine: the same binary .out file and the same .rpt report, apart from the three clock lines. It is not SWMM6 and not a HydroCouple or EPA release; it is a translation checked against SWMM6.

Result

471 of 480 models byte-identical (the other 9 did not finish within the time limit, Hydrology/27_Subs_Horton.inp after 1800 s, Hydrology/SCANLON.inp after 1800 s, Hydrology/292_Storage_Nodes_200_Subs.inp after 1800 s, Hydrology/17_Sub_90_Link_USA_Units.inp after 1800 s, Hydrology/short_trap_SW5.inp after 1800 s, EPA/72_H&H_Elements(2).inp after 1800 s, EPA/10000FootSurchargeDepth.inp after 1800 s, EPA/attenuation_DW_High_CE.inp after 1800 s, Hydrology/CN_Horton.inp after 1800 s; untested, not failed) against the C++ reference engine built from the same commit and run on one thread (OMP_NUM_THREADS=1), on the 480-model gate set (the one the SWMM5 ports were checked on), drawn from 1729-SWMM5-Models-2030. Gate runs pl6_c01, pl6_c02, pl6_c03, pl6_c04, pl6_c04r, pl6_c05, pl6_c06, pl6_c07, pl6_c08, pl6_c09, pl6_c10, pl6_c11, pl6_c12, pl6_s01, pl6_s02, pl6_s03, pl6_s04, pl6_s05, pl6_s06, pl6_s07, pl6_s08, pl6_s09, pl6_s10, pl6_s11, pl6_s12, pl6_s13, pl6_s14, pl6_s15, pl6_s16, pl6_s17, pl6_s18, pl6_s19, pl6_s20, pl6_s21, pl6_s22, pl6_s23, pl6_s24, pl6_s25, pl6_s26; every result, with the SHA-256 of each .out and .rpt, is in gate/evidence/.

The same engine on the 452 extra decks: 450 of 452 extra decks byte-identical (2 did not finish within the time limit: legacy_small.inp, refactored_small.inp; untested, not failed). These are SWMM6's own tests, which the corpus cannot be: the input files in the upstream repository's tests folder at 88329d6, and the synthetic decks of swmm6-rust's gate, which probe the finite-volume solver, its structure coupling, the newer hydrology and the input checks. Gate runs pl6_x01, pl6_x02, pl6_x07, pl6_xs01, pl6_xs02, pl6_xs03, pl6_xs04, pl6_xs05, pl6_xs06, pl6_xs07, pl6_xs08, in gate/evidence/ with the same hashes.

Checked twice more. An independent rerun of a sample (100 corpus models drawn at random from those that passed, plus the decks that SAVE and USE cho.txt that were not drawn, and 40 extra decks drawn the same way; a sample, not the full set, because the corpus gate took more than five hours of engine time) from a clean copy of the repository (git archive), with the translator rebuilt there and the engine (perl/gen/engine.pl, perl/gen/literals.txt and the translator's three reports) and perl/cpp/primelist.pl regenerated there, all byte-identical to the committed files (perl/results/pl6_v_build.txt); every .out and .rpt hash equal to the first run's: gate runs pl6_v_a, pl6_v_b, pl6_v_c, pl6_v_d, pl6_vx, 142 of 142 byte-identical. Then the main session's own check, from a clean git clone: the translator rebuilt and the engine and primelist.pl regenerated (identical again; the engine compiles under perl); and gate runs pl6_main on 45 corpus models drawn at random (seed 20261110) plus the three decks that SAVE and USE cho.txt (47 of 48 byte-identical) and pl6_main_x on 12 extra decks drawn the same way (12 of 12 byte-identical). The math's own tests are in perl/results/libm_tests.txt.

The nine corpus models and two extra decks that did not finish were stopped at the gate's 1,800-second limit, and no longer limit was tried. Every byte of .out each had written by then is identical to the reference (perl/results/*_stopped.txt; the table in perl/README.md), from 0 of 440,275 bytes for 72_H&H_Elements(2).inp to 92.8% for 27_Subs_Horton.inp. They are among the slowest models for the Python port too, and this engine runs about three to five and a half times slower than the Python port (perl/results/pl_vs_py.txt). One of them, 10000FootSurchargeDepth.inp, is in the main session's sample of 48 and stopped there at the limit again.

Hydrology/save_rtk_long.inp was run twice (pl6_c04, then pl6_c04r; PASS both times, the same hashes): another port's clean-up deleted the backup the SAVE-file wrapper had made of Hydrology/cho.txt during the first run, so the wrapper could not put the file back. The file that run left is the engine's own SAVE output and is byte-identical to the corpus's (1,114,474 bytes, md5 5b0ca1fe78588202fa779dbfa417b089); only its modification time changed.

A model passes when its .out is byte-identical to the reference's (when the reference writes one), its .rpt is identical after removing the lines "Analysis begun", "Analysis ended" and "Total elapsed time", and its exit code is the same (the command line exits nonzero when a model stops on an input error).

The translations, all from the same C# and gated the same way: swmm6-csharp, swmm6-go, swmm6-java, swmm6-typescript, swmm6-fortran, swmm6-python, swmm6-kotlin, swmm6-groovy, swmm6-javascript, swmm6-fsharp, swmm6-hy, swmm6-ruby, swmm6-php, swmm6-perl, under SWMMBobSWMM6.

How it was made

The C++ engine was translated to C# first, and the C# gated to 480 of 480. The other languages are translated from that C#, not from the C++. tools/cs2x/Cs2Pl.cs, begun as a copy of the Ruby back end, translates the verified C# engine (cs/gen) through Roslyn into one Perl file (perl/gen/engine.pl; the mapping is in tools/cs2x/PL.md). Perl does whole-number arithmetic with integers, which have no negative zero, so every double +, - and * whose result can be zero carries a repair of the zero's sign. perl/cpp is the runtime library, written in Perl for this port. No math was translated: it is glibc's own, through Perl's built-in functions and POSIX, at the symbol versions the C++ engine links. Nothing in perl/ loads anything from the other ports.

Nothing in the generated engine is edited by hand. Where the output depends on the C library (printf's rounding, strtod, sscanf, the order of a hash table's nodes, introsort's swaps), the runtime reproduces glibc and libstdc++ exactly; the checks in tests/ compare it with them case by case.

Build and run

Needs Perl 5.38 (core modules only; run here with 5.38.2) on x86-64 Linux with glibc; the .NET 8 SDK only to regenerate the engine. No build step. Then run a model the way the C++ command line runs it:

perl/runswmm6 model.inp model.rpt model.out

To regenerate the engine: tools/cs2x/build_pl.sh, then dotnet tools/cs2x/bin/cs2pl.dll cs perl/gen, then perl/make_primelist.sh. The C# engine it starts from is regenerated from the C++ source with tools/cpp2x (see the header of tools/cpp2x/emit_cs.py and cs/README.md), which needs the OpenSWMM source at commit 88329d6 and libclang.

The gate

gate/make_ref.sh makes the reference outputs with the C++ engine (ref/runswmm6: build openswmm.engine at 88329d6 and run it single-threaded); gate/gate.py NAME "perl/runswmm6" --resume runs this engine on every model in gate/models_all.tsv (paths relative to the corpus; set SWMM_CORPUS) and compares; gate/cmp1.sh checks one model. The extra decks are listed in gate/models_extra.tsv, with paths relative to a folder that holds clones of openswmm.engine (at 88329d6) and swmm6-rust: make their references with SWMM_CORPUS=FOLDER MODELS=gate/models_extra.tsv REF=$PWD/gate/ref_outputs_extra gate/make_ref.sh, then run gate/gate.py NAME "perl/runswmm6" --models gate/models_extra.tsv --ref gate/ref_outputs_extra --root FOLDER --resume. The median time per model in the gate runs was 7.40 s (the C# engine's: 0.76 s, which includes .NET's start-up and JIT compilation). The times were measured on a shared two-core cloud machine while other runs were going, so they are a rough guide, not a benchmark.

What this does not show

  • Agreement on models outside the 480 and the 452. The two sets are broad (EPA's examples, the OWA EXTRAN set, hydrology, hydraulics, water quality, LID, RDII, controls, hot start, input errors, the FV solver and SWMM6's own tests), but a feature no gate model or deck uses is untested.
  • The reference's parallel runs. Every parallel loop runs on one thread, in order, which is what the C++ engine does when it is held to one thread; results with OpenMP threads can differ in the last bits.
  • The 2D and other modules of OpenSWMM 6 beyond the 1D engine the command line runs.

License and attribution

This repository is a translation of the OpenSWMM 6 engine.

OpenSWMM Engine — Copyright 2026 HydroCouple Developers, licensed under the Apache License, Version 2.0. See LICENSE and NOTICE. Source: https://github.com/HydroCouple/openswmm.engine (branch swmm6_rel, commit 88329d6).

Every generated engine file here is a modified, mechanically translated form of the OpenSWMM sources: its header names what it was generated from, and each C# file in cs/gen names the OpenSWMM source file it came from.

Portions derive from the USEPA Storm Water Management Model, which is in the public domain under 17 USC § 105. The USEPA does not endorse this product, and neither does HydroCouple.

The translators, the runtime, the gate and the notes: Copyright 2026 Robert Dickinson, licensed under the Apache License, Version 2.0.

AI use

Made with Claude (Anthropic): the translators, the runtime, the gate and the notes are Claude's work, directed by Robert Dickinson; the engine itself is OpenSWMM's, translated mechanically. See AI-USE.md.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages