PYSWMM toolkitapi.py Summary

Below is an extended summary of this module, clarifying the purpose of each enumeration and data structure, their roles in mapping SWMM’s internal C data to Python, and how they integrate into a broader PySWMM workflow.

---

Overview

This code provides enums (enumerations) and ctypes.Structure-based data definitions that act as a bridge between Python and the underlying C-based SWMM toolkit. In essence, each enum or structure name here corresponds to an aspect of SWMM’s internal representation (e.g., Node parameters, Link results, system stats). By defining these in Python, PySWMM can look up, retrieve, or modify simulation data in a more readable and maintainable way.

Key components include:

1. Enumerations for describing simulation times, object types, parameters, and results.
2. ctypes.Structure classes for collecting detailed statistics (e.g., node flooding durations, link peak flows) in a typed and memory-aligned manner.
3. Constants (like DLLErrorKeys) that map error codes to human-readable messages, simplifying error handling when retrieving SWMM output data.

---

Enumerations

1. SimulationTime

   • Enumerates indices for retrieving or setting the start date, end date, and report start date/time of a SWMM run.
   • Used by PySWMM’s internal calls to solver.simulation_get_datetime(...), etc.

2. SimulationUnits

   • Distinguishes between UnitSystem (US vs. SI) and FlowUnits (CFS, GPM, MGD, CMS, LPS, MLD) in the model.
   • Allows code to check or set flow units at runtime for consistency or data manipulation.

3. SimAnalysisSettings

   • Flags that can be toggled on or off for a given simulation, e.g., whether ponding at nodes is allowed, or whether to ignore specific processes like rainfall, groundwater, or quality.
   • Typically used in read-only form to verify if certain SWMM features (e.g., “IgnoreSnowmelt”) are enabled or disabled.

4. SimulationParameters

   • Identifiers (RouteStep, CourantFactor, MinSlope, etc.) for numeric simulation parameters—like the routing time step or tolerance for system flow.
   • Used by PySWMM to retrieve or set these “global” parameters via solver.simulation_get_parameter(...) or solver.simulation_set_parameter(...).

5. ObjectType

   • Maps high-level SWMM object categories (GAGE, SUBCATCH, NODE, LINK, etc.) to integer codes.
   • Fundamental for identifying which type of object PySWMM is querying or modifying (e.g., getProjectSize(ObjectType.NODE), etc.).

6. NodeParams, NodeResults, NodePollut, NodeType

   • NodeParams: Parameter indices for node properties (inverted elevation, full depth, etc.).
   • NodeResults: Indices for retrieving real-time node outputs (depth, head, inflows, overflow).
   • NodePollut: Indices for fetching or setting pollutant concentrations within node reactors or inflows.
   • NodeType: Enumerates possible node categories (junction, outfall, storage, divider).

7. LinkParams, LinkResults, LinkPollut, LinkType

   • LinkParams: Parameter indices for link geometry and constraints (offsets, flow limits, seepage rates).
   • LinkResults: Indices for retrieving link flow, depth, volume, Froude number, or control gate setting.
   • LinkPollut: Water quality results in a link (pollutant concentration, total load).
   • LinkType: Conduit, pump, orifice, weir, or outlet categories.

8. SubcParams, SubcResults, SubcPollut

   • SubcParams: Parameter indices for subcatchment geometry (width, area, slope, curb length).
   • SubcResults: Indices for retrieving simulation-time data like rainfall, infiltration loss, or runoff.
   • SubcPollut: Indices for surface buildup, ponded concentration, runoff water quality, or total load from subcatchments.

9. LidUParams, LidResults, LidUOptions

   • Relate to Low Impact Development (LID) “units” in a subcatchment.
   • LidUParams: Parameter indices for LID sizing or fraction of impervious/pervious flow routed.
   • LidResults: Time-varying data about each LID’s infiltration, storage, drain flow, etc.
   • LidUOptions: Indices for additional configuration like drain node or subcatchment, number of replicate units, etc.

10. LidLayers, LidLayersProperty

• Distinguish layered properties in LIDs (surface, soil, storage, pavement, drain, drainMat).
• Each layer can have properties like thickness, void fraction, roughness, infiltration parameters, etc.

11. RainGageResults

• For rainfall-based objects, enumerates indices for total precipitation, rainfall portion, or snowfall portion.
• Ties into PySWMM’s calls that read or modify raingage intensities.

12. HotstartFile

• Used to indicate whether a hotstart file is being used (loaded) or saved at a point in time.

