ยฉ Institute of Urban Water Management and Landscape Water Engineering, Graz University of Technology and Markus Pichler
Go to GitLab to see the full source.
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)
pip install swmm-api
... to install the package with all dependencies for macros use:
pip install swmm-api[macros]
... to install the package with all dependencies for GIS I/O use (for Linux or for Windows using python >= 3.10):
pip install swmm-api[gis]
... and to install the package with all dependencies for macros and GIS I/O use (for Linux or for Windows using python >= 3.10):
pip install swmm-api[full]
To add the GIS functionality to Windows, I recommend using python with Mamba
(or miniconda or Anaconda)
and run mamba install geopandas
to install the GIS dependencies (see GeoPandas).
Installing GeoPandas and its dependencies now work on Windows since python version >= 3.10.
Link to the documentation of the api and some example jupyter notebook.
R-language:
python:
- swmmio / docs / pypi / GitHub / simular to this package but more high-level approach (= slower for specific tasks)
- GisToSWMM5 / GitHub / converting gis data to swmm model (also possible with swmm_api:
swmm_api.input_file.macro_snippets.gis_standard_import
andswmm_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
andSWMMOutputAPI
- 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
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 SWMM
from swmm_api import read_inp_file, SwmmInput
inp = read_inp_file('inputfile.inp') # type: swmm_api.SwmmInput
# or
inp = SwmmInput.read_file('inputfile.inp')
# or
inp = SwmmInput('inputfile.inp')
from swmm_api.input_file.section_labels import TIMESERIES
# getting a specific section of the inp-file
sec_timeseries = inp[TIMESERIES] # type: swmm_api.input_file.helpers.InpSection
# or
sec_timeseries = inp.TIMESERIES # type: swmm_api.input_file.helpers.InpSection
# getting a specific timeseries as pandas.Series
ts = inp[TIMESERIES]['regenseries'].pandas # type: pandas.Series
from swmm_api.input_file.section_labels import JUNCTIONS
# setting the elevation of a specific node to a new value
inp[JUNCTIONS]['J01'].elevation = 210
# or
inp.JUNCTIONS['J01'].elevation = 210
# or
inp.JUNCTIONS['J01']['elevation'] = 210
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 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]
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
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
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')
As python is case-sensitive this API is also case-sensitive, but SWMM is case-insensitive. This is important for the naming of the objects. For example, you could create a junction 'a' and 'A' with this API, but SWMM would only consider one and ignore the other.
This documentation will be continuously extended and enhanced. If you have any question, don't hesitate to write the author and email or create an issue on GitLab or GitHub.
MORE INFORMATION COMING SOON
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
- Baumann, H., Ravn, N. H., & Schaum, A. (2022). Efficient hydrodynamic modelling of urban stormwater systems for real-time applications. Modelling, 3(4), 464โ480. https://doi.org/10.3390/modelling3040030
- Farina, A., Di Nardo, A., Gargano, R., & Greco, R. (2022). Assessing the environmental impact of combined sewer overflows through a parametric study. EWaS5, 8. https://doi.org/10.3390/environsciproc2022021008
- Schilling, J., & Trรคnckner, J. (2022). Generate_swmm_inp: An open-source qgis plugin to import and export model input files for swmm. Water, 14(14), 2262. https://doi.org/10.3390/w14142262
- Zhang, Z., Tian, W., & Liao, Z. (2023). Towards coordinated and robust real-time control: A decentralized approach for combined sewer overflow and urban flooding reduction based on multi-agent reinforcement learning. Water Research, 229, 119498. https://doi.org/10.1016/j.watres.2022.119498