#WhatIsSwmmAPI

1. What is swmm-api?

swmm-api is an open-source Python library that provides a low-level, real-time interface to the EPA Storm Water Management Model (SWMM). It allows Python developers to:

• Read, modify, and control SWMM simulations dynamically
• Access internal states of SWMM objects at each timestep
• Inject custom control logic for pumps, valves, inflows, or rain events
• Integrate SWMM models into automated workflows, simulations, or optimization loops

Unlike high-level tools like PySWMM, swmm-api provides direct memory access to the internal SWMM simulation, making it extremely powerful for real-time control, data assimilation, and fine-grained simulation manipulation.

It is developed and maintained by jbgo/swmm-api and supports SWMM5 engine integration across platforms.

#SwmmAPIUseCases

2. Major Use Cases of swmm-api

The swmm-api package offers advanced control and automation for stormwater simulations. It is best suited for professionals and developers requiring programmatic, stepwise control of the simulation process.

💧 2.1. Real-Time Control (RTC) of Urban Drainage Systems

• Implement sensor-driven control of gates, pumps, or regulators
• Integrate SCADA systems to drive SWMM control logic
• Update model parameters based on live weather or flow data

🧪 2.2. Calibration and Sensitivity Analysis

• Adjust parameters (e.g., catchment area, slope, or roughness) during runtime
• Run multiple simulation iterations programmatically
• Export results for analysis or optimization

📊 2.3. Research and Custom Simulation Scenarios

• Experiment with novel flow control strategies
• Apply machine learning to predict optimal setpoints
• Conduct storm event scenario testing with variable rainfall profiles

📡 2.4. Data Assimilation and Digital Twins

• Ingest real-time sensor data (rainfall, depth, flow) and simulate system response
• Use SWMM as a digital twin of a physical urban stormwater system
• Validate and refine predictive models in real-time

🧰 2.5. Automation and Workflow Integration

• Integrate with CI/CD pipelines, APIs, or data dashboards
• Use in notebooks or remote simulations
• Combine with optimization libraries like scipy.optimize or pyomo

#SwmmAPIArchitecture

3. How swmm-api Works – Architecture Overview

The swmm-api package operates by directly interfacing with the SWMM5 engine’s compiled binary (usually swmm5.dll or swmm5.so) and accessing its simulation memory using Python’s ctypes module.

🧱 3.1. Architecture Layers

✅ A. SWMM Engine (Core)

• Original C-based SWMM5 engine (e.g., version 5.1.15 or newer)
• Responsible for time-based hydrologic/hydraulic simulations
• Processes .inp files defining system topology and parameters

✅ B. swmm-api Memory Interface

• Loads SWMM engine dynamically using ctypes
• Attaches to the in-memory objects used during simulation
• Provides access to core SWMM structures like:
  • Nodes
  • Links
  • Subcatchments
  • Controls

✅ C. Python Interface Layer

• Offers Pythonic classes and methods to:
  • Read simulation outputs in real time
  • Set inflows, control settings, and time parameters
  • Monitor water quality, depth, volume, and more

✅ D. User Script / Application

• Typically written in Python
• Drives the simulation loop, custom control logic, optimization, or logging
• Optionally visualizes results using matplotlib, pandas, or Plotly

#SwmmAPIWorkflow

4. Basic Workflow of swmm-api

Here’s a high-level view of how a typical swmm-api based simulation workflow proceeds:

🔄 Simulation Loop Workflow

🔍 Access Points

• getNodeParam, setLinkFlow, getRainfall
• stepSimulation, getSimulationTime, getWaterQuality
• All access is low-level and performant (direct pointer access)

#GettingStartedWithSwmmAPI

5. Step-by-Step Guide to Using swmm-api

This guide assumes you’re familiar with SWMM .inp files and basic Python.

✅ Step 1: Install Dependencies

Clone the repository:

git clone https://github.com/jbgo/swmm-api.git
cd swmm-api
pip install -r requirements.txt

Install a compatible version of SWMM5 engine:

• Windows: download swmm5.dll
• Linux: compile swmm5.so
• Place it in your project directory or system path

✅ Step 2: Prepare a SWMM Model

Use EPA SWMM or QGIS plugin to create a .inp file defining:

• Subcatchments
• Junctions
• Pipes
• Control rules
• Simulation time and rainfall data

✅ Step 3: Initialize Simulation

from swmm_api.input_file import read_inp_file
from swmm_api.simulation import Simulation

inp = read_inp_file("model.inp")
sim = Simulation(inp)

sim.start()

✅ Step 4: Step Through Simulation

while not sim.is_finished():
    sim.step_advance()  # advance simulation
    flow = sim.get_link_result('C1')['flow_rate']
    depth = sim.get_node_result('J2')['depth']
    print(f"Flow at C1: {flow:.2f} m³/s, Depth at J2: {depth:.3f} m")

✅ Step 5: Inject Custom Logic

if depth > 1.5:
    sim.set_link_setting('C1', 0.3)  # throttle valve

✅ Step 6: Post-Process and Visualize

import matplotlib.pyplot as plt

times = sim.get_times()
flows = sim.get_link_result('C1')['flow_rate_series']

plt.plot(times, flows)
plt.title("Flow Rate at Conduit C1")
plt.xlabel("Time")
plt.ylabel("Flow (m³/s)")
plt.show()

✅ Step 7: Advanced Uses

