Difference between revisions of "Tutorial Troubleshooting QGIS"

From Tuflow
Jump to navigation Jump to search
 
(52 intermediate revisions by 4 users not shown)
Line 9: Line 9:
 
<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>
 
<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>
 
<br>
[[File:Troubleshooting CommonErrors 01.png]]<br>
+
[[File:Troubleshooting_CommonErrors_01a.png]]<br>
 
<br>
 
<br>
 
<li>Use the 'Save All' tool to save all unsaved control files:<br>
 
<li>Use the 'Save All' tool to save all unsaved control files:<br>
 
<br>
 
<br>
[[File:Animation Troubleshooting CommonErrors 12.gif]]<br>
+
[[File:Troubleshooting_CommonErrors_12.png]]<br>
 
<br>
 
<br>
 
</ol>
 
</ol>
Line 23: Line 23:
 
<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. <br>
 
<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. <br>
 
<br>
 
<br>
[[File:Animation Troubleshooting CommonErrors 02a.gif]]<br>
+
{{Video|name=Animation_Troubleshooting_CommonErrors_02c.mp4}}<br>
 
<br>
 
<br>
 
</ol>
 
</ol>
  
 
===TUFLOW Syntax Rules===
 
===TUFLOW Syntax Rules===
Control files use a double equal sign (==). When a single equal sign is used, the simulation stops with and error at the end of the .tlf file:<br>
+
Control files use a double equal sign (==). When a single equal sign (=) is used, the simulation stops with and error at the end of the .tlf file:<br>
 
<br>
 
<br>
 
<ol>
 
<ol>
[[File:Troubleshooting CommonErrors 15.png]]<br>
+
[[File:Troubleshooting_CommonErrors_16b.png]]<br>
 +
<br>
 +
[[File:Troubleshooting_CommonErrors_15a.png]]<br>
 
</ol>
 
</ol>
 
<br>
 
<br>
  
===Typos in Control Files===
+
===Spelling Mistakes in Control Files===
  
Typos in control files are common, with the majority resulting in a 'does not exist' pop up message:<br>
+
Spelling mistakes in control files are a common mistake, resulting in a 'does not exist' pop up message:<br>
 
<br>
 
<br>
 
<ol>
 
<ol>
[[File:Troubleshooting CommonErrors 03.png]]<br>
+
[[File:Troubleshooting_CommonErrors_03b.png]]<br>
 
</ol>
 
</ol>
 
<br>
 
<br>
 
To fix the reference:
 
To fix the reference:
 
<ol>
 
<ol>
<li>The file that cannot by found is '''M02_01.tgc'''. Go to the folder where the file should be (in this example the '''TUFLOW\model''' folder).  
+
<li>The file that cannot by found is '''M01_01.tgc'''. Go to the folder where the file should be (in this example the '''TUFLOW\model''' folder).  
<li>The file referenced should be M02_'''001'''.tgc.
+
<li>The file referenced should be M01_'''001'''.tgc.
 
<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>
 
<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>
 
<br>
 
<br>
[[File:Animation Troubleshooting CommonErrors 04.gif]]<br>
+
{{Video|name=Animation_Troubleshooting_CommonErrors_04a.mp4|width=1128}}<br>
 
<br>
 
<br>
 
</ol>
 
</ol>
  
===Typos in Input Layers===
+
===Spelling Mistakes in Input Layers===
Typos in input layers are common, resulting in a 'does not exist' pop up message:<br>
+
Spelling mistakes in input layers are also a common mistake, resulting in a 'does not exist' pop up message:<br>
 
<br>
 
<br>
 
<ol>
 
<ol>
[[File:Troubleshooting CommonErrors 13.png]]<br>
+
[[File:Troubleshooting_CommonErrors_13a.png]]<br>
 
</ol>
 
</ol>
 
<br>
 
<br>
 
To fix the reference:
 
To fix the reference:
 
<ol>
 
<ol>
<li>The layer that cannot by found is '''1d_nwk_M03_culverts_001_L.shp'''. Go to the folder where the file should be (in this example the '''TUFLOW\model\gis''' folder).  
+
<li>The layer that cannot by found is '''2d_bc_M03_culverts_001_P.shp'''. Go to the folder where the file should be (in this example the '''TUFLOW\model\gis''' folder).  
<li>The layer has a spelling mistake 'culvrts'.
+
<li>The layer has a spelling mistake 'culvets'.
 
