View source for Tutorial M07

= Introduction =
In this module, a quadtree mesh is used. To begin, watch the following video:
:*<u>[https://www.youtube.com/watch?v=2zrNwWUNTXE Quadtree Meshing in TUFLOW]</u>

A quadtree mesh is constructed by subdividing user selected standard cells into four smaller square cells. These smaller cells are then able to be further subdivided into four, and so on. Quadtree allows for larger cells in areas of flat terrain (eg. large flat floodplains) and smaller cells where either terrain varies rapidly or along known primary flow paths (eg. river channels, road gutters, open channels). By increasing the cell size in locations away from the area of interest, a model run time can be reduced. <br>
<ol>
<br>
[[File:Animation M07 Quadtree 01.gif]]<br>
<br>
</ol>
The GIS layers are:
:*QCF layers:
<ol><ol><li>2d_qnl: A layer used to define the location and levels of mesh refinement.</ol></ol>

'''Module 7 builds from the model created in <u>[[Tutorial_M02 | Module 2]]</u>. The completed Module 2 model is provided in the Module_07\TUFLOW folder.''' <br>
<br>

= GIS Inputs =
Create, import and view input data:
:*<u>[[Tutorial_M07_GIS_Inputs_QGIS | QGIS - SHP]]</u>
:*<u>[[Tutorial_M07_GIS_Inputs_QGIS_GPKG | QGIS - GPKG]]</u>
<br>

= Simulation Control Files = 
=== TUFLOW Quadtree Control File (QCF) ===
<ol>
<li>Create a new text file '''M07_001.qcf''' and save it in the '''Module_07\TUFLOW\model''' folder.
<li>The following commands are mandatory in a QCF. The 'level 1' refers to the base cell size of the model. The 'level 2' polygon is the second nested level digitised in the 2d_qnl layer (e.g. level 1 polygon divided into 4 cells).
:*Orientation Angle - model orientation angle, there are three options available:
<ol><ol><li>'TGC': matches the orientation angle defined in the TGC.
<li>A numerical value: defines a new model orientation angle and overrides any angle or location in the TGC.
<li>'Optimise': the parent level 1 polygon is used to optimise the angle of the mesh.
</ol></ol>
:*Base Cell Size - cell size of level 1 polygon, there are two options available:
<ol><ol><li>'TGC': matches the cell size defined in the TGC.
<li>A numerical value: defines a new level 1 cell size and overrides the cell size command in the TGC. 
</ol></ol>
:*Model Origin and Extent - there are two options available:
<ol><ol><li>'TGC': matches the model origin and extent defined in the TGC.
<li>'Auto': the extent of the level 1 polygon is used to define the model origin and extents.
</ol></ol>
:*Read GIS Nesting: used to define polygons of mesh refinement (different levels).

<li>Add the following command lines:<br>
<u>'''QGIS - SHP'''</u><br>
<font color="blue"><tt>Orientation Angle </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>TGC</tt></font> <font color="green"><tt>  ! Uses orientation angle same as the TGC</tt></font> <br>
<font color="blue"><tt>Base Cell Size </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>10</tt></font> <font color="green"><tt>  ! Sets level 1 cell size to 10 metres</tt></font> <br>
<font color="blue"><tt>Model Origin and Extent </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>TGC</tt></font> <font color="green"><tt> ! Uses origin and extent same as the TGC </tt></font> <br>
<font color="blue"><tt>Read GIS Nesting </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>gis\2d_qnl_M07_001_R.shp</tt></font> <font color="green"><tt> ! Reads in Quadtree nesting level GIS layer </tt></font> <br>
<u>'''QGIS - GPKG'''</u><br>
<font color="blue"><tt>Orientation Angle </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>TGC</tt></font> <font color="green"><tt>  ! Uses orientation angle same as the TGC</tt></font> <br>
<font color="blue"><tt>Base Cell Size </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>10</tt></font> <font color="green"><tt>  ! Sets level 1 cell size to 10 metres</tt></font> <br>
<font color="blue"><tt>Model Origin and Extent </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>TGC</tt></font> <font color="green"><tt> ! Uses origin and extent same as the TGC </tt></font> <br>
<font color="blue"><tt>Read GIS Nesting </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2d_qnl_M07_001_R</tt></font> <font color="green"><tt> ! Reads in Quadtree nesting level GIS layer </tt></font> <br>
<li>Save the QCF.
</ol>

=== TUFLOW Control File (TCF) ===
<ol>
<li>Save a copy of the '''M02_5m_001.tcf''' as '''M07_5m_001.tcf''' in the '''Module_07\TUFLOW\runs''' folder. 
<li>Open the '''M07_5m_001.tcf''' in a text editor and add the following line in the 'Model Inputs' section:  <br>
<font color="blue"><tt>Quadtree Control File </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\M07_001.qcf	 </tt></font> <font color="green"><tt>  ! Reference the Quadtree Control File</tt></font> <br>
<li>For GeoPackage users, update the Spatial Database reference: <br>
<u>'''QGIS - GPKG'''</u><br>
<font color="blue"><tt>Spatial Database </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\model\gis\M07_001.gpkg</tt></font> <font color="green"><tt>  ! Specify the location of the GeoPackage Spatial Database</tt></font> <br>
<li>Save the TCF.
</ol>
<br>

= Running the Simulation =
<ol>
<li>Save a copy of '''_run_M02_HPC.bat''' as '''_run_M07_HPC.bat''' in the '''Module_07\TUFLOW\runs''' folder.
<li>Update the batch file to reference the '''M07_5m_001.tcf''' :<br>
<font color="blue"><tt>'''set'''</tt></font> <font color="black"><tt>exe</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>"..\..\..\exe\2025.1.0\TUFLOW_iSP_w64.exe"</tt></font> <br>
<font color="blue"><tt>'''set'''</tt></font> <font color="black"><tt>run</tt></font><font color="red"><tt>=</tt></font><font color="black"><tt>start "TUFLOW" /wait</tt></font> <font color="orange"><tt> %exe%</tt></font> <font color="black"><tt> -b</tt></font> <br>
<font color="orange"><tt>%run% </tt></font> <font color="black"><tt>M07_5m_001.tcf </tt></font> <br>

<li>Double click the batch file in file explorer to run the simulation. <br>
</ol>
<br>

= Troubleshooting = 
See tips on common mistakes and troubleshooting steps if the model doesn't run:
:*<u>[[Tutorial_Troubleshooting_QGIS | QGIS]]</u>
<br>

= Check Files = 
While the model is running, review the added features are specified correctly:
:*<u>[[Tutorial_M07_Check_Files_QGIS | QGIS - SHP]]</u>
:*<u>[[Tutorial_M07_Check_Files_QGIS_GPKG | QGIS - GPKG]]</u>
<br>

= Results =
When the model is finished, review the results:
:*<u>[[Tutorial_M07_Results_QGIS | QGIS]]</u>
Using the quadtree mesh reduces the total cell count as larger cells are used in areas of flat terrain, the original cell size is kept along primary flow paths. The '''_TUFLOW Simulations.log''' shows the simulation times for the standard 5m grid '''M02_5m_001''' and the quadtree model '''M07_5m_001'''. In this example, the quadtree model is 1.5 times faster than the non quadtree predecessor. <br>
<br>
[[File:M07_TUFLOW_Simulations_d.png]]<br>
<br>

= Conclusion =
:*A two level quadtree mesh was constructed using a quadtree nested level layer.
:*Check files were used to review the mesh.
:*Results were viewed to assess the results resolution.
:*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>

<br>
{{Tips Navigation
|uplink=[[Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}