Tutorial M07

From Tuflow
Jump to navigation Jump to search


In this module, a quadtree mesh is used. To begin, watch the following video:

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.

    Animation M07 Quadtree 01.gif

The GIS layers are:

  • QCF layers:
    1. 2d_qnl: A layer used to define the location and levels of mesh refinement.

Module 7 builds from the model created in Module 2. The completed Module 2 model is provided in the Module_07\TUFLOW folder.

GIS Inputs

Create, import and view input data:

Simulation Control Files

TUFLOW Quadtree Control File (QCF)

  1. Create a new text file M07_001.qcf and save it in the Module_07\TUFLOW\model folder.
  2. 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:
      1. 'TGC': matches the orientation angle defined in the TGC.
      2. A numerical value: defines a new model orientation angle and overrides any angle or location in the TGC.
      3. 'Optimise': the parent level 1 polygon is used to optimise the angle of the mesh.
    • Base Cell Size - cell size of level 1 polygon, there are two options available:
      1. 'TGC': matches the cell size defined in the TGC.
      2. A numerical value: defines a new level 1 cell size and overrides the cell size command in the TGC.
    • Model Origin and Extent - there are two options available:
      1. 'TGC': matches the model origin and extent defined in the TGC.
      2. 'Auto': the extent of the level 1 polygon is used to define the model origin and extents.
    • Read GIS Nesting: used to define polygons of mesh refinement (different levels).
  3. Add the following command lines:
    Orientation Angle == TGC ! Uses orientation angle same as the TGC
    Base Cell Size == 10 ! Sets level 1 cell size to 10 metres
    Model Origin and Extent == TGC  ! Uses origin and extent same as the TGC
    Read GIS Nesting == gis\2d_qnl_M07_001_R.shp  ! Reads in Quadtree nesting level GIS layer
  4. Save the QCF.

TUFLOW Control File (TCF)

  1. Save a copy of the M02_5m_001.tcf as M07_5m_001.tcf in the Module_07\TUFLOW\runs folder.
  2. Open the M07_5m_001.tcf in a text editor and add the following line in the 'Model Inputs' section:
    Quadtree Control File == ..\model\M07_001.qcf ! Reference the Quadtree Control File
  3. Save the TCF.

Running the Simulation

  1. Save a copy of _run_M02_HPC.bat as _run_M07_HPC.bat in the Module_07\TUFLOW\runs folder.
  2. Update the batch file to reference the M07_5m_001.tcf :
    set exe="..\..\..\exe\2023-03-AA\TUFLOW_iSP_w64.exe"
    set run=start "TUFLOW" /wait %exe% -b
    %run% M07_5m_001.tcf
  3. Double click the batch file in file explorer to run the simulation.


See tips on common mistakes and troubleshooting steps if the model doesn't run:

Check Files

While the model is running, review the added features are specified correctly:


When the model is finished, review the results:

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.

M07 TUFLOW Simulations.png


  • 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.

Go-up.png Back to Tutorial Introduction Main Page