<li>In QGIS use the 'Increment Selected Layer' tool to save the file with the correct name.<br>  
 
<li>In QGIS use the 'Increment Selected Layer' tool to save the file with the correct name.<br>  
 
Note: The tool automatically increments a number if it is at the end of the file name.<br>
 
Note: The tool automatically increments a number if it is at the end of the file name.<br>
 
<br>
 
<br>
[[File:Animation Troubleshooting CommonErrors 14.gif]]<br>
+
{{Video|name=Animation_Troubleshooting_CommonErrors_14b.mp4|width=1217}}<br>
 +
</ol>
 +
<br>
 +
 
 +
===TCF does not exist===
 +
Typos or spaces in the TCF name result in a 'does not exist' message in the DOS 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:Troubleshooting CommonErrors 19.png]]<br>
 +
<br>
 +
[[File:Troubleshooting_CommonErrors_20a.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:Troubleshooting_CommonErrors_17a.png]]<br>
 
<br>
 
<br>
 
</ol>
 
</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> lists all the available commands and specifies which TUFLOW control file each command belongs to.<br>
 +
<ol>
 +
<li>Example of a typo in the 'BC Control File ==' command: <br>
 +
<br>
 +
[[File:Troubleshooting_CommonErrors_18b.png]]<br>
 +
<br>
 +
<li>Example of 'Map Output Data Types ==' command entered into TGC instead of TCF: <br>
 +
<br>
 +
[[File:Troubleshooting_CommonErrors_21b.png]]<br>
 +
</ol>
 +
<br>
  
 
=Troubleshooting Steps=
 
=Troubleshooting Steps=
=== DOS Window Flashes and Disappears ===
+
=== Simulation DOS Window Flashes and Disappears ===
When a batch file has been clicked and a DOS window flashes up and disappears:
+
When batch file is double clicked and the simulation DOS window flashes and disappears the problem might be in the filepath of the TUFLOW executable or incorrect syntax:
 
<ol>
 
<ol>
<li>Check the location of the TUFLOW executable. Right click on the .exe from the batch file and ensure that the executable can be found and open.  
+
<li>Check the TUFLOW executable can be found with the specified filepath (absolute or relative).
<li>Check the location of the TCF. Right click on the TCF from the batch file and ensure that the file can be found and open.
+
<li>Double click the executable, this performs a licence check and DOS 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>If using environment variable 'set exe', confirm there are no spaces surrounding the equals sign (e.g. set exe="..\..\..\..\exe\2020-10-AD\TUFLOW_iSP_w64.exe").
+
<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>Check where the model and executable are located. We recommend to '''not''' use the C drive or an external hard drive.
+
<li>If using environment variable 'set exe', confirm there are no spaces surrounding the equals sign (e.g. set exe="..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe").
<li>Batch files do not currently support UNC paths. The folder with the executable has to be opened with a mapped drive. Type "net use <drive>: \\server_name\share_name" in the command line to map desired drive.
+
<li>Write 'pause' at the end of the script, rerun the batch file and the DOS window should remain open providing more information. In the below example, the file path to the TUFLOW exe is incorrect:<br>
<li>Write 'pause' at the end of the script. Re-run the batch file and the DOS window remains, giving some more information. In the below example, the file path to the TUFLOW exe is incorrect:<br>
 
 
<br>
 
<br>
[[File:Animation Troubleshooting CommonErrors 05a.gif]]<br>
+
{{Video|name=Animation_Troubleshooting_CommonErrors_05b.mp4|width=1124}}<br>
 
<br>
 
<br>
 
</ol>
 
</ol>
  
 
=== _ TUFLOW Simulations (*.log) ===
 
=== _ TUFLOW Simulations (*.log) ===
To confirm the simulation has finished:
+
The log file contains brief overview of the simulation:
 
<ol>
 
<ol>
 
<li>Navigate to the '''TUFLOW\runs''' folder and open the '''_ TUFLOW Simulations.log''' in a text editor.  
 
