© [Institute of Urban Water Management and Landscape Water Engineering](https://www.sww.tugraz.at), [Graz University of Technology](https://www.tugraz.at/home/) and [Markus Pichler](mailto:markus.pichler@tugraz.at)
# Getting started 💡
[](https://pypi.python.org/pypi/swmm-api)
[](https://gitlab.com/markuspichler/swmm_api/-/commits/main)
[](https://opensource.org/licenses/MIT)
[](https://markuspichler.gitlab.io/swmm_api)
[](https://zenodo.org/doi/10.5281/zenodo.5862140)
[](https://gitlab.com/markuspichler/swmm_api/-/releases)
[](https://matrix.to/#/#swmm-api-python:matrix.org)
[](https://pypi.python.org/pypi/swmm-api)
[](https://pypi.python.org/pypi/swmm-api)
[](https://pypi.python.org/pypi/swmm-api)
With this package you can read INP-files, manipulate them and write new ones.
You can start SWMM within this python package.
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](https://www.epa.gov/system/files/documents/2022-04/swmm-users-manual-version-5.2.pdf))
## 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.
## Install the package
```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](https://github.com/conda-forge/miniforge#mambaforge)
(or [miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Anaconda](https://www.anaconda.com/))
and run `mamba install geopandas` to install the GIS dependencies (see [GeoPandas](https://geopandas.org/en/stable/getting_started.html)).
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 |
| fastparquet | | 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 |
[](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqFl01zmzwQgP8Ko8N7Moz58gdNe8o1p3amMy3vQcEyUQyIgmiCM_nvXUkgiRjIJazCw2q_tCu_oYydCEqQ67pplbHqTPMkrRynwD3reOKQ4pJW8uW5YC_ZE2648-NeEI6TFbht78nZKWnb0ip3Wt6wC3FPuAWuwX3ixIrEpOrK3ymSz7vH5lvo-Z7vp-j_QRNpOD1TIAZJMME2iLyDF24NxirOuqbuBTjKAvW90LOwBpfPWOw3SFKbd7SRPitIIwgpCGDr-YFnTDrjlte4-dMRDpi10qbFlr4zWMMZK1rBjrIgAYtsrW1bk0xAUtC6_K2lLCesxhVEETgtKze3lq5n9ljQR2CUoIDICwzQFRRXApDC4GSk31_oC21Z8VcGwixGRXsNlpjXBeNqN7NQiTxaO1aEv7Dm8grYKCrINgtKQGZQPlVqIH_6dY2zC86hnADRssRsJTpAJjqBF9hqaAEFKwApSKdE_EyY657lDWUCUdIQoCkDWW8HY0ZZuRRMsYY9KwYEBewnQPtSlhIQgjLXTmbd8ydWwdHhpOO0kOTkP7qGvZq13NbMr4q-6moyYWozeqHcLQhuRCHYS5XmeArLxMineu3bxQunuiaFJJQ0urEzCBW5h7_D5zsrBsJxVxwMMEFA1nKIfOzFU_q1JRmnrGpduaObk4o0mDNRsN9_PjwsA0rjXgbLeMifGoJPNWyacRHjyVplzT7V_M9J5Ew81Fne2TnlV8gNFu-lMBN93aMc13VS9F9OvvheADUK62_qHNw0GxuVtkhWVfkKLEtfokPPW2Bx1Q-c6kCfYmtWGkof1A8dzBgokhGMtDpviywEKbjdfhaMZkM0gwbq7Et0KN9FNlTjZLBVnOhZdNF90yJt__1RpZo5y-jQ5hU7ltAaPldS82SoFZt-v8wHFq-73xq-1_Ckd618srXy92kM4WwFmtdjdpk_jKrlCLAHxyR6O63Tit9t_Rys-p1x7-aDbbC1osevi5iJm-okk_H0sdSGC9IqY7sxT3wItiryT7YSHXlSz9HAqevFEnY0x87q-PP0eC2UuLws3nIrTkyyMmmkowX09XYu2qB_1KwVxCXaFKO6gq3TpszkgF2DRRxGeDKjrEE9bQBevLkzM8C2XfW6iZPR5m6OtNKj8K9flxKyPp0X6jGt0AaVpCkxPcFPjjehSsxgUpIUJSCeyBl3BU9RWr0DijvOvvdVhhLedGSDGtblTyg546KFVVeLTN9TnMPAGxFyorD_g_pNI3_abMQN8Rdjpf4Q1ih5Q68oceOd7x3j6BCGx0MU7uMN6lHi-3B3i8LYj7d-tIsOUfS-QVepARqof4QXh3AXwxf793-PLQ4V)
## Documentation 📖
[Link](https://markuspichler.gitlab.io/swmm_api) to the documentation of the package and some example jupyter notebooks.
[Here](https://gitlab.com/markuspichler/swmm_api/-/tree/main/examples) are example files for other use-cases.
## Read, manipulate and write the INP-File
### Read the INP-File
```python
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')
```
### Getting information
```python
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
```
### Manipulate the INP-File
```python
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
```
### Write the manipulated INP-File
```python
inp.write_file('new_inputfile.inp')
```
see [examples/inp_file_reader.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_reader.ipynb)
see [examples/inp_file_structure.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_structure.ipynb)
see [examples/inp_file_macros.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_macros.ipynb) for plotting the model on a map or as a longitudinal plot.
## Run SWMM
Run SWMM with a specified executable.
```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](https://github.com/OpenWaterAnalytics/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 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](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/out_file_reader.ipynb)
## Read the RPT-File
```python
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](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/rpt_file_reader.ipynb)
## GIS interactions 🗺️
[`geopandas`](https://geopandas.org/) must be installed! (Use python version >3.10 or conda (Anaconda|miniconda) on Windows)
```python
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 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'
```
---
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, Markus. (2022). swmm_api: API for reading, manipulating and running SWMM-Projects with python (0.3). Zenodo. https://doi.org/10.5281/zenodo.7054804*
## Publications using or mentioning swmm-api 📚
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). 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>
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>
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>
6. 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>
7. 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>
8. 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>
9. 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), e2022WR033854. <https://doi.org/10.1029/2022WR033854>
10. 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>
11. 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>
12. 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>
## Packages or repositories using swmm-api (on GitHub)
[MarkusPic / swmm-model-simplification](https://github.com/MarkusPic/swmm-model-simplification)
- [alBartig / PacketSWMM](https://github.com/alBartig/PacketSWMM) | [swmmRouting](https://github.com/alBartig/swmmRouting) | [SWMMpulse](https://github.com/alBartig/SWMMpulse)
- [Zhiyu014 / GNN-UDS](https://github.com/Zhiyu014/GNN-UDS) | [MARL-UDS](https://github.com/Zhiyu014/MARL-UDS)
- [QianyangWang / PyCUP](https://github.com/QianyangWang/PyCUP)
- [Ahad-Hasan-Tanim10 / Bayes_opt-SWMM](https://github.com/Ahad-Hasan-Tanim10/Bayes_opt-SWMM)
- [zhentaoumich / pyswmm_viz](https://github.com/zhentaoumich/pyswmm_viz) | [pyswmm / pyswmm_viz](https://github.com/pyswmm/pyswmm_viz)
- [NidaboyinTokyo / ProjectShiERD](https://github.com/NidaboyinTokyo/ProjectShiERD)
## Alternative packages
- **swmmr** / R-language / [GitHub](https://github.com/dleutnant/swmmr) / [cran](https://cran.r-project.org/web/packages/swmmr/index.html)
- **MatSWMM** / Matlab / [GitHub](https://github.com/gandresr/MatSWMM)
- **swmmNode** / TypeScript / [GitHub](https://github.com/swmm-js/swmmNode)
---
- **swmmio** / [docs](https://swmmio.readthedocs.io/en/latest/) / [pypi](https://pypi.org/project/swmmio/) / [GitHub](https://github.com/aerispaha/swmmio) / simular to this package but more high-level approach (= slower for specific tasks)
- **GisToSWMM5** / [GitHub](https://github.com/AaltoUrbanWater/GisToSWMM5) / 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](https://github.com/timcera/swmmtoolbox) / 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](https://github.com/austinorr/swmmnetwork) / create graph network from swmm model (see `swmm_api.input_file.macros.inp_to_graph`)
- **SWMMOutputAPI** / [GitHub](https://github.com/bemcdonnell/SWMMOutputAPI) / read the output file (see `swmm_api.output_file.out`) / (OpenWaterAnalytics)
- **swmm-pandas** / [pypi](https://pypi.org/project/swmm-pandas/) / equal functionalities to this package, but not feature complete
- **swmmout** / [pypi](https://pypi.org/project/swmmout/) / [docs](https://swmmout.readthedocs.io/en/latest/) / simular to `swmmtoolbox` and `SWMMOutputAPI`
- **swmmtonetcdf** / [pypi](https://pypi.org/project/swmmtonetcdf/) / [GitHub](https://github.com/cbuahin/swmmtonetcdf)
- **hymo** / [GitHub](https://github.com/lucashtnguyen/hymo) Input and Report Reader (Lucas Nguyen)
- **shmm** / [GitHub](https://github.com/lucashtnguyen/shmm) Input Reader (Lucas Nguyen)
- **swmmreport** / [GitHub](https://github.com/lucashtnguyen/swmmreport) Report Reader (Lucas Nguyen)
- **swmmdoodler** / [GitHub](https://github.com/Geosyntec/swmmdoodler)
### Other SWMM-related python-packages
- **pyswmm** / [pypi](https://pypi.org/project/pyswmm/) / [GitHub](https://github.com/OpenWaterAnalytics/pyswmm) / [Website](https://www.pyswmm.org) / RTC, etc. / based on swmm-toolkit (OpenWaterAnalytics)
- **swmm-toolkit** / [pypi](https://pypi.org/project/swmm-toolkit/) / [GitHub](https://github.com/OpenWaterAnalytics/swmm-python) / by Michael Tryby (OpenWaterAnalytics)
- **SWMM5** / [pypi](https://pypi.org/project/SWMM5/) / [GitHub](https://github.com/asselapathirana/swmm5-python) / simular approach to swmm-toolkit (by Assela Pathirana)
- **SWMM-xsections-shape-generator** / [pypi](https://pypi.org/project/SWMM-xsections-shape-generator/) / tool to generate custom shapes (by me)
- **SWMM_EA** / [pypi](https://pypi.org/project/SWMM5_EA/) / usage of genetic algorithms with SWMM (by Assela Pathirana)
- **OSTRICH-SWMM** / [GitHub](https://github.com/ubccr/ostrich-swmm) / OSTRICH optimization software toolkit with SWMM
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/markuspichler/swmm_api",
"name": "swmm-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "swmm, environment, civil_engineering, api",
"author": "Markus Pichler",
"author_email": "Markus Pichler <markus.pichler@tugraz.at>",
"download_url": "https://files.pythonhosted.org/packages/ee/b7/35f5ca3924617eca7cf483e434407c2e615fe5928d5f88a77b307344cacf/swmm_api-0.4.60.tar.gz",
"platform": null,
"description": "\u00a9 [Institute of Urban Water Management and Landscape Water Engineering](https://www.sww.tugraz.at), [Graz University of Technology](https://www.tugraz.at/home/) and [Markus Pichler](mailto:markus.pichler@tugraz.at)\n\n# Getting started \ud83d\udca1\n\n[](https://pypi.python.org/pypi/swmm-api)\n[](https://gitlab.com/markuspichler/swmm_api/-/commits/main)\n[](https://opensource.org/licenses/MIT)\n[](https://markuspichler.gitlab.io/swmm_api)\n[](https://zenodo.org/doi/10.5281/zenodo.5862140)\n[](https://gitlab.com/markuspichler/swmm_api/-/releases)\n[](https://matrix.to/#/#swmm-api-python:matrix.org)\n\n[](https://pypi.python.org/pypi/swmm-api)\n[](https://pypi.python.org/pypi/swmm-api)\n[](https://pypi.python.org/pypi/swmm-api)\n\n\nWith this package you can read INP-files, manipulate them and write new ones.\nYou can start SWMM within this python package.\nAnd you can read the RPT- and OUT-files as a pandas DataFrame for further analysis.\n\nThis package is based on the command line SWMM syntax. ([see Appendix D in the SWMM User Manual 5.2](https://www.epa.gov/system/files/documents/2022-04/swmm-users-manual-version-5.2.pdf))\n\n## Introduction\n\nThe 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.\n\nOne 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.\n\nThe 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.\n\n## Install the package\n```bash\npip install swmm-api\n```\n\n... to install the package with all dependencies for macros use:\n\n```bash\npip install swmm-api[macros]\n```\n\n... to install the package with all dependencies for GIS I/O use (for Linux or for Windows using python >= 3.10):\n\n```bash\npip install swmm-api[gis]\n```\n\n... and to install the package with all dependencies for macros and GIS I/O use (for Linux or for Windows using python >= 3.10):\n\n```bash\npip install swmm-api[full]\n```\n\nTo add the GIS functionality on **Windows**, I recommend using python version >= 3.10 or with [Mamba](https://github.com/conda-forge/miniforge#mambaforge)\n (or [miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Anaconda](https://www.anaconda.com/))\nand run `mamba install geopandas` to install the GIS dependencies (see [GeoPandas](https://geopandas.org/en/stable/getting_started.html)).\n\nHere you can see which packages are getting installed:\n\n| packages | required | macros | gis | full | docs |\n|:------------------------------:|:--------:|:------:|:---:|:----:|:----:|\n| pandas | x | x | x | x | x |\n| tqdm | x | x | x | x | x |\n| networkx | | x | | x | x |\n| fastparquet | | x | | x | x |\n| matplotlib | | x | | x | x |\n| SWMM_xsections_shape_generator | | x | | x | x |\n| pyswmm | | x | | x | x |\n| geopandas | | | x | x | x |\n| sphinx | | | | | x |\n| nbsphinx | | | | | x |\n| recommonmark | | | | | x |\n| pydata_sphinx_theme | | | | | x |\n\n\n\n[](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqFl01zmzwQgP8Ko8N7Moz58gdNe8o1p3amMy3vQcEyUQyIgmiCM_nvXUkgiRjIJazCw2q_tCu_oYydCEqQ67pplbHqTPMkrRynwD3reOKQ4pJW8uW5YC_ZE2648-NeEI6TFbht78nZKWnb0ip3Wt6wC3FPuAWuwX3ixIrEpOrK3ymSz7vH5lvo-Z7vp-j_QRNpOD1TIAZJMME2iLyDF24NxirOuqbuBTjKAvW90LOwBpfPWOw3SFKbd7SRPitIIwgpCGDr-YFnTDrjlte4-dMRDpi10qbFlr4zWMMZK1rBjrIgAYtsrW1bk0xAUtC6_K2lLCesxhVEETgtKze3lq5n9ljQR2CUoIDICwzQFRRXApDC4GSk31_oC21Z8VcGwixGRXsNlpjXBeNqN7NQiTxaO1aEv7Dm8grYKCrINgtKQGZQPlVqIH_6dY2zC86hnADRssRsJTpAJjqBF9hqaAEFKwApSKdE_EyY657lDWUCUdIQoCkDWW8HY0ZZuRRMsYY9KwYEBewnQPtSlhIQgjLXTmbd8ydWwdHhpOO0kOTkP7qGvZq13NbMr4q-6moyYWozeqHcLQhuRCHYS5XmeArLxMineu3bxQunuiaFJJQ0urEzCBW5h7_D5zsrBsJxVxwMMEFA1nKIfOzFU_q1JRmnrGpduaObk4o0mDNRsN9_PjwsA0rjXgbLeMifGoJPNWyacRHjyVplzT7V_M9J5Ew81Fne2TnlV8gNFu-lMBN93aMc13VS9F9OvvheADUK62_qHNw0GxuVtkhWVfkKLEtfokPPW2Bx1Q-c6kCfYmtWGkof1A8dzBgokhGMtDpviywEKbjdfhaMZkM0gwbq7Et0KN9FNlTjZLBVnOhZdNF90yJt__1RpZo5y-jQ5hU7ltAaPldS82SoFZt-v8wHFq-73xq-1_Ckd618srXy92kM4WwFmtdjdpk_jKrlCLAHxyR6O63Tit9t_Rys-p1x7-aDbbC1osevi5iJm-okk_H0sdSGC9IqY7sxT3wItiryT7YSHXlSz9HAqevFEnY0x87q-PP0eC2UuLws3nIrTkyyMmmkowX09XYu2qB_1KwVxCXaFKO6gq3TpszkgF2DRRxGeDKjrEE9bQBevLkzM8C2XfW6iZPR5m6OtNKj8K9flxKyPp0X6jGt0AaVpCkxPcFPjjehSsxgUpIUJSCeyBl3BU9RWr0DijvOvvdVhhLedGSDGtblTyg546KFVVeLTN9TnMPAGxFyorD_g_pNI3_abMQN8Rdjpf4Q1ih5Q68oceOd7x3j6BCGx0MU7uMN6lHi-3B3i8LYj7d-tIsOUfS-QVepARqof4QXh3AXwxf793-PLQ4V)\n\n## Documentation \ud83d\udcd6\n[Link](https://markuspichler.gitlab.io/swmm_api) to the documentation of the package and some example jupyter notebooks.\n\n[Here](https://gitlab.com/markuspichler/swmm_api/-/tree/main/examples) are example files for other use-cases.\n\n## Read, manipulate and write the INP-File\n\n### Read the INP-File\n\n```python\nfrom swmm_api import read_inp_file, SwmmInput\n\ninp = read_inp_file('inputfile.inp') # type: swmm_api.SwmmInput\n# or \ninp = SwmmInput.read_file('inputfile.inp')\n# or\ninp = SwmmInput('inputfile.inp')\n\n```\n\n### Getting information\n\n```python\nfrom swmm_api.input_file.section_labels import TIMESERIES\n\n# getting a specific section of the inp-file\n\nsec_timeseries = inp[TIMESERIES] # type: swmm_api.input_file.helpers.InpSection\n# or\nsec_timeseries = inp.TIMESERIES # type: swmm_api.input_file.helpers.InpSection\n\n# getting a specific timeseries as pandas.Series\nts = inp[TIMESERIES]['regenseries'].pandas # type: pandas.Series\n```\n\n### Manipulate the INP-File\n\n```python\nfrom swmm_api.input_file.section_labels import JUNCTIONS\n\n# setting the elevation of a specific node to a new value\n\ninp[JUNCTIONS]['J01'].elevation = 210\n# or\ninp.JUNCTIONS['J01'].elevation = 210\n# or\ninp.JUNCTIONS['J01']['elevation'] = 210\n```\n\n### Write the manipulated INP-File\n```python\ninp.write_file('new_inputfile.inp')\n```\n\nsee [examples/inp_file_reader.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_reader.ipynb) \n\nsee [examples/inp_file_structure.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_structure.ipynb)\n\nsee [examples/inp_file_macros.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_macros.ipynb) for plotting the model on a map or as a longitudinal plot.\n\n\n\n\n## Run SWMM\n\nRun SWMM with a specified executable.\n\n```python\nfrom swmm_api import swmm5_run\nswmm5_run('new_inputfile.inp', swmm_lib_path=r'C:\\path\\to\\runswmm.exe')\n```\n\nOr run SWMM with [pyswmm](https://github.com/OpenWaterAnalytics/pyswmm). This would be platform independent as pyswmm is compiled for all platforms.\nAdditionally, you gain the advantage of a progress bar.\n\n```python\nfrom swmm_api import swmm5_run\nswmm5_run('new_inputfile.inp', progress_size=100)\n```\n\n```\nswmm5 C:\\path\\to\\new_inputfile.inp: 77%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u258b | 77/100 [00:03<00:01, 22.36it/s, 2007-02-16 08:46:27]\n```\n\n## Read the OUT-File\n```python\nfrom swmm_api import read_out_file, SwmmOutput\n\nout = read_out_file('new_inputfile.out') # type: swmm_api.SwmmOut\n# or\nout = SwmmOutput('new_inputfile.out')\n\ndf = out.to_frame() # type: pandas.DataFrame\n\n# or if only a single timeseries of the results is needed\nts = out.get_part('node', 'J1', 'depth') # type: pandas.Series\n```\nsee [examples/out_file_reader.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/out_file_reader.ipynb)\n\n\n## Read the RPT-File\n```python\nfrom swmm_api import read_rpt_file, SwmmReport\n\nrpt = read_rpt_file('new_inputfile.rpt') # type: swmm_api.SwmmReport\n# or\nrpt = SwmmReport('new_inputfile.rpt')\n\nnode_flooding_summary = rpt.node_flooding_summary # type: pandas.DataFrame\n```\nsee [examples/rpt_file_reader.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/rpt_file_reader.ipynb)\n\n## GIS interactions \ud83d\uddfa\ufe0f\n\n[`geopandas`](https://geopandas.org/) must be installed! (Use python version >3.10 or conda (Anaconda|miniconda) on Windows)\n\n```python\nfrom swmm_api import SwmmInput\nfrom swmm_api.input_file.macros.gis import write_geo_package, gpkg_to_swmm, complete_vertices\n\ninp = SwmmInput('inputfile.inp')\n\ncoords = inp.COORDINATES.geo_series # type: geoandas.GeoSeries with points for all nodes\n\ncomplete_vertices(inp) # this will insert the start and end node points into the link vertices.\n# this function is automatically called in `write_geo_package`, but is needed if the geo-series of vertices is used directly.\n\nvertices = inp.VERTICES.geo_series # type: geoandas.GeoSeries with lines for all links\npolygons = inp.POLYGONS.geo_series # type: geoandas.GeoSeries with polygons for all subcatchments\n\n# create geopackage of all objects in inp file\nwrite_geo_package(inp, gpkg_fn='geopackage.gpkg', driver='GPKG', label_sep='.', crs=\"EPSG:32633\", add_style=True)\n\n# read above written geopackage and convert it to inp-data\ninp_new = gpkg_to_swmm('geopackage.gpkg', label_sep='.')\ninp_new.write_file('new_inputfile.inp')\n```\n\nFor example the default GIS export looks in QGIS like this:\n\n\n\n## Be Aware! \u26a0\ufe0f\n\n> As python is case-sensitive this API is also case-sensitive, but SWMM is case-insensitive. \n> This is important for the naming of the objects. \n> For example, you could create a junction 'a' and 'A' with this API, but SWMM would only consider one and ignore the other.\n\nAND\n\n> This package uses `utf-8` as default encoding for the file I/O (reading and writing inp, rpt and out files.)\n> 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'`).\n\nBut one can set a default encoding for the package using:\n```python\nfrom swmm_api import CONFIG\nCONFIG['encoding'] = 'iso-8859-1'\n```\n\nYou can also set a default SWMM exe for the package using:\n```python\nCONFIG['exe_path'] = r'C:\\path\\to\\runswmm.exe'\n```\n\n---\n\nThis documentation will be continuously extended and enhanced. \nIf you have any question, don't hesitate to write the author and email or create an issue on GitLab or GitHub.\n\nMORE INFORMATION COMING SOON\n\n## Cite as\n\n> *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*\n\n## Publications using or mentioning swmm-api \ud83d\udcda\n\n1. Baumann, H., Ravn, N. H., & Schaum, A. (2022). Efficient hydrodynamic modelling of urban stormwater systems for real-time applications. *Modelling, 3(4)*, 464\u2013480. <https://doi.org/10.3390/modelling3040030>\n2. 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>\n3. Schilling, J., & Tr\u00e4nckner, 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>\n4. Wicki, T. (2022). Effekt der Einzugsgebietsmodellierung auf die Abflusssimulation im urbanen Gebiet. Master thesis. Paris Lodron-Universit\u00e4t Salzburg. <https://unigis.at/files/Mastertheses/Full/106726.pdf>\n5. 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>\n6. 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\u20131028. <https://doi.org/10.2166/wst.2023.027>\n7. 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>\n8. 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>\n9. 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), e2022WR033854. <https://doi.org/10.1029/2022WR033854>\n10. 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\u2013934. <https://doi.org/10.2166/wst.2024.261>\n11. Pichler, M., K\u00f6nig, 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>\n12. 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>\n\n\n## Packages or repositories using swmm-api (on GitHub)\n\n[MarkusPic / swmm-model-simplification](https://github.com/MarkusPic/swmm-model-simplification)\n\n- [alBartig / PacketSWMM](https://github.com/alBartig/PacketSWMM) | [swmmRouting](https://github.com/alBartig/swmmRouting) | [SWMMpulse](https://github.com/alBartig/SWMMpulse)\n- [Zhiyu014 / GNN-UDS](https://github.com/Zhiyu014/GNN-UDS) | [MARL-UDS](https://github.com/Zhiyu014/MARL-UDS)\n- [QianyangWang / PyCUP](https://github.com/QianyangWang/PyCUP)\n- [Ahad-Hasan-Tanim10 / Bayes_opt-SWMM](https://github.com/Ahad-Hasan-Tanim10/Bayes_opt-SWMM)\n- [zhentaoumich / pyswmm_viz](https://github.com/zhentaoumich/pyswmm_viz) | [pyswmm / pyswmm_viz](https://github.com/pyswmm/pyswmm_viz)\n- [NidaboyinTokyo / ProjectShiERD](https://github.com/NidaboyinTokyo/ProjectShiERD)\n\n\n## Alternative packages\n\n- **swmmr** / R-language / [GitHub](https://github.com/dleutnant/swmmr) / [cran](https://cran.r-project.org/web/packages/swmmr/index.html)\n- **MatSWMM** / Matlab / [GitHub](https://github.com/gandresr/MatSWMM) \n- **swmmNode** / TypeScript / [GitHub](https://github.com/swmm-js/swmmNode)\n\n---\n\n- **swmmio** / [docs](https://swmmio.readthedocs.io/en/latest/) / [pypi](https://pypi.org/project/swmmio/) / [GitHub](https://github.com/aerispaha/swmmio) / simular to this package but more high-level approach (= slower for specific tasks)\n- **GisToSWMM5** / [GitHub](https://github.com/AaltoUrbanWater/GisToSWMM5) / 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`)\n- **swmmtoolbox** / [GitHub](https://github.com/timcera/swmmtoolbox) / 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.\n- **swmmnetwork** / [GitHub](https://github.com/austinorr/swmmnetwork) / create graph network from swmm model (see `swmm_api.input_file.macros.inp_to_graph`)\n- **SWMMOutputAPI** / [GitHub](https://github.com/bemcdonnell/SWMMOutputAPI) / read the output file (see `swmm_api.output_file.out`) / (OpenWaterAnalytics)\n- **swmm-pandas** / [pypi](https://pypi.org/project/swmm-pandas/) / equal functionalities to this package, but not feature complete\n- **swmmout** / [pypi](https://pypi.org/project/swmmout/) / [docs](https://swmmout.readthedocs.io/en/latest/) / simular to `swmmtoolbox` and `SWMMOutputAPI`\n- **swmmtonetcdf** / [pypi](https://pypi.org/project/swmmtonetcdf/) / [GitHub](https://github.com/cbuahin/swmmtonetcdf)\n- **hymo** / [GitHub](https://github.com/lucashtnguyen/hymo) Input and Report Reader (Lucas Nguyen)\n- **shmm** / [GitHub](https://github.com/lucashtnguyen/shmm) Input Reader (Lucas Nguyen)\n- **swmmreport** / [GitHub](https://github.com/lucashtnguyen/swmmreport) Report Reader (Lucas Nguyen)\n- **swmmdoodler** / [GitHub](https://github.com/Geosyntec/swmmdoodler)\n\n### Other SWMM-related python-packages\n\n- **pyswmm** / [pypi](https://pypi.org/project/pyswmm/) / [GitHub](https://github.com/OpenWaterAnalytics/pyswmm) / [Website](https://www.pyswmm.org) / RTC, etc. / based on swmm-toolkit (OpenWaterAnalytics)\n- **swmm-toolkit** / [pypi](https://pypi.org/project/swmm-toolkit/) / [GitHub](https://github.com/OpenWaterAnalytics/swmm-python) / by Michael Tryby (OpenWaterAnalytics)\n- **SWMM5** / [pypi](https://pypi.org/project/SWMM5/) / [GitHub](https://github.com/asselapathirana/swmm5-python) / simular approach to swmm-toolkit (by Assela Pathirana)\n- **SWMM-xsections-shape-generator** / [pypi](https://pypi.org/project/SWMM-xsections-shape-generator/) / tool to generate custom shapes (by me)\n- **SWMM_EA** / [pypi](https://pypi.org/project/SWMM5_EA/) / usage of genetic algorithms with SWMM (by Assela Pathirana)\n- **OSTRICH-SWMM** / [GitHub](https://github.com/ubccr/ostrich-swmm) / OSTRICH optimization software toolkit with SWMM\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "API for reading, manipulating and running US-EPA-SWMM-Projects",
"version": "0.4.60",
"project_urls": {
"Changelog": "https://gitlab.com/markuspichler/swmm_api/-/blob/main/CHANGELOG.md",
"Documentation": "https://markuspichler.gitlab.io/swmm_api",
"Homepage": "https://gitlab.com/markuspichler/swmm_api"
},
"split_keywords": [
"swmm",
" environment",
" civil_engineering",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5abe88fc74137bbc74a80784c0d5ce98b6c7346a63e851bf08b9cc3b518f2d24",
"md5": "63c0812a3671469a6a8e7025e7dc9cf6",
"sha256": "dba8263682901bce05a309371ecca226e3b58797653737a58447f434987a437a"
},
"downloads": -1,
"filename": "swmm_api-0.4.60-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63c0812a3671469a6a8e7025e7dc9cf6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 288276,
"upload_time": "2024-11-20T22:33:38",
"upload_time_iso_8601": "2024-11-20T22:33:38.962476Z",
"url": "https://files.pythonhosted.org/packages/5a/be/88fc74137bbc74a80784c0d5ce98b6c7346a63e851bf08b9cc3b518f2d24/swmm_api-0.4.60-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eeb735f5ca3924617eca7cf483e434407c2e615fe5928d5f88a77b307344cacf",
"md5": "b48bb46359f5907f6f3963d826accf05",
"sha256": "0fc1f0a0d9bee0a5b7f6a384d7e8d28f48949646a117979597ae2715701db7e8"
},
"downloads": -1,
"filename": "swmm_api-0.4.60.tar.gz",
"has_sig": false,
"md5_digest": "b48bb46359f5907f6f3963d826accf05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 250020,
"upload_time": "2024-11-20T22:33:41",
"upload_time_iso_8601": "2024-11-20T22:33:41.048794Z",
"url": "https://files.pythonhosted.org/packages/ee/b7/35f5ca3924617eca7cf483e434407c2e615fe5928d5f88a77b307344cacf/swmm_api-0.4.60.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 22:33:41",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "markuspichler",
"gitlab_project": "swmm_api",
"lcname": "swmm-api"
}
JSON