swmm-api 0.3.post3

US-EPA-SWMM python interface

© Institute of Urban Water Management and Landscape Water Engineering, Graz University of Technology and Markus Pichler

Getting started

With this package you can read INP-files, manipulate them and write new ones. You can run swmm within the python api. And you can read the RPT- and OUT-files as a pandas DataFrame for further analysis.

This package is based on the command line SWMM syntax. (see Appendix D in the SWMM User Manual 5.2)

Install the package

pip install swmm-api

Documentation

Link to the documentation of the api and some example jupyter notebook.

Alternative packages

R-language:

• swmmr / GitHub / cran

python:

• swmmio / docs / pypi / GitHub
• GisToSWMM5 / GitHub / converting gis data to swmm model (also possible with swmm_api: swmm_api.input_file.macro_snippets.gis_standard_import and swmm_api.input_file.macro_snippets.gis_export)
• swmmtoolbox / GitHub / Thanks to Tim Cera for this package! I used his package to understand the .out-files but completely rewrote the reading process in this package.
• swmmnetwork / GitHub / create graph network from swmm model (see swmm_api.input_file.macros.inp_to_graph)
• SWMMOutputAPI / GitHub / read the output file (see swmm_api.output_file.out) / (OpenWaterAnalytics)
• swmm-pandas / pypi / equal functionalities to this package, but not feature complete
• swmmout / pypi / docs / simular to swmmtoolbox and SWMMOutputAPI
• swmmtonetcdf / pypi / GitHub
• hymo / GitHub Input and Report Reader (Lucas Nguyen)
• shmm / GitHub Input Reader (Lucas Nguyen)
• swmmreport / GitHub Report Reader (Lucas Nguyen)
• swmmdoodler / GitHub

Other SWMM-related packages

python:

• pyswmm / pypi / GitHub / RTC, etc. / based on swmm-toolkit (OpenWaterAnalytics)
• swmm-toolkit / pypi / GitHub / by Michael Tryby (OpenWaterAnalytics)
• SWMM5 / pypi / GitHub / simular approach to swmm-toolkit (by Assela Pathirana)
• SWMM-xsections-shape-generator / pypi / tool to generate custom shapes (by me)
• SWMM_EA / pypi / usage of genetic algorithms with SWMM (by Assela Pathirana)
• OSTRICH-SWMM / GitHub / OSTRICH optimization software toolkit with the SWMM

Read, manipulate and write the INP-File

Read the INP-File

from swmm_api.input_file.section_labels import TIMESERIES
from swmm_api import read_inp_file

inp = read_inp_file('inputfile.inp')  # type: swmm_api.SwmmInput

sec_timeseries = inp[TIMESERIES]  # type: swmm_api.input_file.helpers.InpSection
ts = inp[TIMESERIES]['regenseries'].pandas  # type: pandas.Series

Manipulate the INP-File

from swmm_api import read_inp_file, SwmmInput
from swmm_api.input_file.section_labels import JUNCTIONS

inp = read_inp_file('inputfile.inp')  # type: swmm_api.SwmmInput
# or 
inp = SwmmInput.read_file('inputfile.inp')

inp[JUNCTIONS]['J01'].elevation = 210

Write the manipulated INP-File

inp.write_file('new_inputfile.inp')

see examples/inp_file_reader.ipynb

see examples/inp_file_structure.ipynb

see examples/inp_file_macros.ipynb

Run SWMM

Run SWMM with a specified executable.

from swmm_api import swmm5_run
swmm5_run('new_inputfile.inp', swmm_lib_path=r'C:\path\to\runswmm.exe')

Or run SWMM with pyswmm. This would be platform independent as pyswmm is compiled for all platforms. Additionally, you gain the advantage of a progress bar.

from swmm_api import swmm5_run
swmm5_run('new_inputfile.inp', progress_size=100)

swmm5 C:\path\to\new_inputfile.inp:  77%|███████▋  | 77/100 [00:03<00:01, 22.36it/s, 2007-02-16 08:46:27]

Read the OUT-File

from swmm_api import read_out_file
out = read_out_file('new_inputfile.out')   # type: swmm_api.SwmmOut
df = out.to_frame()  # type: pandas.DataFrame

see examples/out_file_reader.ipynb

Read the RPT-File

from swmm_api import read_rpt_file
rpt = read_rpt_file('new_inputfile.rpt')  # type: swmm_api.SwmmReport
node_flooding_summary = rpt.node_flooding_summary  # type: pandas.DataFrame

see examples/rpt_file_reader.ipynb

GIS interactions

geopandas and its requirements (Shapely, pyproj, Rtree) must be installed! (not that easy on Windows)

from swmm_api import SwmmInput
from swmm_api.input_file.macros.gis import write_geo_package, gpkg_to_swmm

inp = SwmmInput.read_file('inputfile.inp')

coords = inp.COORDINATES.geo_series  # type: geoandas.GeoSeries with points for all nodes
vertices = inp.VERTICES.geo_series  # type: geoandas.GeoSeries with lines for all links
polygons = inp.POLYGONS.geo_series  # type: geoandas.GeoSeries with polygons for all subcatchments

# create geopackage of all objects in inp file
write_geo_package(inp, gpkg_fn='geopackage.gpkg', driver='GPKG', label_sep='.', crs="EPSG:32633")

# read above written geopackage and convert it to inp-data
inp_new = gpkg_to_swmm('geopackage.gpkg', label_sep='.')
inp_new.write_file('new_inputfile.inp')

MORE INFORMATION COMING SOON

Cite as

Pichler, Markus. (2022). swmm_api: API for reading, manipulating and running SWMM-Projects with python (0.3). Zenodo. https://doi.org/10.5281/zenodo.7054804