Tutorial M01: Difference between revisions
Content deleted Content added
No edit summary |
|||
| (40 intermediate revisions by 5 users not shown) | |||
Line 15:
<ol><ol><li> 2d_loc: A layer defining the origin and orientation of the 2D grid.
<li> 2d_code: A layer containing polygons that define the cell codes (active or inactive status).
<li> *.
<li> 2d_mat: A layer defining the land-use (material) types within the 2D study area.</ol></ol>
:*TBC layers:
Line 24:
<ol><ol><li>2d_po: A time series data output from 2D domains, for a range of hydraulic parameters.
</ol></ol>
This tutorial is setup with shapefiles (SHP) and geopackage (GPKG) layers. For more information on these formats, see <u>[https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]</u>.
<br>
= Project Initialisation =
TUFLOW models are separated into a series of folders which contain the input and output files. The recommended set up for the model directory and sub-folders is shown below. For a more detailed description,
<ol>
[[File:Tute M01 Directory Structure v3.png|left]]
Line 46 ⟶ 47:
| model\mi|| Input || GIS layers that are inputs to the 2D and 1D model domains are contained within this folder, model\mi is typically used for MapInfo formatted GIS files.
|-
| results|| Output|| TUFLOW outputs the results to this folder in
|-
| runs|| Input|| TUFLOW Control Files (TCF).
Line 53 ⟶ 54:
|}
</ol>
The TUFLOW folders can be set up manually, automatically running TUFLOW model with <font color="blue"><tt>
:*<u>[[Tutorial_M01_Configure_TUFLOW_Project_QGIS | QGIS - SHP]]</u>
:*<u>[[Tutorial_M01_Configure_TUFLOW_Project_QGIS_GPKG | QGIS - GPKG]]</u>
:*SMS - the folder structure listed above is automatically created before running the model using the 'Export TUFLOW files' command (see <u> [[Run TUFLOW from within SMS | Run TUFLOW from within SMS]])</u>.
:*ArcMap (10.1 and newer) - the ArcTUFLOW Toolbox can be used to automatically create the model folders, model projection, TUFLOW control files and run TUFLOW to create the template files.
Line 80 ⟶ 82:
=== 2D Domain ===
Grid formats currently supported by TUFLOW include the ESRI ASCII
Defining the location and orientation of the TUFLOW 2D domain can be undertaken using four different methods: <br>
Line 105 ⟶ 107:
<font color="blue"><tt>Set Code </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>0</tt></font> <font color="green"><tt> ! Sets all cells to inactive</tt></font>
<li>Define active areas: <br>
:*<u>[[Tutorial_M01_Define_Active_Area_QGIS | QGIS - SHP]]</u>
:*<u>[[Tutorial_M01_Define_Active_Area_QGIS_GPKG | QGIS - GPKG]]</u>
<li>Set all cells within the code polygon to active. The command needs to be written after the <font color="blue"><tt> Set Code </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>0 </tt></font> command to overwrite the inactive cells within the polygon: <br>
<u>'''QGIS - SHP'''</u><br>
<font color="blue"><tt>Read GIS Code </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>gis\2d_code_M01_001_R.shp</tt></font> <font color="green"><tt> ! Sets cell codes according to attributes in the GIS layer</tt></font> <br>
<u>'''QGIS - GPKG'''</u><br>
<font color="blue"><tt>
</ol>
Note: As mentioned, the order of commands in the TGC is critical. The final cell value (such as for code, elevation or material) is specified by the file lowest in the TGC. Consider the above two commands to set active and inactive cells, if the <font color="blue"><tt>Read GIS Code </tt></font> was written before the <font color="blue"><tt>Set Code </tt></font> command, all the cells within the code polygon would be first set to active and then overwritten to be all inactive, no hydraulic simulation could occur.<br>
=== Topography ===
The points that assign elevations at each 2D cell centre, mid-side and corner are called Zpts. For a description on the computational function of each of the Zpts in a TUFLOW cell, see <u>[https://wiki.tuflow.com/
A DEM is used to assign elevations to the Zpts: <br>
<ol>
<li>Copy the DEM (
<li>Set a global elevation for the Zpts by adding the following line to the TGC file:<br>
<font color="blue"><tt>Set Zpts </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 100</tt></font> <font color="green"><tt> ! Sets every 2D elevation zpt to 100 metres</tt></font> <br>
<li>Assign elevations to the Zpts from the DEM. The command needs to be written after the <font color="blue"><tt> Set Zpts </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>100 </tt></font> command to overwrite global Zpts where the DEM data are available: <br>
<font color="blue"><tt>Read GRID Zpts </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> grid\DEM.
</ol>
Note: The above data layering technique is common. After the first simulation, it is a good modelling practice to review the check files to confirm the topography in the model is as expected. Searching for a value of '100' is an easy way to identify if there are any gaps in the DEM dataset that were not expected (these should be fixed). <br>
Line 134 ⟶ 140:
<font color="blue"><tt>Set Mat </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>1</tt></font> <font color="green"><tt> ! Sets all cells to a material ID of 1</tt></font><br>
<li>Define spatial material definition:
:*<u>[[Tutorial_M01_Materials_QGIS | QGIS - SHP]]</u>
:*<u>[[Tutorial_M01_Materials_QGIS_GPKG | QGIS - GPKG]]</u>
<li>Assign materials from the GIS layer to overwrite the global material at all cells that fall within the material polygons: <br>
<u>'''QGIS - SHP'''</u><br>
<font color="blue"><tt>Read GIS Mat </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>gis\2d_mat_M01_001_R.shp</tt></font> <font color="green"><tt> ! Sets material values according to attributes in the GIS layer</tt></font><br>
<u>'''QGIS - GPKG'''</u><br>
<font color="blue"><tt>
<li>Save the TGC file.
Line 161 ⟶ 171:
Set up boundary condition layers: <br>
:*<u>[[Tutorial_M01_Boundary_Conditions_QGIS | QGIS - SHP]]</u>
:*<u>[[Tutorial_M01_Boundary_Conditions_QGIS_GPKG | QGIS - GPKG]]</u>
=== TUFLOW Boundary Control File (TBC) ===
Line 168 ⟶ 179:
<li>Create a new text file and save as '''M01_001.tbc''' in the '''Module_01\TUFLOW\model''' folder. <br>
<li>Open the file in a text editor and add the boundary conditions: <br>
<u>'''QGIS - SHP'''</u><br>
<font color="blue"><tt>Read GIS BC </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>gis\2d_bc_M01_001_L.shp</tt></font> <font color="green"><tt> ! Reads in 2D boundaries</tt></font> <br>
<font color="blue"><tt>Read GIS SA </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>gis\2d_sa_M01_001_R.shp</tt></font> <font color="green"><tt> ! Reads in 2D source area boundaries</tt></font> <br>
<u>'''QGIS - GPKG'''</u><br>
<font color="blue"><tt>
<font color="blue"><tt>Read GIS SA </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2d_sa_M01_001_R</tt></font> <font color="green"><tt> ! Reads in 2D source area boundaries</tt></font> <br>
<li>Save the TBC.
</ol>
Line 179 ⟶ 194:
<ol>
<li>Open the template bc database '''TUFLOW Tutorial Model BC Database.xlsx''' from the '''Module_01\Tutorial_Data''' folder. <br>
<li>There are two sheets in the file, 'bc_dbase' and '01p2hr'. Complete the bc_dbase worksheet
<ol>
<li>Enter the name of the first upstream boundary condition under the 'Name' heading. The name must appear exactly as it does in the boundary condition layer, (i.e. FC01). <br>
<li>Enter the text '01p2hr.csv' under the 'Source' heading. It is a source file for TUFLOW to extract the timeseries data. <br>
<li>Enter the text 'time' and 'inflow_FC01' under the 'Column 1' and 'Column 2' heading. These correspond to the data headers in the source timeseries file. <br>
</ol>
<li>Repeat the above process for
<br>
[[File:M01 bc dbase 003.png]]<br>
Line 197 ⟶ 213:
= 2D Time Series Plot Output =
The 2D plot output (2d_po) objects allow for a wide range of hydraulic parameters to be output from the 2D domain as time
:*<u>[[
:*<u>[[Tutorial_M01_Time_Series_Plot_Output_QGIS_GPKG | QGIS - GPKG]]</u><br>
<br>
Line 204 ⟶ 221:
The TCF file references all the control files, specifies time and output controls. This is the last step before running the simulation.<br>
<ol>
<li>
<li>Open the file in a text editor and add the following commands: <br>
<u>'''QGIS - SHP'''</u><br>
<font color="green"><tt>! MODEL INITIALISATION</tt></font><br>
<font color="blue"><tt>Tutorial Model </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ON</tt></font> <font color="green"><tt> ! Required command to run this tutorial model licence free </tt></font> <br>
<font color="blue"><tt>GIS Format </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> SHP</tt></font> <font color="green"><tt> ! Specify SHP as the output format for all GIS files</tt></font> <br>
<font color="blue"><tt>SHP Projection </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\gis\Projection.prj </tt></font> <font color="green"><tt> ! Sets the GIS projection for the TUFLOW Model
<font color="blue"><tt>TIF Projection </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\grid\DEM.tif </tt></font> <font color="green"><tt> ! Sets the GIS projection for the output grid files</tt></font><br>
<font color="green"><tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt></font> <br>
<u>'''QGIS - GPKG'''</u><br>
<font color="green"><tt>! MODEL INITIALISATION</tt></font><br>
<font color="blue"><tt>Spatial Database </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\gis\M01_001.gpkg </tt></font> <font color="green"><tt> ! Specify the location of the GeoPackage Spatial Database </tt></font> <br>
<font color="blue"><tt>Tutorial Model </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ON</tt></font> <font color="green"><tt> ! Required command to run this tutorial model licence free </tt></font> <br>
<font color="blue"><tt>GIS Format </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> GPKG</tt></font> <font color="green"><tt> ! Specify GPKG as the output format for all GIS files</tt></font> <br>
<font color="blue"><tt>GPKG Projection </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\gis\Projection.gpkg </tt></font> <font color="green"><tt> ! Sets the GIS projection for the TUFLOW Model</tt></font><br>
<font color="blue"><tt>TIF Projection </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\grid\DEM.tif </tt></font> <font color="green"><tt> ! Sets the GIS projection for the output grid files</tt></font><br>
<font color="green"><tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt></font> <br><br>
<li> Define the solution scheme and specify Sub-Grid Sampling (SGS) commands: <br>
<font color="green"><tt>! SOLUTION SCHEME</tt></font> <br>
Line 219 ⟶ 243:
<font color="blue"><tt>Hardware </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> GPU</tt></font> <font color="green"><tt> ! Comment out if GPU card is not available or replace with "Hardware == CPU" </tt></font> <br>
<font color="blue"><tt>SGS </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ON</tt></font> <font color="green"><tt> ! Switches on Sub-Grid Sampling</tt></font> <br>
<font color="blue"><tt>SGS Sample
▲<font color="blue"><tt>SGS Approach</tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> Method C</tt></font> <font color="green"><tt> ! Sets SGS Sample Approach to Method C</tt></font> <br>
For information on SGS, see Section 3.2 of the latest <u>[https://downloads.tuflow.com/TUFLOW/Releases/2020-10/TUFLOW%20Release%20Notes.2020-10-AD.pdf Release Notes])</u>
<br><br>
Line 236 ⟶ 259:
<font color="blue"><tt>Timestep </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 1</tt></font> <font color="green"><tt> ! Specifies the first 2D computational timestep of 1 second</tt></font> <br>
<font color="blue"><tt>Start Time </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 0</tt></font> <font color="green"><tt> ! Specifies a simulation start time of 0 hours</tt></font> <br>
<font color="blue"><tt>End Time </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 3</tt></font> <font color="green"><tt>
<li>Add the following output folder commands: <br>
<font color="green"><tt>! OUTPUT FOLDERS</tt></font> <br>
Line 242 ⟶ 266:
<font color="blue"><tt>Output Folder </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\results\</tt></font> <font color="green"><tt> ! Location of the 2D output files and prefixes them with the .tcf filename</tt></font> <br>
<font color="blue"><tt>Write Check Files </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\check\</tt></font> <font color="green"><tt> ! Location of the 2D check files and prefixes them with the .tcf filename</tt></font> <br><br>
<li>Add the following output settings commands: <br>
<font color="green"><tt>! OUTPUT SETTINGS</tt></font> <br>
<font color="blue"><tt>Map Output Format </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> XMDF
<font color="blue"><tt>Map Output Data Types </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> h V d dt</tt></font> <font color="green"><tt> ! Outputs water levels, velocities, depths, minimum timestep</tt></font> <br>
<font color="blue"><tt>Map Output Interval </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 300</tt></font> <font color="green"><tt> ! Outputs map data every 300 seconds (5 minutes)</tt></font> <br>
<font color="blue"><tt>
▲<font color="blue"><tt>SGS Map Extent Trim </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ALL</tt></font> <font color="green"><tt> ! Specifies partially wet cells as dry</tt></font> <br>
▲<font color="blue"><tt>SGS Depth Output </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> Cell Average</tt></font> <font color="green"><tt> ! Specifies cell average depth output</tt></font> <br><br>
<li>Reference the 2d_po layers. When reading in time-series layers, such as 2d_po files, its necessary to use a <font color="blue"><tt>Time Series Output Interval </tt></font> command. This command specifies the output interval in seconds for the time-series based output: <br>
<u>'''QGIS - SHP'''</u><br>
<font color="green"><tt>! TIME SERIES PLOT OUTPUT</tt></font> <br>
<font color="blue"><tt>Read GIS PO </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\gis\2d_po_M01_001_L.shp</tt></font> <font color="green"><tt> ! Reads in plot output line</tt></font> <br>
<font color="blue"><tt>Read GIS PO </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\gis\2d_po_M01_001_P.shp</tt></font> <font color="green"><tt> ! Reads in plot output point</tt></font> <br>
<font color="blue"><tt>Time Series Output Interval </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 60</tt></font> <font color="green"><tt> ! Outputs time series data every 60 seconds</tt></font> <br>
<u>'''QGIS - GPKG'''</u><br>
<font color="green"><tt>! TIME SERIES PLOT OUTPUT</tt></font> <br>
<font color="blue"><tt>Read GIS PO </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 2d_po_M01_001_L</tt></font> <font color="green"><tt> ! Reads in plot output line</tt></font> <br>
<font color="blue"><tt>Read GIS PO </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 2d_po_M01_001_P</tt></font> <font color="green"><tt> ! Reads in plot output point</tt></font> <br>
<font color="blue"><tt>Time Series Output Interval </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> 60</tt></font> <font color="green"><tt> ! Outputs time series data every 60 seconds</tt></font> <br><br>
<li>Save the TCF file. The TUFLOW simulation is ready to be run for the first time.
</ol>
The comments (following the exclamation marks) are not required and these commands are generally self
<br>
Line 266 ⟶ 294:
<ol>
<li>Create a new text file in the '''Module_01\TUFLOW\runs''' folder and save as '''_run_M01_HPC.bat'''.
<li>Open the '''_run_M01_HPC.bat''' in a text editor and include a file path to the executable from the '''exe\
<font color="black"><tt>"..\..\..\exe\
Note: A relative path is used for the executable and the TCF, a full file path can also be used.
<li>Save the batch file and double click it in file explorer to run the simulation.
</ol>
This opens the TUFLOW
If the simulation is successful, the console window should look like the image below.
<ol>
<br>
[[File:
<br>
</ol>
= Troubleshooting =
See tips on common mistakes and troubleshooting steps if the model doesn't run:
:*<u>[[Tutorial_Troubleshooting_QGIS | QGIS]]</u>
<br>
= Check Files =
TUFLOW writes a series of check files during the model initialisation process when the <font color="blue"><tt>Write Check Files </tt></font> command is specified in the TCF. The files are either in a tabular form (.csv)
While the model is running, review the added features are specified correctly: <br>
:*<u>[[Tutorial_M01_Check_Files_QGIS | QGIS - SHP]]</u>
:*<u>[[Tutorial_M01_Check_Files_QGIS_GPKG | QGIS - GPKG]]</u>
<br>
= Results=
Two map output formats specified for this tutorial:
:*
:*XMDF - Mesh based output format containing all map output data types in a single file
When the model is finished, review the results: <br>
:*<u>[[Tutorial_M01_Results_QGIS | QGIS]]</u>
Line 306 ⟶ 335:
<ol>
<br>
[[File:
<br>
</ol>
=== HPC TUFLOW Log File ===
As the model is using the HPC solution scheme, there is a second log file automatically written from the same command. Navigate to the '''Module_01\TUFLOW\runs\log''' folder and open the '''M01_5m_001.hpc.tlf''' file. The HPC solution scheme, by default, uses adaptive timestepping to progress through the simulation. The timestep is adjusted so it complies with the mathematical stability criteria of a 2D SWE explicit solution. This is controlled by three control numbers, further information is provided <u>[https://wiki.tuflow.com/
Scroll down the '''hpc.tlf''' to 'iStep'. This is the point at which the model successfully compiled and began running. The three HPC control numbers are listed in the columns after time. Then the number of wet cells, the volume of water, the dt (minimum timestep) and the efficiency of the solver. As the model starts to gain wet cells dt drops, but should eventually stabilise. Similarly, model efficiency should increase as the model progresses.<br>
<br>
Line 327 ⟶ 356:
:*Check files were used to review the model setup.
:*Results were visualised and the performance of the model reviewed. <br>
:*For further training opportunities see <u>[https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue]</u> and/or contact <u>[mailto:training@tuflow.com training@tuflow.com]</u>. <br>
:*Alternatively, see the <u>[[TUFLOW_Example_Models#Example_Model_Catalogue | TUFLOW Example Models]]</u> to explore the full list of TUFLOW features.
<br>
Line 336 ⟶ 367:
<li>Save the geometry control file '''M01_001.tgc''' as '''M01_2.5m_001.tgc'''.
<li>Modify the cell size in the geometry control file to '2.5' meters.
<li>In the TCF,
<li>Update the batch file with the updated TCF file and run the simulation.
<br></ol>
| |||