SWMM5 Model Manager — How It Works (Detailed Guide) for Arc Gis Pro
SWMM5 Model Manager — How It Works (Detailed Guide)
A complete, plain-English guide to the SWMM5 Model Manager ArcGIS Pro Python Toolbox: what each piece does, how data flows through it, and the exact click-by-click workflow to catalog, search, map, run, and visualize thousands of EPA SWMM5 models — without leaving ArcGIS Pro.
This is the companion to README.md. The README is the quick reference; this
guide explains the mechanics and walks the full workflow end to end.
Table of contents
- The idea in one paragraph
- Architecture & data flow
- The files and what each does
- Installation (one time)
- The SWMM engine for running models
- The six tools — full reference
- End-to-end worked example
- Showing a different model from the catalog
- Coordinates, CRS, and "Zoom To Layer"
- Symbolizing results (the thematic map)
- Database schema reference
- Cross-model SQL queries
- Command-line use (no ArcGIS Pro)
- Troubleshooting
- Path reference for this machine
1. The idea in one paragraph
You have a large library of SWMM5 .inp models (the 1729-SWMM5-Models-2030
repo — 3,798 models in practice). The toolbox parses every one of them into
a single SQLite database so you can find models by their properties,
draw any model on the ArcGIS Pro map as real feature classes, run it through
the EPA SWMM engine, and paint the simulation results (peak depth, flow,
runoff…) back onto the map. It is a Python Toolbox (.pyt), so it runs inside
ArcGIS Pro's own Python with no compiling and is maintainable in plain Python.
2. Architecture & data flow
┌──────────────────────────────────────────────┐
.inp files │ swmm5_inp.py (parser) │
(your repo) ───▶│ reads every section of every .inp │
│ → catalog row + typed object tables + raw │
└───────────────────┬──────────────────────────┘
▼
┌───────────────────────────────┐
│ catalog.db (SQLite) │
│ • models (1 row/model) │
│ • junctions, conduits, … │
│ • coordinates, vertices, … │
│ • inp_sections_raw (lossless) │
│ • results_summary (peaks) │ ◀── Tool 6
└───────┬───────────────┬────────┘
│ │
Tool 2: Search ◀──┘ └──▶ Tool 3: Import to Map
(query the catalog) (geometry → feature classes)
│
.inp ──▶ Tool 4: Run Model ──▶ <name>.rpt + <name>.out ▼
(runswmm.exe / pyswmm) │ <model>_nodes (points)
│ <model>_links (lines)
▼ <model>_subcatchments (polys)
Tool 5: Join Results ────────────────┘
(read .out via swmm5_results.py,
write max_depth / max_flow / … fields,
optional time-series table)
│
▼
Symbolize by the result field
→ flood / surcharge / runoff map
Two design choices make this robust:
- The catalog has two layers of detail. A catalog (one row per model in
the
modelstable) for fast searching, and a full network parse (typed tables per object type, plus a losslessinp_sections_rawtable that keeps every data line of every section). Nothing from the original.inpis thrown away. - Reading results needs no third-party libraries.
swmm5_results.pyis a pure-Python reader of the binary.outfile, validated to matchpyswmmexactly. Only running a model needs an engine; viewing results does not.
3. The files and what each does
| File | Role |
|---|---|
SWMM5ModelManager.pyt |
The ArcGIS Pro Python Toolbox — the six tools you see in the Catalog pane. |
swmm5_inp.py |
Parses .inp files and builds the SQLite catalog. Pure standard library. Also runs from a command line. |
swmm5_results.py |
Dependency-free reader of the SWMM5 binary .out results file. Used by Tools 5 & 6. |
swmm5_rpt.py |
Dependency-free parser of the SWMM5 text .rpt report (peak summaries + continuity). Used by Tool 6. |
swmm5_results_db.py |
Ingests results (.out/.rpt) across the whole library into the catalog for cross-model ranking. Used by Tool 6. |
swmm5_out.py |
Backwards-compatible shim — re-exports swmm5_results.py. |
examples/ |
Three tiny sample models (Hydrology/Bob_Continuous.inp is rain-driven and runs end to end). |
README.md / this guide |
Documentation. |
Rule: the four
.pymodules must sit next to the.pyt. The toolbox adds its own folder tosys.pathand imports them by name.
4. Installation (one time)
- Put
SWMM5ModelManager.pytand the fourswmm5_*.pymodules in one folder (here:C:\Users\rober\OneDrive\Documents\SWMM5_Model_Manager\). - In ArcGIS Pro, open or create a project.
- Catalog pane → Toolboxes → right-click → Add Toolbox → browse to
SWMM5ModelManager.pyt→ OK. (Pro asks once to trust the Python toolbox — click Yes, it's your code.) - Expand Toolboxes → SWMM5ModelManager.pyt and you'll see the six tools.
Tip — make it stick: after adding the toolbox, save the project (Ctrl+S). The toolbox connection lives in the
.aprx; if you don't save, you re-add it next time.
The Catalog pane lives on the right side of the Pro window (tabs along the bottom-right: Catalog / Geoprocessing / Symbology). If it's hidden: ribbon View → Catalog Pane.
5. The SWMM engine for running models
Tool 4 (Run Model) is the only part that needs a compute engine. You have two options:
Option A — point at runswmm.exe (simplest; what we used).
EPA SWMM ships a command-line engine. On this machine it is at:
C:\Program Files\EPA SWMM 5.2.4 (64-bit)\runswmm.exe
Note the folder name carries the patch version (
5.2.4), which is why a guess atC:\Program Files\EPA SWMM 5.2\fails — browse to the real one.
Option B — pyswmm in a cloned Pro Python environment.
Pro's base arcgispro-py3 env is read-only, so clone it first:
"%PROGRAMFILES%\ArcGIS\Pro\bin\Python\Scripts\conda" create --clone arcgispro-py3 --name swmm
"%PROGRAMFILES%\ArcGIS\Pro\bin\Python\Scripts\proswap" swmm
"%PROGRAMFILES%\ArcGIS\Pro\bin\Python\envs\swmm\python" -m pip install pyswmm
If you leave Tool 4's engine parameter blank it tries pyswmm; otherwise it
shells out to the .exe you give it. Reading results (Tool 5) needs
neither.
6. The six tools — full reference
Tool 1 — Build / Refresh Model Database
Purpose: parse every .inp under a root folder into one SQLite catalog.
| Parameter | Meaning |
|---|---|
Root folder containing .inp models |
Top of your repo. The top-level subfolder name becomes each model's category (e.g. Hydrology/… → category Hydrology). |
Output SQLite database (.db) |
Where to write the catalog. |
| Rebuild from scratch | Checked = delete and rebuild; unchecked = append. |
Behavior: recursive; defensive — a malformed file is still cataloged
with the reason recorded in models.parse_errors, and the build keeps going.
On the real repo this produced 3,798 models, 0 errors, ~2.5 minutes (writing
to a OneDrive-synced folder; a plain local path is faster).
Tool 2 — Search Models
Purpose: find models by their catalog properties.
| Parameter | Meaning |
|---|---|
| Model database | The .db from Tool 1. |
| Category / Flow units / Flow routing | Drop-downs that auto-populate from the database (e.g. routing shows DIFWAVE, DYNWAVE, KINWAVE, STEADY, STEADYFLOW). |
| Name contains | Substring match on the model name. |
| Minimum node count | Only models with ≥ N nodes. |
| Only models that have coordinates | Restrict to models that will actually draw on a map. |
| Output CSV | Optional — save the result list. |
Results print to the tool Messages. Example run: DYNWAVE + has-coordinates returned 3,572 matches in 0.62 s from the 3,798-model catalog.
Tool 3 — Import Model To Map
Purpose: turn one model's parsed geometry into ArcGIS feature classes.
| Parameter | Meaning |
|---|---|
| Model database | The .db. |
| Model (relative path) | Drop-down of model relpaths from the .db (type to filter). |
| Output geodatabase | Usually the project gdb (…\SWMM5_Models.gdb). |
| Coordinate system | Optional — SWMM stores none (see §9). |
| Create subcatchment polygons | On by default. |
Produces three layers, added to the map:
<model>_nodes— points (junctions, outfalls, storage, dividers; fieldswmm_type)<model>_links— polylines (conduits, pumps, orifices, weirs, outlets; built from end-node coords + any vertices)<model>_subcatchments— polygons (from[POLYGONS])
Models with no [COORDINATES] are skipped here (with a warning) but stay fully
queryable in the database.
Tool 4 — Run Model (SWMM5 engine)
Purpose: run an .inp and produce .rpt + .out.
| Parameter | Meaning |
|---|---|
SWMM5 input file (.inp) |
The model to run. |
| Output folder | Default = same folder as the .inp. |
| SWMM engine executable | runswmm.exe path, or blank to use pyswmm. |
Ensure [REPORT] ALL |
On by default. |
Key detail: if the model has no [REPORT] section, the tool injects
[REPORT] NODES ALL / LINKS ALL / SUBCATCHMENTS ALL into a run copy first —
otherwise the .out would contain no elements and nothing could be mapped.
Continuity errors from the report are echoed to the Messages. Example:
Bob_Continuous.inp ran via runswmm.exe in 1 second → .rpt + .out.
Tool 5 — Join Results To Map
Purpose: read a .out and paint results onto the imported layers.
| Parameter | Meaning |
|---|---|
Results file (.out) |
From Tool 4 (or a committed .out). |
| Node / Link / Subcatchment feature class | The layers from Tool 3 (any subset). |
| Node / Link / Subcatchment variable | Which quantity to summarize. |
| Summary statistic | max / mean / min / last. |
| Also build a time-series table | Optional — for the Pro time slider. |
Writes a DOUBLE field named <stat>_<variable> on each feature class — e.g.
max_depth on nodes, max_flow on links, max_runoff on subcatchments — then
you symbolize by it. With the time-series option it builds a long table
(element, category, variable, dtime, value) you relate on element and enable
time on to animate the simulation.
Variable menus:
- Nodes:
depth, head, total_inflow, lateral_inflow, flooding, volume - Links:
flow, depth, velocity, capacity, volume - Subcatchments:
runoff, rainfall, infil_loss, evap_loss
Tool 6 — Ingest Results Into Database
Purpose: load peak results for the whole library at once so you can rank
across models. For each model it finds a sibling .out (preferred, exact) or
.rpt (text summary) and writes a tidy results_summary table plus a
model_results table (continuity per model). No per-model run needed when the
results files already exist beside the .inps.
7. End-to-end worked example
This is the exact sequence proven in the session, with real numbers.
- Build the catalog. Tool 1, root = the repo, output =
catalog.db, Rebuild ✓ → 3,798 models, 0 errors. - Search. Tool 2 on
catalog.db, Flow routing =DYNWAVE, Only models that have coordinates ✓ → 3,572 matches in 0.62 s. - Run a model. Tool 4, input
examples\Hydrology\Bob_Continuous.inp, engineC:\Program Files\EPA SWMM 5.2.4 (64-bit)\runswmm.exe→ producedBob_Continuous.rptandBob_Continuous.outin 1 s. - Import to map. Tool 3 with
examples.db, modelHydrology/Bob_Continuous.inp, output = the project gdb → three layers (Bob_Continuous_nodes/_links/_subcatchments). - Join results. Tool 5 with
Bob_Continuous.outand the three layers, stat =max→ wrotemax_depth,max_flow,max_runoff. - Render. Right-click
Bob_Continuous_subcatchments→ Symbology → Graduated Colors → fieldmax_runoff→ the three subcatchments shade S2 red (0.97), S1 orange (0.63), S3 yellow (0.44) — matching the engine output, with conduitC1and nodesJ1/OF1overlaid.
8. Showing a different model from the catalog
The map accumulates a layer set per imported model; you change what's shown by importing another model and toggling visibility. To display any of the 3,798 repo models:
- Catalog → Toolboxes → SWMM5ModelManager.pyt → double-click 3. Import Model To Map.
- Model database (
.db):C:\Users\rober\OneDrive\Documents\SWMM5_Model_Manager\catalog.db - Model (relative path): open the drop-down, type to filter (3,798
entries), pick one.
- To be sure it draws, run Tool 2 (Search) on the same
.dbfirst with Only models that have coordinates ✓ (and maybe Minimum node count ~50 for a real network), note a relpath from the Messages, then choose it here.
- To be sure it draws, run Tool 2 (Search) on the same
- Output geodatabase:
C:\Users\rober\OneDrive\Documents\ArcGIS\Projects\SWMM5_Models\SWMM5_Models.gdb - Run.
- In the Contents pane (left), uncheck the previous model's layers
(e.g.
Bob_Continuous_*) to hide them, or right-click → Remove (drops the layer from the map; the data stays in the gdb). Then right-click the new<model>_subcatchments(or_nodes) layer → Zoom To Layer. - (Optional results) Run the new model (Tool 4) → Join Results (Tool 5) → symbolize.
There is no single "current model" selector — each model is its own set of feature classes, and you control display with the checkboxes in the Contents pane.
9. Coordinates, CRS, and "Zoom To Layer"
SWMM stores raw X/Y with no coordinate system. So:
- The database/search covers 100% of models regardless of coordinates.
- A map only works for models that have a
[COORDINATES]section, and the features sit in schematic space (the model's own X/Y units), not on the basemap, unless you assign a real projection. - After importing, the layers won't appear over the world basemap — they're at schematic coordinates near the map origin. Right-click the layer → Zoom To Layer to jump to them.
- The catalog's
has_coordinatesflag andx_min/x_max/y_min/y_maxbounding box tell you up front which models will draw.
If you know a model's true projection, set the Coordinate system parameter in Tool 3; otherwise leave it blank and use Zoom To Layer.
10. Symbolizing results (the thematic map)
After Tool 5 has written the result fields:
- Right-click the layer (e.g.
<model>_subcatchments) → Symbology. - Primary symbology → Graduated Colors.
- Field → the result field (
max_runoff,max_depth,max_flow, …). - Pick a color scheme (yellow→red reads naturally as low→high).
Typical thematic maps:
- Nodes by
max_depth→ flood / surcharge depth. - Links by
max_flowormax_capacity→ conveyance / surcharge. - Subcatchments by
max_runoff→ runoff intensity.
For animation, re-run Tool 5 with "Also build a time-series table", relate
the <name>_results_ts table to the layer on element, enable Time on the
table, and scrub the Time slider.
11. Database schema reference
models — catalog, one row per file:
id, name, filename, relpath, category, subcategory, file_size, file_mtime, title, flow_units, infiltration, flow_routing, link_offsets, start_date, end_date, report_step, routing_step, n_raingages, n_subcatchments, n_junctions, n_outfalls, n_storage, n_dividers, n_nodes, n_conduits, n_pumps, n_orifices, n_weirs, n_outlets, n_links, n_pollutants, n_lid_usage, n_controls, has_coordinates, x_min, y_min, x_max, y_max, parse_errors
options — model_id, key, value (every [OPTIONS] line).
Typed object tables (each with a model_id foreign key):
raingages, subcatchments, subareas, infiltration, junctions, outfalls, dividers, storage, conduits, pumps, orifices, weirs, outlets, xsections, coordinates, vertices, polygons.
inp_sections_raw — model_id, section, row_index, content: the complete,
lossless record of every data line of every section.
Results tables (after Tool 6):
results_summary(model_id, category, element, variable, value, time_of_max, source)model_results(model_id, source, runoff_continuity, routing_continuity, n_elements, status, ingested_at)
12. Cross-model SQL queries
Open the .db in any SQLite tool (or Python) and ask questions across the whole
library:
-- Every dynamic-wave model with more than 100 nodes
SELECT name, category, n_nodes, n_links
FROM models
WHERE flow_routing = 'DYNWAVE' AND n_nodes > 100
ORDER BY n_nodes DESC;
-- Inventory by category and routing method
SELECT category, flow_routing, COUNT(*) AS models
FROM models GROUP BY category, flow_routing;
-- Distribution of circular pipe diameters across the entire library
SELECT geom1 AS diameter, COUNT(*) AS n
FROM xsections WHERE shape = 'CIRCULAR'
GROUP BY geom1 ORDER BY n DESC;
-- After Tool 6: the 50 nodes with the most flooding anywhere
SELECT m.name, r.element, r.value AS flood_volume
FROM results_summary r JOIN models m ON m.id = r.model_id
WHERE r.category='node' AND r.variable='max_flooding'
ORDER BY r.value DESC LIMIT 50;
13. Command-line use (no ArcGIS Pro)
swmm5_inp.py builds the catalog by itself — handy for scheduled refreshes:
python swmm5_inp.py "C:\Users\rober\GitHub\1729-SWMM5-Models-2030" catalog.db --rebuild
swmm5_results_db.py ingests results across the library:
python swmm5_results_db.py catalog.db "C:\Users\rober\GitHub\1729-SWMM5-Models-2030" --prefer auto
Reading one .out in Python:
from swmm5_results import SwmmOut
o = SwmmOut("Bob_Continuous.out")
print(o.flow_units, o.n_periods, o.nodes)
print(o.summary("node", "depth", "max")) # {node: peak depth, ...}
14. Troubleshooting
"This project is read-only" (yellow banner / [Read-Only] in the title).
A leftover file lock — usually a second Pro instance still has the project open.
Fix: close every ArcGIS Pro window (check Task Manager for ArcGISPro.exe),
wait ~10 s, reopen the project. If it persists it's OneDrive holding the
.aprx: right-click the project folder → OneDrive → Always keep on this
device, or Project → Save As to a local folder like C:\ArcGIS\SWMM5_Models
(also makes SQLite writes faster).
Imported a model but nothing shows on the map. Expected — schematic coordinates. Right-click the layer → Zoom To Layer (see §9).
Import says it skipped a model / created nothing. That model has no
[COORDINATES]. Use Search with Only models that have coordinates ✓ to
pick one that draws.
Run Model produced an empty .out / Join finds no elements. The model had a
[REPORT] section that didn't request elements. Tool 4 injects [REPORT] … ALL
only when there is no [REPORT] at all; if one exists it's respected. Add
NODES ALL / LINKS ALL / SUBCATCHMENTS ALL to that model, or run a copy without
a [REPORT] section.
runswmm.exe path is invalid. The EPA SWMM folder is version-specific
(EPA SWMM 5.2.4 (64-bit)), so browse to it rather than typing a guessed
path.
Toolbox missing after reopening the project. It wasn't saved into the
.aprx. Re-add it (Catalog → Toolboxes → Add Toolbox) and Ctrl+S.
Full-library build is slow. Writing the SQLite file into a OneDrive-synced
folder is the bottleneck. Point Tool 1's output at a plain local folder
(e.g. C:\SWMM\catalog.db).
15. Path reference for this machine
| Thing | Path |
|---|---|
| Toolbox + modules | C:\Users\rober\OneDrive\Documents\SWMM5_Model_Manager\ |
| Full repo catalog (3,798 models) | C:\Users\rober\OneDrive\Documents\SWMM5_Model_Manager\catalog.db |
| Examples catalog (3 models) | C:\Users\rober\OneDrive\Documents\SWMM5_Model_Manager\examples.db |
| Model repo | C:\Users\rober\GitHub\1729-SWMM5-Models-2030 |
| ArcGIS project + gdb | C:\Users\rober\OneDrive\Documents\ArcGIS\Projects\SWMM5_Models\SWMM5_Models.gdb |
| SWMM engine | C:\Program Files\EPA SWMM 5.2.4 (64-bit)\runswmm.exe |
Validation note: the .out reader (swmm5_results.py) was checked against
pyswmm's Output API — node depth, link flow, subcatchment runoff, and every
reporting datetime match. The full pipeline (build → search → run → import →
join → symbolize) was exercised end to end in ArcGIS Pro on the real
3,798-model library.
