Skip to content
BuczynskiRafalPublic

About

Decision support for storm sewer design: EPA SWMM simulation, hydraulic checks and graph neural network recommendations.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

StormLab

CI License: Apache 2.0

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.

Network map coloured by the recommended action

What it does

  • Simulation. Runs EPA SWMM 5.2 on an uploaded .inp model.
  • 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.

How it works

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
Loading

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.

What the model reads for one conduit of the Rakowiec network

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.

Quick start

Requires Python 3.12.

python3.12 -m venv venv
make install
cp app/.env.example app/.env
make migrate
make run

Open 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.

Tour

  1. 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).
  2. On the Map tab, colour the network by Recommendation, Checks passed or Filling. Click a conduit, node or subcatchment for its key values.
  3. Browse the Conduits, Nodes and Subcatchments tabs, or export a table with CSV.
  4. 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.
  5. Open Method to see, on the same network, which conduits the model reads for the one you select.
  6. Back on Analysis, upload your own .inp file with Upload & Analyse (flow units: CMS). More examples are in examples/.
Filling Conduit panel
Network map coloured by filling Conduit profile, checks and recommendation

Models

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.

Documentation

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

Deployment

A production image and a Docker Compose setup are included; see docs/deployment.md.

Development

make test        # unit, contract and Django tests
make lint        # ruff
make typecheck   # pyright

Changes go through topic branches merged into develop; main holds released states.

License and citation

Apache License 2.0, see LICENSE and NOTICE. To cite the software, use CITATION.cff.

About

Decision support for storm sewer design: EPA SWMM simulation, hydraulic checks and graph neural network recommendations.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages