Pick the path that fits — the hosted beta in your browser, the prebuilt Docker image, or a full development setup from source. The current release is v0.5.0.
Nothing to install. Open swmm.h2ox.me, draw a small area, pick dates, and click Build SWMM model.
The demo runs on a small server (~2 GB RAM), so it works best for small areas; large regions can run out of memory and fail. For large-scale modeling, self-host the frontend and backend on a bigger machine or an HPC cluster — both run well as shipped.
Every command below has a copy button.
The quickest local path — the API comes up on port 8000 (all tags on Docker Hub).
docker run --rm -p 8000:8000 zhonghao0901/swmmcanada:latest # API on http://localhost:8000 · health: /api/v1/healthz
The same image is mirrored to GitHub Container Registry as ghcr.io/zhonghao1995/swmmcanada:latest, which is what the deployment guide uses.
The backend needs Python 3.11; the frontend is React + Vite.
# backend (Python 3.11) cd backend && python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]" .venv/bin/uvicorn swmmcanada.api.main:app --port 8000 # frontend (another terminal) cd frontend && npm install && npm run dev
Verify the install offline — no live data, no external APIs, a good first check right after cloning. It builds a tiny runnable model.inp:
backend/.venv/bin/python backend/scripts/smoke_build.py
Skip the map entirely and drive the pipeline from Python. build_from_aoi picks the build mode for you; build_city targets one of the 35 real-network cities directly:
from datetime import date
from swmmcanada.geo import aoi_from_geojson
from swmmcanada.pipeline import build_from_aoi
aoi = aoi_from_geojson({"type": "Polygon", "coordinates": [...]})
build_from_aoi(aoi, date(2022, 6, 1), date(2022, 6, 7), "out/")Running the whole thing in production — the backend as a container (GHCR image) and the frontend as a static site (GitHub Pages), and how the two are wired — is documented step by step in DEPLOY.md.
A build gives you a complete, runnable first-pass model — not a calibrated one. Rainfall losses, roughness and curve numbers are first-pass estimates from open data, and every city's vertical data completeness is published as a tier so you know what you are holding.
Calibrate against observations before using any results for design or decisions. An uncalibrated model reproduced all 12 events of a summer on the correct days at a real gauge, with a −22.3% volume bias — good enough to reason with, not good enough to design with. See the validation →