PYSWMM reader.py Summary

 Below is an extended summary of the SWMMBinReader class and its supporting components. It explains the purpose of this code, how it fits into PySWMM’s architecture, and the role of each method in reading and processing a SWMM output file (.out).

---

Overview

This module provides a low-level output reading interface for SWMM (Storm Water Management Model) binary result files. It defines a SWMMBinReader class (though it raises a “Not Implemented” exception by design in this snippet) that, once implemented, would allow Python code to open and parse SWMM’s binary .out files to extract simulation results (e.g., flow rates, water depths, pollutant concentrations, etc.).

Key tasks include:

1. Opening/Closing SWMM output files.
2. Reading metadata (e.g., start time, report interval, total number of simulation periods).
3. Fetching IDs for subcatchments, nodes, links, and pollutants stored in the output.
4. Extracting time series or single-time-step data for various attributes (rainfall, runoff, water depth, flow, etc.) across subcatchments, nodes, links, or system-level outputs.

Although the class currently raises OutReaderNotImplementedYet, it outlines how one would integrate with SWMM’s output API DLL (which is referred to as outputAPI_winx86.dll in some comments) and map its C functions to Python.

---

Structure and Key Components

1. _Opaque Class

• A ctypes.Structure used to represent the underlying C-struct pointer (smoapi) that references SWMM’s output reading library.
• Acts as a placeholder so that the Python code can store a pointer to the C library’s internal data structures.

2. SWMMBinReader Class

Purpose

• Creates a wrapper around SWMM’s output API library, providing methods to open, close, and read data from a SWMM .out file in Pythonic ways.

Notable Attributes and Methods

1. __init__

   • Note: The snippet immediately raises OutReaderNotImplementedYet, signaling that full functionality was not yet provided.
   • Normally, it would load the SWMM output API DLL, store function pointers, and set up argument/return types for each C function.

2. OpenBinFile(self, OutLoc)

   • Would call C functions (SMO_init and SMO_open) to open a SWMM binary results file from disk.
   • On failure, it raises an exception with a relevant error message.

3. CloseBinFile(self)

   • Closes the output file and frees resources by calling SWMM’s SMO_close.
   • Deletes any cached subcatchment, node, link, or pollutant ID lists from the class instance.

4. Helpers for ID Caching

   • _get_SubcatchIDs, _get_NodeIDs, _get_LinkIDs, _get_PollutantIDs
   • Each retrieves the name strings for subcatchments, nodes, links, or pollutants from the output file and caches them in Python dictionaries (self.SubcatchmentIDs, etc.). These methods rely on SWMM’s SMO_getElementName function.

5. get_IDs(self, SMO_elementIDType)

   • Returns a list of IDs for a given element type (e.g., subcatchments, nodes, links, pollutants).
   • If not already cached, it calls one of the _get_*IDs methods to build the dictionary.

6. get_Units(self, unit)

   • Returns the flow/concentration unit system used by the output.
   • Internally calls SWMM’s SMO_getUnits to determine if flow is in CFS, CMS, etc.

7. get_Times(self, SMO_timeElementType)

   • Fetches time-related parameters (e.g., reporting interval, number of periods) from the output.
   • Ties to SWMM’s SMO_getTimes.

8. get_StartTime(self) and _get_StartTimeSWMM(self)

   • Retrieves the simulation start date/time as a floating-point “Julian date” from the SWMM library.
   • Converts it to a Python datetime.

9. get_TimeSeries(self)

   • Constructs a Python list of datetime objects for each reporting timestep by starting at get_StartTime and incrementing in steps of the reporting interval.
   • Returns a convenient timeline for index-based data retrieval.

10. get_ProjectSize(self, SMO_elementCount)

• Returns the total count of a particular type of element (subcatchments, nodes, links, or pollutants).
• Calls SWMM’s SMO_getProjectSize.

11. Data Retrieval Methods

• get_Series(...): Returns time-series data for a particular element (subcatchment, node, link, or system attribute) from a start to end index. Internally uses SWMM’s SMO_getSubcatchSeries, SMO_getNodeSeries, etc.
• get_Attribute(...): Returns a snapshot (e.g., across all nodes or all links) of a particular attribute at one time index.
• get_Result(...): Returns all attributes for a specific subcatchment, node, or link (or system-level data) at a single time index.

Error Handling

• Many methods check the return value of SWMM’s C functions (ErrNo) and raise exceptions with a descriptive message if non-zero. They use a dictionary tka.DLLErrorKeys to map numeric error codes to strings.

---

Typical Usage Flow (Hypothetical)

Although this particular snippet includes a raised exception to indicate “not yet implemented,” a fully functional version would follow this workflow:

1. Instantiate the reader:

   reader = SWMMBinReader()
   

2. Open a SWMM .out file:

   reader.OpenBinFile("my_simulation.out")
   

3. Query basic info (e.g., number of nodes):

   node_count = reader.get_ProjectSize(tka.SMO_elementCount.nodeCount.value)
   node_ids = reader.get_IDs(tka.SMO_elementType.SM_node.value)
   

4. Fetch a timeseries for a particular node attribute:

   flow_series = reader.get_Series(
       tka.SMO_elementType.SM_node.value,
       tka.SMO_systemAttribute.total_inflow,
       "Node1",
       0,   # start index
       100  # end index
   )
   

5. Close once done:

   reader.CloseBinFile()
   

---

Integration with PySWMM

• This code references and expands upon PySWMM’s toolkitapi module (pyswmm.toolkitapi as tka), which defines enumerations and error-handling keys (e.g., DLLErrorKeys).
• The approach is consistent with how PySWMM typically uses ctypes to invoke underlying SWMM C functions.
• Once finished, this low-level API would be part of the backbone for a higher-level interface (like pyswmm.Output) that simplifies reading .out files for subcatchment or node results.

---

Conclusion

Although the snippet raises a “Not Implemented” exception by design, the SWMMBinReader class outlines a robust approach for opening and parsing SWMM output files in Python. Its methods detail how one might:

• Locate and load a library (outputAPI_winx86.dll).
• Initialize a SWMM output reading session (smoapi pointer).
• Retrieve IDs, time steps, and simulation results for subcatchments, nodes, links, or system attributes.
• Convert data (e.g., Julian times) into Python-friendly formats (datetime).

In a fully implemented system, SWMMBinReader would serve as the foundational class enabling advanced post-processing or real-time data consumption from SWMM binary outputs within Python.