├── .github └── FUNDING.yml ├── gis_export_bellinge_simple_light.png ├── setup.py ├── CITATION.cff ├── requirements.txt ├── LICENSE ├── setup.cfg ├── pyproject.toml ├── CONTRIBUTING.md └── README.md /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | buy_me_a_coffee: MarkusP 2 | -------------------------------------------------------------------------------- /gis_export_bellinge_simple_light.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MarkusPic/swmm_api/HEAD/gis_export_bellinge_simple_light.png -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup 2 | from swmm_api import __version__ 3 | # __version__ = '0.3.3' 4 | 5 | setup(version=__version__) 6 | -------------------------------------------------------------------------------- /CITATION.cff: -------------------------------------------------------------------------------- 1 | cff-version: 1.2.0 2 | message: "If you use this software, please cite it as below." 3 | type: journalArticle 4 | authors: 5 | - family-names: "Pichler" 6 | given-names: "Markus" 7 | orcid: "https://orcid.org/0000-0002-8101-2163 " 8 | 9 | title: "swmm_api: A Python Package for Automation, Customization, and Visualization in SWMM-Based Urban Drainage Modeling" 10 | doi: 10.3390/w17091373 11 | date-released: 2025-05-01 12 | url: "https://www.mdpi.com/2073-4441/17/9/1373" 13 | issn: 2073-4441 14 | issue: 9 15 | journal: Water 16 | languages: 17 | - en 18 | pages: 1373 19 | volume: 17 20 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | # REQUIRED 2 | numpy 3 | pandas 4 | tqdm 5 | 6 | # for OPTIONAL functionality 7 | networkx # analyse network (some marcos i.e. splitting the network at a give node) 8 | fastparquet # write out-file timeseries as parquet file 9 | matplotlib # plot the sewer-network, longitudinal section or timeseries 10 | Shapely # handle GIS data 11 | pyproj # handle GIS data 12 | Rtree # handle GIS data 13 | geopandas # handle GIS data 14 | fiona # read and write to GIS database 15 | SWMM_xsections_shape_generator # analyse cross-section information 16 | pyswmm # run swmm with progress bar (tqdm) 17 | swmm-toolkit # run swmm 18 | cchardet # get inp-file encoding 19 | 20 | scikit-learn -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Markus 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | name = swmm-api 3 | version = attr: swmm_api.__version__ 4 | 5 | url = https://gitlab.com/markuspichler/swmm_api 6 | project_urls = 7 | Documentation = https://markuspichler.gitlab.io/swmm_api 8 | Changelog = https://gitlab.com/markuspichler/swmm_api/-/blob/master/CHANGES.md 9 | 10 | license = MIT 11 | license_files = 12 | LICENSE 13 | author = Markus Pichler 14 | author_email = markus.pichler@tugraz.at 15 | description = US-EPA-SWMM python interface 16 | long_description = file: README.md 17 | long_description_content_type = text/markdown 18 | classifiers = 19 | Programming Language :: Python :: 3 20 | License :: OSI Approved :: MIT License 21 | Operating System :: OS Independent 22 | Development Status :: 4 - Beta 23 | Natural Language :: English 24 | Topic :: Scientific/Engineering 25 | Topic :: Scientific/Engineering :: Hydrology 26 | Intended Audience :: Science/Research 27 | 28 | keywords = 29 | swmm 30 | environment 31 | civil_engineering 32 | api 33 | 34 | [options] 35 | python_requires = >= 3.7 36 | include_package_data = True 37 | packages = 38 | swmm_api 39 | swmm_api.report_file 40 | swmm_api.output_file 41 | swmm_api.input_file 42 | swmm_api.hotstart_file 43 | swmm_api._io_helpers 44 | swmm_api.run_swmm 45 | swmm_api.input_file.sections 46 | swmm_api.input_file.misc 47 | swmm_api.input_file.macro_snippets 48 | swmm_api.input_file.macros 49 | install_requires = 50 | numpy 51 | pandas 52 | tqdm 53 | 54 | [options.extras_require] 55 | macros = 56 | networkx 57 | fastparquet 58 | matplotlib 59 | SWMM_xsections_shape_generator 60 | 61 | gis = 62 | Shapely 63 | pyproj 64 | Rtree 65 | geopandas 66 | full = 67 | networkx 68 | fastparquet 69 | matplotlib 70 | SWMM_xsections_shape_generator 71 | Shapely 72 | pyproj 73 | Rtree 74 | geopandas -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools", "wheel"] 3 | build-backend = "setuptools.build_meta" 4 | 5 | 6 | [project] 7 | name = "swmm-api" 8 | description = "US-EPA-SWMM python interface" 9 | readme = "README.md" 10 | authors = [ 11 | { name = "Markus Pichler", email = "markus.pichler@tugraz.at" } 12 | ] 13 | requires-python = ">=3.7" 14 | keywords = ["swmm", "environment", "civil_engineering", "api"] 15 | license = { text = "MIT" } 16 | classifiers = [ 17 | "Programming Language :: Python :: 3", 18 | "License :: OSI Approved :: MIT License", 19 | "Operating System :: OS Independent", 20 | "Development Status :: 4 - Beta", 21 | "Natural Language :: English", 22 | "Topic :: Scientific/Engineering", 23 | "Topic :: Scientific/Engineering :: Hydrology", 24 | "Intended Audience :: Science/Research", 25 | ] 26 | dependencies = [ 27 | "numpy", 28 | "pandas", 29 | "tqdm" 30 | ] 31 | dynamic = ["version"] 32 | 33 | [tool.setuptools.dynamic] 34 | version = { attr = "swmm_api.__version__" } 35 | 36 | [project.optional-dependencies] 37 | macros = ["networkx", "fastparquet", "matplotlib", "SWMM_xsections_shape_generator", "pyswmm"] 38 | gis = ["Shapely", "pyproj", "Rtree", "geopandas"] 39 | full = ["networkx", "fastparquet", "matplotlib", "SWMM_xsections_shape_generator", "Shapely", "pyproj", "Rtree", "geopandas", "pyswmm"] 40 | docs = ["networkx", "fastparquet", "matplotlib", "Shapely", "pyproj", "Rtree", "geopandas", "SWMM_xsections_shape_generator", 41 | "sphinx", "nbsphinx", "recommonmark", "pydata_sphinx_theme"] 42 | 43 | [project.urls] 44 | Documentation = "https://markuspichler.gitlab.io/swmm_api" 45 | Changelog = "https://gitlab.com/markuspichler/swmm_api/-/blob/master/CHANGELOG.md" 46 | homepage = "https://gitlab.com/markuspichler/swmm_api" 47 | 48 | [tool.setuptools.packages.find] 49 | exclude = ['joss_paper*', 'docker_website*', 'documentation*', 'examples*'] 50 | namespaces = false 51 | 52 | 53 | # https://github.com/python-semantic-release/python-semantic-release 54 | [tool.semantic_release] 55 | version_variable = 'swmm_api/__init__.py:__version__' # "setup.py:__version__" # 56 | upload_to_pypi = true 57 | hvcs = 'gitlab' 58 | branch = 'main' 59 | major_on_zero = false 60 | version_source = 'commit' # 'tag' 'tag_only' commit 61 | commit_subject = 'New version v{version} 🔥' -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Thank you for considering contributing to this project! Your help is greatly appreciated. 4 | 5 | ## How to Contribute 6 | 7 | ### Reporting Issues 8 | If you encounter a bug, have a feature request, or need clarification, please open an issue in the [Gitlab Issues](https://gitlab.com/markuspichler/swmm_api/-/issues) section. 9 | If you don't have an GitLab account you can use also open an issue in the [GitHub Issues](https://github.com/MarkusPic/swmm_api/issues) section. 10 | When reporting a bug, include: 11 | 12 | - A clear description of the issue 13 | - Steps to reproduce 14 | - Expected vs. actual behavior 15 | - Any relevant error messages or logs 16 | 17 | ### Submitting Code Changes 18 | 1. **Fork the repository** and clone it locally. 19 | 2. **Create a new branch** for your feature or fix: 20 | ```sh 21 | git checkout -b feature-name 22 | ``` 23 | 3. **Make your changes** and ensure they follow the project's coding style. 24 | 4. **Run tests** to verify your changes: 25 | ```sh 26 | pytest tests 27 | ``` 28 | 5. **Commit your changes** with a meaningful message: 29 | ```sh 30 | git commit -m "Describe your change briefly" 31 | ``` 32 | 6. **Push the branch** to your fork: 33 | ```sh 34 | git push origin feature-name 35 | ``` 36 | 7. **Create a Pull Request (PR)** from your branch to the `main` branch. 37 | 38 | #### Code Style 39 | This project follows standard Python best practices ([PEP 8](https://pep8.org)). 40 | 41 | Please ensure your code is typed where applicable using type hints. 42 | 43 | Make sure that every function has a docstring with types. We use the [Google style docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings). Here is an [example for a Google style docstring](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html). 44 | 45 | 46 | ### Writing Tests 47 | If your contribution includes code changes, please add or update tests to maintain high code quality. We use `pytest` for testing. All tests are located in the tests folder: 48 | ```sh 49 | pytest tests 50 | ``` 51 | Ensure all tests pass before submitting your PR. 52 | 53 | ### Reviewing Pull Requests 54 | We encourage contributors to review open PRs and provide constructive feedback. 55 | 56 | ### Donate 57 | 58 | If you find this project useful, consider supporting it by [buying me a coffee](https://www.buymeacoffee.com/MarkusP). 59 | 60 | ### Other Ways to Contribute 61 | 62 | * Writing tutorials or examples using [Gitlab Snippets](https://gitlab.com/markuspichler/swmm_api/-/snippets) or [GitHub Gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists) and referencing them in [discussions](https://github.com/MarkusPic/swmm_api/discussions/categories/show-and-tell). 63 | * Fixing typos and improving the documentation by opening issues or creating pull requests. 64 | 65 | ## Getting Help 66 | If you have any questions, feel free to open a discussion in the [Matrix Chat](https://matrix.to/#/#swmm-api-python:matrix.org) or [GitHub Discussions](https://github.com/MarkusPic/swmm_api/discussions) or comment on an open issue. 67 | 68 | 69 | ## Ground Rules 70 | The goal is to maintain a diverse community that's pleasant for everyone. 71 | **Please be considerate and respectful of others**. Everyone must abide by our 72 | [Code of Conduct](https://gitlab.com/markuspichler/swmm_api/-/blob/main/code_of_conduct.md) 73 | and we encourage all to read it carefully. 74 | 75 | ## Miscellaneous 76 | For more information on contributing to open source projects, 77 | [GitHub's own guide](https://opensource.guide/how-to-contribute) 78 | is a great starting point if you are new to version control. Also, checkout the 79 | [Zen of Scientific Software Maintenance](https://jrleeman.github.io/ScientificSoftwareMaintenance/) 80 | for some guiding principles on how to create high quality scientific software 81 | contributions. 82 | 83 | Thank you for contributing! 84 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [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) 2 | 3 | # THIS IS A SNAPSHOT OF THE ORIGINAL README 4 | 5 | Go to [GitLab](https://gitlab.com/markuspichler/swmm_api) to see the full source. 6 | 7 | # Getting started 💡 8 | 9 | [![PyPI](https://img.shields.io/pypi/v/swmm-api.svg?logo=pypi&logoColor=white)](https://pypi.python.org/pypi/swmm-api) 10 | [![pipeline status](https://gitlab.com/markuspichler/swmm_api/badges/main/pipeline.svg)](https://gitlab.com/markuspichler/swmm_api/-/commits/main) 11 | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 12 | [![docs](https://img.shields.io/static/v1.svg?label=&message=documentation&color=blue&logo=readthedocs&logoColor=white)](https://markuspichler.gitlab.io/swmm_api) 13 | [![DOI](https://img.shields.io/badge/10.3390/w17091373-white?logo=doi)](https://doi.org/10.3390/w17091373) 14 | [![Latest Release](https://gitlab.com/markuspichler/swmm_api/-/badges/release.svg)](https://gitlab.com/markuspichler/swmm_api/-/releases) 15 | [![Matrix](https://img.shields.io/matrix/swmm_api_python%3Amatrix.org?style=flat&logo=matrix)](https://matrix.to/#/#swmm_api_python:matrix.org) 16 | [![Buymeacoffee](https://badgen.net/badge/icon/buymeacoffee?icon=buymeacoffee&label=donate)](https://www.buymeacoffee.com/MarkusP) 17 | 18 | [![PyPI - Downloads](https://img.shields.io/pypi/dd/swmm-api)](https://pypi.python.org/pypi/swmm-api) 19 | [![PyPI - Downloads](https://img.shields.io/pypi/dw/swmm-api)](https://pypi.python.org/pypi/swmm-api) 20 | [![PyPI - Downloads](https://img.shields.io/pypi/dm/swmm-api)](https://pypi.python.org/pypi/swmm-api) 21 | 22 | 23 | With this package you can: 24 | - read, manipulate and write [INP-files](https://markuspichler.gitlab.io/swmm_api/examples/inp_file_reader.html). 25 | - many macros can be found for analysing and manipulating the input data in the package under [`swmm_api.input_file.macros`](https://markuspichler.gitlab.io/swmm_api/api_reference/inp/macros.html) 26 | - start a SWMM simulation within this python package. 27 | - read the [report](https://markuspichler.gitlab.io/swmm_api/examples/rpt_file_reader.html) (.rpt) and [output](https://markuspichler.gitlab.io/swmm_api/examples/out_file_reader.html) (.out) files as a `pandas.DataFrame` for further analysis. 28 | - export the model to GIS for spatial data analysis (import function also available, but must be adopted depending on the used GIS files). 29 | 30 | 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)) 31 | 32 | 💡 The Technical Note in Water (MDPI) is published 💡 33 | 34 | > Pichler, M. (2025). swmm_api: A Python Package for Automation, Customization, and Visualization in SWMM-Based Urban Drainage Modeling. Water, 17(9), 1373. 35 | 36 | ## Introduction 37 | 38 | 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. 39 | 40 | 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. 41 | 42 | 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. 43 | 44 | ## Installation 45 | 46 | Ensure you have Python 3.8 or higher. 47 | 48 | Install using: 49 | 50 | ```bash 51 | pip install swmm-api 52 | ``` 53 | 54 | ... to install the package with all dependencies for macros use: 55 | 56 | ```bash 57 | pip install swmm-api[macros] 58 | ``` 59 | 60 | ... to install the package with all dependencies for GIS I/O use (for Linux or for Windows using python >= 3.10): 61 | 62 | ```bash 63 | pip install swmm-api[gis] 64 | ``` 65 | 66 | ... and to install the package with all dependencies for macros and GIS I/O use (for Linux or for Windows using python >= 3.10): 67 | 68 | ```bash 69 | pip install swmm-api[full] 70 | ``` 71 | 72 | To add the GIS functionality on **Windows**, I recommend using python version >= 3.10 or with [Mamba](https://github.com/conda-forge/miniforge#mambaforge) 73 | (or [miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Anaconda](https://www.anaconda.com/)) 74 | and run `mamba install geopandas` to install the GIS dependencies (see [GeoPandas](https://geopandas.org/en/stable/getting_started.html)). 75 | 76 | Here you can see which packages are getting installed: 77 | 78 | | packages | required | macros | gis | full | docs | 79 | |:------------------------------:|:--------:|:------:|:---:|:----:|:----:| 80 | | pandas | x | x | x | x | x | 81 | | tqdm | x | x | x | x | x | 82 | | networkx | | x | | x | x | 83 | | pyarrow | | x | | x | x | 84 | | matplotlib | | x | | x | x | 85 | | SWMM_xsections_shape_generator | | x | | x | x | 86 | | pyswmm | | x | | x | x | 87 | | geopandas | | | x | x | x | 88 | | sphinx | | | | | x | 89 | | nbsphinx | | | | | x | 90 | | recommonmark | | | | | x | 91 | | pydata_sphinx_theme | | | | | x | 92 | 93 | ![Python-packages Dependency Tree](documentation/images/dependency_tree.svg) 94 | 95 | [![Python-packages Dependency Tree online](https://mermaid.ink/img/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?type=png)](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) 96 | 97 | ## Documentation 📖 98 | [Link](https://markuspichler.gitlab.io/swmm_api) to the documentation of the package and some example jupyter notebooks. 99 | 100 | [Here](https://gitlab.com/markuspichler/swmm_api/-/tree/main/examples) are example files for other use-cases. 101 | 102 | ## Community and Support 103 | 104 | For questions or feedback, join the [Matrix chat](https://matrix.to/#/#swmm-api-python:matrix.org) or create an issue on [GitLab](https://gitlab.com/markuspichler/swmm_api). 105 | 106 | There is also a [GitHub page](https://github.com/MarkusPic/swmm_api) for this project, so feel free to [open an issue](https://github.com/MarkusPic/swmm_api/issues) of [start a discussion](https://github.com/MarkusPic/swmm_api/discussions) there if you don't have a gitlab account. 107 | 108 | If you like this project and want to show your support, consider donate with [buy me a coffee](https://www.buymeacoffee.com/MarkusP). 109 | 110 | 111 | ## Read, manipulate and write the INP-File 112 | 113 | ### Read the INP-File 114 | 115 | ```python 116 | from swmm_api import read_inp_file, SwmmInput 117 | 118 | inp = read_inp_file('inputfile.inp') # type: swmm_api.SwmmInput 119 | # or 120 | inp = SwmmInput.read_file('inputfile.inp') 121 | # or 122 | inp = SwmmInput('inputfile.inp') 123 | 124 | ``` 125 | 126 | ### Getting information 127 | 128 | ```python 129 | from swmm_api.input_file.section_labels import TIMESERIES 130 | 131 | # getting a specific section of the inp-file 132 | 133 | sec_timeseries = inp[TIMESERIES] # type: swmm_api.input_file.helpers.InpSection 134 | # or 135 | sec_timeseries = inp.TIMESERIES # type: swmm_api.input_file.helpers.InpSection 136 | 137 | # getting a specific timeseries as pandas.Series 138 | ts = inp[TIMESERIES]['regenseries'].pandas # type: pandas.Series 139 | ``` 140 | 141 | ### Manipulate the INP-File 142 | 143 | ```python 144 | from swmm_api.input_file.section_labels import JUNCTIONS 145 | 146 | # setting the elevation of a specific node to a new value 147 | 148 | inp[JUNCTIONS]['J01'].elevation = 210 149 | # or 150 | inp.JUNCTIONS['J01'].elevation = 210 151 | # or 152 | inp.JUNCTIONS['J01']['elevation'] = 210 153 | ``` 154 | 155 | ### Write the manipulated INP-File 156 | ```python 157 | inp.write_file('new_inputfile.inp') 158 | ``` 159 | 160 | see [examples/inp_file_reader.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_reader.ipynb) 161 | 162 | see [examples/inp_file_structure.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/inp_file_structure.ipynb) 163 | 164 | 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. 165 | 166 | 167 | 168 | 169 | ## Run SWMM 170 | 171 | Run SWMM with a specified executable. (You can set a default SWMM exe using the CONFIG object or a config file, see below) 172 | 173 | ```python 174 | from swmm_api import swmm5_run 175 | swmm5_run('new_inputfile.inp', swmm_lib_path=r'C:\path\to\runswmm.exe') 176 | ``` 177 | 178 | Or run SWMM with [pyswmm](https://github.com/OpenWaterAnalytics/pyswmm). This would be platform independent as pyswmm is compiled for all platforms. 179 | Additionally, you gain the advantage of a progress bar. 180 | 181 | ```python 182 | from swmm_api import swmm5_run 183 | swmm5_run('new_inputfile.inp', progress_size=100) 184 | ``` 185 | 186 | ``` 187 | swmm5 C:\path\to\new_inputfile.inp: 77%|███████▋ | 77/100 [00:03<00:01, 22.36it/s, 2007-02-16 08:46:27] 188 | ``` 189 | 190 | ## Read the OUT-File 191 | ```python 192 | from swmm_api import read_out_file, SwmmOutput 193 | 194 | out = read_out_file('new_inputfile.out') # type: swmm_api.SwmmOut 195 | # or 196 | out = SwmmOutput('new_inputfile.out') 197 | 198 | df = out.to_frame() # type: pandas.DataFrame 199 | 200 | # or if only a single timeseries of the results is needed 201 | ts = out.get_part('node', 'J1', 'depth') # type: pandas.Series 202 | ``` 203 | see [examples/out_file_reader.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/out_file_reader.ipynb) 204 | 205 | 206 | ## Read the RPT-File 207 | ```python 208 | from swmm_api import read_rpt_file, SwmmReport 209 | 210 | rpt = read_rpt_file('new_inputfile.rpt') # type: swmm_api.SwmmReport 211 | # or 212 | rpt = SwmmReport('new_inputfile.rpt') 213 | 214 | node_flooding_summary = rpt.node_flooding_summary # type: pandas.DataFrame 215 | ``` 216 | see [examples/rpt_file_reader.ipynb](https://gitlab.com/markuspichler/swmm_api/-/blob/main/examples/rpt_file_reader.ipynb) 217 | 218 | ## GIS interactions 🗺️ 219 | 220 | [`geopandas`](https://geopandas.org/) must be installed! (Use python version >3.10 or conda (Anaconda|miniconda) on Windows) 221 | 222 | ```python 223 | from swmm_api import SwmmInput 224 | from swmm_api.input_file.macros.gis import write_geo_package, gpkg_to_swmm, complete_vertices 225 | 226 | inp = SwmmInput('inputfile.inp') 227 | 228 | coords = inp.COORDINATES.geo_series # type: geoandas.GeoSeries with points for all nodes 229 | 230 | complete_vertices(inp) # this will insert the start and end node points into the link vertices. 231 | # this function is automatically called in `write_geo_package`, but is needed if the geo-series of vertices is used directly. 232 | 233 | vertices = inp.VERTICES.geo_series # type: geoandas.GeoSeries with lines for all links 234 | polygons = inp.POLYGONS.geo_series # type: geoandas.GeoSeries with polygons for all subcatchments 235 | 236 | # create geopackage of all objects in inp file 237 | write_geo_package(inp, gpkg_fn='geopackage.gpkg', driver='GPKG', label_sep='.', crs="EPSG:32633", add_style=True) 238 | 239 | # read above written geopackage and convert it to inp-data 240 | inp_new = gpkg_to_swmm('geopackage.gpkg', label_sep='.') 241 | inp_new.write_file('new_inputfile.inp') 242 | ``` 243 | 244 | For example the default GIS export as a geo-package (with included styles) looks in QGIS like this: 245 | 246 | ![QGIS screenshot of Bellinge export](/documentation/images/gis_export_bellinge_simple_light.png) 247 | 248 | ## Be Aware! ⚠️ 249 | 250 | > As python is case-sensitive this API is also case-sensitive, but SWMM is case-insensitive. 251 | > This is important for the naming of the objects. 252 | > For example, you could create a junction 'a' and 'A' with this API, but SWMM would only consider one and ignore the other. 253 | 254 | AND 255 | 256 | > This package uses `utf-8` as default encoding for the file I/O (reading and writing inp, rpt and out files.) 257 | > 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'`). 258 | 259 | But one can set a default encoding for the package using: 260 | ```python 261 | from swmm_api import CONFIG 262 | CONFIG['encoding'] = 'iso-8859-1' 263 | ``` 264 | 265 | You can also set a default SWMM exe for the package using: 266 | ```python 267 | CONFIG['exe_path'] = r'C:\path\to\runswmm.exe' 268 | # or 269 | CONFIG.exe_path = r'C:\path\to\runswmm.exe' 270 | ``` 271 | 272 | ### New in version `0.4.61` 273 | 274 | You can save your default in a config file which will then be used by default in the future. 275 | simply set your default and use `CONFIG.save()`. This will save the cinfig data into the file `~/.config/swmm-api_config.json` 276 | 277 | ### New in version `0.4.64` 278 | 279 | You can also set a default Coordinate Reference System for the GIS import and export: 280 | ```python 281 | CONFIG['default_crs'] = 'EPSG:4326' 282 | # or 283 | CONFIG.default_crs = 'EPSG:4326' 284 | ``` 285 | 286 | --- 287 | 288 | This documentation will be continuously extended and enhanced. 289 | If you have any question, don't hesitate to write the author and email or create an issue on GitLab or GitHub. 290 | 291 | MORE INFORMATION COMING SOON 292 | 293 | ## Cite as 294 | 295 | > Pichler, M. (2025). swmm_api: A Python Package for Automation, Customization, and Visualization in SWMM-Based Urban Drainage Modeling. Water, 17(9), 1373. 296 | 297 | ## Publications using or mentioning `swmm_api` 📚 298 | 299 | ### 2022 300 | 301 | 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. 302 | 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. 303 | 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. 304 | 4. Wicki, T. (2022). Effekt der Einzugsgebietsmodellierung auf die Abflusssimulation im urbanen Gebiet. Master thesis. Paris Lodron-Universität Salzburg. 305 | 306 | ### 2023 307 | 308 | 5. 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. 309 | 6. Ryrfors Wien, C. (2023). Nature-based solution retrofit in an urban catchment for CSO reduction (Master's thesis, NTNU). 310 | 7. 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. 311 | 8. 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), 312 | 9. 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. 313 | 314 | ### 2024 315 | 316 | 10. Farina, A., Gargano, R., & Greco, R. (2024). Effects of urban catchment characteristics on combined sewer overflows. Environmental Research, 244, 117945. 317 | 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. 318 | 12. 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. 319 | 13. 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. 320 | 14. 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, 321 | 322 | ## Packages or repositories using `swmm_api` (on GitHub) 323 | 324 | [MarkusPic / swmm-model-simplification](https://github.com/MarkusPic/swmm-model-simplification) 325 | 326 | - [alBartig / PacketSWMM](https://github.com/alBartig/PacketSWMM) | [swmmRouting](https://github.com/alBartig/swmmRouting) | [SWMMpulse](https://github.com/alBartig/SWMMpulse) 327 | - [Zhiyu014 / GNN-UDS](https://github.com/Zhiyu014/GNN-UDS) | [MARL-UDS](https://github.com/Zhiyu014/MARL-UDS) 328 | - [QianyangWang / PyCUP](https://github.com/QianyangWang/PyCUP) 329 | - [Ahad-Hasan-Tanim10 / Bayes_opt-SWMM](https://github.com/Ahad-Hasan-Tanim10/Bayes_opt-SWMM) 330 | - [zhentaoumich / pyswmm_viz](https://github.com/zhentaoumich/pyswmm_viz) | [pyswmm / pyswmm_viz](https://github.com/pyswmm/pyswmm_viz) 331 | - [NidaboyinTokyo / ProjectShiERD](https://github.com/NidaboyinTokyo/ProjectShiERD) 332 | 333 | 334 | ## Alternative packages 335 | 336 | - **swmmr** / R-language / [GitHub](https://github.com/dleutnant/swmmr) / [cran](https://cran.r-project.org/web/packages/swmmr/index.html) 337 | - **MatSWMM** / Matlab / [GitHub](https://github.com/gandresr/MatSWMM) 338 | - **swmmNode** / TypeScript / [GitHub](https://github.com/swmm-js/swmmNode) 339 | 340 | --- 341 | 342 | - **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) 343 | - **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`) 344 | - **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. 345 | - **swmmnetwork** / [GitHub](https://github.com/austinorr/swmmnetwork) / create graph network from SWMM model (see `swmm_api.input_file.macros.inp_to_graph`) 346 | - **SWMMOutputAPI** / [GitHub](https://github.com/bemcdonnell/SWMMOutputAPI) / read the output file (see `swmm_api.output_file.out`) / (OpenWaterAnalytics) 347 | - **swmm-pandas** / [pypi](https://pypi.org/project/swmm-pandas/) / equal functionalities to this package, but not feature complete 348 | - **swmmout** / [pypi](https://pypi.org/project/swmmout/) / [docs](https://swmmout.readthedocs.io/en/latest/) / simular to `swmmtoolbox` and `SWMMOutputAPI` 349 | - **swmmtonetcdf** / [pypi](https://pypi.org/project/swmmtonetcdf/) / [GitHub](https://github.com/cbuahin/swmmtonetcdf) 350 | - **hymo** / [GitHub](https://github.com/lucashtnguyen/hymo) Input and Report Reader (Lucas Nguyen) 351 | - **shmm** / [GitHub](https://github.com/lucashtnguyen/shmm) Input Reader (Lucas Nguyen) 352 | - **swmmreport** / [GitHub](https://github.com/lucashtnguyen/swmmreport) Report Reader (Lucas Nguyen) 353 | - **swmmdoodler** / [GitHub](https://github.com/Geosyntec/swmmdoodler) 354 | 355 | ### Other SWMM-related python-packages 356 | 357 | - **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) 358 | - **swmm-toolkit** / [pypi](https://pypi.org/project/swmm-toolkit/) / [GitHub](https://github.com/OpenWaterAnalytics/swmm-python) / by Michael Tryby (OpenWaterAnalytics) 359 | - **SWMM5** / [pypi](https://pypi.org/project/SWMM5/) / [GitHub](https://github.com/asselapathirana/swmm5-python) / simular approach to `swmm-toolkit` (by Assela Pathirana) 360 | - **SWMM-xsections-shape-generator** / [pypi](https://pypi.org/project/SWMM-xsections-shape-generator/) / tool to generate custom shapes (by me) 361 | - **SWMM_EA** / [pypi](https://pypi.org/project/SWMM5_EA/) / usage of genetic algorithms with SWMM (by Assela Pathirana) 362 | - **OSTRICH-SWMM** / [GitHub](https://github.com/ubccr/ostrich-swmm) / OSTRICH optimization software toolkit with SWMM 363 | --------------------------------------------------------------------------------