PYSWMM system.py Summary

 Below is an extended summary of this module. It explains its purpose, structure, and how the SystemStats class fits into a broader Pythonic interface for SWMM (Storm Water Management Model) simulations.

---

Overview

This code defines a SystemStats class, providing high-level access to cumulative (system-wide) flow routing and runoff statistics during or after a SWMM simulation. It allows Python scripts to easily retrieve aggregated hydrologic and hydraulic performance metrics—such as total inflows, flooding, seepage losses, or infiltration—without manually parsing SWMM’s internal data structures.

---

The SystemStats Class

Purpose

• SystemStats exposes two core properties:
  • routing_stats – Summarizes system-level flow routing data.
  • runoff_stats – Summarizes system-level runoff data.

By calling these properties (dictionaries), users can inspect real-time or final simulation statistics, including total inflows, total outflow, evaporation, infiltration, and more. This is especially useful for mass-balance checks or for quickly referencing global simulation metrics mid-run in a Python loop.

Initialization

system_routing = SystemStats(simulation_instance)

• Takes a Simulation (or similarly structured) object as input.
• Internally checks if the simulation model (model._model.fileLoaded) is open; raises a PYSWMMException if not.

Properties and Their Meanings

1. routing_stats

   • A dictionary reporting accumulated flow routing results, such as:
     • dry_weather_inflow: Volume from DWF (dry-weather flows).
     • wet_weather_inflow: Volume from storm events.
     • groundwater_inflow: Volume from groundwater sources.
     • II_inflow: Inflow/infiltration (sanitary sewer infiltration).
     • external_inflow: External inflows from user-defined sources.
     • flooding: Total flooded volume in the system.
     • outflow: Total outflow volume leaving the system.
     • evaporation_loss: Volume lost to evaporation.
     • seepage_loss: Volume lost to seepage.
     • reacted: Water volume lost or gained via chemical/biological reactions (if water quality is modeled).
     • initial_storage / final_storage: System’s stored volume at start and end.
     • routing_error: The mass-balance discrepancy for flow routing in percent or absolute terms.

2. runoff_stats

   • Another dictionary for runoff-specific accumulations, including:
     • rainfall: Total precipitation over the model area.
     • evaporation: Total evaporation from subcatchment surfaces.
     • infiltration: Volume infiltrated into soil.
     • runoff: Total surface runoff generated.
     • drains: Flow captured by underdrains (e.g., LID or other drainage).
     • runon: Flow from other subcatchments or external surfaces.
     • init_storage / final_storage: Storage in the surface or soil layers at the simulation start/end.
     • init_snow_cover / final_snow_cover: Snow depth or volume at start/end (if snowmelt is modeled).
     • snow_removed: Snow depth or volume removed by plowing, sublimation, or other processes.
     • routing_error: Mass-balance discrepancy for runoff (rainfall-runoff) in percent or absolute terms.

Typical Usage

from pyswmm import Simulation, SystemStats

with Simulation('example.inp') as sim:
    system_info = SystemStats(sim)
    for step in sim:
        # Access routing stats mid-run
        print(system_info.routing_stats)
        # Access runoff stats mid-run
        print(system_info.runoff_stats)

1. Context Manager (with Simulation(...) as sim:) ensures that the SWMM model is opened and closed properly.
2. SystemStats(sim) creates an instance that uses sim._model, the underlying SWMM reference, to fetch or update data.
3. Within a simulation loop, calling system_info.routing_stats or system_info.runoff_stats returns the up-to-date or final system metrics.

---

Integration with PySWMM

• SystemStats is part of a broader Pythonic interface that includes classes for nodes, links, subcatchments, LIDs, etc.
• The underlying method calls like self._model.flow_routing_stats() and self._model.runoff_routing_stats() presumably reference the lower-level functions to gather system-wide accumulations and mass balances.
• By providing two read-only properties, it keeps usage simple and consistent with other PySWMM objects that expose SWMM data in dictionary forms (e.g., for node or link statistics).

---

Key Takeaways

1. Easy Access to System-Wide Metrics

   • Eliminates the need to manually parse SWMM outputs for total inflows, outflows, evaporation, infiltration, etc.
   • Ideal for quick verification of overall water balance or real-time monitoring within a simulation loop.

2. Consistent Dictionary Return

   • Each property returns a named dictionary, making it straightforward to log or further process in Python or convert to a Pandas DataFrame.

3. Error Handling

   • If the SWMM model is not open, SystemStats raises a PYSWMMException. This ensures that system stats aren’t requested prematurely.

4. Statistical Summaries

   • As the data includes initial and final storages, infiltration, and other volumes, it greatly aids mass-balance checks and overall performance evaluations in real-time or after the simulation.

---

Conclusion

The SystemStats class is a concise yet powerful tool for tracking cumulative flow routing and runoff metrics in a SWMM simulation. Through two main properties—routing_stats and runoff_stats—it provides an at-a-glance or in-depth look at system-level water movements, infiltration, evaporation, flooding, and errors, all without rummaging through raw output files or coding complex logic. It’s an essential part of the PySWMM suite, ensuring developers and researchers can seamlessly monitor and debug system-wide hydrologic/hydraulic performance in Python.