PYSWMM swmm5.py Summary

 Below is an extended summary of the code, highlighting its purpose, structure, and capabilities, as well as how it fits into PySWMM for managing SWMM simulations through Python.

---

Overview

This code defines the PySWMM class, which serves as a foundational wrapper around SWMM’s C-based toolkit. It consolidates various SWMM operations (opening an input file, starting/stopping a simulation, stepping through time, and retrieving or setting parameters for objects like nodes, links, or subcatchments) into a Python-friendly interface. By building upon swmm.toolkit.solver (the underlying SWMM API calls) and pyswmm.toolkitapi, it provides a flexible and robust approach for both full-run executions (Mode 1) and more advanced, step-by-step control (Mode 2).

Key Features:

1. File & Simulation Management

   • swmm_open: Opens an input file and reads the SWMM network data.
   • swmm_close: Closes the model and frees memory.
   • swmm_start, swmm_step, swmm_end: Offers granular control over a simulation run (e.g., Mode 2).
   • swmmExec: One-shot run from open to close (Mode 1).
   • swmm_run: Internal method called by swmmExec.

2. Real-Time Adjustments

   • swmm_step: Advances the simulation by one SWMM routing step.
   • swmm_stride: Allows you to advance the simulation by a user-defined number of seconds before returning control to Python. This is useful for performance optimizations or external control logic.

3. Hotstart Integration

   • swmm_save_hotstart: Saves the current model state to a hotstart file at any point mid-simulation.
   • swmm_use_hotstart: Loads a hotstart file before a run, ensuring continuity from a previous run or partial state.

4. Mass-Balance & Engine Info

   • swmm_getMassBalErr: Retrieves runoff, flow routing, and quality routing errors to check the simulation’s continuity performance.
   • swmm_getVersion: Returns the SWMM engine version currently used.

5. SWMM Object & Parameter Access

   • getProjectSize / getObjectId / getObjectIDList: Helps discover the count and IDs (e.g., node “J1”, subcatchment “S1”) for each object type.
   • getNodeParam / setNodeParam: Retrieves or modifies parameters like invert elevation or initial depth.
   • getLinkParam / setLinkParam: Manages link-specific data, such as offsets or flow limits.
   • getSubcatchParam / setSubcatchParam: Handles area, slope, etc. for subcatchments.
   • ObjectIDexist: Checks if a given ID is valid in the current SWMM model.
   • getNodeType, getLinkType: Identifies the type of a node (junction, outfall, etc.) or a link (conduit, pump, etc.).

6. Real-Time Simulation Results

   • Node, Link, Subcatchment “getResult” methods: Retrieve time-varying data (e.g., water depth for a node, flow through a link, or runoff for a subcatchment).
   • Water quality methods (like getNodePollut, getLinkPollut, getSubcatchPollut) allow reading pollutant concentrations or loads at each time step.
   • flow_routing_stats, runoff_routing_stats, node_statistics, conduit_statistics, etc. return aggregated performance measures (peak flows, average depths, total volumes, etc.) across the entire simulation run.

---

Code Structure

1. Imports

   • Uses swmm.toolkit.solver for direct calls to the C library’s SWMM functions.
   • Relies on pyswmm.toolkitapi for enumerations and additional definitions (like SimulationTime, ObjectType, parameter IDs, etc.).

2. Custom Exceptions

   • SWMMException and PYSWMMException: These wrap potential errors in more friendly messages, distinguishing between raw SWMM engine errors and PySWMM-level issues.

