MODFLOW-SWMM Coupling

Bidirectional coupling of SWMM (stormwater/sewer) and MODFLOW 6 (groundwater) for daily-timestep coastal-flood and sea-level-rise modeling. Originally developed for Bowers Beach, Delaware.

Three exchanges happen every stress period (1 day):

• SWMM → MODFLOW: subcatchment infiltration becomes MODFLOW recharge (spatially proportioned to grid cells, lagged one day).
• MODFLOW → SWMM: groundwater drainage from coupled cells injected into SWMM junctions.
• MODFLOW ↔ sanitary nodes: head-based leakage into pipes via the MODFLOW WEL package. Sanitary nodes are identified from the SWMM [DWF] section.

Installation

The coupling requires patched builds of PySWMM and the SWMM toolkit. Vanilla pyswmm from PyPI does not expose the groundwater hooks and will fail at the MODFLOW→SWMM exchange. requirements.txt is a reference list only — do not install from it.

bash bash env/setup.sh conda activate pyflo

This creates the pyflo conda env from env/environment.yml, then clones and builds three forks pinned by commit (solver, toolkit, pyswmm). It ends by running env/verify_install.py, which asserts the groundwater setter round-trips, so a silent half-install cannot slip through.

MODFLOW 6 binaries for all three platforms ship in exe/ and are auto-detected; pass --dll-path to override.

Running a simulation

One scenario per invocation. Run from the repository root — default input paths are relative to it.

bash python main.py run-simulation --scenario baseline

For the SLR scenario (CHD 1.2 m instead of 0.0 m), edit the head value in modflow_ws/Bowers_beach.chd first, then run with --scenario slr. The scenario tag is appended to every output filename, so runs never collide.

--scenario output filename suffix (default: baseline) --model-name MODFLOW model name (default: Bowers_beach) --log-level DEBUG | INFO | WARNING | ERROR (default: INFO) --dll-path path to libmf6.{dylib,so,dll} (auto-detected) --no-validate-first skip the pre-run setup validation

Input-path flags (--modflow-workspace, --swmm-input, --subcatchments-shapefile, --nodes-shapefile, --well-csv) default to the Bowers Beach files. python main.py validate-setup checks inputs without simulating; --help lists everything.

A run always writes logs/simulation_<scenario>.log. Redirecting the console as well captures MODFLOW's own output and the node-mapping summary, which Python does not log:

bash mkdir -p logs python main.py run-simulation --scenario baseline > logs/console_baseline.log 2>&1 &

Outputs

results/ ├── sanitary_nodes.csv # node-to-cell mapping └── simulation/ ├── gw_head_differences_<scenario>.csv ├── gw_head_differences_<scenario>.png ├── subcatchment_gwt_elev_ft_<scenario>.csv ├── subcatchment_max_infil_depth_<scenario>.csv ├── subcatchment_max_infil_depth_<scenario>.png ├── subcatchment_water_table_<scenario>.png ├── mean_water_table_<scenario>.tif └── mean_groundwater_depth_map_<scenario>.png

run-simulation writes the CSVs, the .tif and mean_groundwater_depth_map. The other three PNGs come from a separate, manual step:

bash python plots/time_series_plots.py --scenario baseline

These do not refresh when you re-run a simulation. Re-run this command after any run whose figures you intend to use, or they will silently show the previous run's results.

MODFLOW also writes modflow_ws/*.lst, *.hds, *.cbc; SWMM writes swmm_inp/Bowers_beach.rpt and .out. None of results/ is tracked by git.

Adapting to a new study area

The coupling logic is generic; the inputs are not.

1. Replace the MODFLOW model in modflow_ws/ and the SWMM .inp in swmm_inp/. Set --model-name if it isn't Bowers_beach.
2. Replace the two shapefiles the coupling reads. Columns are indexed by name, so a missing one raises a bare KeyError:

Shapefiles and the MODFLOW grid must share one projected CRS in the same units as delr/delc. Nodes are placed by raw coordinate arithmetic (col = (x - xmin)/delr) with no reprojection; a mismatch appears as a flood of "nodes outside MODFLOW grid bounds" warnings in the console log rather than an error. Both are PCSWMM exports of the same model as the .inp, so re-export them together. 3. Sanitary nodes are detected automatically from the [DWF] section of the .inp — no code change needed. The classifier seeds from those and propagates through the pipe network. Run python main.py validate-setup once to generate results/sanitary_nodes.csv and print a coupling report. 4. Scenarios: edit the CHD value in modflow_ws/Bowers_beach.chd and pass any tag via --scenario.

Tests

bash pytest tests/ -q

21 tests covering drainage routing (separate vs. combined sewers, mass conservation), node-inflow accumulation and reset semantics, and head-based sanitary leakage. They need no MODFLOW solve and no SWMM run, and finish in about a second.

Project layout

main.py CLI entry point env/ setup.sh, environment.yml, verify_install.py src/ coupled_simulation.py, validation.py, postprocess.py, core/ (coupling components), utils/ (loaders, geolocation, proportioning, classifier) plots/ plotting source only — figures go to results/simulation/ tests/ pytest suite modflow_ws/ MODFLOW 6 workspace swmm_inp/ SWMM .inp + outputs shp_files/ subcatchment + node shapefiles exe/ MODFLOW 6 binaries tutorial/ Bowers_beach_tutorial.ipynb results/ generated outputs, not tracked

Troubleshooting

No CMAKE_C_COMPILER could be found — you ran conda env create directly instead of bash env/setup.sh. This cannot be fixed from environment.yml.

gw_set_state missing / setGroundwaterState fails — vanilla pyswmm is shadowing the fork:

bash conda activate pyflo pip uninstall -y pyswmm swmm-toolkit bash env/setup.sh --skip-env

Build picks the wrong Python or CMake — another conda env or Homebrew is ahead on PATH. If building by hand, export PATH="$CONDA_PREFIX/bin:$PATH" after activating.

Citation

If you use this software, please cite it using the metadata from the CITATION.cff file.

Alternatively, use the "Cite this repository" button in the GitHub sidebar to export the citation in APA or BibTeX format.

License

Released under the MIT License — free to use, modify, and redistribute, including commercially, provided the copyright notice and licence text are retained.

The MODFLOW 6 binaries in exe/ are USGS software in the public domain and are redistributed unchanged. The patched SWMM forks are built from source at install time and are not covered by this licence; they carry the licences of their upstream projects (see Reference).

Reference

SWMM's underlying source is US EPA public domain; Austin's forks and our coupling build on that base.The swmm_getGWaterState / swmm_setGWaterState API that makes this coupling possible is Austin Farnum's work. Our forks descend directly from his repositories with his commits and authorship intact; our additions fix compilation and complete the Python binding. Every change is visible as a diff against his code: solver, toolkit, pyswmm.