9. Run and engines

9.1 Engines

An engine is EPA's command-line runner, runswmm.exe on Windows or runswmm elsewhere, found on disk as §1.2 describes. Each is identified by the version it reports to --version and by the SHA-256 of the executable file, and both are stamped into every run. The Run menu lists them as EPA SWMM 5.2.4 — 32-bit (x86); the SWMM panel adds runs out-of-process when the architecture differs from AquaSWMM's.

Several may be registered — 5.1.015 beside 5.2.4, or a 64-bit build you compiled beside EPA's 32-bit one — and the chosen engine is the one F5 uses. Find Engines (Run menu and panel) rescans. The choice persists for the session.

AquaSWMM never modifies an engine, links to it, or patches its results. What EPA ships is what runs.

9.2 Running

Run (F5, the toolbar button, Run → Run, or Run Model in the panel) does, in order:

1. Validates the document. Error-level findings refuse the run with The model has errors; the list is clickable (§3.11). Warning-level findings show once, per document state, as Warnings before running — the same window as Run → Check Model… — with Run anyway and Cancel; once you have run anyway, the same warnings do not ask again until the model changes.
2. Decides which file to run. A saved, clean model on an ASCII path runs in place. Otherwise — unsaved, dirty, or a path with characters outside ASCII, which the stock engine may not open — a scratch copy of the current text is written under %TEMP%\AquaSWMM\run\<hash>\, with the model's [FILES] and data files carried along so their relative paths still resolve, and that copy runs. The report and results land beside whichever file ran, and the Run Status window says which (Model read, Ran a scratch copy). A model with ARM subcatchments always runs a scratch copy, with their hydrographs as node inflows (§24.8).
3. Deletes any stale .rpt and .out beside it, because runswmm appends to an existing report and a run that dies without writing could otherwise be mistaken for a success.
4. Starts the engine on a worker thread with inp rpt out as arguments and waits. The window stays responsive; the toolbar shows a spinner and the panel says running…. Nothing else in the app runs in the background.
5. Reads the report. runswmm exits 0 whether the run worked or not, so the exit code is recorded for the log and ignored for the verdict. A run succeeded when the report has no ERROR line and a non-empty .out exists.
6. Reads the .out metadata (periods, step, object counts, flow units, start date) and computes the peaks for the map.
7. Copies the run into %TEMP%\AquaSWMM\runs\<n>\ for Compare Runs; the last ten are kept.

Stop (Run menu, the SWMM panel, or the Live Results window) kills the engine and keeps the partial .rpt and .out; see chapter 23.

The Run menu also holds Check Model… (the QA pass on demand — the findings grouped as Errors — the engine will refuse or misread the model and Warnings — the model runs, but check these, each clickable to select the object) and Autosave every N min (0 = off; §1.6).

9.3 The SWMM panel

Under the Project/Layers tabs:

