PYSWMM subcatchments.py Summary

· December 30, 2024

 Below is an extended summary of the code, describing its purpose, structure, and how the classes integrate with PySWMM to manage and query subcatchment data within a SWMM model.

Overview

This module provides Pythonic wrappers for interacting with subcatchments in a SWMM (Storm Water Management Model) simulation. It defines two main classes:

  1. Subcatchments – A container/iterator over all subcatchments, allowing you to list, retrieve, and check the existence of subcatchments by ID.
  2. Subcatchment – A single subcatchment object, offering property-based access to both static parameters (e.g., area, slope) and dynamic simulation results (e.g., rainfall, runoff).

Together, they bridge SWMM’s low-level C toolkit and Python, enabling users to modify or read subcatchment data in near real-time as a simulation proceeds.

Subcatchments

Purpose

  • Acts as a Python collection of all subcatchments in an open SWMM model.
  • Integrates with PySWMM’s internal _model pointer (which references the SWMM engine) to iterate through or lookup individual subcatchments.

Key Behaviors

  1. Initialization

    subcatchments = Subcatchments(simulation_object)
    • Checks if the model is open; otherwise raises a PYSWMMException.

  2. Length and Containment

    • len(subcatchments) returns the total number of subcatchments in the model.
    • "S1" in subcatchments checks if a subcatchment with ID "S1" exists.

  3. Lookup

    • subcatchments["S1"] returns a Subcatchment instance corresponding to subcatchment S1.
    • Raises a PYSWMMException if the ID is invalid.

  4. Iteration

    • for sc in subcatchments: yields Subcatchment objects one by one, in the order the subcatchments are stored in SWMM.

Example Usage

from pyswmm import Simulation, Subcatchments

with Simulation("my_model.inp") as sim:
    subcs = Subcatchments(sim)
    print(len(subcs))           # e.g., prints total number of subcatchments

    for sc in subcs:
        print(sc.subcatchmentid)   # e.g., "S1", "S2"

Subcatchment

Purpose

  • Represents one subcatchment in a SWMM model.
  • Exposes both static parameters (width, area, slope) and dynamic (time-varying) results (runoff, infiltration, etc.).

Initialization

subcatchment_obj = Subcatchment(model, "S1")
  • Validates that "S1" exists in the model’s subcatchment list.

Key Properties

  1. Identifiers & Connections

    • subcatchmentid: The SWMM ID (e.g., "S1").
    • connection: A tuple indicating where runoff is sent (another subcatchment or a node). Example return: (2, 'J2'), meaning the runoff flows to a node with ID "J2."

  2. Subcatchment Parameters

    • width (effective flow width).
    • area (subcatchment area).
    • percent_impervious (fraction of area that is impervious).
    • slope (average slope).
    • curb_length (total length of curbs).

    Each parameter has both a getter and setter, allowing real-time or pre-run modifications:

    s1.area = 50.0
current_area = s1.area

  3. Simulation Results

    • rainfall: Instantaneous rainfall on the subcatchment (in user-defined units).
    • evaporation_loss: Current evaporation rate from the subcatchment.
    • infiltration_loss: Current infiltration rate.
    • runon: Lateral inflow from other surfaces.
    • runoff: Current runoff rate leaving the subcatchment.
    • snow_depth: Current snow depth (if snowmelt is modeled).

  4. Pollutant-Related

    • buildup: Surface buildup amounts for each pollutant.
    • conc_ponded: Pollutant concentration in any ponded water.
    • pollut_quality: Pollutant concentration in subcatchment runoff.
    • runoff_total_loading: Total pollutant mass leaving the subcatchment in runoff.

    Each of these returns a dictionary keyed by pollutant ID, e.g.:

    {
    "TSS": 12.3,
    "Lead": 0.05
}

  5. statistics

    • Returns rolling/cumulative subcatchment flow stats (total precipitation, runon, evap, infiltration, total runoff, and peak runoff rate).
    • Example structure: 
      {
  "precipitation": 2.15,
  "runon": 0.5,
  "evaporation": 0.1,
  "infiltration": 0.3,
  "runoff": 1.7,
  "peak_runoff_rate": 0.12
}

Example Usage

with Simulation("my_model.inp") as sim:
    s1 = Subcatchments(sim)["S1"]
    # Modify area
    s1.area = 20.0
    # Access time-varying results during the run
    for step in sim:
        print("Runoff at this timestep:", s1.runoff)
        print("Pollutant buildup:", s1.buildup)

Typical Workflow

  1. Open a Simulation (context-manager recommended): 
    from pyswmm import Simulation, Subcatchments

with Simulation("model.inp") as sim:
    subc_collection = Subcatchments(sim)
    ...
  2. Access a Subcatchment: 
    s1 = subc_collection["S1"]
print(s1.area, s1.percent_impervious)
s1.slope = 0.015
  3. Iterate During a Simulation: 
    for step in sim:
    current_runoff = s1.runoff
    # Possibly adjust properties or log data
  4. Utilize Pollutant Data (if water quality is enabled): 
    # e.g., TSS concentration in S1's runoff
tss_conc = s1.pollut_quality["TSS"]
  5. Close:
    • The Simulation context manager automatically finalizes the SWMM run.

Error Handling

  • A PYSWMMException is raised if:
    • The SWMM model file hasn’t been opened.
    • A subcatchment ID doesn’t exist when requested.

Key Benefits

  1. Pythonic Access:

    • Subcatchment properties (e.g., area, slope) and real-time results (e.g., runoff rate) can be read or updated via standard property syntax, making the code more readable and maintainable than direct calls to the C API.

  2. Real-Time Control:

    • Parameters can be modified mid-simulation if needed, supporting advanced scenario testing or real-time control strategies.

  3. Intuitive Iteration:

    • The Subcatchments class supports Python’s iteration protocol and membership checks, improving discoverability and dynamic analysis of subcatchments.

  4. Pollutant Loading & Quality:

    • Built-in methods return dictionaries keyed by pollutant ID, simplifying water quality analysis or post-processing tasks.

Conclusion

The Subcatchments and Subcatchment classes offer a high-level interface to SWMM’s subcatchment data, allowing Python developers and modelers to manipulate and observe hydrologic processes in near real-time. By exposing subcatchment parameters and simulation outputs in a straightforward, property-based manner, they further streamline typical tasks like:

  • Parameter adjustments (e.g., changing area or slope).
  • Hydrologic result retrieval (e.g., rainfall, infiltration, or runoff).
  • Pollutant water quality checks (e.g., buildup, runoff concentration).

Together, they make modeling workflows in PySWMM more intuitive, robust, and Pythonic.