SWMM5 Delphi GUI Ucalib.pas Summary

 Extended and Expanded Summary of Ucalib.pas

This Delphi unit, named Ucalib.pas, is part of the EPA SWMM GUI codebase. It provides routines for retrieving and plotting observed calibration data that match SWMM's simulation data. More specifically, it fetches time-series observations (e.g., measured runoff, flow, groundwater elevations, water quality) from an external calibration file and then plots them (as points) on a TeeChart series in a graph.

---

1. Primary Purpose

• Read measured data from a set of calibration files (each file dedicated to a specific kind of data, such as runoff, node depth, link flow, etc.).
• Parse these calibration files for a particular location (like a subcatchment ID or node ID) and for a particular variable.
• Plot the data onto a TChartSeries object for visual comparison with the model’s computed time-series on the same plot.

---

2. Key Constants and Structures

1. Link between "view variable indexes" and "calibration file indexes":

   A comment block explains which calibration file index corresponds to a certain SWMM variable. For instance:

   • Subcatchment RUNOFF -> calibration file index #1
   • Node NODEDEPTH -> calibration file index #3
   • Link FLOW -> calibration file index #4
   • etc.

2. CalibData array:
   An external global array (declared somewhere else, presumably Uglobals.pas) that records the file name and location list for each calibration file index.
   For example, CalibData[1].FileName might be the file containing subcatchment runoff measurements. And CalibData[1].Locations might be a string listing which subcatchment IDs have data there.

3. Toklist: TStringList:
   Used to store tokenized strings read from the calibration file lines.

4. StartDate, EndDate, TimeFactor, DateTimeDisplay, SimStartDate:
   Shared module-level variables set by the main procedure, used in reading/processing times from the calibration file so that they line up with the time displayed on the TChart.

---

3. Main Procedure: GetCalibData(...)

This is the central routine that:

1. Identifies which calibration file to use by calling GetCalibFileIndex().
2. Checks if that file has measurement data for the user-specified location (like a subcatchment or node ID).
3. Opens the calibration file and tokenizes each line.
4. Processes lines belonging to the location of interest.
5. Extracts the measurement time and data value from tokens.
6. Adds a point to the chart if it passes checks (within time range, is valid numeric value, etc.).

Parameters:

• VarIndex: Index identifying the SWMM result variable (like RUNOFF, FLOW, etc.).
• ObjType: Whether it’s subcatchment, node, or link variable.
• LocID: The name (ID) of the specific object (like "Node10" or "Subcatch5") to find in the calibration file.
• aStartDate, aEndDate: Date range that we want to plot.
• aTimeFactor: If we’re not plotting date/time, this factor is used to convert from days to hours or something similar.
• aDateTimeDisplay: True if chart uses real date/time for the X-axis. Otherwise, it’s using an elapsed time scale.
• ChartSeries: A TChartSeries object (for instance a TPointSeries) to which calibration data points are added.

Steps:

1. GetCalibFileIndex(...): Figures out which calibration file index (1..12, etc.) applies to the variable. Some variables have an additional offset if it’s a pollutant.
2. If FileIndex = 0, we know there’s no relevant calibration file for that variable.
3. If the LocID is not present in that file’s Locations string, we skip.
4. Calculate a “simulation start date” that is slightly earlier than the actual start (one reporting step earlier).
5. Open the file:
   • For each line, strip comments, parse tokens, detect if a single token indicates new location header.
   • If it matches LocID, we turn on UseData := True; if not, turn it off.
   • Otherwise, if line has enough tokens, parse the measurement time from token[0,1] and the measurement value from token[ DataTok ].
   • Check if the date/time is within [StartDate..EndDate]. If so, add it to the chart.
6. Close the file & free resources.

AddCalibDataPoint(...) is a helper function that tries to parse the first two tokens as date/time or as an “elapsed day/hour,” then parse the measurement value from a third token. If successful and in range, it calls ChartSeries.AddXY(...).

---

4. GetCalibFileIndex(VarIndex, ObjType, var FileIndex, var VarOffset)

This helper function looks at:

• Which object type (Subcatch, Node, or Link).
• Which variable index (RUNOFF, FLOW, etc.).

It sets:

• FileIndex: which calibration file index to use (1 for runoff, 2 for subcatchment water quality, 3 for node depth, etc.).
• VarOffset: a zero-based offset used when a variable might be a pollutant. That means the base index for the calibration file is 2 or 5, but if we have multiple pollutants, we add an offset to know which pollutant is being measured.

---

5. File Format / Data Reading

Calibration file structure is presumably:

; Comments
Subcatch5
6/1/2019  7:00  0.25
6/1/2019  7:15  0.28
... etc ...
SomeOtherLocation
...

• A single token line indicates a new location ID.
• Next lines with multiple tokens: [Date/Time] [Value(s)...].

AddCalibDataPoint tries to parse the date/time. If it fails, it tries to interpret the tokens as “Elapsed days and hours.” Either way, it forms a TDateTime or a float X-value for the chart.

---

6. Summary

1. Ucalib.pas provides a way to read measured calibration data from external text files (the CalibData array).
2. The function GetCalibData does the main work: deciding which file to open, searching for the location ID, parsing lines, building time-value data points, and adding them to a chart series.
3. The calibration file can have multiple location blocks. Only lines after the “LocID” line are used until a new location name is encountered.
4. The measured times can be in actual date/time or in elapsed time. The code tries one method, catches exceptions, and then tries the other method.
5. Points are only included if within [StartDate..EndDate].
6. The final effect is that the chart can overlay these measured points on top of the model’s simulated time-series for that location and variable, enabling visual calibration or error checking.

Thus, Ucalib.pas is a straightforward but crucial component for importing and plotting observed calibration data in the SWMM interface. It ensures the user can compare computed vs. observed results directly within the GUI’s time series graphs.