/swmm-uncertainty

name: swmm-uncertainty
description: Parameter and forcing uncertainty for EPA SWMM. Without observed flow, call propagate_parameter_ranges (global ranges, one SWMM run per sample, peak spread); the Morris/OAT/Sobol tools need an observed series. Use when an agent needs to (1) propagate parameter uncertainty through SWMM (fuzzy alpha-cut or Monte Carlo), (2) quantify hydrograph envelopes or output entropy without treating the run as calibration, (3) screen which parameters matter using OAT / Morris elementary-effects / Sobol' indices, (4) generate a rainfall ensemble (observed-series perturbation or IDF-curve design storms) and aggregate the resulting hydrograph envelope, or (5) build the integrated paper-reviewer-facing uncertainty source decomposition (`uncertainty_source_summary.md` + `uncertainty_source_decomposition.json`) over the raw outputs of the prior steps.

SWMM Uncertainty

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

Agent path without observed data

The honest split (live findings F-107 and F-109, 2026-09-03): WITH observed flow, `swmm_sensitivity_oat` / `swmm_sensitivity_morris` / `swmm_sensitivity_sobol` rank parameters against the data (they need an observed series and a patch map). WITHOUT observed flow, `propagate_parameter_ranges` is the tool for both questions: `mode=one_at_a_time` varies each parameter alone in one call and returns a per-parameter spread and a ranking ("which parameters matter most"); the default `joint` mode samples all ranges together and reports the spread ("how uncertain is the peak"). Never emulate a ranking with one sweep per parameter. Rainfall: a request to scale the observed event by factors (0.8, 1.0, 1.2) on a model with inline rain is `run_climate_scenarios` with those factors (live finding F-112, 2026-09-03); `swmm_rainfall_ensemble` needs a prepared rainfall series file and a JSON config (perturbation or IDF).

`propagate_parameter_ranges` is the typed tool for "how uncertain is the peak if Manning's n and imperviousness vary". It applies each named parameter globally (the same value on every subcatchment or conduit), runs SWMM once per sample through the audited runner, and writes `09_audit/parameter_sweep.json` and `.md` with the baseline peak, the min/median/max over the samples, the spread as a percent of the baseline and the dominant parameter. Ranges are a mapping such as `{"n_imperv": [0.010, 0.020], "pct_imperv": [60, 80]}`; aliases `manning_n`, `imperviousness`, `conduit_roughness`, `n_perv`, `s_imperv`, `s_perv`, `width`, `slope`. It is prior sensitivity, not calibrated uncertainty; the per-object fuzzy and Monte Carlo workflows below remain the research path.

What this skill provides

• User-defined fuzzy membership functions for SWMM parameters.
• Baseline-aware triangular fuzzy numbers, where the current model value is the default triangle peak.
• Alpha-cut transformation from fuzzy membership functions to parameter intervals.
• LHS, random, or boundary sampling inside each alpha-cut interval.
• Monte Carlo parameter sampling for prior or calibration-informed probability distributions.
• Normal/lognormal/truncated-normal/uniform sampling with simple physical constraints such as bound parameters and greater-than rules.
• Batch propagation through SWMM by reusing the existing calibration patch-map convention.
• Normalized Shannon entropy metrics for output ensembles, such as hydrograph entropy over time.
• Machine-readable uncertainty summaries for output envelopes, entropy records, and failed/invalid samples.
• Sensitivity-analysis screening with three sub-methods (OAT / Morris / Sobol') sharing one entry point (`scripts/sensitivity.py`).
• Rainfall-forcing ensembles: time-series perturbation of an observed rainfall record (gaussian, multiplicative, AR(1), intensity_scaling) or IDF-curve sampling of design storms (Chicago / Huff / SCS Type II), with optional per-realisation SWMM runs and ensemble envelope aggregation.

This skill is intentionally separate from `swmm-calibration`.

• `swmm-calibration` asks: which parameter set best matches observations?
• `swmm-uncertainty` asks: how much output uncertainty is induced by user-defined parameter uncertainty, and which parameters drive that uncertainty?

Calibration requires observed data and performance metrics such as NSE, RMSE, or KGE. This skill can run without observed data when the task is prior uncertainty propagation. The sensitivity-analysis path *does* read an observed series (it scores trials by RMSE against observed flow), but it answers a different question from calibration: "which parameter spread matters?" rather than "which single set is best?". When calibration outputs exist, they can be used to narrow Monte Carlo ranges or define posterior-like parameter sets.

Scripts

• `scripts/fuzzy_membership.py`
• parses and validates crisp, interval, triangular, and trapezoidal fuzzy parameter specs
• resolves `baseline: "from_model"` from the base INP through the patch map
• computes alpha-cut intervals
• `scripts/sampling.py`
• generates parameter sets from alpha-cut intervals
• supports `lhs`, `random`, and `boundary`
• `scripts/probabilistic_sampling.py`
• generates Monte Carlo parameter sets from probability distributions
• supports `uniform`, `normal`, `truncnorm`, and `lognormal`
• supports simple constraints such as `bind`, `greater_than`, and `less_than`
• `scripts/parameter_recommender.py`
• inspects an INP and recommends prior Monte Carlo parameters that are actually present in the model
• reports the evidence boundary so prior ranges are not mistaken for calibrated posterior ranges
• `scripts/monte_carlo_propagate.py`
• extracts node-flow ensembles from Monte Carlo trial `.out` files
• calls `entropy_metrics.py` to produce node entropy JSON records
• plots normalized output entropy c