swmmgi: a reproducible tool and diagnostic protocol for watershed-scale SWMM green-infrastructure modelling

Abstract

Open-source, unit-tested Python tool for building watershed-scale EPA SWMM 5.2 green-infrastructure (GI/LID) models from public and incomplete municipal data, with a Gaussian-process-emulator global (Sobol') sensitivity analysis and a transferable forcing/parameter calibration-diagnostic protocol. Companion code for the manuscript prepared for Environmental Modelling & Software. Contributions: Config-driven pipeline handling incomplete municipal storm-sewer data (orphan-outfall reconnection, DEM-Strahler channel augmentation) and SWMM's easily-missed multi-LID stacking constraint. A forcing/parameter calibration-diagnostic protocol (forcing-swap + GP-Sobol' + roughness sweep) localizing model error to forcing, losses, or conveyance, validated on a synthetic twin with known truth (5/5 correct, including the no-error control) and with quantified detection floors. An explicit mass-conservation precondition check. A node-flooding sink, which arises from SWMM's default configuration, can mask a real loss error: holding one loss error fixed while enlarging the sink, a genuine 27% volume error reports as +0.3% at a 21% sink so the protocol returns 'none, within tolerance', and beyond about 60% the sign inverts. Routing continuity error stays at 0.00% throughout and never registers it. Reproducible via tools/twin_masking.py. GP-emulator global sensitivity analysis: channel Manning's n dominates outlet peak Q (total-order index 0.94-0.98 among four sampled parameters). A controlled twin experiment varying only the channel size shows the ranking order is invariant from a free-draining network to 88% flooding loss, while the shares are not: surcharge drives the loss parameter's total-order index from 0.17 to 0.00. A paired 100-member ensemble on the repaired configuration then tests the same question on the real basin. Removing the mass sink leaves the outlet ranking almost unchanged (total-order index for channel n 0.978 to 0.968), so roughness leads there because the reach routes the flood wave rather than because surcharge suppressed the alternatives; at the headwater the loss parameter's share does rise, 0.652 to 0.872. Controlled two-basin build-and-diagnose demonstration (Leon Creek + Lower Medina, San Antonio, TX) plus third-basin generalization: the FOSS (WhiteboxTools/pysheds) pipeline reproduces the reference arcpy channel network within ~1% on length and drainage density (89% spatial overlap) and builds an independent third basin (Headwaters Salado Creek) with no code changes, delineating 98.5% of its mapped area. GI scenario performance and its cross-basin transferability are quantified in a separate companion paper. The demonstration model is reported candidly as uncalibrated for absolute prediction. Acting on the protocol's own verdict shows the raw diagnostics understated the error, because the flooding sink was removing most of the excess runoff; the true event-volume deficit is roughly sixfold. Four candidate mechanisms are then excluded by measurement (gauge-to-node drainage area, unrepresented detention, channel transmission loss, closed-depression storage removed by DEM filling). A fifth, Edwards Aquifer recharge-zone infiltration, is confirmed as a contributor and narrows the bias further. A second masked error then surfaces, since the calibration hyetographs were themselves synthetic: under basin-average radar forcing the wettest-antecedent event closes to within 7% of observed volume. The residual orders by antecedent wetness and is attributed to the model's single fixed soil-moisture state, which continuous simulation would track. Results rest on pipeline validation, sensitivity attribution, and diagnostic error attribution rather than absolute discharge.