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

Getting started 💡

With this package you can: - read, manipulate and write INP-files. - many macros can be found for analysing and manipulating the input data in the package under swmm_api.input_file.macros - start a SWMM simulation within this python package. - read the report (.rpt) and output (.out) files as a pandas.DataFrame for further analysis. - export the model to GIS for spatial data analysis (import function also available, but must be adopted depending on the used GIS files).

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

💡 The Technical Note in Water (MDPI) is published 💡

Pichler, M. (2025). swmm_api: A Python Package for Automation, Customization, and Visualization in SWMM-Based Urban Drainage Modeling. Water, 17(9), 1373. https://doi.org/10.3390/w17091373

Introduction

The swmm_api package is a powerful tool for modellers and researchers who use the Storm Water Management Model (SWMM). This software enables the manipulation and analysis of SWMM models, both in terms of the input data and the simulation results. The package is written in Python, making it an attractive option for those who use this language for data management and advanced analysis.

One of the key features of swmm_api is its ability to read and write SWMM import-files (.inp), allowing the user to manipulate the model structure and input data. The package also has the capability to run the SWMM model within the Python environment, providing users with quick access to simulation results. Furthermore, swmm-api can read both the report (.rpt) and binary output-files (.out), presenting the results as a Pandas DataFrame for easy analysis. The ability to read binary hotstart-files (.hst) is also included, which enables the acceleration of simulation time by using initial values stored in the file.

The swmm_api package is designed to be flexible and user-friendly, with an object-oriented structure that is lightweight and fast. The package is based on the SWMM command line syntax, making it easy to use for those familiar with this model. Additionally, swmm-api has the ability to interact with GIS data, making it a valuable tool for modellers working with spatial data.

Installation

Ensure you have Python 3.8 or higher.

Install using:

bash pip install swmm-api

... to install the package with all dependencies for macros use:

bash 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):

bash 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):

bash pip install swmm-api[full]

To add the GIS functionality on Windows, I recommend using python version >= 3.10 or with Mamba (or miniconda or Anaconda) and run mamba install geopandas to install the GIS dependencies (see GeoPandas).

Here you can see which packages are getting installed:

| packages | required | macros | gis | full | docs | |:------------------------------:|:--------:|:------:|:---:|:----:|:----:| | pandas | x | x | x | x | x | | tqdm | x | x | x | x | x | | networkx | | x | | x | x | | pyarrow | | x | | x | x | | matplotlib | | x | | x | x | | SWMMxsectionsshapegenerator | | x | | x | x | | pyswmm | | x | | x | x | | geopandas | | | x | x | x | | sphinx | | | | | x | | nbsphinx | | | | | x | | recommonmark | | | | | x | | pydatasphinx_theme | | | | | x |

Documentation 📖

Link to the documentation of the package and some example jupyter notebooks.

Here are example files for other use-cases.

Community and Support

For questions or feedback, join the Matrix chat or create an issue on GitLab.

There is also a GitHub page for this project, so feel free to open an issue of start a discussion there if you don't have a gitlab account.

If you like this project and want to show your support, consider donate with buy me a coffee.

Read, manipulate and write the INP-File

Read the INP-File

```python from swmmapi import readinp_file, SwmmInput

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

or

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

or

inp = SwmmInput('inputfile.inp')

```

Getting information

```python from swmmapi.inputfile.section_labels import TIMESERIES

getting a specific section of the inp-file

sectimeseries = inp[TIMESERIES] # type: swmmapi.input_file.helpers.InpSection

or

sectimeseries = inp.TIMESERIES # type: swmmapi.input_file.helpers.InpSection

getting a specific timeseries as pandas.Series

ts = inp[TIMESERIES]['regenseries'].pandas # type: pandas.Series ```

Manipulate the INP-File

```python from swmmapi.inputfile.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 ```

Write the manipulated INP-File

python inp.write_file('new_inputfile.inp')

see examples/inpfilereader.ipynb

see examples/inpfilestructure.ipynb

see examples/inpfilemacros.ipynb for plotting the model on a map or as a longitudinal plot.

Run SWMM

Run SWMM with a specified executable. (You can set a default SWMM exe using the CONFIG object or a config file, see below)

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

python 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

```python from swmmapi import readout_file, SwmmOutput

out = readoutfile('newinputfile.out') # type: swmmapi.SwmmOut

or

out = SwmmOutput('new_inputfile.out')

df = out.to_frame() # type: pandas.DataFrame

or if only a single timeseries of the results is needed

ts = out.get_part('node', 'J1', 'depth') # type: pandas.Series ``` see examples/outfilereader.ipynb

Read the RPT-File

```python from swmmapi import readrpt_file, SwmmReport

rpt = readrptfile('newinputfile.rpt') # type: swmmapi.SwmmReport

or

rpt = SwmmReport('new_inputfile.rpt')

nodefloodingsummary = rpt.nodefloodingsummary # type: pandas.DataFrame ``` see examples/rptfilereader.ipynb

GIS interactions 🗺️

geopandas must be installed! (Use python version >3.10 or conda (Anaconda|miniconda) on Windows)

