PYSWMM lidunits.py Summary

 Below is an extended summary of the code, describing its structure, primary functionalities, and how each class interacts with SWMM’s LID (Low Impact Development) data.

---

Purpose and Context

This code defines Python classes (Surface, Pavement, Storage, Soil, and WaterBalance) that provide a user-friendly interface to SWMM’s LID components. Each class focuses on a specific layer (or conceptual grouping) of a Low Impact Development unit—such as bioretention cells, permeable pavements, or green roofs—and exposes numeric properties (inflows, outflows, evaporations, infiltration rates, etc.) by querying PySWMM’s low-level toolkit functions (getLidUResult and getLidUFluxRates).

By wrapping SWMM’s C-based toolkit calls into clear, Pythonic property getters, modelers can easily monitor real-time hydraulic processes within each LID layer.

---

Structure and Key Components

1. _flux_rate Helper Function

def _flux_rate(model, subcatchment, lid_index, layer):
    return model.getLidUFluxRates(subcatchment, lid_index, layer)

• A private utility that retrieves net inflow/outflow (flux) for a particular LID unit layer.
• Supports surface, soil, storage, and pavement layers as enumerated by LidLayers.

2. Surface Class

• Represents the surface layer of an LID unit (e.g., ponded water on top of a biocell or permeable pavement).
• Properties:
  • depth: Current depth of water on the surface.
  • inflow: Rate of precipitation + runon flowing into this LID unit.
  • infiltration: Rate at which water is infiltrating from the surface layer downward.
  • evaporation: Water lost to evaporation from the surface.
  • outflow: Overflow or surface water leaving the LID.
  • flux_rate: Net flux (inflow - outflow) from the surface layer in the previous time step.

3. Pavement Class

• Focuses on the porous pavement layer in certain LID designs.
• Properties:
  • depth: Depth of water within the pavement voids.
  • evaporation: Pavement water lost via evaporation.
  • percolation: Water percolating out of the pavement layer down into the underlying layer.
  • flux_rate: Net flux from the pavement layer.

4. Storage Class

• Applies to the storage layer, which might represent a storage zone underneath surface layers (e.g., gravel storage in permeable pavement or an underdrain storage chamber).
• Properties:
  • depth: Current depth of water in the storage layer.
  • inflow: Water entering this storage layer from above.
  • exfiltration: Water exfiltrating into native soil.
  • evaporation: Water lost via evaporation from the storage zone.
  • drain: Flow leaving through an underdrain or outlet.
  • flux_rate: Net inflow-outflow rate from the storage layer.

5. Soil Class

• Represents the soil layer for LIDs such as bioretention cells or green roofs.
• Properties:
  • moisture: The current soil moisture content.
  • evaporation: Evaporation from soil.
  • percolation: Percolation (downward flow) from the soil layer.
  • flux_rate: Net flux of water into/out of the soil layer.

6. WaterBalance Class

• Provides overall LID water balance metrics, representing totals across the entire LID unit.
• Properties:
  • inflow: Total inflow received by the LID (surface and subsurface combined).
  • evaporation: Total evaporation from all layers.
  • infiltration: Total infiltration to the native soil.
  • surface_flow: Total surface runoff leaving the LID.
  • drain_flow: Flow exiting the LID through an underdrain.
  • initial_volume, final_volume: Stored water volume at the start and end of a time step.

---

Typical Usage

1. Accessing LID Data

   • These classes are generally instantiated within a broader LIDUnit context in PySWMM. For example:

     surf = Surface(model, lidunit_object)
     current_depth = surf.depth
     

   • Each class needs references to the SWMM model object (model) and the specific LID unit and subcatchment (lidunit).

2. Retrieving Real-Time Values

   • Within a simulation loop, a user might query Surface infiltration or Soil moisture at each time step to make control decisions or track performance.

     for step in sim:
         print(surf.infiltration, soil.moisture)
     

3. Analyzing End-of-Simulation Results

   • Users may also retrieve final state or total inflow/outflow totals after running the simulation, aiding in post-processing or reporting.

---

Key Advantages

1. High-Level Abstraction:

   • By naming each property (surface.inflow, pavement.depth) rather than relying on numeric indices, the code is more readable and user-friendly.

2. Modular LID Layers:

   • Splitting each layer (Surface, Pavement, Storage, Soil) into its own class clarifies the distinct processes involved and simplifies maintenance.

3. Consistent Access Patterns:

   • All classes follow a similar pattern: @property getters that call getLidUResult or _flux_rate under the hood, ensuring a uniform interface across different layers.

4. Real-Time or Post-Run Data:

   • The properties can be queried on-the-fly during a time-stepped simulation or after the simulation completes for a detailed water balance assessment.

---

Conclusion

In summary, these classes (Surface, Pavement, Storage, Soil, and WaterBalance) encapsulate SWMM’s LID layer data into convenient, Python-based APIs. By doing so, they empower engineers and researchers to more easily inspect and manage the complex hydrologic and hydraulic processes occurring within a Low Impact Development practice during a SWMM simulation.