PySWMM Documentation

The pyswmm.raingages module provides classes to interact with and manage rain gages within a SWMM5 simulation. It includes the RainGages container class for managing multiple gages and the RainGage class for interacting with individual rain gage objects.

To use these, you typically access them through a simulation instance. Detailed API signatures for RainGages and RainGage can be found in the specific API documentation.

The pyswmm.output module provides classes to extract time-series data and results from a completed SWMM simulation. You can access data for specific nodes, links, subcatchments, or the entire system using the following primary classes:

• Output: The base class for accessing simulation results.
• NodeSeries: For retrieving time-series data for nodes (e.g., junctions, outfalls).
• LinkSeries: For retrieving time-series data for links (e.g., conduits, orifices).
• SubcatchSeries: For retrieving time-series data for subcatchments.
• SystemSeries: For retrieving system-wide summary statistics and results.

PySWMM is a Python interface for the EPA's Stormwater Management Model (SWMM5). Unlike standard SWMM distributions that primarily rely on reading and writing .inp files (which creates data redundancy), PySWMM provides direct access to the SWMM data model.

This architecture allows for:

• Mid-simulation interaction: You can interact with the model during simulation time, rather than just before or after.
• Direct Data Access: Access node, link, subcatchment, LID statistics, and results both during and after simulation without duplicating the data model in external files.
• Parameter Manipulation: Use low-level getters and setters to edit hydraulic network settings, load externally-generated inflows, and manipulate Low Impact Development (LID) parameters on the fly.

PySWMM is designed to augment SWMM's capabilities while maintaining backward compatibility.

LID controls are composed of multiple layers. PySWMM exposes these layers through the pyswmm.lidlayers module. Each class in this module represents a specific type of layer within an LID Control object:

• Surface
• Soil
• Storage
• Pavement
• Drain
• DrainMat

You can use these classes to access or modify the properties of the specific layers that make up a defined LID control.

PySWMM allows you to move control rules from the native SWMM5 engine into Python. This enables the use of complex Python logic and external libraries for model control.

Priority and Execution:

• PySWMM control actions have the highest priority.
• They are evaluated at the end of each simulation step, after native EPA-SWMM5 controls have been evaluated.
• Any updates made via PySWMM are reported in the *.rpt file.

from pyswmm import Simulation, Links, Nodes

def TestDepth(node, node2):
    return node > node2

with Simulation('./testmodel.inp') as sim:
    link_object = Links(sim)
    c1c2 = link_object["C1:C2"]

    node_object = Nodes(sim)
    J1 = node_object["J1"]
    J2 = node_object["J2"]

    for step in sim:
        if TestDepth(J1.depth, J2.depth):
            c1c2.target_setting = 0.5

PySWMM provides access to objects defined in the [LID_CONTROLS] section of a SWMM input file through the pyswmm.lidcontrols module.

To interact with LID controls, you use the following classes:

• LidControls: Provides access to the collection of LID controls.
• LidControl: Represents an individual LID control object.

For detailed implementation patterns, refer to the LidControls API documentation.

You can install the latest version of PySWMM from PyPI using pip.

Starting from version 1.3.1, you can also specify a particular version of the SWMM engine (ranging from 5.1.14 to 5.2.4) during installation using pip extras.

# Standard installation
pip install pyswmm

# Install with a specific SWMM engine version
pip install pyswmm[swmm5.2.4]

You can load a model using the Simulation class. There are two primary ways to run it:

1. Simple Execution: Use sim.execute() if you only want to run the model without interacting with parameters during the simulation.
2. Manual Stepping: Use a with statement to iterate through the simulation steps. This is the recommended approach for interacting with the model (getting/setting parameters) while it runs. The with statement ensures automatic cleanup when the simulation completes.

from pyswmm import Simulation

# Option 1: Simple execution
sim = Simulation('./testmodel.inp')
sim.execute()

# Option 2: Manual stepping with interaction
with Simulation('./testmodel.inp') as sim:
    for step in sim:
        pass

To use PySWMM, import the Simulation class from the pyswmm module. You can then initialize a simulation object by passing the path to a SWMM input file (*.inp) to the Simulation constructor. Once initialized, you can run or edit the simulation using the available methods on the simulation object.

from pyswmm import Simulation

# Initialize a SWMM model with an input file
sim = Simulation(r"./example.inp")