View source for TUFLOW SWMM Troubleshooting

= Introduction =
This page contains useful information outlining common modeling mistakes and steps to troubleshoot them.<br>

=Common Modeling Mistakes=
===Unsaved Control Files===
When changes are made in the control files and the files are not saved, errors occur. 
<ol>
<li>Check all simulation control files and batch files are saved ([[File:Notepad Saved Icon.png]]). A red icon indicates that there are unsaved changes in the file:<br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_01a.png]]<br>
<br>
<li>Use the 'Save All' tool to save all unsaved control files:<br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_02a.png]]<br>
<br>
</ol>

===Unsaved GIS Layers===
When changes are made in GIS layers and the layers are not saved, errors occur. 
<ol>
<li>Check all GIS input layers are saved. If the 'Save Layer Edits' icon is available ([[File:QGIS UnsavedEdits.png|20px]]), there are unsaved edits in the layer. 
<li>A pencil icon on the layer ([[File:QGIS ToggleEditing.png]]) indicates that the layer is still editable and may contain unsaved edits. It is recommended to always turn off editing for all input layers after the edits are complete. <br>
<br>
{{Video|name=Animation_SWMM_Troubleshooting_CommonErrors_01a.mp4|width=500}}<br>
</ol>

=== Unsaved SWMM INP file ===
After edits are complete and saved to the SWMM GeoPackage database, a copy of the information needs to be exported to an INP format for reading into TUFLOW. Two mistakes can occur in relation to INP files:
<ol>
<li> No INP file has been exported. If an INP file referenced in the SWMM control file (TSCF) does not exist, the following dialog will appear when attempting to run the model. If this error occurs, check the INP file has been exported from the SWMM GeoPackage and ensure the file reference in the TSCF does not contain any spelling mistakes.<br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_03a.png]]<br>
<br>

<li> The save date of the INP must be later than its associated GeoPackage file. If this is not the case, the following dialog will appear when attempting to run the model. The error will also be written to the TUFLOW Log File (.tlf). If this error occurs, export the INP file again to ensure it is newer then its associated GeoPackage file. <br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_04a.png]]<br>
<br>
</ol>

===TUFLOW Syntax Rules===
Control files use a double equal sign (<font color="red"><tt>==</tt></font>). When a single equal sign (<tt>=</tt>) is used, the simulation stops with and error at the end of the .tlf file:<br>
<br>
<ol>
[[File:SWMM_Troubleshooting_CommonErrors_05a.png]]<br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_06a.png]]<br>
<br>
</ol>

===Spelling Mistakes in Control Files===
Spelling mistakes in control files can result in a 'does not exist' pop up message:<br>
<br>
<ol>
[[File:SWMM_Troubleshooting_CommonErrors_07a.png]]<br>
</ol>
<br>
To fix the reference:
<ol>
<li>In this example, the file that cannot be found is '''TS01_01.tbc'''. Go to the folder where the file should be ('''TUFLOW\model''' folder). 
<li>The file referenced should be '''TS01_<font color="red">001</font>.tbc'''.
<li>Update the reference in the TCF and confirm the file can now be found by right clicking on the file and selecting open. <br>
{{Video|name=Animation_SWMM_Troubleshooting_CommonErrors_02a.mp4|width=1000}}<br>
</ol>

===Spelling Mistakes in Input Layers===
Spelling mistakes in input layers can result in an error message in the .tlf:<br>
<br>
<ol>
[[File:SWMM_Troubleshooting_CommonErrors_08a.png]]<br>
</ol>
<br>
To fix the reference:
<ol>
<li>In this example, the layer that cannot by found is '''2d_bc_SWMM_Culvert_Connections_001_L'''. This layer is within the '''TS01_001.gpkg''' database. 
<li>In QGIS, within the Browser Panel, navigate to the folder containing the database (the '''TUFLOW\model\gis''' folder in this case). 
<li>Locate the layer with the spelling mistake. In this case '''2d_bc_SWMM_''Culvet''_Connections_001_L'''. 
<li>Right click the layer and select 'Manage' > 'Rename Layer' to save the layer under the correct name ('''2d_bc_SWMM_<font color="red">Culvert</font>_Connections_001_L''').<br>
<br>
{{Video|name=Animation_SWMM_Troubleshooting_CommonErrors_03a.mp4|width=1218}}<br>
</ol>

