swmm-calibration

SWMM Calibration / Validation

Part of Agentic SWMM — 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.