PYSWMM nodes.py Summary

 Below is an extended summary of the code, highlighting its structure, purpose, and how each component interacts with SWMM’s node objects in a Pythonic way:

---

Overview

This module defines classes (Nodes, Node, Outfall, Storage) that offer a Pythonic interface to SWMM (Storm Water Management Model) node objects. By leveraging PySWMM’s underlying toolkit (through self._model references), these classes enable users to easily query and modify various node parameters—such as invert elevations, initial depths, pollutant levels, and real-time hydraulic results (inflow, outflow, water depth)—during a SWMM simulation.

In addition to the base Node class, there are specialized subclasses:

• Outfall for handling outfall-specific parameters and statistics
• Storage for extended storage node statistics

This modular design makes it straightforward for modelers to handle general node properties while also supporting custom behaviors unique to storage nodes and outfalls.

---

Core Classes

1. Nodes

• Purpose: Manages a collection (iterator) of all node objects within an open SWMM model.
• Initialization:

  nodes = Nodes(simulation_instance)
  

  • Ensures that the model (simulation_instance._model) is loaded. If not, it raises a PYSWMMException.
• Iteration:
  • Supports Python’s iteration protocol (__iter__, __next__), allowing you to loop over nodes:

    for node in Nodes(sim):
        print(node.nodeid)
    

  • Each iteration returns a Node object (or one of its subclasses, such as Outfall or Storage), depending on the node’s SWMM type.
• Lookup:
  • The __getitem__ method lets you directly retrieve a specific node by ID:

    j1 = nodes['J1']
    print(j1.depth)
    

  • The correct subclass is assigned automatically if the node is an outfall or storage node.
• Membership:
  • The __contains__ method checks whether a given node ID exists in the model:

    "J1" in nodes  # returns True or False
    

• Length:
  • len(nodes) returns the total number of nodes in the model.

---

2. Node

• Purpose: Represents an individual SWMM node (junction, outfall, divider, or storage). This is the base class for all node types except for specialized functionality.

• Initialization:

  j1 = Node(model_object, "J1")
  

  • Ensures the model is loaded and the provided ID is valid for a node.

• Common Parameters (exposed as properties):

  1. Geometry and Configuration
     • invert_elevation, full_depth, surcharge_depth, ponding_area, initial_depth

       j1.invert_elevation = 20.0
       current_invert = j1.invert_elevation
       

  2. Runtime Hydraulic Results (retrieved during or after simulation stepping):
     • total_inflow, total_outflow, losses, volume, flooding, depth, head, lateral_inflow, hydraulic_retention_time

       print(j1.depth, j1.total_inflow)
       

  3. Pollutant Quality
     • pollut_quality: Current concentration in the node’s water volume
     • inflow_quality: Quality of inflow entering the node
     • reactor_quality: Quality within the “mixed reactor” portion of the node

       print(j1.pollut_quality)
       j1.pollut_quality = ('pollut_name', 50.0)  # sets pollutant concentration
       

  4. Helpers and Others
     • nodeid: The SWMM ID of the node
     • generated_inflow(...): Directly sets an inflow rate into the node for real-time control or scenario testing.
     • cumulative_inflow: Returns the total inflow volume over the simulation for continuity checks.

• Node Type Checks:

  • is_junction(), is_outfall(), is_storage(), is_divider() each returns a boolean indicating the node’s type based on SWMM’s internal classification.

• Statistics:

  • The statistics property returns a dictionary of rolling/cumulative node statistics (e.g., average depth, max flooding rate, total surcharge duration).

---

3. Outfall (Subclass of Node)

• Purpose: Specializes the Node class for outfalls.
• Primary Features:
  1. outfall_statistics
     • Dictionary of outfall-specific metrics (e.g., average flowrate, peak flowrate, total pollutant loading).
  2. outfall_stage(stage)
     • Overrides the outfall water surface elevation (head) at runtime, allowing a user to simulate tidal backwater conditions or other external water levels dynamically.

Example:

with Simulation('network.inp') as sim:
    outfall_node = Nodes(sim)['OF1']  # This will be an Outfall object
    for step in sim:
        if step > 2.0:
            outfall_node.outfall_stage(5.0)  # Setting stage to 5.0
    stats = outfall_node.outfall_statistics

---

4. Storage (Subclass of Node)

• Purpose: Specializes the Node class for storage nodes, such as detention basins or tanks.
• Primary Feature:
  • storage_statistics: A dictionary of rolling/cumulative metrics relevant to storage units (e.g., initial volume, average volume, evaporation losses, exfiltration losses, maximum volume date).

Example:

with Simulation('storage_model.inp') as sim:
    storage_node = Nodes(sim)['Tank1']  # This will be a Storage object
    for step in sim:
        pass
    stats = storage_node.storage_statistics
    print("Max volume:", stats["max_volume"])

---

Typical Workflow

1. Open a SWMM simulation:

   from pyswmm import Simulation, Nodes
   
   with Simulation('my_network.inp') as sim:
       # ...
   

2. Instantiate the Nodes collection:

   nodes = Nodes(sim)
   

3. Lookup or iterate over nodes:

   # Directly by ID
   j1 = nodes['J1']
   print(j1.depth, j1.head)
   
   # Or by iteration
   for node in nodes:
       print(node.nodeid, node.depth, node.is_outfall())
   

4. Modify node parameters (e.g., invert elevation):

   j1.invert_elevation = 25.5
   j1.initial_depth = 2.0
   

5. Run or step through the simulation:

   for step in sim:
       inflow = j1.total_inflow
       # Possibly add some external inflow if conditions are met
       if inflow < 1.0:
           j1.generated_inflow(1.2)
   

6. Retrieve final statistics:

   print(j1.statistics)  # e.g., peak flooding, max depth date
   

7. Outfall and Storage:
   • If the node is an outfall or storage node, you can access specialized stats after the simulation:

     if j1.is_outfall():
         print(j1.outfall_statistics)
     
     if j1.is_storage():
         print(j1.storage_statistics)
     

---

Key Advantages

1. User-Friendly Access:

   • Node parameters are accessible through Python properties rather than opaque function calls or manual data parsing, reducing coding errors and improving readability.

2. On-the-Fly Control:

   • The Node.generated_inflow(...) and Outfall.outfall_stage(...) methods allow real-time manipulation of node boundary conditions, enabling advanced control logic and scenario testing.

3. Subclass Specialization:

   • Outfall and Storage classes surface relevant statistics that do not apply to generic nodes, making the interface more organized and clear.

4. Seamless Integration with SWMM:

   • All reads and writes are internally routed through PySWMM’s low-level C-toolkit calls, ensuring direct and efficient communication with the SWMM engine.

---

Conclusion

By defining Nodes, Node, Outfall, and Storage, this module simplifies how modelers and developers interact with SWMM nodes. It abstracts away lower-level API details and provides a clean, Pythonic syntax for reading and modifying both static and dynamic node attributes (inflow/outflow, depth, pollutant concentrations). This design makes PySWMM especially well-suited for tasks like real-time simulation control, data analysis, scenario-based optimization, and educational demonstrations of hydrodynamic modeling concepts.