===TCF does not exist===
Typos or spaces in the TCF name result in a 'does not exist' message in the console window:
<ol>
<li>Check the name of the TCF is referenced correctly in the batch file.
<li>Right click on the TCF in the batch file, select 'Open File' to make sure it can be opened.<br>
<li>Example of incorrect TCF name missing an underscore:<br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_09a.png]]<br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_10a.png]]<br>
<br>
<li>Example of using space in the TCF name causing TUFLOW to look for a TCF name ending with the first space:<br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_11a.png]]<br>
<br>
</ol>

===Ambiguous Command===
TUFLOW control files are command driven text files. The commands must be in the format and location TUFLOW is expecting. The <u>[https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]</u> and the <u>[https://docs.tuflow.com/classic-hpc/release/latest/ TUFLOW Release Notes]</u> list all the available commands and specify which TUFLOW control file each command belongs to.<br>
<ol>
<li>Example of a typo in the ' <font color="blue"><tt>BC Control File</font><font color="red"> ==</tt></font> ' command: <br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_12a.png]]<br>
<br>
<li>Example of ' <font color="blue"><tt>Map Output Data Types </font><font color="red">==</tt></font> ' command entered into TGC instead of TCF: <br>
<br>
[[File:SWMM_Troubleshooting_CommonErrors_13a.png]]<br>
<br>
</ol>

