SWMM5 Delphi GUI Ucombine.pas Summary

 Extended and Expanded Summary of Ucombine.pas

This Delphi unit, Ucombine.pas, contains a single public function, CombineFiles, which merges two SWMM interface files into a third file. In SWMM, these interface files (often called routing interface or intermediate data files) store flow and water quality data at specific time steps for multiple locations. The combined file merges data from two such interface files into one, effectively combining hydrographs and pollutographs in terms of flow and mass.

---

1. Purpose and Context

• Interface Files are text-based data files produced by or read by SWMM at the boundary between different model components (e.g., used when splitting a large model into two stages or combining separate upstream routing results).
• This unit aims to read two interface files (F1 and F2) and produce a single combined interface file (F3) where flow and mass-based water quality parameters from F1 and F2 are added at each location and time.
  • For flow variables, the new file's flow is the sum of flows from the two input files.
  • For water quality variables, the new file's pollutant concentration is derived by combining mass flow (flow * concentration) from each file and then dividing by the resulting flow to get a new concentration.

The procedure ensures that all dates, times, node names, and parameter names from both input files are consolidated properly.

---

2. Key Data Structures

1. F: An array of TextFile, containing:

   • F[1]: The first input file.
   • F[2]: The second input file.
   • F[3]: The temporary output file (which eventually becomes F3).

2. Nparams[i], Nnodes[i]: The number of parameters and the number of nodes found in file i.

3. Tstep[i]: The time step (in seconds) for file i.

4. Params[i], ParamUnits[i]: TStringList that store the parameter names and units for file i.

5. Nodes[i]: TStringList holding all node (location) names for file i.

6. ParamIndex2[]: An integer array mapping each parameter in file 2 to its position (index) in the merged set of parameters.

7. NodeIndex2[]: Similar mapping for node names from file 2 to the merged node list.

8. Time-based arrays:

   • V1 (primary file’s data at the current time).
   • V2, V2before, V2after (secondary file’s data, for interpolation).
   • V3 (the merged data to write to the new file).

9. Dates:

   • BeforeDate[1..2] / AfterDate[1..2]: The times from the primary or secondary file that bracket the current date used in combining.
   • CurrentDate: The date/time for which the code merges data from both files.
   • Ndates: The number of time records ultimately written to the new file.

---

3. CombineFiles Function Logic

function CombineFiles(const F1, F2, F3, Title: String): Boolean;

Takes four arguments:

• F1: Name of interface file #1.
• F2: Name of interface file #2.
• F3: Name of the resulting combined file.
• Title: A string stored in the combined file’s header.

Returns True if combining is successful, otherwise False.

Steps in the Combining Process

1. File Name Checks:

   • Ensures F1 and F2 exist and are distinct from each other and from F3.

2. Open Files:

   • Opens F1 and F2 for reading (Reset)
   • Opens a temporary file for combined output, because if an error occurs, we discard it.

3. Parse Header:

   • Each interface file has a specified header with:
     1. A line containing 'SWMM5'
     2. A project-specific title line
     3. A time step integer
     4. A count of parameters + each parameter’s name/units
     5. A count of nodes + each node’s name
   • The code checks each file for correct formatting and extracts these elements into arrays/lists:
     • Nparams[], Params[], ParamUnits[], Nnodes[], Nodes[]
   • If not properly formatted, raises an error.

4. Merge Parameter & Node Lists:

   • Some parameters might be present in both files. For instance, each file must have "FLOW" as its first parameter.
   • If a parameter is new to the second file, it is appended to the combined parameter list.
   • The code also merges the node (location) lists from both files, so the result includes every node from both input files.
   • The arrays ParamIndex2[] and NodeIndex2[] record the mapping from file #2’s param/node to the merged list.

5. Allocate Data Arrays:

   • The code sets up the V1, V2, V2before, V2after, and V3 arrays with row dimension = number of nodes, column dimension = number of parameters.
   • The “primary file” is the one with the smaller time step.

6. Write Combined File Header:

   • SWMM5 Interface File
   • The Title argument
   • The time step for the combined file (the smaller of the two input file steps)
   • The total count of parameters, their names & units
   • The total count of merged nodes, plus their names
   • A final heading line for data columns

7. Initial Data Reading:

   • The routine loads the first data record from each file (the code calls ReadValues) which extracts date/time and an array of parameter values for each node.

8. Iterative Combine:

   • The function keeps a CurrentDate that increments in steps of the primary file’s time step.
   • For each iteration:
     • (a) If the secondary file times haven’t yet started for the CurrentDate, the code uses repeated increments, or if it’s started but not caught up, the code reads from the secondary file.
     • (b) Interpolation might be used if the primary file’s CurrentDate is between two date/times in the secondary file.
       • V2before and V2after bracket the times around CurrentDate.
       • The code linearly interpolates the parameter values into V2.
     • (c) Summation is done by “flow” plus “mass.” The code:
       1. Clears V3.
       2. Merges the primary flow V1 + secondary flow V2.
       3. Merges pollutant loads (mass flow = flow * concentration).
       4. Then “convert” to concentration by dividing total mass by total flow.
     • (d) Writes out a line to the combined file for each node.
   • The loop continues until both input files are exhausted.

9. Cleanup:

   • Closes all files.
   • If no errors, renames the temporary output to user’s requested name F3.
   • If errors, notifies the user and returns False.

---

4. Interpolation Explanation

When the primary file’s CurrentDate is between BeforeDate[2] and AfterDate[2] from the secondary file:

1. BeforeDate[2] is the last known date/time from file #2 that is <= CurrentDate.
2. AfterDate[2] is the next date/time from file #2 that is >= CurrentDate.
3. V2before and V2after store the node parameter arrays from those two bounding times.
4. The code uses linear interpolation fraction F = (CurrentDate - BeforeDate[2]) / (AfterDate[2] - BeforeDate[2]).
5. Then sets V2[j,k] = V2before[j,k] + F*( V2after[j,k] - V2before[j,k] ).

---

5. Error Handling

• Various checks are made: e.g., verifying file existence, format correctness, matching parameter units for parameters with same name, date/time expansions, etc.
• A global string ErrorTxt is used to store error messages. If it’s non-empty, the routine stops and returns False.
• If an error occurs or the user-supplied output file can't be created, the code deletes the temporary file and displays a message.

---

6. Summary of Output

• The combined file is a valid SWMM interface file with:
  • Time steps at the smaller interval of the two input files.
  • Parameter set that includes all unique parameters from both input files.
  • Node set that includes all unique node/location IDs from both input files.
  • Merged flow & concentration values at each time step for each node.

Hence, the function CombineFiles is the entry point used by a higher-level user interface form (FileCombineForm) to merge two routing interface files, producing one that sums flows and merges water quality data.