SWMM5 Delphi GUI Uoutput.pas Summary

 Extended and Expanded Summary of the Uoutput.pas Unit

This Uoutput.pas unit is responsible for reading and interpreting the results of an EPA SWMM simulation from its binary output file. It also provides methods to color-code (thematic map) the project objects (subcatchments, nodes, and links) based on simulation results or input data. Below is a consolidated overview of the unit’s purpose, core routines, data flow, and interactions with other parts of SWMM.

---

1. Purpose and Responsibilities

1. Output File Handling:

   • Open/Close Binary File
     - The unit opens an existing SWMM output file in read-only mode to extract simulation results.
     - Closes the file when the read is complete or when a new run is triggered.

   • Check and Clear Output
     - It checks if a run was successfully completed (CheckRunStatus).
     - Clears (frees) any in-memory data structures storing results when needed (ClearOutput).

2. Retrieving Computed Results:

   • Basic Data (time steps, subcatch/node/link counts).
   • Detailed Data for each subcatchment, node, and link across time.
   • Summaries (min/max) at a specific time period.
   • Single or array-based retrieval (e.g., GetLinkOutVal, GetNodeOutVals, etc.).

3. Color Coding in Thematic Maps:

   • Each subcatchment/node/link is assigned a ColorIndex used by the map display code to show color gradients.
   • The color index is determined by comparing a computed or input value against intervals stored in the legend (via calls like FindSubcatchColor, FindNodeColor, etc.).
   • Also handles “query mode,” which color-codes objects if their value meets a certain condition (above/below/equal).

4. String Conversion Routines:

   • Converts a numeric result into a formatted string for display in the SWMM user interface (e.g., ID, run results, or input variables).

5. Integration with Other SWMM Units:

   • Uglobals.pas: Provides global variables (like CurrentSubcatchVar, CurrentLinkVar, color legend arrays, etc.).
   • Uproject.pas: Access to the project’s subcatchment/node/link objects and their input data.
   • Uresults.pas: Specialized routines to retrieve summary (min/max) results.
   • Fmain.pas and Ubrowser.pas: The main UI and project browser forms can ask Uoutput for time series or single-value outputs.

---

2. Key Data Structures

1. Global Variables

   • Nsubcatchs, Nnodes, Nlinks, Npolluts: counts of objects stored in the output file.
   • Fout: A file handle to the open binary results file.
   • Offset0, Offset1, Offset2: Byte offsets in the file to different data sections.

2. Computed Value Arrays

   • Zsubcatch[], Znode[], Zlink[]: Arrays that store results for subcatchments, nodes, and links, respectively, at a single time step.
   • FlowDir[]: Stores flow directions (±) for each link.

3. Legend/Color Index Mechanisms

   • The FindSubcatchColor, FindNodeColor, and FindLinkColor methods implement lookups to see where a value sits in a set of intervals.

---

3. Primary Procedures & Functions

3.1 Opening, Checking, and Clearing Output

• OpenOutputFile(Fname: String): TRunStatus
  Opens the SWMM output file Fname in read-only mode, returning a run status. If the file cannot be opened or is invalid, returns rsError.

• CheckRunStatus(Fname: String): TRunStatus
  Confirms whether the SWMM run ended successfully by reading “magic number,” version, number of periods, and error code at the file’s end.

• ClearOutput()
  Closes the file handle if open, re-initializes run flags, and resets each object’s OutFileIndex.

• CloseOutputFile()
  Simply closes the file handle Fout.

3.2 Retrieving Basic Output Metadata

• GetBasicOutput()
  Reads metadata from the output file (like flow units, count of subcatch/node/link, number of computed variables, start time, etc.). Sets up arrays for results retrieval.
  Also sets StartDateTime, Nperiods, DeltaDateTime, etc.

• GetConduitSlope(L: TLink): Extended
  For a given conduit link, calculates slope from its upstream/downstream offsets.

• GetFlowDir(TimePeriod: Integer)
  Retrieves link flows at TimePeriod and sets each link’s flow direction in global FlowDir[] array.