---

Data Structures

These ctypes.Structure classes map C memory layouts for SWMM statistics into Python objects. They’re typically returned by SWMM’s “get stats” calls (like node_get_stats(...), link_get_stats(...), etc.) and then converted into dictionaries.

1. NodeStats

   • Tracks a node’s depth behavior, flooding volume/duration, infiltration flow, max inflows, ponded volume, etc.
   • Contains fields like avgDepth, maxDepth, volFlooded, and times of surcharge or flooding.

2. StorageStats

   • For storage nodes, holds data on volumes (initial, average, max), peak flow, evaporation, exfiltration losses, plus the date/time at which the max volume occurred.

3. OutfallStats

   • Summarizes outfall flows: average, max flow, total pollutant loads, and how many time periods were valid.
   • Has an internal pointer (PollutArray) for total pollutant loads.

4. LinkStats

   • Includes maximum flow/velocity/depth, times spent in normal flow vs. surcharged conditions, capacity-limited durations, etc.

5. PumpStats

   • Focused on pump usage: min/avg/max flow, energy consumption, number of startups, off-curve behaviors, etc.

6. SubcStats

   • Subcatchment-level precipitation, runon, evaporation, infiltration, runoff, and peak runoff rate.

7. RoutingTotals

   • Aggregated system-level flow routing data: total inflows (dry, wet, groundwater, external), flooding, outflow, evaporation, seepage, initial/final storages, and mass-balance errors.

8. RunoffTotals

   • Aggregated system-level runoff data: total rainfall, evaporation, infiltration, runoff, drains, runon, initial/final storages, snow cover changes, and mass-balance errors.

---

Additional Constants & Classes

• DLLErrorKeys: A dictionary mapping integer error codes (e.g., 411, 412) to descriptive strings. For instance, “Input Error 411: no memory allocated for results.” This is helpful when SWMM’s binary output API returns errors, enabling more user-friendly messages in Python logs or exceptions.

• SMO_* Enums (e.g., SMO_elementCount, SMO_unit, SMO_apiFunction, SMO_elementType, etc.)

  • Used by a separate SWMM output library to manage binary file data retrieval (like SMO_subcatchAttribute or SMO_nodeAttribute).
  • Distinguish different queries (e.g., attributes vs. results, flow rate vs. concentration, node vs. subcatchment) in an output file context.

---

How They Are Used in Practice

1. Parameter Identification

   • For instance, if you want to set a node’s invert elevation, you might call setNodeParam('J1', NodeParams.invertElev, 10.0). The code needs an integer identifier for which parameter to set, which is provided by NodeParams.invertElev.value == 0.

2. Retrieving Time-Varying Results

   • NodeResults.newDepth.value might be used in a function like getNodeResult('J1', NodeResults.newDepth.value), returning the node’s current water depth for the ongoing simulation step.

3. Reading Detailed Stats

   • After a simulation, you can call something like node_statistics('J1'), which returns a NodeStats structure from the C library, then PySWMM converts it to a Python dictionary with keys from _py_alias_ids. For example, {'average_depth': 1.2, 'max_depth': 3.5, ... }.

4. Output File Processing

   • The SMO_* enumerations are used under-the-hood (often by a different part of PySWMM) to interpret binary output files. For example, SMO_elementType.SM_subcatch.value can help retrieve subcatchment data from an external .out file.

---

Key Takeaways

• Enumerations: They serve as “named constants,” bridging human-readable terms (e.g., “invertElev,” “rainfall”) to integer indexes the SWMM C library expects.
• Structures: Provide a direct memory mapping of SWMM’s internal data (like node depth stats) into Python, enabling easy creation of dictionaries or objects for higher-level consumption.
• Integration: All these enums and structures are fundamental to PySWMM’s approach of calling SWMM’s “toolkit” library, thereby offering a coherent, Pythonic approach to setting and retrieving simulation data.
• Error Mapping: DLLErrorKeys clarifies error codes, ensuring that a numeric code (e.g., 411) translates into a descriptive message (e.g., “no memory allocated for results.”).

---

Conclusion

This enumeration module is essentially the “glue” that keeps PySWMM’s higher-level classes (for nodes, links, subcatchments, and system-wide statistics) aligned with SWMM’s internal numeric references. By systematically enumerating parameter indices, result indices, and data structures, it ensures robust, readable, and maintainable code that can easily set or retrieve simulation parameters, real-time results, and post-run statistics from SWMM.