• Engine — the registered engines, the chosen one highlighted, or No SWMM engine found. in red; Find Engines.
• Model — the path of the model to run and Choose Model (.inp)…, which runs a file without opening it in the editor (a legacy path; the editor's open model is normally what runs).
• The view buttons Map, Chart, Results, Profile, Plots, Tables and Fit Map.
• Time — the reporting-period slider with Play/Pause, Step, Show Peaks, and the current frame's date and elapsed hours. This one slider drives the Results map, the Profile's HGL and the Chart cursor.
• Run Model.
• Last run — engine version and id, elapsed seconds, every ERROR (red) and WARNING (grey) line from the report, worst continuity ±x.xxx% (section), and the failure reason if it failed; Run ALR Checks when the run succeeded.
• Results — n periods every s s, node and link counts with the flow units, the start date.
• ALR — the ALR verdict, when it has been run.
• The run log, monospace: the command line, stdout and stderr.

9.4 The Run Status window

When a run finishes, Results → Run Status… opens by itself with the whole story of the run in one window:

• Engine — EPA SWMM 5.2.4 and Binary sha256, the SHA-256 of the runswmm executable that produced this run; Elapsed; Model read — the path the engine read, with Ran a scratch copy when the model was dirty or on a non-ASCII path.
• Result — Run finished and wrote results, or Run failed: … with the first fatal line, or — in red — Results are not valid: … when a continuity error came back as nan or inf. The engine prints that when the solution has blown up, and still writes a results file full of numbers (a 1D-2D model on disk here reported outfall peaks of over a million cfs that way). The results stay open so the blow-up can be found, but the status bar, the model report, scenario runs and the calibrator all treat the run as failed.
• Continuity — every continuity section's error, coloured green below 1 %, amber from 1 to 10 %, red above 10 % (absolute). The thresholds are printed on the window. No continuity section: the run did not get that far. when the engine stopped in input.
• Highest continuity errors by node, Highest flow instability indexes, Time-step critical elements, Most frequent non-converging nodes, Routing time step summary — every entry the report carries (the engine's own text lists up to five per table; the window shows all it printed). Each entry that names a node or link is a button that selects and zooms to it.
• Node flow balance errors of 5 % or more — read from the whole Node Inflow Summary rather than the engine's top five, which can pass over a node with a large error on a small volume (a pooled 2D cell at 48 % was missing from it in one real model). Each entry gives the node's total inflow volume, and the list is ranked by the volume in error — percent times volume — so a 40 % error on a pond outranks 77 % of a trickle. The window draws the first 50; Copy summary has them all, and aquaswmm-swmm report prints the first ten.
• Warnings and Errors — every WARNING nn and ERROR nnn line, each with what the code means, the usual cause and the fix from the built-in index, and the object it names (if any) selected on click. Error codes… opens the index.
• Copy summary — a plain-text version for a note or an e-mail.

Help → SWMM Error Codes… lists the whole index — 112 codes from the EPA SWMM 5.2 User's Manual, with causes and fixes drawn from what the forum threads show people needed — with a Search box. Appendix C.

9.5 Reading the report

The report (.rpt) is the only place the engine says whether the run was any good. AquaSWMM parses:

• the banner (EPA STORM WATER MANAGEMENT MODEL - VERSION 5.2 (Build 5.2.4)) for the version;
• every ERROR nnn: line (fatal) and WARNING nn: line;
• every Continuity Error (%) line with the section it sits in (Runoff Quantity Continuity, Flow Routing Continuity, Quality Routing Continuity, Groundwater Continuity), including the non-finite spellings the C runtime uses for a blown-up run (-nan(ind), nan, -inf, and the older -1.#IND, 1.#QNAN, 1.#INF);
• every summary table, by its asterisk-boxed title, into columns with the units line kept.

worst continuity is the largest absolute value across the sections, and a non-finite value outranks every finite one. What the number means and what to do about it is §16.1.

9.6 ALR checks

Tools → ALR Checks (or Run ALR Checks) runs the ALR post-processor on a finished run. ALR is a separate Python package that reads the .out and the .inp beside it and evaluates conditions the engine's own report does not. AquaSWMM finds it through AQUASWMM_ALR_SCRIPT (the path to run_headless_swmm.py) and AQUASWMM_ALR_PYTHON (the interpreter, when it is not python), runs python run_headless_swmm.py <model.out> --json, and shows the verdict: a one-line summary and each failed check with its node and message. Without those variables the item does nothing useful. The .inp must be beside the .out, which a AquaSWMM run guarantees.

9.7 The command-line runner

The same engine registry, report parser and result reader are in aquaswmm-swmm, a command-line tool built with the app:

aquaswmm-swmm engines
aquaswmm-swmm run <model.inp> [--engine <id>] [--alr]
aquaswmm-swmm info <model.out>
aquaswmm-swmm series <model.out> (--node <name> | --link <name>) [--var <variable>]
aquaswmm-swmm report <model.rpt>
aquaswmm-swmm alr <model.out> [--nodes a,b] [--top N] [--all]
aquaswmm-swmm inp <model.inp>
aquaswmm-swmm compare <a.out> <b.out> [--inp <model.inp>] [--tol X] [--top N]
aquaswmm-swmm froude <model.out> [--inp <model.inp>] [--top N]
aquaswmm-swmm merge <model.inp> <other.inp> -o <merged.inp>

Unlike runswmm, it exits non-zero when a run fails — or finishes with a nan/inf continuity error, printed as NOT VALID: … — so it can drive a batch. report exits non-zero on the same two conditions. inp parses a model losslessly, proves the round trip, lists its sections and prints the validator's findings.

compare tabulates the peak differences between two results files — node max depth, total inflow and flooding; link max flow, velocity and fraction full — with the largest differences named. It is how a model already run in PCSWMM or the EPA GUI is checked here: run the .inp, then compare their .out with this one. Given the model (--inp, or a .inp beside the first file), a PCSWMM 1D-2D model's [TAGS] split every table into 1D nodes, 2D cells, Connect2D nodes, 1D links, 1D-2D coupling links and 2D-2D links, which is where two runs of a 2D model usually part ways. It exits non-zero when any difference exceeds --tol (default 1e-6).

froude lists the links with the highest Froude number at their peak flow, with the largest at any time beside it, and counts the links that were supercritical at peak flow. The method is the one in §10.3. The shapes come from --inp, or the .inp beside the .out.

merge is File → Merge Model… without the app (§13.6). It writes the merged model to -o and prints the account of renames, shared and kept objects, and what was left out. It exits non-zero, writing nothing, when the merge is refused.

Node variables are depth head volume lateral-inflow total-inflow flooding; link variables flow depth velocity volume capacity.

9.8 What the runner does not do

• Batch or scenario runs: one model, one engine, one run at a time (Compare Engines runs two back to back). Batch from the CLI or the Python terminal (chapter 18).
• Hotstart management: [FILES] lines are written as text in the Options dialog and the engine does the rest.
• Parallel engines: THREADS is an engine option and is passed through.