• Combine with sensor data via requests or MQTT
• Integrate with Jupyter notebooks for interactive analysis
• Automate batch runs for calibration

The post Swmm-Api: Python-Powered Real-Time Access to EPA’s SWMM Models appeared first on scmGalaxy.

Urban water systems — from stormwater drains to sewer networks — are under increasing pressure due to rapid urbanization and climate change. Traditional tools like EPA SWMM (Storm Water Management Model) have long been used for modeling such systems, but they are often limited by outdated interfaces and batch-style execution.

Enter pyswmm, a powerful Python wrapper for SWMM that unlocks real-time control, dynamic simulation, and seamless integration into modern data-driven workflows. With pyswmm, engineers, researchers, and smart city developers can finally build intelligent, reactive, and automated urban water management systems.

#WhatIsPyswmm

🔍 1. What is pyswmm?

pyswmm is an open-source Python wrapper for the EPA’s Storm Water Management Model (SWMM), enabling seamless interaction with SWMM simulations in real-time. Developed and maintained by the Open Water Analytics (OWA) community, pyswmm bridges the gap between hydrologic/hydraulic modeling and modern data-driven Python workflows.

While SWMM is traditionally used for long-term rainfall-runoff simulation in urban drainage systems, pyswmm allows dynamic control, monitoring, and analysis of model parameters during simulation runs. This makes it a valuable tool for integrating SWMM into smart city applications, optimization tasks, and adaptive stormwater system control.

✅ Core Capabilities:

• Real-time access to simulation objects (nodes, links, subcatchments, etc.)
• On-the-fly model parameter updates
• Integration with machine learning and optimization libraries
• Compatible with Jupyter, pandas, NumPy, matplotlib, etc.

#PyswmmUseCases

💡 2. Major Use Cases of pyswmm

pyswmm is used extensively in water resource engineering, research, and smart infrastructure management. Its reactive capabilities empower both simulation and control workflows.

🌧️ 2.1. Real-Time Control (RTC) of Stormwater Systems

• Implement adaptive control policies for valves, pumps, and weirs during a simulation.
• Optimize performance under changing rainfall patterns or sensor inputs.

📈 2.2. Post-Processing & Time-Series Analysis

• Extract flow, depth, velocity, and flooding results directly into Python.
• Use pandas and matplotlib for detailed plots, dashboards, and analysis.

🔄 2.3. Model Calibration and Sensitivity Testing

• Perform automated parameter sweeps using scipy.optimize or custom algorithms.
• Tune hydrologic parameters like infiltration or catchment characteristics.

🧪 2.4. Machine Learning and Predictive Modeling

• Train ML models using simulation outputs.
• Use predictive models to inform simulation inputs dynamically.

🏙️ 2.5. Integration with IoT and Smart Cities

• Combine pyswmm with real-time sensor data to simulate or control urban drainage networks.
• Create digital twins for flood forecasting and emergency planning.

#PyswmmArchitecture

🏗️ 3. How pyswmm Works – Architecture Overview

pyswmm interacts with SWMM’s underlying C-based dynamic link library (DLL) or shared object using Python bindings. It exposes simulation objects and internal processes in a Pythonic, object-oriented format.

⚙️ Key Architectural Components

🔄 Interaction Flow

1. User initializes a simulation via Simulation(model_path)
2. pyswmm loads the SWMM model and begins a time-stepped run
3. At each timestep:
   • State variables (flow, depth) can be read
   • Control actions (e.g., valve positions) can be updated
4. Output data is extracted and optionally written to CSV, Excel, or visualized

#PyswmmWorkflow

🔁 4. Basic Workflow of pyswmm

This makes pyswmm ideal for embedding SWMM within larger data pipelines and optimization frameworks.

#PyswmmGettingStarted

🚀 5. Step-by-Step Getting Started Guide

✅ Step 1: Install pyswmm

Make sure Python (3.6+) is installed.

pip install pyswmm

✅ Step 2: Download EPA SWMM

Install EPA SWMM to get access to the GUI and base engine:

• https://www.epa.gov/water-research/storm-water-management-model-swmm

Ensure that your system path includes the SWMM dynamic library (DLL on Windows, .so/.dylib on Unix/Mac).

✅ Step 3: Load Your First Model

from pyswmm import Simulation, Nodes

model_path = "C:/models/sample_model.inp"

with Simulation(model_path) as sim:
    node = Nodes(sim)["J1"]
    for step in sim:
        print(f"Time: {sim.current_time}, Depth at J1: {node.depth:.2f} m")

✅ Step 4: Apply Custom Control Logic

from pyswmm import Links

link = Links(sim)["C1"]

for step in sim:
    if node.depth > 1.0:
        link.target_setting = 0.5  # Partially close
    else:
        link.target_setting = 1.0  # Fully open

✅ Step 5: Plot or Export Data

Use pandas or matplotlib for analysis:

import matplotlib.pyplot as plt

depths = []
times = []

with Simulation("model.inp") as sim:
    node = Nodes(sim)["J1"]
    for step in sim:
        times.append(sim.current_time)
        depths.append(node.depth)

plt.plot(times, depths)
plt.title("Node J1 Depth Over Time")
plt.xlabel("Time")
plt.ylabel("Depth (m)")
plt.grid(True)
plt.show()

The post pyswmm: Python-Powered Control and Simulation for Urban Water Systems appeared first on scmGalaxy.