PYSWMM links.py Summary

Below is an extended summary of this code, highlighting its main classes, functionality, and how each piece fits into the broader PySWMM architecture:

---

Overview

This module defines Python classes (Links, Link, Conduit, and Pump) that provide a user-friendly interface to SWMM5’s link objects. By leveraging PySWMM’s underlying toolkit (primarily through self._model references), it enables modelers to access and manipulate hydraulic and water-quality data for conduits, pumps, orifices, weirs, and other link types during a SWMM simulation.

Key capabilities include:

1. Iteration over all links in a SWMM model.
2. Easy retrieval of key link parameters (e.g., offsets, flow limit, seepage rate).
3. On-the-fly manipulation of specific link properties (initial flow, target setting, etc.).
4. Access to runtime results (flow depth, volume, water quality) at each simulation timestep.
5. Specialized subclasses for conduits and pumps, enabling detailed statistics and custom methods.

---

Core Classes

1. Links

• Purpose: Acts as a container and iterator for all links in an open SWMM model.
• Initialization:

  links = Links(sim)
  

  Here, sim is an active Simulation object. The constructor verifies that the SWMM model is loaded (model._model.fileLoaded) before proceeding.
• Iteration:
  • Supports Python’s iteration protocol (__iter__, __next__), allowing developers to loop over links:

    for link in Links(sim):
        print(link.linkid)
    

  • Internally, each iteration retrieves a new Link instance using its index-based ID from the underlying SWMM model.
• Lookup:
  • Provides __getitem__ to retrieve a Link object directly by ID:

    c1c2 = links['C1:C2']
    

  • If the retrieved link is identified as a conduit or pump, it is automatically cast to the appropriate subclass (Conduit or Pump).
• Membership:
  • Implements __contains__ to check if a link ID exists in the model:

    "C1:C2" in links  # returns True or False
    

2. Link

• Purpose: Represents an individual SWMM link. This base class applies to all link types (conduit, pump, orifice, weir, outlet).
• Initialization:

  c1c2 = Link(model, 'C1:C2')
  

  • Verifies the model is open and that the given ID is valid.
• Properties & Methods:
  1. Link Identification
     • linkid: Returns the link’s SWMM ID (e.g., "C1:C2").
     • connections: Returns a tuple (inlet_node_id, outlet_node_id).
  2. Link Type Checks
     • is_conduit(), is_pump(), is_orifice(), is_weir(), is_outlet(): Each returns a boolean indicating the link’s specific type.
  3. Parameter Accessors (Getters/Setters)
     • Structural Parameters:
       • inlet_offset, outlet_offset
       • initial_flow (link’s startup flow), flow_limit (maximum flow rate)
       • inlet_head_loss, outlet_head_loss, average_head_loss, seepage_rate
     • Each property retrieves or updates SWMM’s internal data via self._model.getLinkParam or self._model.setLinkParam.
  4. Runtime Results
     • flow, depth, volume, froude, ups_xsection_area, ds_xsection_area
     • current_setting (real-time setting for a controlled link)
     • target_setting (allows the user to change the setting programmatically via self._model.setLinkSetting(linkid, value)).
  5. Water Quality
     • pollut_quality: Dictionary of pollutant concentrations currently in the link.
       • Can be set by passing a tuple (pollutant_ID, pollutant_value) to the property.
     • total_loading: Summed pollutant loading in the link.
     • reactor_quality: Pollutant concentration in the “mixed reactor” portion of the link (also a dictionary).
• Usage:

  with Simulation('my_model.inp') as sim:
      link_obj = Links(sim)['C1:C2']
      link_obj.flow_limit = 10.0       # Set max flow
      link_obj.target_setting = 0.75   # Adjust link setting mid-simulation
  

3. Conduit (Subclass of Link)

• Purpose: Specialized link class for conduits, inheriting from Link.
• Primary Feature:
  • conduit_statistics: Provides a dictionary of extended hydraulic metrics (peak flow/velocity/depth, surcharging times, capacity-limited fraction, flow class durations, and more).
  • These statistics are cumulative over the entire simulation run and are accessed after the simulation loop completes:

    with Simulation('my_model.inp') as sim:
        c1c2 = Links(sim)['C1:C2']
        for step in sim:
            pass
        stats = c1c2.conduit_statistics
        print(stats['peak_flow'])  # e.g., 2.134 cfs
    

4. Pump (Subclass of Link)

• Purpose: Specialized link class for pumps.
• Primary Feature:
  • pump_statistics: Cumulative usage data for the pump, including utilization time, min/avg/max flow rates, total volume pumped, energy consumed, and how frequently the pump operates off-curve.
  • Accessed similarly to the conduit stats:

    with Simulation('my_pump_model.inp') as sim:
        pump_link = Links(sim)['Pump1']
        for step in sim:
            pass
        stats = pump_link.pump_statistics
        print(stats['energy_consumed'], stats['total_volume'])
    

---

Typical Workflow

1. Open a SWMM simulation:

   from pyswmm import Simulation, Links
   
   with Simulation('network.inp') as sim:
       # ...
   

2. Instantiate the Links collection:

   links_collection = Links(sim)
   

3. Iterate or access individual links:

   # Directly by ID
   mylink = links_collection['LinkID123']
   
   # Or by iteration
   for link in links_collection:
       print(link.linkid)
       if link.is_pump():
           print(link.flow)
   

4. Manipulate or retrieve parameters:

   mylink.flow_limit = 15.0
   print(mylink.seepage_rate)
   

5. Run or step through the simulation:

   for step in sim:
       # Retrieve real-time results
       current_flow = mylink.flow
       if current_flow > 10.0:
           mylink.target_setting = 0.5  # Partially close a weir or orifice
   

6. Obtain summary statistics after the simulation ends:

   if mylink.is_conduit():
       stats = mylink.conduit_statistics
       print("Peak flow was:", stats["peak_flow"])
   elif mylink.is_pump():
       stats = mylink.pump_statistics
       print("Pump total volume pumped:", stats["total_volume"])
   

---

Key Advantages

1. Pythonic Access: Modelers can reference link properties (offsets, flows, pollutant concentrations) through intuitive property getters/setters rather than manually parsing SWMM data files.
2. Class Inheritance: The Conduit and Pump subclasses handle specialized metrics that don’t apply to all link types (e.g., pump energy consumption).
3. Runtime Control: Because these properties can be changed during a time-stepped simulation, users can implement sophisticated real-time control strategies (e.g., adjusting a pump setting when a flow threshold is exceeded).
4. Robust Error-Handling: Each method checks that the model is loaded. If it isn’t, a PYSWMMException is raised, preventing inadvertent calls on an uninitialized state.

---

Conclusion

By providing an object-oriented, user-friendly abstraction over SWMM’s link objects, this module simplifies both reading and writing of key simulation parameters. The Links container and its subclasses (Conduit, Pump) significantly reduce the complexity of stormwater modeling workflows, allowing for powerful, Pythonic real-time control and post-processing of SWMM simulations.