PySWMM is a Python-based interface to the Stormwater Management Model (SWMM5)

Below is an extended and concise summary of the information provided in the README. It covers the motivation behind PySWMM, key capabilities, installation details, and community resources.

---

Overview and Purpose

PySWMM is a Python-based interface to the Stormwater Management Model (SWMM5)—a software tool widely used to simulate the hydraulic and hydrologic performance of stormwater networks. Developed to integrate seamlessly with SWMM5, PySWMM streamlines workflows by enabling advanced scripting, control, and data processing directly in Python. It empowers engineers, modelers, and researchers to automate stormwater modeling tasks, optimize system designs, perform detailed post-processing, and implement sophisticated real-time control (RTC) algorithms.

Core Features

1. SWMM Integration

   • Provides a direct API for accessing and manipulating SWMM’s core data (nodes, links, subcatchments, etc.).
   • Allows on-the-fly changes to model parameters (e.g., node inflows, link settings) during simulations.

2. Metadata and Time Series Analysis

   • Interacts with SWMM’s binary output files, enabling easy extraction of hydraulic and hydrologic time series.
   • Offers immediate insights into subcatchment runoff, node depths, link flows, and system-wide summary metrics.

3. Flexible Control Logic

   • Users can develop custom operational controls in Python for active stormwater management.
   • Moves beyond native SWMM rules by integrating Python’s full ecosystem (machine learning libraries, optimization routines, etc.).

4. Broad Compatibility

   • Supports various SWMM engine versions from 5.1.14 to 5.2.4, with pinned dependencies to swmm-toolkit.
   • Compatible with Python 3.7 to 3.12, ensuring accessibility for a wide range of computational environments.

Installation

Installing PySWMM typically involves a single command:

pip install pyswmm

For more targeted setups—such as specifying a particular SWMM engine version—PySWMM leverages Python extras:

pip install pyswmm[swmm5.2.4]

This approach makes it simple to match the PySWMM installation to different SWMM versions and toolkits as needed.

Getting Started and Usage

• Documentation & Tutorials

  • Official documentation is hosted at docs.pyswmm.org.
  • Additional learning resources, including video tutorials and practical examples, are available on the PySWMM YouTube Channel and via the project’s Example Bundles.

• Basic Workflow

  • Import the Simulation, Nodes, or Links classes to access and modify SWMM model components.
  • Step through a simulation with Python’s for loops to monitor or adjust parameters (e.g., node depth, link flow).
  • Use PySWMM’s Output class to read binary outfiles and extract time series for further analysis.

Community and Support

• Discussions and Questions

  • The project’s GitHub Discussions forum is the first stop for questions, ideas, and collaborative problem-solving.
  • Issues and bug reports should be submitted on GitHub Issues.

• Contributing

  • PySWMM is community-driven and welcomes contributions. New contributors can start by reviewing the guidelines on the project’s wiki.
  • The maintainers encourage pull requests, documentation improvements, and new feature proposals.

• SWAG Store

  • A dedicated storefront offers merchandise (e.g., hoodies, coffee cups) to help fund hosting and services associated with maintaining the project.

Citation and License

• Citation

  • If you use PySWMM in academic or professional research, please cite the paper published in the Journal of Open Source Software DOI: 10.21105/joss.02292.

• License

  • Distributed under a BSD2 license, encouraging open collaboration and broad usage. See LICENSE.txt for full terms.

---

In summary, PySWMM extends the capabilities of SWMM5 by providing a user-friendly Pythonic interface. It is ideal for users who want to do more advanced control, real-time scenario adjustments, or deeper data post-processing than what is available in native SWMM. With a supportive community, thorough documentation, and a straightforward installation process, PySWMM stands out as a robust tool for modern stormwater and urban drainage modeling projects.