3.3 Retrieving Computed Values

There is a consistent pattern of methods to retrieve data for subcatchments, nodes, or links.

1. Subcatchment

   • GetSubcatchOutVal(V, Period, Zindex): Single retrieves a single subcatchment’s output variable at a time.
   • GetSubcatchOutVals(SubcatchVar, Period, Value[]) fills an array of subcatchment values for that variable and time.
   • GetSubcatchValStr(SubcatchVar, Period, SubcatchIndex): String returns the string form.

2. Node

   • GetNodeOutVal(V, Period, Zindex): Single retrieves a single node’s variable.
   • GetNodeOutVals(NodeVar, Period, Value[]) array form.
   • GetNodeValStr(NodeVar, Period, NodeType, NodeIndex): String string form.

3. Link

   • GetLinkOutVal(V, Period, Zindex): Single single retrieval.
   • GetLinkOutVals(LinkVar, Period, Value[]) array form.
   • GetLinkValStr(LinkVar, Period, LinkType, LinkIndex): String string form.

4. System-Wide

   • GetSysOutVal(V, Period): Single retrieves a single “system” variable (like total runoff or infiltration) at a given time step.

3.4 Setting Color Indices for Thematic Mapping

• FindSubcatchColor(Z: Single): Integer: Determines the subcatchment color index for the value Z based on the intervals in the SubcatchLegend.

• FindNodeColor(Z: Single): Integer: Same logic for nodes.

• FindLinkColor(Z: Single): Integer: Same logic for links.

• SetSubcatchColors, SetNodeColors, SetLinkColors
  High-level routines that check the current “theme variable” (input or output) and call sub-routines:

  • If theme is an input variable, they call e.g. SetSubcatchInColors(var).
  • If theme is an output variable (and run is complete), they call e.g. SetSubcatchOutColors(var).
  • If theme is a summary variable, they call e.g. SetSubcatchRptColors(var).

• SetQueryColor(Z: Single): Integer
  Special color-coding if the user is performing a query (above/below/equal to a threshold).

---

4. Data Flow and Execution Steps

Typical usage:

1. Simulation completes and writes a .out file.
2. OpenOutputFile is called with the .out path.
3. CheckRunStatus ensures the .out file is valid.
4. GetBasicOutput reads high-level info (# subcatch, # nodes, # links, times, etc.) and sets up arrays (Zsubcatch, Znode, Zlink).
5. The SWMM user interface calls various data retrieval methods (e.g. GetNodeOutVal(...) or GetLinkValStr(...)) for table displays, profile plots, or map labeling.
6. For the thematic map, the SWMM engine calls SetSubcatchColors, SetNodeColors, SetLinkColors. Each subcatch/node/link object’s ColorIndex is assigned by reading a relevant variable value from the .out file or from input data.
7. The map drawing code (in Umap.pas) picks up each object’s ColorIndex to determine which color from the legend intervals.

---

5. Edge Cases and Error Handling

• No or Invalid Output File: CheckRunStatus and OpenOutputFile can return rsError. The calling code must handle it.
• Query-Mode: If QueryFlag is true, the code bypasses normal intervals and uses SetQueryColor.
• Missing Values: The code uses MISSING or returns string NA if a subcatch/node/link has no results or is out of range.

---

6. Links to Other Units

• Uglobals.pas for global variables, color arrays, the theme variable indexes (CurrentNodeVar, CurrentLinkVar, etc.), and run state flags.
• Uproject.pas for direct references to subcatch/node/link objects and their input fields.
• Uresults.pas for reading summary results into arrays.
• Umap.pas for using the ColorIndex set by Uoutput in drawing.
• Fmain.pas & Ubrowser.pas for UI-level calls to display results.

---

Conclusion:

• The Uoutput.pas unit is pivotal for bridging the SWMM binary results file to the user interface.
• It carefully references object data in Uproject.pas to label, color, or compute transformations on the run results.
• The consistency and clarity of how it handles variables (input vs. output, subcatch/node/link) is key to SWMM’s flexible display of data.