```python from swmmapi import SwmmInput from swmmapi.inputfile.macros.gis import writegeopackage, gpkgtoswmm, completevertices

inp = SwmmInput('inputfile.inp')

coords = inp.COORDINATES.geo_series # type: geoandas.GeoSeries with points for all nodes

complete_vertices(inp) # this will insert the start and end node points into the link vertices.

this function is automatically called in write_geo_package, but is needed if the geo-series of vertices is used directly.

vertices = inp.VERTICES.geoseries # type: geoandas.GeoSeries with lines for all links polygons = inp.POLYGONS.geoseries # type: geoandas.GeoSeries with polygons for all subcatchments

create geopackage of all objects in inp file

writegeopackage(inp, gpkgfn='geopackage.gpkg', driver='GPKG', labelsep='.', crs="EPSG:32633", add_style=True)

read above written geopackage and convert it to inp-data

inpnew = gpkgtoswmm('geopackage.gpkg', labelsep='.') inpnew.writefile('new_inputfile.inp') ```

For example the default GIS export as a geo-package (with included styles) looks in QGIS like this:

Be Aware! ⚠️

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.

AND

This package uses utf-8 as default encoding for the file I/O (reading and writing inp, rpt and out files.) Every function to read a file has the option to define a custom encoding (for example Windows uses this as default for german encoding='iso-8859-1').

But one can set a default encoding for the package using: python from swmm_api import CONFIG CONFIG['encoding'] = 'iso-8859-1'

You can also set a default SWMM exe for the package using: ```python CONFIG['exe_path'] = r'C:\path\to\runswmm.exe'

or

CONFIG.exe_path = r'C:\path\to\runswmm.exe' ```

New in version 0.4.61

You can save your default in a config file which will then be used by default in the future. simply set your default and use CONFIG.save(). This will save the cinfig data into the file ~/.config/swmm-api_config.json

New in version 0.4.64

You can also set a default Coordinate Reference System for the GIS import and export: ```python CONFIG['default_crs'] = 'EPSG:4326'

or

CONFIG.default_crs = 'EPSG:4326' ```

---

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

Cite as

Pichler, M. (2025). swmm_api: A Python Package for Automation, Customization, and Visualization in SWMM-Based Urban Drainage Modeling. Water, 17(9), 1373. https://doi.org/10.3390/w17091373

Publications using or mentioning swmm_api 📚

2022

1. 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
2. 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
3. Schilling, J., & Tränckner, J. (2022). Generateswmminp: An open-source qgis plugin to import and export model input files for swmm. Water, 14(14), 2262. https://doi.org/10.3390/w14142262
4. Wicki, T. (2022). Effekt der Einzugsgebietsmodellierung auf die Abflusssimulation im urbanen Gebiet. Master thesis. Paris Lodron-Universität Salzburg. https://unigis.at/files/Mastertheses/Full/106726.pdf

2023

1. Farina, A., Di Nardo, A., Gargano, R., Van Der Werf, J. A., & Greco, R. (2023). A simplified approach for the hydrological simulation of urban drainage systems with SWMM. Journal of Hydrology, 623, 129757. https://doi.org/10.1016/j.jhydrol.2023.129757
2. Ryrfors Wien, C. (2023). Nature-based solution retrofit in an urban catchment for CSO reduction (Master's thesis, NTNU). https://hdl.handle.net/11250/3108487
3. van der Werf, J. A., Kapelan Z., Langeveld, J. G. (2023). Predictive heuristic control: inferring risks from heterogeneous nowcast accuracy. Water Sci Technol 2023; 87 (4): 1009–1028. https://doi.org/10.2166/wst.2023.027
4. Van Der Werf, J. A., Kapelan, Z., & Langeveld, J. G. (2023). Happy to control: A heuristic and predictive policy to control large urban drainage systems. Water Resources Research, 59(8), https://doi.org/10.1029/2022WR033854
5. 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

2024

1. Farina, A., Gargano, R., & Greco, R. (2024). Effects of urban catchment characteristics on combined sewer overflows. Environmental Research, 244, 117945. https://doi.org/10.1016/j.envres.2023.117945
2. Pichler, M., König, A. W., Reinstaller, S., & Muschalla, D. (2024). Fully automated simplification of urban drainage models on a city scale. Water Science & Technology. https://doi.org/10.2166/wst.2024.337
3. Pritsis, S., Pons, V., Rokstad, M. M., Clemens-Meyer, F. H. L. R., Kleidorfer, M., & Tscheikner-Gratl, F. (2024). The role of hyetograph shape and designer subjectivity in the design of an urban drainage system. Water Science & Technology, 90(3), 920–934. https://doi.org/10.2166/wst.2024.261
4. Zhang, Z., Tian, W., Lu, C., Liao, Z., & Yuan, Z. (2024). Graph neural network-based surrogate modelling for real-time hydraulic prediction of urban drainage networks. Water Research, 263, 122142. https://doi.org/10.1016/j.watres.2024.122142
5. Karki, Namrata (2024) Comparison between single and multi-objective strategies for urban drainage model optimization using genetic algorithms: a case study of Badalona urban drainage network, Master's thesis, TU Dresden, http://hdl.handle.net/2117/415350

Packages or repositories using swmm_api (on GitHub)

MarkusPic / swmm-model-simplification

• alBartig / PacketSWMM | swmmRouting | SWMMpulse
• Zhiyu014 / GNN-UDS | MARL-UDS
• QianyangWang / PyCUP
• Ahad-Hasan-Tanim10 / Bayes_opt-SWMM
• zhentaoumich / pyswmm_viz | pyswmm / pyswmm_viz
• NidaboyinTokyo / ProjectShiERD

Alternative packages

• swmmr / R-language / GitHub / cran
• MatSWMM / Matlab / GitHub
• swmmNode / TypeScript / GitHub

---

• 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 swmmapi: `swmmapi.inputfile.macrosnippets.gisstandardimportandswmmapi.inputfile.macrosnippets.gisexport`)
• 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 python-packages

• pyswmm / pypi / GitHub / Website / 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