Decision support for storm sewer design. StormLab runs an EPA SWMM simulation of a network, checks every conduit against design criteria and uses a graph neural network to recommend an action for each conduit.
- Simulation. Runs EPA SWMM 5.2 on an uploaded
.inpmodel. - Design checks. Seven checks per conduit: filling, velocity, slope, depth and cover.
- Recommendations. A graph neural network reads each conduit together with the conduits that drain into it and scores nine actions, from No changes to Increase diameter or Retention tank.
- Catchment categories. Read from the model's tags, or assigned by a classifier.
- Results. Interactive network map, tables with CSV export and a longitudinal profile for every conduit.
flowchart LR
inp["SWMM model (.inp)"] --> sim["EPA SWMM 5.2"]
sim --> checks["7 design checks per conduit"]
sim --> cats["Catchment categories"]
sim --> feats["Conduit graph, 66 features per conduit"]
feats --> gnn["Graph model, 5 runs averaged"]
gnn --> res["9 action probabilities per conduit"]
checks --> ui["Map, tables, conduit panel"]
cats --> ui
res --> ui
Every conduit becomes a node of a directed graph; an edge joins two conduits that meet in a manhole and points with the flow. For each conduit the model reads its own 66 physical features and a weighted average over the conduits that drain into it, up to four links upstream. The simulation supplies the hydraulics; the model interprets them.
On held-out network families the graph model names the main action for 89.3% of conduits (90.7% with the five runs averaged, as served), against 87.6% for the same network without neighbours. How the model was trained, which experiments led to it and where it falls short is described in docs/method.md and, with an interactive view of the graph, on the application's Method page.
Requires Python 3.12.
python3.12 -m venv venv
make install
cp app/.env.example app/.env
make migrate
make runOpen http://127.0.0.1:8000, choose Sign up and follow the tour below.
On macOS, make install also re-signs the SWMM libraries: the published wheel carries
invalid code signatures and the system refuses to load it otherwise.
- Go to Analysis, pick a frost zone and choose Try with Demo Data. It loads the storm sewer network of the Rakowiec estate in Wrocław (62 conduits).
- On the Map tab, colour the network by Recommendation, Checks passed or Filling. Click a conduit, node or subcatchment for its key values.
- Browse the Conduits, Nodes and Subcatchments tabs, or export a table with CSV.
- Click a conduit's name in the table, or Open details on the map, to see its profile, the seven design checks and the recommended action with the model score of every class.
- Open Method to see, on the same network, which conduits the model reads for the one you select.
- Back on Analysis, upload your own
.inpfile with Upload & Analyse (flow units: CMS). More examples are inexamples/.
| Filling | Conduit panel |
|---|---|
![]() |
![]() |
The repository ships the trained models the application uses: the recommendation network (five training runs, averaged) and the catchment classifier. Training code is not part of this repository.
| Document | Content |
|---|---|
| docs/method.md | The method: conduit graph, features, model, data, training, experiments, results and limits |
| docs/architecture.md | The code: components, path of one analysis, recommendation path, data model, tests |
| docs/deployment.md | Production setup with Docker Compose |
| examples/README.md | Example networks |
A production image and a Docker Compose setup are included; see docs/deployment.md.
make test # unit, contract and Django tests
make lint # ruff
make typecheck # pyrightChanges go through topic branches merged into develop; main holds released states.
Apache License 2.0, see LICENSE and NOTICE. To cite the software, use CITATION.cff.