=Troubleshooting Steps=
== Model won't run == 
=== Simulation Console Window Flashes and Disappears ===
When batch file is double clicked and the simulation console window flashes and disappears the problem might be in the filepath of the TUFLOW executable or incorrect syntax:
<ol>
<li>Check the TUFLOW executable can be found with the specified filepath (absolute or relative).
<li>Double click the executable, this performs a licence check and console window appears. If it doesn't, move the executable to a location where it is permitted to run. Some locations on C drive might be restricted for some users preventing to execute the simulation.
<li>TUFLOW doesn't run from a batch file if the filepaths are specified as UNC paths. The folder with both, the executable and the model, must be opened with a mapped drive. Type "net use <drive>: \\server_name\share_name" in the command line to map the drives.
<li>If using environment variable 'set exe', confirm there are no spaces surrounding the equals sign (e.g. <font color="blue"><tt>set </font>exe<font color="red>=</font>"..\..\..\exe\2026.0.0\TUFLOW_iSP_w64.exe"</tt>).
<li>Write '<font color="blue><tt>pause</tt></font>' at the end of the script, rerun the batch file and the console window should remain open providing more information. In the below example, the file path to the TUFLOW exe is incorrect:<br>
<br>
{{Video|name=Animation_SWMM_Troubleshooting_Steps_01a.mp4|width=1218}}<br>
</ol>

=== _ TUFLOW Simulations (*.log) ===
The log file contains brief overview of the simulation:
<ol>
<li>Navigate to the '''TUFLOW\runs''' folder and open the '''_ TUFLOW Simulations.log''' in a text editor. 
<li>Confirm if the simulation has 'Started' and 'Finished' line.
<li>If there is no log file, see the '''Simulation Console Window Flashes and Disappears''' advice above.<br>
<br>
</ol>

=== TUFLOW Log File (*.tlf) ===
The .tlf file contains information on the model run status and any error messages:
<ol>
<li>Navigate to the '''TUFLOW\runs\log''' folder and open the '''.tlf''' file in a text editor.
<li>Scroll to the bottom to confirm the model run finished successfully by observing "Simulation FINISHED".
<li>If not, search from the bottom up for any error, warning or check messages.
<li>Review the error number, open the link provided in a web browser and read through the description and suggestions:<br>
<br>
{{Video|name=Animation_SWMM_Troubleshooting_Steps_02a.mp4|width=1218}}<br>

<li>Open the .qgs workspace in QGIS from the '''TUFLOW\runs\log''' folder.
<li>Click 'Apply TUFLOW Styles to Open Layers'.
<li>Zoom in to the location of any error messages, turn on labelling to view the error. 
<li>In this example the 2d_bc CN connection isn't snapped to the SX line.<br>
<br>
{{Video|name=Animation_SWMM_Troubleshooting_Steps_03a.mp4|width=1218}}<br>

<li>If no error messages appear in the .tlf and the last line shows 'Sending initialisation data to HPC...' see <u>[[Tutorial_Troubleshooting_QGIS#HPC_TUFLOW_Log_File_.28.2Ahpc.tlf.29 | HPC TUFLOW Log File]]</u> below.
<li>Ensure that the final cumulative mass error is less then 1%. To reduce the mass error and fix model instabilities, see <u>[[TUFLOW_SWMM_Troubleshooting#Model_runs_with_high_mass_error_or_instabilities | Improving Model Stability]]</u> below.<br>
<br> 
[[File:SWMM_Troubleshooting_Steps_01a.png]]<br>
<br>
</ol>

=== SWMM Report File (*rpt)===
The SWMM Report File ('''*.rpt''') contains SWMM related error messages. If the error relates to SWMM, the .tlf will state:<br> 
:<tt>NoXY: ERROR during Preparing and starting SWMM simulation</tt><br>
::<tt>For SWMM Model Errors see: <<path to rpt file>></tt><br>
To investigate the error(s):
<ol>
<li>Navigate to the '''TUFLOW\results''' folder and open the '''.rpt''' file in a text editor. Review the SWMM initialization error message.
<li>In this case, there is an invalid keyword in the 'OUTFALL' section. This refers to the SWMM INP file. 
<li>Navigate to the '''TUFLOW\model\swmm''' folder and open the INP file in a text editor. Find and correct the error.<br>
<br>
{{Video|name=Animation_SWMM_Troubleshooting_Steps_04a.mp4|width=1218}}<br>
</ol>

=== HPC TUFLOW Log File (*.hpc.tlf) ===
The .hpc.tlf file contains error messages not recorded in the .tlf file:
<ol>
<li>Navigate to the '''TUFLOW\runs\log''' folder and open the '''.hpc.tlf''' file in a text editor. If the last lines shows:<br>
<br>
[[File:SWMM_Troubleshooting_Steps_02a.png]]<br>
<br>
<li>The model is set up to run on GPU and there is no GPU available, or
<li>The GPU needs a driver update, for more information see <u>[https://wiki.tuflow.com/index.php?title=GPU_Setup Update GPU Driver]</u>.<br>
<br>
</ol>

== Model runs with high mass error or instabilities ==
=== Identifying Trouble Spots ===
<ol>
<li>TUFLOW GIS messages file ('''_messages.gpkg'''):
*Navigate to the '''TUFLOW\runs\log''' folder and open the '''_messages.gpkg''' file in QGIS. 
*Look for instabilities and 2D timestep instability warnings in the file to identify areas of concern. They will often occur near SWMM/2D connections.
<li>SWMM Report file ('''.rpt'''):
*Navigate to the '''TUFLOW\results''' folder and open the '''.rpt''' file in a text editor. 
*To determine overall model health, look at the '<tt>Continuity Error (%)</tt>'. This value should be between -0.5% and 0.5%.  
*The '<tt>Highest Flow Instability Indexes</tt>' and '<tt>Most Frequent Nonconverging Nodes</tt>' may indicate areas of instability in the model. 
<li>Update the Report Step:
*Open the GeoPackage file containing the SWMM options into QGIS. By default, this GeoPackage will be in the '''TUFLOW\model\swmm''' folder.
*Turn on editing for the '''Project--Options''' layer and update the 'REPORT_STEP' attribute to a small time frame (i.e. 5 seconds). 
*Ensure the 'ROUTING_STEP' attribute is smaller then the new 'REPORT_STEP' value. Save the edits and export the SWMM INP.
*Rerun the model with the updated Report Step. The time series reports may then include oscillations at unstable areas. <br>
<br>
</ol>

=== Improving Model Stability ===
Below are some common causes of instabilities and methods to improve them. 
<ol>
<li>The timestep:
*The timestep can cause instabilities. By default, SWMM uses the 2D timestep. Use the TCF command <font color="blue"><tt>Timestep Maximum</font></tt> to force a smaller 2D timestep and improve SWMM stability. This fix is often required when using SWMM hydrology as it puts water into the 1D domain before the 2D, which can lead to large 2D timesteps.
<li>Insufficient storage at 1D nodes:
*Model instabilities often arise from insufficient storage at 1D nodes, especially those associated with HX boundaries. HX cells do not have storage associated with them, so the storage for those cells should be represented in the SWMM domain. 
*Storage nodes using the 'PYRAMIDAL' type can be set up to match the 2D model. The size of the shape should correspond to the area of the 2D cells. For example, if two 10m cells are selected, the length (L) and width (W) should be set to 20m and 10m, respectively. Larger dimensions may improve stability, but increasing them too far beyond the cell size may artificially attenuate flood hydrographs.
<li>Not enough connections between the 2D cells and the SWMM 1D network:
*Instabilities may arise from having too few 2D cells connected to the SWMM 1D network. For example, a rectangular culvert 20m wide connected to a single 5m cell may create an instability. In this case, it is recommended that the culvert is connected to four (or more) cells.
<li>2D cells are raised due to a HX connection:
*Instabilities may occur if 2D cells are raised due to an HX connection. HX connections require 2D cell elevations be higher than the node elevation. If an embankment culvert is elevated above the 2D cell elevations (which is common), set the node elevation at or below the lowest 2D cell elevation. Use the 'InOffset' elevation on adjacent conduits to set the culvert to the appropriate elevation, preventing the cell from being raised to the culvert invert.
<li>Incorrectly placed SWMM connections:
*Incorrectly placed SWMM connections may lead to instabilities. For example, if an embankment culvert connects adjacent ditches, but the connections select cells adjacent to rather than containing the ditches, the improper cell selection tends to throttle the flows in 2D even though the 1D has sufficient capacity. This creates a mismatch that leads to oscillations.
<li>If the model is still unstable after trying all the above options:
*If some SWMM to 2D HX connections (embankment culverts) are still unstable, consider converting the HX connections to SX connections with an inlet. This is generally required for embankment culverts where there is overtopping so only a fraction of the flow goes through the culverts (HX culvert connections work well if the culverts convey the majority of the flow). An inlet is required for SX connections. A drop curb inlet can provide a suitable open area for a culvert connection. An SX connection with an inlet may be more stable in these situations because the discharge is based on the WSE (water surface elevation) in the cell rather than the flow going through the cell.
</ol>
<br>

=Conclusion=
If the above tips do not assist in fixing the error, email [mailto:support@tuflow.com support@tuflow.com].<br>

TUFLOW SWMM Tutorial Models:
*<u>[[TUFLOW_SWMM_Tutorial_M01 | TUFLOW SWMM Module 1]]</u>  - 1D SWMM Culverts
*<u>[[TUFLOW_SWMM_Tutorial_M02 | TUFLOW SWMM Module 2]]</u>  - 1D SWMM Pipe Network / 2D TUFLOW Direct Rainfall Hydrology
*<u>[[TUFLOW_SWMM_Tutorial_M03 | TUFLOW SWMM Module 3]]</u>  - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology
*<u>[[TUFLOW_SWMM_Tutorial_M04 | TUFLOW SWMM Module 4]]</u>  - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology: Executing multiple different event simulations from a single model control file.
*<u>[[XPSWMM_to_TUFLOW-SWMM | XPSWMM to TUFLOW SWMM]]</u>  - How to convert an XPSWMM model to TUFLOW SWMM.