PYSWMM lidcontrols.py Summary

 Below is an extended summary of this module, highlighting its purpose, class structure, and how it facilitates the management of Low Impact Development (LID) usage data for SWMM subcatchments:

---

Purpose and Context

This module provides a high-level, Pythonic interface to the LID usage section of a SWMM model. In particular, it helps users discover which subcatchments have LIDs, how many LID units exist per subcatchment, and the parameters and real-time results of each LID unit. By building on PySWMM’s low-level API (toolkitapi), these classes enable both pre-simulation configuration and dynamic, mid-simulation manipulation of LID settings (for those parameters allowed to be changed at runtime).

Key ideas:

1. One LidGroups object corresponds to all subcatchments in the model.
2. Each LidGroup object is associated with one subcatchment but may contain multiple LID units.
3. A LidUnit represents a single LID instance (e.g., “Permeable Pavement #1”) in that subcatchment, exposing both configuration parameters (like area, drain node) and runtime results (like drain flow or evaporation).

---

Class-by-Class Overview

1. LidGroups

• Role: Acts as a top-level container for LID usage across all subcatchments in the SWMM model.
• Initialization:

  lid_groups = LidGroups(simulation)
  

  • Checks if the SWMM model is open; raises PYSWMMException otherwise.
• Key Behaviors:
  1. Iteration (__iter__, __next__):
     • Iterates over each subcatchment in the model by ID, returning a LidGroup object.
     • Uses __len__ to report the total number of subcatchments.
  2. Lookup (__getitem__):
     • lid_groups[subcatchment_id] yields the LidGroup for that specific subcatchment, if it exists.
  3. Contains (__contains__):
     • Enables expressions like "S1" in lid_groups to check if subcatchment “S1” is valid.

Example:

for group in LidGroups(sim):
    print(group)  # Prints each subcatchment ID that has LID usage defined

2. LidGroup

• Role: Represents all LID units associated with a single subcatchment.
• Initialization:

  LidGroup(model, "SubcatchmentID")
  

  • Ensures that the subcatchment exists and the model is open.
• Key Behaviors:
  1. Iteration / Lookup (__iter__, __next__, __getitem__):
     • Iterates through each LID unit index (0, 1, 2, …) in the subcatchment, yielding LidUnit objects.
     • lid_group[i] returns the i-th LID unit in that subcatchment.
     • len(lid_group) reveals how many LIDs are defined in this subcatchment.
  2. Aggregated Results:
     • pervious_area: Total pervious area associated with these LID units.
     • flow_to_pervious: Flow directed from the LID(s) to pervious surfaces.
     • old_drain_flow, new_drain_flow: The previous and current drain flows, summed across all LID units in this subcatchment.
• Typical Use:

  lid_group_S1 = LidGroups(sim)["S1"]
  print(len(lid_group_S1))  # e.g., number of LID units in subcatchment S1
  
  for lid_unit in lid_group_S1:
      print(lid_unit.index, lid_unit.unit_area)
  

3. LidUnit

• Role: Encapsulates a single LID instance (e.g., one green roof, one bioretention cell) within a subcatchment.
• Initialization:

  LidUnit(model, subcatchment_id, lid_index)
  

  • lid_index is the 0-based index for a particular LID usage record in that subcatchment’s [LID_USAGE] section.
• Sub-Components:
  • surface, pavement, soil, storage: Layer-specific objects (defined in pyswmm.lidunits) that manage the physical parameters of each layer (thickness, porosity, infiltration, etc.).
  • water_balance: Provides aggregated infiltration, evaporation, drain flow, etc.
• Key Properties:
  1. LID Setup:
     • unit_area, full_width, initial_saturation
     • from_impervious, from_pervious: Fraction of runoff from impervious/pervious areas that is treated by this LID.
  2. Routing and Drainage:
     • drain_subcatchment, drain_node: Where underdrain flow is directed (other subcatchment or a node).
     • to_pervious: Whether outflow is sent to a pervious area (1) or not (0).
  3. Runtime Results:
     • dry_time: Time since last rainfall (in seconds).
     • old_drain_flow, new_drain_flow: Drain flow amounts in previous vs. current time step.
     • evaporation, native_infiltration: Real-time rates for evaporation and infiltration.
  4. IDs & Indices:
     • index: The ID for the LID Control (matching ObjectType.LID) in the overall model.
     • lid_control: Returns the textual ID of the LID control used (if index is known).

Typical Workflow:

lid_group_s1 = LidGroups(sim)['S1']
lid_unit0 = lid_group_s1[0]

# Check or adjust parameters before/after simulation
lid_unit0.unit_area = 200  # Set area in square feet (or model units)
lid_unit0.drain_node = "J5"  # Route underdrain flow to node J5

# During the simulation
for step_idx, step_time in enumerate(sim):
    if step_idx == 100:
        # Switch drain node mid-run
        lid_unit0.drain_node = "J6"

---

Typical Use Cases

1. Pre-Run Configuration:
   • Adjusting the LID area, fraction of impervious/pervious inflow, or drain routing node to experiment with different LID designs.
2. Dynamic Control:
   • During a SWMM simulation, changing drain_node or other runtime-adjustable parameters to test how real-time management might affect system performance.
3. Data Extraction:
   • After or during the run, retrieving LID results like new_drain_flow or evaporation helps measure performance, infiltration capacity, or water balance.

---

Key Takeaways

1. Hierarchical Design
   • LidGroups > LidGroup > LidUnit mirrors SWMM’s data organization:
     • Model has multiple subcatchments (each subcatchment can have LID usage)
     • Each subcatchment’s LID usage can have multiple LID units.
2. Property Access
   • Clear “getter” and “setter” properties for each LID parameter.
   • Some parameters (e.g., drain_subcatchment, drain_node) can be altered during simulation. Others (e.g., unit_area) must typically be set before starting the simulation.
3. Integration with pyswmm.lidunits
   • A LidUnit automatically includes references to sub-layer classes (Surface, Pavement, Soil, Storage, WaterBalance), which further expands the user’s control over LID components.

---

Final Notes

• Error Handling:
  • Raises PYSWMMException if the model is not open or if an invalid subcatchment/LID unit index is requested.
• Scalability:
  • By iterating over LidGroups and each LidGroup, this design gracefully handles large models with many subcatchments and multiple LID units per subcatchment.
• Real-Time Flexibility:
  • The code supports dynamic adjustments to certain LID parameters mid-simulation, enabling advanced scenario testing and real-time control strategies in PySWMM.

Overall, these classes significantly streamline the process of configuring and analyzing SWMM’s LID usage in Python, bridging the gap between low-level toolkit functions and high-level environmental modeling needs.