3. PySWMM Class

   • Constructor: Accepts an input file, optional report file, optional binary file, and an optional custom library path.
   • Simulation Methods
     • swmmExec(): Full-run approach.
     • swmm_run(): The internal call to solver.swmm_run.
     • swmm_open(), swmm_close(): Bookend for reading and cleaning up the SWMM data.
     • swmm_start(), swmm_end(), swmm_step(), swmm_stride(): Step-by-step control.
     • swmm_report(): Writes the SWMM output to the .rpt file after a run.
   • Hotstart: swmm_save_hotstart(file), swmm_use_hotstart(file).
   • Information Retrieval
     • Engine version, mass-balance, date/time settings, and simulation unit settings.
     • Methods for enumerating project objects (getProjectSize, getObjectIDList) and retrieving or setting parameters (e.g., setNodeParam, getSubcatchParam).
     • Functions to read results at runtime or post-run (like getNodeResult, getLinkResult).
   • Aggregated Statistics
     • flow_routing_stats(), runoff_routing_stats(), node_statistics(ID), conduit_statistics(ID), etc.

---

Typical Usage Scenarios

1. Full Simulation Execution (One-Shot)

   from pyswmm import PySWMM
   
   model = PySWMM("model.inp", "model.rpt", "model.out")
   model.swmm_open()
   model.swmmExec()  # runs start->sim->end->close automatically
   model.swmm_close()
   

2. Step-by-Step Control

   from pyswmm import PySWMM
   
   model = PySWMM("model.inp", "model.rpt", "model.out")
   model.swmm_open()
   model.swmm_start(SaveOut2rpt=True)
   
   while True:
       current_time = model.swmm_step()
       if current_time <= 0:
           break
       # Possibly update parameters, read states
   
   model.swmm_end()
   model.swmm_report()
   model.swmm_close()
   

3. Setting Inflow Mid-Simulation

   # Suppose user wants to inject flow into node "J1" at a certain time
   while True:
       current_time = model.swmm_step()
       if current_time >= 2.0:  # after 2.0 days
           model.setNodeInflow("J1", 5.0)  # cfs or user-defined units
   

4. Retrieving Stats After the Run

   stats_flow = model.flow_routing_stats()
   # => {
   #      'dry_weather_inflow': 100.0,
   #      'wet_weather_inflow': 200.0,
   #      ...
   #    }
   
   node_stats = model.node_statistics("J1")
   # => {
   #      'average_depth': 1.2,
   #      'max_depth': 3.5,
   #      ...
   #    }
   

5. Hotstart File Usage

   model = PySWMM("model.inp", "model.rpt", "model.out")
   model.swmm_open()
   model.swmm_use_hotstart("previous_run.hsf")  # load state
   model.swmm_start()
   ...
   model.swmm_save_hotstart("new_run.hsf")  # save state mid-run
   ...
   model.swmm_end()
   model.swmm_report()
   model.swmm_close()
   

---

Advantages and Integration

1. High-Level vs. Low-Level

   • PySWMM encapsulates raw C calls into more intuitive Python methods and properties, reducing error risks and code clutter.

2. Real-Time Control

   • Step-based iteration plus setter methods (like setNodeParam) allow advanced scenarios (machine learning, PID controllers, external heuristics) to manipulate SWMM elements on the fly.

3. Compatibility

   • Because it uses the official SWMM toolkit library, it remains compatible with standard SWMM input files and the recognized solver.

4. Hotstart and Partial Runs

   • The ability to load and save hotstart files fosters incremental or branching scenario analyses without re-running the entire model from the initial conditions.

5. Error Handling

   • SWMMException and PYSWMMException let developers distinguish between solver-level errors and higher-level PySWMM issues, enabling more targeted exception handling and debugging.

---

Conclusion

In summary, the PySWMM class stands as a crucial component within the PySWMM ecosystem. By abstracting the complexities of SWMM’s C-based toolkit into a streamlined Python API, it empowers engineers and researchers to:

• Effortlessly open and close SWMM models.
• Run simulations in one-shot or stepwise modes.
• Dynamically modify SWMM objects and read data at each simulation timestep.
• Manage advanced tasks such as hotstart files, mass-balance checks, and real-time control logic.

This flexible design makes it invaluable for a wide range of tasks—from simple batch runs to complex scenario testing, controller prototyping, and teaching SWMM in interactive Python environments.