<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'.
+
<li>Confirm if the simulation has 'Started' and 'Finished' line.
<li>If there is no log file, see <u>[[Draft_Troubleshooting#DOS_Window_Flashes_and_Disappears | here]]</u>.
+
<li>If there is no log file, see <u>[[Tutorial_Troubleshooting_QGIS#Simulation DOS Window Flashes and Disappears | here]]</u>.
 
</ol>
 
</ol>
  
 
=== TUFLOW Log File (*.tlf) ===
 
=== TUFLOW Log File (*.tlf) ===
Open the TUFLOW log file (*.tlf) and confirm at the bottom of the file, that the model run finished successfully by observing "Simulation FINISHED". If the simulation has not finished:
+
The .tlf file contains information on the model run status and any error messages:
 
<ol>
 
<ol>
<li>Scroll to the bottom of the TLF, work from the bottom up to review any error, check or warning messages. If no error messages appear 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>.
+
<li>Navigate to the '''TUFLOW\runs\log''' folder and open the '''.tlf''' file in a text editor.<br>
<li>Review the Error number, open the link provided in a web browser and read through the description and suggestions:<br>
+
<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>
 
<br>
[[File:Animation Troubleshooting CommonErrors 07a.gif]]<br>
+
{{Video|name=Animation_Troubleshooting_CommonErrors_07b.mp4|width=1265}}<br>
 
<br>
 
<br>
<li>Open the workspace in QGIS from the '''TUFLOW\runs\log''' folder.
+
<li>Open the .qgs workspace in QGIS from the '''TUFLOW\runs\log''' folder.
<li>Click 'Apply TUFLOW Styling'.
+
<li>Click 'Apply TUFLOW Styles to All Layers'.
 
<li>Zoom in to the location of any error messages, turn on labelling to view the error. <br>
 
<li>Zoom in to the location of any error messages, turn on labelling to view the error. <br>
 +
<li>In this example the 2d_bc SX point isn't snapped to the 1d_nwk culvert.<br>
 +
<br>
 +
{{Video|name=Animation_Troubleshooting_CommonErrors_08b.mp4|width=1217}}<br>
 
<br>
 
<br>
[[File:Animation Troubleshooting CommonErrors 08a.gif]]<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.2A.hpc.tlf.29 | HPC TUFLOW Log File]]</u> below.<br>
 
<br>
 
<br>
 
</ol>
 
</ol>
  
=== HPC TUFLOW Log File (*hpc.tlf) ===
+
=== HPC TUFLOW Log File (*.hpc.tlf) ===
If there is no error message in the TLF and the last lines show:<br>
+
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>
 
<br>
[[File:Troubleshooting CommonErrors 11.png]]<br>
+
[[File:Troubleshooting_CommonErrors_11a.png]]<br>
 
<br>
 
<br>
<ol>
+
<li>The model is set up to run on GPU and there is no GPU available, or
<li>The model has been 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>.
 
<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>.
 
</ol>
 
</ol>
Line 122: Line 159:
  
 
=Conclusion=
 
=Conclusion=
If the above tips do not assist in fixing the error, email [mailto:support@tuflow.com support@tuflow.com].
+
If the above tips do not assist in fixing the error, email [mailto:support@tuflow.com support@tuflow.com].
  
 
<br>
 
<br>

Latest revision as of 10:21, 23 September 2024

Introduction

This troubleshooting page contains common errors and steps to follow when investigating models.

Common Errors

Unsaved Control Files

When changes are made in the control files and the files are not saved, errors occur.

  1. Check all simulation control files and batch files are saved (Notepad Saved Icon.png). A red icon indicates that there are unsaved changes in the file:

    Troubleshooting CommonErrors 01a.png

  2. Use the 'Save All' tool to save all unsaved control files:

    Troubleshooting CommonErrors 12.png

Unsaved GIS Layers

When changes are made in GIS layers and the layers are not saved, errors occur.

  1. Check all GIS input layers are saved. If the 'Save Layer Edits' icon is available (QGIS UnsavedEdits.png), there are unsaved edits in the layer.
  2. A pencil icon on the layer (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.



TUFLOW Syntax Rules

Control files use a double equal sign (==). When a single equal sign (=) is used, the simulation stops with and error at the end of the .tlf file:

    Troubleshooting CommonErrors 16b.png

    Troubleshooting CommonErrors 15a.png


Spelling Mistakes in Control Files

Spelling mistakes in control files are a common mistake, resulting in a 'does not exist' pop up message:

    Troubleshooting CommonErrors 03b.png


To fix the reference:

  1. The file that cannot by found is M01_01.tgc. Go to the folder where the file should be (in this example the TUFLOW\model folder).
  2. The file referenced should be M01_001.tgc.
  3. Update the reference in the TCF and confirm the file can now be found by right clicking on the file and selecting open.



Spelling Mistakes in Input Layers

Spelling mistakes in input layers are also a common mistake, resulting in a 'does not exist' pop up message:

    Troubleshooting CommonErrors 13a.png


To fix the reference:

  1. The layer that cannot by found is 2d_bc_M03_culverts_001_P.shp. Go to the folder where the file should be (in this example the TUFLOW\model\gis folder).
  2. The layer has a spelling mistake 'culvets'.
  3. In QGIS use the 'Increment Selected Layer' tool to save the file with the correct name.
    Note: The tool automatically increments a number if it is at the end of the file name.



TCF does not exist

Typos or spaces in the TCF name result in a 'does not exist' message in the DOS window:

  1. Check the name of the TCF is referenced correctly in the batch file.
  2. Right click on the TCF in the batch file, select 'Open File' to make sure it can be opened.
  3. Example of incorrect TCF name missing an underscore:

    Troubleshooting CommonErrors 19.png

    Troubleshooting CommonErrors 20a.png

  4. Example of using space in the TCF name causing TUFLOW to look for a TCF name ending with the first space:

    Troubleshooting CommonErrors 17a.png

Ambiguous Command

TUFLOW control files are command driven text files. The commands must be in the format and location TUFLOW is expecting. The TUFLOW Manual lists all the available commands and specifies which TUFLOW control file each command belongs to.

  1. Example of a typo in the 'BC Control File ==' command:

    Troubleshooting CommonErrors 18b.png

  2. Example of 'Map Output Data Types ==' command entered into TGC instead of TCF:

    Troubleshooting CommonErrors 21b.png


Troubleshooting Steps

Simulation DOS Window Flashes and Disappears

When batch file is double clicked and the simulation DOS window flashes and disappears the problem might be in the filepath of the TUFLOW executable or incorrect syntax:

  1. Check the TUFLOW executable can be found with the specified filepath (absolute or relative).
  2. Double click the executable, this performs a licence check and DOS 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.
  3. 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.
  4. If using environment variable 'set exe', confirm there are no spaces surrounding the equals sign (e.g. set exe="..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe").
  5. Write 'pause' at the end of the script, rerun the batch file and the DOS window should remain open providing more information. In the below example, the file path to the TUFLOW exe is incorrect:



_ TUFLOW Simulations (*.log)

The log file contains brief overview of the simulation:

  1. Navigate to the TUFLOW\runs folder and open the _ TUFLOW Simulations.log in a text editor.
  2. Confirm if the simulation has 'Started' and 'Finished' line.
  3. If there is no log file, see here.

TUFLOW Log File (*.tlf)

The .tlf file contains information on the model run status and any error messages:

  1. Navigate to the TUFLOW\runs\log folder and open the .tlf file in a text editor.
  2. Scroll to the bottom to confirm the model run finished successfully by observing "Simulation FINISHED".
  3. If not, search from the bottom up for any error, warning or check messages.
  4. Review the error number, open the link provided in a web browser and read through the description and suggestions:



  5. Open the .qgs workspace in QGIS from the TUFLOW\runs\log folder.
  6. Click 'Apply TUFLOW Styles to All Layers'.
  7. Zoom in to the location of any error messages, turn on labelling to view the error.
  8. In this example the 2d_bc SX point isn't snapped to the 1d_nwk culvert.



  9. If no error messages appear in the .tlf and the last line shows 'Sending initialisation data to HPC...' see HPC TUFLOW Log File below.

HPC TUFLOW Log File (*.hpc.tlf)

The .hpc.tlf file contains error messages not recorded in the .tlf file:

  1. Navigate to the TUFLOW\runs\log folder and open the .hpc.tlf file in a text editor. If the last lines shows:

    Troubleshooting CommonErrors 11a.png

  2. The model is set up to run on GPU and there is no GPU available, or
  3. The GPU needs a driver update, for more information see Update GPU Driver.


Conclusion

If the above tips do not assist in fixing the error, email support@tuflow.com.


Up
Go-up.png Back to Tutorial Introduction Main Page