/swmm-calibration

name: swmm-calibration
description: Calibration and validation scaffold for EPA SWMM. Use when an agent needs to (1) compare simulated vs observed flow, (2) evaluate candidate parameter sets, (3) rank explicit candidates by an objective, (4) run a bounded random / LHS / adaptive search for the best-fitting parameters, (5) run a publication-grade SCE-UA calibration with KGE as the primary objective and (r, alpha, beta) decomposition reported, or (6) run a DREAM-ZS Bayesian calibration producing a posterior over parameters with Gelman-Rubin convergence checks. Dedicated sensitivity-analysis methods (OAT, Morris, Sobol') now live on the `swmm-uncertainty` skill.

SWMM Calibration / Validation

Part of [Agentic SWMM](https://github.com/Zhonghao1995/agentic-swmm-workflow) — install the project first for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).

CLI verb: aiswmm calibrate (real engine)

Since ADR-0005 the top-level verb drives this skill's SCE-UA engine directly:

aiswmm calibrate --inp model.inp --observed-csv observed.csv \
  --patch-map examples/calibration/patch_map.json \
  --run-id calib_001 --total-iters 200 \
  --param pct_imperv_s1=20,70 --run-dir runs/agent/calib_001 --progress

Contract highlights:

• **Units**: observed values MUST be in the same units as the SWMM output

attribute selected by `--node`/`--attr`. There is no conversion layer; a greater-than-100x median magnitude mismatch between the best trial and the observed series triggers a loud `UNITS MISMATCH` warning (stderr + summary) to catch L/s vs m3/s style errors.

• **Parameters**: `--param name=low,high` supplies search bounds only; every

name must exist in the `--patch-map` file (the sole parameter-definition contract). Unknown names fail fast and list what IS available.

• **Experiment layout**: `progress.json` (live checkpoint), `convergence.csv`,

`calibration_summary.json` (`engine: sceua-spotpy`, `is_stub: false`), `best_params.json`, `09_audit/` candidate artifacts, `trials/sceua_NNNN/` working evaluations. Trials are engine working area; only the candidate in `09_audit/` is audit-grade and feeds `aiswmm calibration accept`.

• The historical synthetic walker remains available behind

`--engine synthetic` (still stamped `is_stub: true`) for dry runs.

• `--algorithm dream-zs` is not wired into the verb yet: use the

`calibrate_dream_zs` agent tool or this skill's script directly.

What this skill provides

• A practical calibration scaffold around the existing SWMM runner workflow.
• A strict calibration boundary: calibration and validation require observed data. Without observed flow, depth, soil-moisture, or volume data, use `swmm-uncertainty` for prior uncertainty propagation instead of calling the run calibrated.
• Observed-flow ingestion from delimited text files (`.csv`, `.tsv`, `.dat`, whitespace-separated text).
• Metric calculation for simulated vs observed hydrographs:
• **KGE** (Kling-Gupta Efficiency) + (r, alpha, beta) decomposition — primary metric for publication-grade calibration.
• NSE
• RMSE
• Bias / PBIAS%
• Peak flow error
• Peak timing error
• Simple INP text patching using an explicit mapping from parameter names to line selectors.
• Batch evaluation of candidate parameter sets for:
• `sensitivity`
• `calibrate`
• `validate`
• Bounded internal search for calibration candidate generation:
• `search --strategy random` — uniform random sampling (fast prototyping).
• `search --strategy lhs` — Latin Hypercube Sampling (fast prototyping).
• `search --strategy adaptive` — multi-round LHS refinement around elite trials (fast prototyping).
• `search --strategy sceua` — Shuffled Complex Evolution (SCE-UA); recommended for publication-grade point-estimate calibration. Minimises `(1 - KGE)` via `spotpy.algorithms.sceua` and emits a `calibration_summary.json` with KGE decomposition + secondary metrics.
• `search --strategy dream-zs` — DREAM-ZS Bayesian calibration with a KGE-based likelihood `exp(-0.5 * (1 - KGE) / sigma^2)`. Produces a posterior over parameters via `spotpy.algorithms.dream`, writes 5 audit artefacts (`posterior_samples.csv`, `best_params.json`, `chain_convergence.json`, `posterior_<param>.png`, `posterior_correlation.png`) plus a Slice 1 -compatible `calibration_summary.json` with a `posterior_summary` block (Gelman-Rubin Rhat per parameter + per-parameter quantiles).
• Dedicated sensitivity-analysis methods (OAT, Morris elementary-effects, Sobol' indices) have moved to the **swmm-uncertainty** skill — see `skills/swmm-uncertainty/scripts/sensitivity.py` and the `swmm_sensitivity_oat` / `swmm_sensitivity_morris` / `swmm_sensitivity_sobol` MCP tools.
• MCP wrapper so the agent runtime can call the workflow as tools.

Strategy guidance

| Strategy | When to use | Cost | Reports | |--------------|----------------------------------------------------------------------------|------------|---------| | `random` | First-pass prototyping, smoke-testing the patch map | Very low | Ranking table | | `lhs` | Quick coverage of a small search space | Very low | Ranking table | | `adaptive` | LHS with multi-round refinement around elite trials | Low | Ranking table per round | | **`sceua`** | **Publication-grade point-estimate calibration on a fixed search space** | **Medium** | **`calibration_summary.json` with KGE primary + decomposition + secondary metrics + `convergence.csv`** | | **`dream-zs`** | **Bayesian posterior calibration with Gelman-Rubin convergence checks** | **High** | **`calibration_summary.json` + `posterior_samples.csv` + `chain_convergence.json` + per-parameter marginal PNGs + correlation PNG** |

MCP tools

`mcp/swmm-calibration/server.js` exposes six tools, all thin wrappers around `scripts/swmm_calib