Tuflow

Tutorial M01: Difference between revisions

Browse history interactively
← Older edit
Content deleted Content added
VisualWikitext
 
(18 intermediate revisions by 4 users not shown)
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, seerefer the Folders and File Types Section ofto the <u>[https://downloadsdocs.tuflow.com/_archiveclassic-hpc/TUFLOWmanual/Releaseslatest/2018-03/TUFLOW%20Manual.2018-03.pdf 2018 TUFLOW Manual]</u>. <br>
<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 a specified formats.
|-
| runs|| Input|| TUFLOW Control Files (TCF).
Line 54 ⟶ 55:
</ol>
The TUFLOW folders can be set up manually, automatically running TUFLOW model with <font color="blue"><tt> Write Empty GIS Files </tt></font> command or automatically through GIS programs:
:*<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 Gridgrid format (.asc), binary grids (.flt) and binarygeodetic grids (.tif). The Digital Elevation Model (DEM) is provided in .tif format. <br>
 
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>Read GIS Code </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2d_code_M01_001_R</tt></font> <font color="green"><tt> ! Sets cell codes according to attributes in the GIS layer</tt></font> <br>
</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/index.php?title=Zpt_Description Zpt Description]</u>. <br>
 
A DEM is used to assign elevations to the Zpts: <br>
<ol>
<li>Copy the DEM (both '''DEM.tif''' and '''DEM.hdr''') from the '''DEM''' folder into thea new '''Module_01\TUFLOW\model\grid''' folder.<br>
<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>
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>Read GIS Mat </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2d_mat_M01_001_R</tt></font> <font color="green"><tt> ! Sets material values according to attributes in the GIS layer</tt></font><br>
<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>Read GIS BC </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2d_bc_M01_001_L</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>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 199 ⟶ 214:
= 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 series data at predefined locations. <br>
:*<u>[[Tutorial_M01_Time_Series_Plot_Output_QGIS | QGIS - SHP]]</u><br>
:*<u>[[Tutorial_M01_Time_Series_Plot_Output_QGIS_GPKG | QGIS - GPKG]]</u><br>
<br>
 
Line 205 ⟶ 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>OpenCreate a new text file and save as '''Create_EmptiesM01_5m_001.tcf''' in a text editor from the '''Module_01\TUFLOW\runs''' folder and save a copy as '''M01_5m_001.tcf'''. <br><br>
<li>Open the file in a text editor and add the following commands: <br>
 
<u>'''QGIS - SHP'''</u><br>
<li>In the '''M01_5m_001.tcf''', comment out (or delete) the 'Write Empty GIS Files' line, using a comment character (!): <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 </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>
<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 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> ! ! Specifies a simulation end time of 3 hours</tt></font> <br><br>
 
<li>Add the following output folder commands: <br>
Line 252 ⟶ 275:
 
<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>
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\2020-10-AF2025.1.0''' folder and the TCF name: <br>
<font color="black"><tt>"..\..\..\exe\2023-03-AA2025.1.0\TUFLOW_iSP_w64.exe" M01_5m_001.tcf</tt></font> <br>
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 DOS console window and the simulation begins running. The simulation usually takes a few minutes to process (depending on the computer hardware). While the model is running, it is a good practise to fill out a modelling log. It includes developer notes keeping a record of TUFLOW simulations and changes from one version to the next, for more information see <u>[https://wiki.tuflow.com/index.php?title=TUFLOW_Modelling_Log here]</u>. A template is included in the '''Module_01\Tutorial_Data''' folder.<br>
If the simulation is successful, the console window should look like the image below.
<ol>
Line 285 ⟶ 313:
 
= 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) or, GIS Vector format (.gpkg, .shp, .mif) or GIS Raster format (.tif, .flt, .asc) and contain information on the input data processed by TUFLOW.<br>
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>
 
Line 311 ⟶ 340:
 
=== 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/index.php?title=HPC_Adaptive_Timestepping here]</u>. <br>
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, change the SGS Sample Frequency to '5' and update the reference to the new TGC.
<li>Update the batch file with the updated TCF file and run the simulation.
<br></ol>
Retrieved from "https://wiki.tuflow.com/Tutorial_M01"