© Institute of Urban Water Management and Landscape Water Engineering, Graz University of Technology and Markus Pichler
With this package you can:
swmm_api.input_file.macrospandas.DataFrame for further analysis.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
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.
Ensure you have Python 3.8 or higher.
Install using:
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 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 | ||
| SWMM_xsections_shape_generator | x | x | x | ||
| pyswmm | x | x | x | ||
| geopandas | x | x | x | ||
| sphinx | x | ||||
| nbsphinx | x | ||||
| recommonmark | x | ||||
| pydata_sphinx_theme | x |
Link to the documentation of the package and some example jupyter notebooks.
Here are example files for other use-cases.
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.
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 for plotting the model on a map or as a longitudinal plot.
Run SWMM with a specified executable. (You can set a default SWMM exe using the CONFIG object or a config file, see below)
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, SwmmOutput
out = read_out_file('new_inputfile.out') # type: swmm_api.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/out_file_reader.ipynb
from swmm_api import read_rpt_file, SwmmReport
rpt = read_rpt_file('new_inputfile.rpt') # type: swmm_api.SwmmReport
# or
rpt = SwmmReport('new_inputfile.rpt')
node_flooding_summary = rpt.node_flooding_summary # type: pandas.DataFrame
see examples/rpt_file_reader.ipynb
geopandas must be installed! (Use python version >3.10 or conda (Anaconda|miniconda) on Windows)
from swmm_api import SwmmInput
from swmm_api.input_file.macros.gis import write_geo_package, gpkg_to_swmm, complete_vertices
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.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", add_style=True)
# 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')
For example the default GIS export as a geo-package (with included styles) looks in QGIS like this:
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-8as 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 germanencoding='iso-8859-1').
But one can set a default encoding for the package using:
from swmm_api import CONFIG
CONFIG['encoding'] = 'iso-8859-1'
You can also set a default SWMM exe for the package using:
CONFIG['exe_path'] = r'C:\path\to\runswmm.exe'
# or
CONFIG.exe_path = r'C:\path\to\runswmm.exe'
0.4.61You 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
0.4.64You can also set a default Coordinate Reference System for the GIS import and export:
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
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
swmm_api 📚swmm_api (on GitHub)MarkusPic / swmm-model-simplification
swmm_api.input_file.macro_snippets.gis_standard_import and swmm_api.input_file.macro_snippets.gis_export)swmm_api.input_file.macros.inp_to_graph)swmm_api.output_file.out) / (OpenWaterAnalytics)swmmtoolbox and SWMMOutputAPIswmm-toolkit (OpenWaterAnalytics)swmm-toolkit (by Assela Pathirana)FAQs
API for reading, manipulating and running US-EPA-SWMM-Projects
We found that swmm-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
North Korean threat actors deploy 67 malicious npm packages using the newly discovered XORIndex malware loader.
Security News
Meet Socket at Black Hat & DEF CON 2025 for 1:1s, insider security talks at Allegiant Stadium, and a private dinner with top minds in software supply chain security.
Security News
CAI is a new open source AI framework that automates penetration testing tasks like scanning and exploitation up to 3,600× faster than humans.