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.

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 models table) for fast searching, and a full network parse (typed tables per object type, plus a lossless inp_sections_raw table that keeps every data line of every section). Nothing from the original .inp is thrown away.
Reading results needs no third-party libraries. swmm5_results.py is a pure-Python reader of the binary .out file, validated to match pyswmm exactly. 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 .py modules must sit next to the .pyt. The toolbox adds its own folder to sys.path and imports them by name.

4. Installation (one time)

Put SWMM5ModelManager.pyt and the four swmm5_*.py modules 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 at C:\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; field swmm_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, engine C:\Program Files\EPA SWMM 5.2.4 (64-bit)\runswmm.exe → produced Bob_Continuous.rpt and Bob_Continuous.out in 1 s.
Import to map. Tool 3 with examples.db, model Hydrology/Bob_Continuous.inp, output = the project gdb → three layers (Bob_Continuous_nodes/_links/_subcatchments).
Join results. Tool 5 with Bob_Continuous.out and the three layers, stat = max → wrote max_depth, max_flow, max_runoff.
Render. Right-click Bob_Continuous_subcatchments → Symbology → Graduated Colors → field max_runoff → the three subcatchments shade S2 red (0.97), S1 orange (0.63), S3 yellow (0.44) — matching the engine output, with conduit C1 and nodes J1/OF1 overlaid.

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 .db first 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.
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_coordinates flag and x_min/x_max/y_min/y_max bounding 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_flow or max_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.