Tuflow - User contributions [en]

Tutorial M05 Results QGIS

2026-05-26T04:02:16Z

Emilie Nielsen: Reverted edit by Anne.Kolega (talk) to last revision by Emilie Nielsen

=Introduction=
QGIS is used to view the 1D time series results with the TUFLOW Viewer. For viewing of the 2D map results, see [[Tutorial_M01_Results_QGIS | Module 1]]. 
 

=Method=
Plot Time Series results through the pipe network:
<ol>
<li>Open the TUFLOW Viewer.
<li>Select File > Load Results. Navigate to the '''M05_5m_001.tcf''' in the '''Module_05\TUFLOW\runs''' folder and open it.
<li>When prompted to 'Open Result GIS Layer', click 'Yes'. This loads in all of the 1D and 2D results.
<li>Two additional files appear in the Layers panel:
*'''M05_5m_001_PLOT_L'''
*'''M05_5m_001_PLOT_P'''
<li>Select the '''M05_5m_001_PLOT_L''' file in the Layers panel and using the 'Select Features' tool highlight one of the 1d_nwk lines (to highlight multiple hold down shift).
<li>Select one of the Time Series datasets shown with the [[File:results_2.png | 15px]] icon and the 'Time Series' tab gets updated. 
 
{{Video|name=Animation_M05_Result_01f.mp4|width=1223}} 
 
</ol>
Plot longitudinal profiles from the Time Series datasets: 
<ol>
<li>The available long profile result types have a long profile icon [[File:Image XSLongProfile.png]] and display in the 'Cross Section / Long Profile' tab. 
 
{{Video|name=Animation_M05_Result_02g.mp4|width=1223}} 
</ol>
 

=Conclusion=
:*Both the 1D and 2D results were viewed confirming the the pipe network was getting flows through the pit 1D/2D links and the water was discharging from the downstream pipe to the 2D domain.
:*For further functionality, see [[TUFLOW_Viewer | TUFLOW Viewer]].
 
{{Tips Navigation
|uplink=[[Tutorial_M05#Results| Back to Module 5 Main Page]]
}}

Tutorial M03 Results QGIS

2026-05-25T23:54:48Z

Emilie Nielsen:

= Introduction =
QGIS is used to view the 1D time series results with the TUFLOW Viewer. For viewing of the 2D map results, see [[Tutorial_M01_Results_QGIS | Module 1]]. 
 

= Method =
Plot Time Series results through the culverts:
<ol>
<li>Open the TUFLOW viewer.
<li>Select File > Load Results. Navigate to the '''M03_5m_001.tcf''' in the '''Module_03\TUFLOW\runs''' folder and open it.
<li>When prompted to 'Open Result GIS Layer', click 'Yes'. This loads in all of the 1D and 2D results.
<li>Two additional files appear in the Layers panel:
*'''M03_5m_001_PLOT_L'''
*'''M03_5m_001_PLOT_P'''
<li>Select the '''M03_5m_001_PLOT_L''' file in the Layers panel and using the 'Select Features' tool highlight one of the 1d_nwk lines.
<li>Select one of the Time Series datasets shown with the [[File:results_2.png | 15px]] icon and the 'Time Series' tab gets updated. 
 
{{Video|name=Animation_M03_Results_01e.mp4|width=1258}} 

</ol>
Plot longitudinal profiles from the Time Series output: 
<ol>
<li>The available long profile result types have a long profile icon [[File:results_lp_v2.png | 15px]] and display in the 'Cross Section / Long Profile' tab. 
 
{{Video|name=Animation_M03_Results_02e.mp4|width=1258}} 
</ol>
 

= Conclusion =
:*The 1D results were assessed including time series and long profile results.
:*For further functionality, see [[TUFLOW_Viewer | TUFLOW Viewer]].
 
{{Tips Navigation
|uplink=[[Tutorial_M03#Results| Back to Module 3 Main Page]]
}}

Tutorial M01 Results QGIS update V2 draft

2026-05-25T00:39:46Z

Emilie Nielsen:

= Introduction =
QGIS is used to view the 2D grid and mesh 2D results:
:*The grid results (.tif) are inspected with the Profile Tool plugin. For installation, see [https://wiki.tuflow.com/index.php?title=QGIS_Profile_Tool Installation of Profile Tool]
:*The mesh results (.xmdf, .tpc), including the bed elevation and time series, are inspected with the TUFLOW Viewer 2 as part of the TUFLOW Plugin. For more information on TUFLOW Viewer 2 and installation instructions, see the [https://docs.tuflow.com/qgis-tuflow-plugin/latest/tuflow-viewer/ TUFLOW Viewer Documentation].

=Method=
View grid results with Profile Tool: 
<ol>
<li>Load the '''M01_5m_001_h_Max.tif''' file from the '''Module_01\TUFLOW\results\grids''' folder. It can either be dragged and dropped into QGIS, or loaded by selecting Layer > Add Layer > Add Raster Layer from the menu.
<li>This displays the maximum water level in the model recorded during the whole simulation.
<li>Use the Profile Tool to view the maximum water level and DEM. 
 
{{Video|name=Animation_M01_Results_01b.mp4|width=1265}}
 
 
</ol>
View mesh results (Map Outputs) with TUFLOW Viewer 2:
 
<ol>
<li>Ensure TUFLOW Viewer 2 has been activated. For backwards compatibility, the legacy TUFLOW Viewer is still selected by default. To activate TUFLOW Viewer 2:
* Under the TUFLOW Plugin menu, check on the 'TUFLOW Viewer V2' option to enable the new viewer. 
 
[[File: image of dropdown menu]] 
 
* To confirm the new viewer has been activated, check that the legacy TUFLOW Viewer icon [[File: TUFLOW_Viewer_legacy_icon.png | 20px]] has been replaced with the TUFLOW Viewer Plot Window icon [[File:results_2.png | 20px]]. The TUFLOW Plugin toolbar should look like: 
 
[[File:TUFLOW Viewer 2 Txt.png]] 
 
<li>Open the Map Outputs and Time Series results, either:
:* Within the QGIS Browser Panel drag the following layers into the QGIS workspace, or
::* '''Module_01\TUFLOW\results\M01_5m_001.xmdf''' > loads the map output mesh results
::* '''Module_01\TUFLOW\results\plot\M01_5m_001.tpc''' > loads the time series output results
:* In File Explorer, navigate to the files above and drag and drop them into the QGIS workspace.
<li>The Map Outputs show scalar datasets, e.g. depth and velocity, and vector datasets, e.g. velocity vectors. Only one scalar and one vector dataset can be displayed at the same time. 
 
{{Video|name=02_Animation_M01_LoadResults_V2_b.mp4|width=1265}}
 

<li>In the layers panel, select '''M01_5m_001'''. In the 'Layer Styling' panel, in the 'Datasets' tab, click on the scalar dataset 'Depth' under 'Result Type'. Using the 'Temporal Controller', scroll through the output times. The results update as new output times are selected. </li>
Note: The styling of the Map Outputs can be changed in the 'Contours' tab. 
 
{{Video|name=03_Animation_M01_Depth_V2_b.mp4|width=1265}}
 
<li>Click on a vector dataset 'Vector Velocity' by selecting the arrow icon to add it to the displayed 'Depth' and visualise them together. The vector output shows both direction and magnitude. 
Note: The appearance of vectors (colour, line width, symbology) can be changed in the 'Vectors' tab. 
 
{{Video|name=04_Animation_M01_VVec_V2_b.mp4|width=1265}}
 
</ol>
View mesh results (Time Series) with TUFLOW Viewer 2 from the 2d_po files:
<ol>
<li>Select '''M01_5m_001_PLOT_L''' in the Layers panel and click 'TUFLOW Viewer Plot Window' from the TUFLOW Plugin toolbar. The plot widget will open. Within the plot widget, use the 'Result Names' menu to ensure the results '''M01_5m_001''' are selected. Then select 'Flow' as the data type using the 'Data Types' menu. Finally, use the 'Selection' tool to select the 2d_po line. This shows the flow data across the 2d_po line (Type Q_).
<li>Select '''M01_5m_001_PLOT_P''' in the Layers panel and select 'Level' and 'Velocity' from the 'Data Types' menu (ensure 'Flow' is unselected). Use the 'Selection' tool to select the 2d_po point. This shows level and velocity at the point (Type H_ and V_). To move the velocity to a secondary axis, right click the plot and select 'Move to secondary axis'.
 
{{Video|name=05_Animation_M01_TimeSeries_V2_a.mp4|width=1265}}
 
 

</ol>

=Conclusion=
:*The basics of viewing 2D TUFLOW results in QGIS using the TUFLOW Viewer 2 were covered.
:*For further functionality, see [https://docs.tuflow.com/qgis-tuflow-plugin/2026.0/tuflow-viewer TUFLOW Viewer 2 documentation].

 
{{Tips Navigation
|uplink=[[Tutorial_M01#Results| Back to Module 1 Main Page]]
}}

Tutorial M01 Results QGIS update V2 draft

2026-05-25T00:25:07Z

Emilie Nielsen:

= Introduction =
QGIS is used to view the 2D grid and mesh 2D results:
:*The grid results (.tif) are inspected with the Profile Tool plugin. For installation, see [https://wiki.tuflow.com/index.php?title=QGIS_Profile_Tool Installation of Profile Tool]
:*The mesh results (.xmdf, .tpc), including the bed elevation and time series, are inspected with the TUFLOW Viewer 2 as part of the TUFLOW Plugin. For more information on TUFLOW Viewer 2 and installation instructions, see the [https://docs.tuflow.com/qgis-tuflow-plugin/latest/tuflow-viewer/ TUFLOW Viewer Documentation].

=Method=
View grid results with Profile Tool: 
<ol>
<li>Load the '''M01_5m_001_h_Max.tif''' file from the '''Module_01\TUFLOW\results\grids''' folder. It can either be dragged and dropped into QGIS, or loaded by selecting Layer > Add Layer > Add Raster Layer from the menu.
<li>This displays the maximum water level in the model recorded during the whole simulation.
<li>Use the Profile Tool to view the maximum water level and DEM. 
 
{{Video|name=Animation_M01_Results_01b.mp4|width=1265}}
 
 
</ol>
View mesh results (Map Outputs) with TUFLOW Viewer 2:
 
<ol>
<li>Ensure TUFLOW Viewer 2 has been activated. For backwards compatibility, the legacy TUFLOW Viewer is still selected by default. To activate TUFLOW Viewer 2:
* Under the TUFLOW Plugin menu, check on the 'TUFLOW Viewer V2' option to enable the new viewer. 
 
[[File: image of dropdown menu]] 
 
* To confirm the new viewer has been activated, check that the legacy TUFLOW Viewer icon [[File: TUFLOW_Viewer_legacy_icon.png | 20px]] has been replaced with the time-series icon [[File:results_2.png | 20px]]. The TUFLOW Plugin toolbar should look like: 
 
[[File:TUFLOW Viewer 2 Txt.png]] 
 
<li>Open the Map Outputs and Time Series results, either:
:* Within the QGIS Browser Panel drag the following layers into the QGIS workspace, or
::* '''Module_01\TUFLOW\results\M01_5m_001.xmdf''' > loads the map output mesh results
::* '''Module_01\TUFLOW\results\plot\M01_5m_001.tpc''' > loads the time series output results
:* In File Explorer, navigate to the files above and drag and drop them into the QGIS workspace.
<li>The Map Outputs show scalar datasets, e.g. depth and velocity, and vector datasets, e.g. velocity vectors. Only one scalar and one vector dataset can be displayed at the same time. 
 
{{Video|name=02_Animation_M01_LoadResults_V2_b.mp4|width=1265}}
 

<li>In the layers panel, select '''M01_5m_001'''. In the 'Layer Styling' panel, in the 'Datasets' tab, click on the scalar dataset 'Depth' under 'Result Type'. Using the 'Temporal Controller', scroll through the output times. The results update as new output times are selected. </li>
Note: The styling of the Map Outputs can be changed in the 'Contours' tab. 
 
{{Video|name=03_Animation_M01_Depth_V2_b.mp4|width=1265}}
 
<li>Click on a vector dataset 'Vector Velocity' by selecting the arrow icon to add it to the displayed 'Depth' and visualise them together. The vector output shows both direction and magnitude. 
Note: The appearance of vectors (colour, line width, symbology) can be changed in the 'Vectors' tab. 
 
{{Video|name=04_Animation_M01_VVec_V2_b.mp4|width=1265}}
 
</ol>
View mesh results (Time Series) with TUFLOW Viewer 2 from the 2d_po files:
<ol>
<li>Select '''M01_5m_001_PLOT_L''' in the Layers panel and click 'TUFLOW Viewer Plot Window' from the TUFLOW Plugin toolbar. The plot widget will open. Within the plot widget, use the 'Result Names' menu to ensure the results '''M01_5m_001''' are selected. Then select 'Flow' as the data type using the 'Data Types' menu. Finally, use the 'Selection' tool to select the 2d_po line. This shows the flow data across the 2d_po line (Type Q_).
<li>View the point time series for Level and Velocity dataset (Type H_ and V_). Select '''M01_5m_001_PLOT_P''' in the Layers panel and select 'Level' and 'Velocity' from the 'Data Types' menu (ensure 'Flow' is unselected). Use the 'Selection' tool to select the 2d_po point. This shows level and velocity at the point (Type H_ and V_). To move the velocity to a secondary axis, right click the plot and select 'Move to secondary axis'.
 
{{Video|name=05_Animation_M01_TimeSeries_V2_a.mp4|width=1265}}
 
 

</ol>

=Conclusion=
:*The basics of viewing 2D TUFLOW results in QGIS using the TUFLOW Viewer 2 were covered.
:*For further functionality, see [https://docs.tuflow.com/qgis-tuflow-plugin/2026.0/tuflow-viewer TUFLOW Viewer 2 documentation].

 
{{Tips Navigation
|uplink=[[Tutorial_M01#Results| Back to Module 1 Main Page]]
}}

Tutorial M01 Results QGIS update V2 draft

2026-05-25T00:09:20Z

Emilie Nielsen: /* Method */

= Introduction =
QGIS is used to view the 2D grid and mesh 2D results: (as well as the TUFLOW 1D results). This section describes how to view the following results using the TUFLOW Viewer 2:
:*The grid results (.tif) are inspected with the Profile Tool plugin. For installation, see [https://wiki.tuflow.com/index.php?title=QGIS_Profile_Tool Installation of Profile Tool]
:*The mesh results (.xmdf, .tpc), including the bed elevation and time series, are inspected with the TUFLOW Viewer 2 as part of the TUFLOW Plugin. For more information on TUFLOW Viewer 2 and installation instructions, see the [https://docs.tuflow.com/qgis-tuflow-plugin/latest/tuflow-viewer/ TUFLOW Viewer Documentation].

=Method=
View grid results with Profile Tool: 
<ol>
<li>Load the '''M01_5m_001_h_Max.tif''' file from the '''Module_01\TUFLOW\results\grids''' folder. It can either be dragged and dropped into QGIS, or loaded by selecting Layer > Add Layer > Add Raster Layer from the menu.
<li>This displays the maximum water level in the model recorded during the whole simulation.
<li>Use the Profile Tool to view the maximum water level and DEM. 
 
{{Video|name=Animation_M01_Results_01b.mp4|width=1265}}
 
 
</ol>
View mesh results (Map Outputs) with TUFLOW Viewer 2:
 
<ol>
<li>Ensure TUFLOW Viewer 2 has been activated. For backwards compatibility, the legacy TUFLOW Viewer is still selected by default. To activate TUFLOW Viewer 2:
* Under the TUFLOW Plugin menu, check on the 'TUFLOW Viewer V2' option to enable the new viewer. 
 
[[File: image of dropdown menu]] 
 
* To confirm the new viewer has been activated, check that the legacy TUFLOW Viewer icon [[File: TUFLOW_Viewer_legacy_icon.png | 20px]] has been replaced with the time-series icon [[File:results_2.png | 20px]]. The TUFLOW Plugin toolbar should look like: 
 
[[File:TUFLOW Viewer 2 Txt.png]] 
 
<li>Open the Map Outputs and Time Series results, either:
:* Within the QGIS Browser Panel drag the following layers into the QGIS workspace, or
::* '''Module_01\TUFLOW\results\M01_5m_001.xmdf''' > loads the map output mesh results
::* '''Module_01\TUFLOW\results\plot\M01_5m_001.tpc''' > loads the time series output results
:* In File Explorer, navigate to the files above and drag and drop them into the QGIS workspace.
<li>The Map Outputs show scalar datasets, e.g. depth and velocity, and vector datasets, e.g. velocity vectors. Only one scalar and one vector dataset can be displayed at the same time. 
 
{{Video|name=02_Animation_M01_LoadResults_V2_b.mp4|width=1265}}
 

<li>In the layers panel, select '''M01_5m_001'''. In the 'Layer Styling' panel, in the 'Datasets' tab, click on the scalar dataset 'Depth' under 'Result Type'. Using the 'Temporal Controller', scroll through the output times. The results update as new output times are selected. </li>
Note: The styling of the Map Outputs can be changed in the 'Contours' tab. 
 
{{Video|name=03_Animation_M01_Depth_V2_b.mp4|width=1265}}
 
<li>Click on a vector dataset 'Vector Velocity' by selecting the arrow icon to add it to the displayed 'Depth' and visualise them together. The vector output shows both direction and magnitude. 
Note: The appearance of vectors (colour, line width, symbology) can be changed in the 'Vectors' tab. 
 
{{Video|name=04_Animation_M01_VVec_V2_b.mp4|width=1265}}
 
</ol>
View mesh results (Time Series) with TUFLOW Viewer 2 from the 2d_po files:
<ol>
<li>Select '''M01_5m_001_PLOT_L''' in the Layers panel and click 'TUFLOW Viewer Plot Window' from the TUFLOW Plugin toolbar. The plot widget will open. Within the plot widget, use the 'Result Names' menu to ensure the results '''M01_5m_001''' are selected. Then select 'Flow' as the data type using the 'Data Types' menu. Finally, use the 'Selection' tool to select the 2d_po line. This shows the flow data across the 2d_po line (Type Q_).
<li>View the point time series for Level and Velocity dataset (Type H_ and V_). Select '''M01_5m_001_PLOT_P''' in the Layers panel and select 'Level' and 'Velocity' from the 'Data Types' menu (ensure 'Flow' is unselected). Use the 'Selection' tool to select the 2d_po point. This shows level and velocity at the point (Type H_ and V_). To move the velocity to a secondary axis, right click the plot and select 'Move to secondary axis'.
 
{{Video|name=05_Animation_M01_TimeSeries_V2_a.mp4|width=1265}}
 
 

</ol>

=Conclusion=
:*The basics of viewing 2D TUFLOW results in QGIS using the TUFLOW Viewer 2 were covered.
:*For further functionality, see [https://docs.tuflow.com/qgis-tuflow-plugin/2026.0/tuflow-viewer TUFLOW Viewer 2 documentation].

 
{{Tips Navigation
|uplink=[[Tutorial_M01#Results| Back to Module 1 Main Page]]
}}

File:TUFLOW Viewer legacy icon.png

2026-05-25T00:08:49Z

Emilie Nielsen:

Tutorial M01 Results QGIS update V2 draft

2026-05-25T00:01:03Z

Emilie Nielsen:

= Introduction =
QGIS is used to view the 2D grid and mesh 2D results: (as well as the TUFLOW 1D results). This section describes how to view the following results using the TUFLOW Viewer 2:
:*The grid results (.tif) are inspected with the Profile Tool plugin. For installation, see [https://wiki.tuflow.com/index.php?title=QGIS_Profile_Tool Installation of Profile Tool]
:*The mesh results (.xmdf, .tpc), including the bed elevation and time series, are inspected with the TUFLOW Viewer 2 as part of the TUFLOW Plugin. For more information on TUFLOW Viewer 2 and installation instructions, see the [https://docs.tuflow.com/qgis-tuflow-plugin/latest/tuflow-viewer/ TUFLOW Viewer Documentation].

=Method=
View grid results with Profile Tool: 
<ol>
<li>Load the '''M01_5m_001_h_Max.tif''' file from the '''Module_01\TUFLOW\results\grids''' folder. It can either be dragged and dropped into QGIS, or loaded by selecting Layer > Add Layer > Add Raster Layer from the menu.
<li>This displays the maximum water level in the model recorded during the whole simulation.
<li>Use the Profile Tool to view the maximum water level and DEM. 
 
{{Video|name=Animation_M01_Results_01b.mp4|width=1265}}
 
 
</ol>
View mesh results (Map Outputs) with TUFLOW Viewer 2:
 
<ol>
<li>Ensure TUFLOW Viewer 2 has been activated. For backwards compatibility, the legacy TUFLOW Viewer is still selected by default. To activate TUFLOW Viewer 2:
* Under the TUFLOW Plugin menu, check on the 'TUFLOW Viewer V2' option to enable the new viewer. 
 
[[File: image of dropdown menu]] 
 
* To confirm the new viewer has been activated, check that the legacy TUFLOW Viewer icon [[File: icon]] has been replaced with the time-series icon [[File: icon]]. The TUFLOW Plugin toolbar should look like: 
 
[[File:TUFLOW Viewer 2 Txt.png]] 
 
<li>Open the Map Outputs and Time Series results, either:
:* Within the QGIS Browser Panel drag the following layers into the QGIS workspace, or
::* '''Module_01\TUFLOW\results\M01_5m_001.xmdf''' > loads the map output mesh results
::* '''Module_01\TUFLOW\results\plot\M01_5m_001.tpc''' > loads the time series output results
:* In File Explorer, navigate to the files above and drag and drop them into the QGIS workspace.
<li>The Map Outputs show scalar datasets, e.g. depth and velocity, and vector datasets, e.g. velocity vectors. Only one scalar and one vector dataset can be displayed at the same time. 
 
{{Video|name=02_Animation_M01_LoadResults_V2_b.mp4|width=1265}}
 

<li>In the layers panel, select '''M01_5m_001'''. In the 'Layer Styling' panel, in the 'Datasets' tab, click on the scalar dataset 'Depth' under 'Result Type'. Using the 'Temporal Controller', scroll through the output times. The results update as new output times are selected. </li>
Note: The styling of the Map Outputs can be changed in the 'Contours' tab. 
 
{{Video|name=03_Animation_M01_Depth_V2_b.mp4|width=1265}}
 
<li>Click on a vector dataset 'Vector Velocity' by selecting the arrow icon to add it to the displayed 'Depth' and visualise them together. The vector output shows both direction and magnitude. 
Note: The appearance of vectors (colour, line width, symbology) can be changed in the 'Vectors' tab. 
 
{{Video|name=04_Animation_M01_VVec_V2_b.mp4|width=1265}}
 
</ol>
View mesh results (Time Series) with TUFLOW Viewer 2 from the 2d_po files:
<ol>
<li>Select '''M01_5m_001_PLOT_L''' in the Layers panel and click 'TUFLOW Viewer Plot Window' from the TUFLOW Plugin toolbar. The plot widget will open. Within the plot widget, use the 'Result Names' menu to ensure the results '''M01_5m_001''' are selected. Then select 'Flow' as the data type using the 'Data Types' menu. Finally, use the 'Selection' tool to select the 2d_po line. This shows the flow data across the 2d_po line (Type Q_).
<li>View the point time series for Level and Velocity dataset (Type H_ and V_). Select '''M01_5m_001_PLOT_P''' in the Layers panel and select 'Level' and 'Velocity' from the 'Data Types' menu (ensure 'Flow' is unselected). Use the 'Selection' tool to select the 2d_po point. This shows level and velocity at the point (Type H_ and V_). To move the velocity to a secondary axis, right click the plot and select 'Move to secondary axis'.
 
{{Video|name=05_Animation_M01_TimeSeries_V2_a.mp4|width=1265}}
 
 

</ol>

=Conclusion=
:*The basics of viewing 2D TUFLOW results in QGIS using the TUFLOW Viewer 2 were covered.
:*For further functionality, see [https://docs.tuflow.com/qgis-tuflow-plugin/2026.0/tuflow-viewer TUFLOW Viewer 2 documentation].

 
{{Tips Navigation
|uplink=[[Tutorial_M01#Results| Back to Module 1 Main Page]]
}}

TUFLOW 2D Hydraulic Structures

2026-04-21T23:43:05Z

Emilie Nielsen: /* 2D Layered Flow Constriction (2d_lfcsh) */

= 2D Structure Modelling Theory =
The theory behind the modelling of energy losses and affluxes of hydraulic structures is presented in the following webinars by Bill Syme and Greg Collecutt (TUFLOW Developers).

*[https://www.tuflow.com/library/webinars/#structures Webinar Link: Modelling Energy Losses at Structures] 
*[https://www.tuflow.com/library/webinars/#nov2022_hydraulic_modelling_bridge Webinar Link: 1D, 2D & 3D Hydraulic Modelling of Bridges]
 

= 2D Bridge Modelling in TUFLOW - Overview =
The TUFLOW 2D solution explicitly predicts the majority of “macro” losses due to the expansion and contraction of water through a constriction, or around a bend, provided the resolution of the grid is sufficiently fine ([https://www.tuflow.com/Download/Publications/Flow%20Through%20an%20Abrupt%20Constriction%20-%202D%20Hydrodynamic%20Performance%20and%20Influence%20of%20Spatial%20Resolution,%20Barton,%202001.pdf Barton, 2001]; [https://www.tuflow.com/Download/Publications/Modelling%20of%20Bends%20and%20Hydraulic%20Structures%20in%20a%202D%20Scheme,%20Syme,%202001.pdf Syme, 2001]; [https://www.tuflow.com/Download/Technical_Memos/Modelling%20Bridge%20Piers%20in%202D%20using%20TUFLOW.pdf Ryan, 2013]). Where the 2D model is not of fine enough resolution to simulate the “micro” losses (e.g. from bridge piers, vena contracta, losses in the vertical (3rd) dimension), additional form loss coefficients and/or modifications to the cells widths and flow height need to be added.
==Contraction/Expansion Losses (“Macro” Losses)==
Loss of energy is caused by the flow contraction during the expansion of water after the vena-contracta inside a bridge section and the flow expansion downstream a bridge. As discussed above, this type of "macro" losses can be explicitly resolved by the TUFLOW 2D solver, provided that a proper turbulence model and mesh size are used. Below is an example of the 2D modelling of flow contraction/expansion at a pair of bridge abutments.
 
[[File:FC_Velocity_Example.PNG|600px]] 

==Pier Losses==
Piers are usually smaller than the 2D cell size in real-world flood models. Although flexible mesh solver or quadtree refinement can be applied to reduce the local cell size around the pier, it also comes with an expensive computational cost that could significantly increase the simulation time. More practically, the backwater effect of piers can be modelled as sub-grid form losses.

Pier form loss coefficients can be derived from information in publications such as [https://www.fhwa.dot.gov/engineering/hydraulics/library_arc.cfm?pub_number=1&id=5 ''Hydraulics of Bridge Waterways'' (Bradly, 1978)] or [https://austroads.com.au/publications/bridges/agbt08 ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018)]. Energy loss estimated from bridge piers or other obstructions, vertical or horizontal, that do not cause upstream controlled flow regimes like pressure flow, are dependent on the ratio of the obstruction's area perpendicular to the flow direction to the gross flow area of the bridge opening, the shape of the piers or obstruction, and the angularity of the piers/obstruction to the flow direction. For example, using Hydraulics of Bridge Waterways (Bradly, 1978) the approach is:
<ol>
<li>Calculate the ratio of the water area occupied by piers to the gross water area of the constriction (both based on the normal water surface) and the angularity of the piers. These inputs are used to calculate "J" in the FHA documentation.</li>
<li>Use the Figure 4.10 ''Incremental Backwater Coefficient for Piers'' data to calculate Kp. 
[[File:incremental_backwater_coefficient_2018_pier_losses.png]]
 
'''NOTE''': the pier form loss coefficients in Hydraulics of Bridge Waterways are derived based on the cross-sectional averaged velocity through the bridge opening in the absence of piers. It's not necessary to specify a blockage value if a pier form loss coefficient estimated from this method is used.
</li>
</ol>

==Bridge Deck and Rail (Super Structure)==
When a bridge deck become partially or completely submerged, the deck could generate extra afflux resulting in increased water levels and flood extents upstream of the structure. The flow around the deck is highly 3-dimentional and complexed due to the different deck designs/profiles and/or the occurrence of pressure flow. In 2D SWE solver, depth-varying form loss values are often needed to reproduce the afflux caused by such structure. Due to the complexity of the flow, guidelines on how to set the form loss coefficient for the bridge deck are rare. We have carried out a joint research with QLD TMR (Queensland Department of Transport and Main Roads) regarding how to choose a proper form loss value for the bridge deck [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)] . In the research, CFD modelling was conducted to investigate the characteristics of energy loss of a simple bridge with a flat bottomed deck and guardrails.
 
[[File:CFD_study.png|600px]]

Below are the key findings from the study:
*The results displayed a characteristic shape for head loss coefficient as a function of downstream water level over the deck thickness (TW/T).
*The head loss (afflux) peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out.
[[File:FormLoss_vs_TWT.png|600px]]
 

=== Bridge Design (hB/T) vs Form Loss Coefficient Table===
The peak loss coefficient value is a function of the ratio of the depth underneath the deck (hB) and the thickness of the deck (T). This table can be used to estimate the deck form loss coefficient based on the bridge design (hB/T).
<ol>
{| style="text-align: center;" class="wikitable" width="35%"
! style="background-color:#005581; font-weight:bold; color:white;" width=55%| Deck Height to Thickness Ratio
! style="background-color:#005581; font-weight:bold; color:white;" width=45%| Peak Form Loss Coefficient
|-
| Scenario A (hB/T) = 2 || 0.42
|-
| Scenario B (hB/T) = 4 || 0.28
|-
| Scenario C (hB/T) = 6 || 0.20
|}
</ol>

*The solid portion of the guard rails (blockage * rail depth) can be added to T in addition to the deck thickness to calculate hB/T.
*For bridge with more complicated designs (e.g. girders), higher form loss might be required due to the higher surface roughness of the bridge.
*If the hB/T ratio is less than 2 or greater than 6, use a peak form loss coefficient of 0.42 (minimum) or 0.20 (maximum), respectively.

'''NOTE''': This form loss value should not be confused with the value of 1.56 used in the pressure flow approached adopted in [[1D_Bridges | TUFLOW 1D "B" and "BB" bridge]]. TUFLOW 1D bridge pressure flow approach is based on the section 4.13.2 "All Girders in Contact with Flow (Case II)" of ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018). The original hydraulic experiment conducted by [https://hdl.handle.net/10217/39009 Liu et al (1957)] in a laboratory flume with a pair of bridge abutments and a deck. The flow conditions were similar to orifice flow due to the high blockage ratio caused by the abutments and the deck. When modelling bridges in 2D, the contraction/expansion losses caused by the abutments would be handled explicitly by the 2D solver, so a value 1.56 can lead to duplication of the contraction/expansion losses caused by the bridge abutments. 
 

=TUFLOW 2D Bridge Setup=
There are two methods available to model depth varying form loss of a bridge structure:
* [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 |2D Layered Flow Constriction (2d_lfcsh)]]
:The traditional method used to model depth-varying form loss through bridge components such as piers, decks, and rails.

*[[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 |2D BG Shape (2d_bg)]] (introduced in the 2023 release)
:A simplified approach developed to simplify the model input based on the findings from the joint TMR Study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

Both methods provide options for representing flow surcharging, the pressure flow of bridge decks and eventually submerged bridge flow at higher water levels. During the surcharging of bridge decks, higher energy losses can be specified to simulate the pressure flow.

Examples for how to configure both approaches are provided in the 2D structures section of the [[TUFLOW_Example_Models#2D_Structures |TUFLOW Wiki Example Models]] and [[Tutorial_M04 |Tutorial Module 4]] - 2D Bridges.

==2D Layered Flow Constriction (2d_lfcsh)==
Four flow constriction layers are represented in a 2d_lfcsh layer. The lower three layers represents the pier, the bridge deck and the rails. Each layer has its own attributes to specify the blockage and the form loss coefficient. The top (fourth) layer assumes the flow is unimpeded, representative of flow over the top of a bridge. Within the same shape, the invert of the bed, and thickness of each layer can vary in 3D.

The following table provides an overview for how to determine the blockage and form loss coefficient for each layer. Note that this is just an overview and additional guidelines may need to be considered. 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || Use calibration data, if available, to determine FLC. If no calibration is available, estimate using [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table || Full blockage, no flow through the deck
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 3 || Bridge rails || 10% – 100% || Use calibration data, if available, to determine FLC. 
If no calibration data is available, combined FLC for Layers 2 and 3 should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = L2_Depth + (pBlockage × L3_Depth)
*(pBlockage × L3_Depth) represents the solid portion of the rails
*L2 FLC and L3 FLC should sum to the combined FLC
|Blockage and FLC depends on rail type Sensitivity testing with 100% blockage is recommended due to potential for debris during flood
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}
<ol>
[[File:2d_lfcsh_attributes_02.jpg|700px]]
</ol>
 

===Blockage===

The 2d_lfcsh functions by adjusting the flow width and the form loss of 2D cell faces. The combined blockage across the 4 layers is calculated at each simulation timesteps:
<ol>
 
[[File: Blockage_total_equation_01.png|600px]]
 
where 
'''''yi''''' is the actual depth of water in layer '''''i''''' 
'''''ytotal''''' is the total water depth 
</ol>

===Form Loss Approach===

The combined form loss coefficient is determined using one of three methods. The form loss coefficient method can be specified either individually using the 2d_lfcsh “Shape_Options” attribute or globally using the .tcf command: 
<tt>Layered FLC Default Approach == [ METHOD A | {METHOD B} | METHOD C | METHOD D]</tt> 

:METHOD A: The losses are accumulated as the water level rises through the layers. 
<ol>
[[File:Eq_flc_cumulate.png |450px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Applies the full accumulated form loss continuously, even when overtopping begins (no reduction)
:Note: Simpler method but tends to overestimate losses when the structure is submerged or overtopped 

:METHOD B (default): the losses are applied pro-rata according to the depth of water in each layer. 
<ol>
[[File:Eq_flc_portion.png |430px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure
:Note: Maintains backward compatibility but may underrepresent losses during pressurised or overtopped flows 

:METHOD C (recommended): hybrid approach combining Method A and Method B. 
<ol>
[[File:Eq_flc_methodC.png |520px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Gradual increase in form loss with water level, following Method A
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure, following Method B
:Note: Recommended method; aligns closest to CFD modelling results and TUFLOW HPC behaviour.

:METHOD D: Allows the modeller to control the depth at which the losses start to reduce when the flow transitions between pressure flow and drowned flow.
:This approach is the same used by the 2d_bg layer (introduced in the 2023-03 release). It is recommended to use the 2d_bg layer as it has the benefit of a simplified attribute table, for easier user input.

===Form Loss Calibration Example - Iowa River Flood Study===

In this study, a combined form loss coefficient of 0.35 was used to match observed head loss during slight overtopping of a bridge. The FLC values for each layer were adjusted to achieve the correct combined form loss. The table and plot show how each layer contributes to the total form loss and highlight the differences in calculated form loss between the three methods.

{| style="text-align: left; margin-left: 0;" class="wikitable" width="60%"
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=6%| Layer
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=10%| Depth (m)
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=12%| Blockage (%)
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method A
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method B
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method C
|-
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
|-
| 1 || 5.0 || 5 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07
|-
| 2 || 1.5 || 100 || 0.15 || 0.22 || 1.05 || 0.30 || 0.15 || 0.22
|-
| 3 || 1.0 || 50 || 0.13 || 0.35 || 0.70 || 0.35 || 0.13 || 0.35
|}

</ol>
 
<ol>
[[File:FLC_vs_height_updated.png | 600px ]]
</ol>

==2D BG Shape (2d_bg)==
2D BG Shape is similar to the Layered Flow Constriction, but has several updates to simplify the input based on the findings from the joint study with TMR [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

The following table provides an overview of how to determine the blockage and form loss coefficient for each layer. Note that this is just an overview and additional guidelines may need to be considered. 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || rowspan="2" | The Super Structure (Super_S) is the bridge deck and rails layers combined. 
Use calibration data, if available, to determine FLC. 
If no calibration data is available, the Super_S FLC should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = Deck_Depth + (Rail_pBlockage*Rail_Depth)
*(Rail_pBlockage*Rail_Depth) represents the solid portion of the rails
|| Full blockage, no flow through the deck
|-
| 3 || Bridge rails || 10% – 100% || Sensitivity testing with 100% blockage is recommended due to potential for debris during flood events
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}

<ol>
[[File:Bridge block.jpg | 800px]]
</ol>

===Inflection Point===

Based on findings from the joint study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)], the head loss peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out. The 'SuperS_IPf' attribute (inflection point factor, default = 1.6) can be used to define the height of the inflection point. The solid portion of the rail layer is also added to the deck thickness to calculate the depth to the inflection point (DIP), i.e.:
<ol>
[[File:eq_flc_bg_infection_point.png | 520px ]]
</ol>

===Form Loss Approach===
The form loss approach is similar to the FLC approach METHOD C, with L2/L3 replaced by a single super structure layer:
<ol>
[[File:eq_flc_bg.png | 480px ]]
</ol>

===Form Loss Calibration Example - Iowa River Flood Study===
This example uses the same bridge setup described in the[[TUFLOW_2D_Hydraulic_Structures#Form_Loss_Calibration_Example_-_Iowa_River_Flood_Study | 2D Layered Flow Constriction]] section, with the following parameters applied:
*SuperS_FLC = 0.28
*SuperS_Ipf = 1.6,
The Depth to Inflection Point (DIP) is calculated as 3.2m above the bridge soffit.

The table and figure below show how the form loss value varies with water depth.
<ol>
{| style="text-align: center;" class="wikitable" width="32%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Depth (m)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Form Loss
|-
| Pier || 5.0 || 5 || 0.07
|-
| Deck || 1.5 || 100 || rowspan="2" | 0.28
|-
| Rail || 1.0 || 50
|}

[[File:FLC_vs_height_bg.png | 600px ]]
</ol>

== 2D Bridges Line vs Polygon Layer ==
The form loss coefficient (FLC) is applied differently when using a line compared to a polygon for both 2d_lfcsh and 2d_bg inputs. The FLC is applied at cell sides (u and v faces) as this is where velocities are calculated. 
For larger bridges that spread across multiple cells, it is recommended to use a polygon layer, which selects all u and v faces falling within the polygon.
 
 
'''2D Layered Flow Constriction (2d_lfcsh)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides
| This approach is cell size independent. It is the easiest setup and the preferred / recommended approach when using 2d_lfcsh.
|-
| Thick
| between zero and 1.5 times the cell size
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| A cell is selected if the polyline intersects the cell crosshair. Caution should be taken when using a "thick" line, as changes in cell size can cause it to become a "wide" line. If this occurs, the FLC attribute may need to be recalculated to avoid overestimating or underestimating losses.
|-
| Wide
| larger than 1.5 times the cell size
| Total form loss of the bridge ''(may need to be recalculated, see notes)''
| FLC divided by number of cell sides in the direction of flow 
''(number of cell sides in the direction of flow is calculated as line width divided by cell size)''
| Polygon shapes are recommended if more than 3 rows of faces must be selected.. 
Caution should be taken when using a "wide" line. The cell size and alignment of the 2d_lfcsh line may result in selecting too many or too few cell faces in the direction of the flow. The FLC input may need to be recalculated to ensure FLC Applied multiplied by the number of cell sides in the direction of flow equates to the intended total form loss.
|-
!rowspan="1" | Polygon
| -
| -
| Total loss per unit length (meters or feet) in the direction of flow
| FLC * cell size applied to all sides of selected cells
|
|}

'''2D Bridge (2d_bg)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides.
| This approach is cell size independent.
|-
| Thick
| larger than zero
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| This approach is cell size independent. A cell is selected if the polyline intersects the cell crosshair.
|-
| Wide
| Not supported
| –
| –
| BG polygon shapes are recommended if more than 3 rows of faces must be selected.
|-
!rowspan="1" |Polygon
| -
| ''(used to automatically distribute the total FLC to the selected faces)''
| Total form loss of the bridge
| FLC / Deck_Width * cell size applied to all sides of selected cells
| For bridges modelled using a 2d_bg polygon the relative ratio of the bridge width to the 2D cell size should be 4 or greater. For more information on this see [https://downloads.tuflow.com/Other/2d_bg_R_Bridge_Configuration_Advice_202503.pdf 2d_bg_R_Bridge_Configuration_Advice.pdf].
|}
 
The following diagrams demonstrate how the input FLC is applied for the four geometry options for 2d_lfcsh and 2d_bg layers: 
[[File:2dlfcsh 2dbg combined v2.png|1200px]]

It is good modelling practice to check the [[Check_Files_2d_lfcsh_uvpt | lfcsh_uvpt_check]] and [[Check Files 2d bg uvpt check | bg_uvpt_check]] files to confirm the number of faces selected and the FLC values assigned. It is also strongly recommended to undertake a sensitivity analysis on the applied form losses in the model to check if it makes any difference to the results and/or double check against other methods (hand calculations, other software, CFD modelling), especially if the bridge is near an area of interest. If calibration data is available, this should be used to guide the form loss value specification. 
 

= Common Questions Answered (FAQ)=
== What blockage values should I use for bridge guard rails? ==
The blockage of bridge guard rails can be anything from 100% blocked (solid concrete rails) to 10% blocked (very open rails). In addition, the accumulation of debris during a flood can be substantial as shown in the image below. Sensitivity testing with 100% blockage is recommended.
 
[[File:Bridge rail debris.jpg | 500px]]

== How to conduct sensitivity test for 2D bridges? ==
General recommendations to cross-check the results are:
* Compare computed affluxes against desktop methods (e.g. Hydraulics of Bridge Waterways, 1978) and/or other software including CFD, especially for unusual bridge designs.
* Use any recorded flood marks or general observations from past events to check and calibrate FLC values.
* Conduct sensitivity testing by assessing the impact and influence of FLC values on your modelling objectives. The afflux resulting from the FLC values will be proportional to the velocity head, i.e. ∆h=FLC*(v^2/2g). As such, if velocities are low (e.g. 1 m/s), the results may not be overly sensitive to uncertainties in the FLC values. If completing a check using this equation for a long skew bridge it is best to calculate the total structure velocity from a PO line digitised in the same location as the bridge.

Finally, after completing sensitivity testing and understanding the range of uncertainty due to unknowns like the degree of blockage and influence of FLC values (e.g. +/-20%), you are in a position to discuss with your client how best to proceed. For example, if the modelling is to set planning levels for a development upstream then it may be appropriate to choose values on the higher side (higher FLC values and/or blockage assumptions), noting that the uncertainty may be amply covered by a regulatory freeboard. Conversely, if the development is on the downstream side the conservative approach would be to use the results at the lower end of your FLC/blockage values. 
[[File:Bridge Flood Debris Loading.jpg | 500px]] 

== Should I use both FLC and blockage for layer one in 2D bridge layered flow constriction? ==
When applying FLC and blockage values to model obstructions such as piers, the following considerations need to be taken into account:
* The FLC value applies an energy loss along 1D channels or across 2D cell faces equivalent to FLC*V2/2g where V is the 1D channel velocity or the 2D cell face velocity.
* FLC values are often sourced from publications such as Hydraulics of Bridge Waterways or AustRoads (e.g. Kp chart for piers).
* If possible, establish whether the source of the FLC value is based on the approach velocity (the velocity in the absence of piers) or structure velocity (the velocity with area blocked out by the piers) noting that it often isn’t clear or stated.
** If it is the structure velocity, this is usually the velocity at the vena-contracta (point of greatest contraction within the entrance to the structure and therefore highest velocity) - see image below. Bluff or sharp-edged obstructions will have a much more pronounced vena-contracta, and therefore higher velocity compared with a round-edged obstruction.
** FLC values based on the approach velocity will be higher than those based on the structure velocity to achieve the same energy loss.
* Applying a blockage equivalent to the obstruction width will increase, usually very slightly, the velocity of the 1D channel or 2D cell face. This won’t be the vena-contracta velocity, but a velocity between the approach velocity and the vena-contracta velocity. A greater blockage will need to be applied to emulate the vena-contracta velocity.
* If the FLC source value is based on:
** The approach velocity then there is no need to apply a blockage value.
** The structure velocity then the blockage value should be applied noting that it may be appropriate to apply a larger blockage to take into account the vena-contracta.
* If it is not clear or unknown whether the FLC source value is based on the approach or structure velocity, the recommendation would be to apply the blockage in the interests of being slightly conservative on the upstream flood level calculation.
* For most minor obstructions such as bridge piers, the blockage is usually relatively small and whether included or not has a negligible or minor affect on flood levels compared with other factors such as the approach embankments and the bridge deck.
* Blockage from debris wrapped around piers can have a greater influence on the results than the effect of applying or not applying a blockage. Debris wrapped around piers can be accounted for in the FLC value calculated for the pier layer.
* As always, sensitivity testing with and without blockage and +/- the FLC value is highly recommended to understand their importance in regard to the broader modelling objectives and the effects of uncertainties in the input data, boundaries, other parameters such as Manning’s n values, and the accuracy of the numerical solution scheme (see [https://www.tuflow.com/library/webinars/#maximise_accuracy Maximising the Accuracy of Hydraulic Models webinar]).
[[File: Vena_contracta.png]] 
''Image showing the formation of the vena-contracta.'' 
 

==I don't see results that I expect when using 2d_lfcsh layer==
The 2d_lfcsh layer is a versatile feature that was designed to model bridges in 2D, but can also be used for other applications like fences, buildings raised on pillars and so on.
Some of the unexpected results could be:
* Water level going through the bridge deck in 2D map output.
* Water transiting through 100% blocked Layer 1, e.g. fences with solid base.
* SHMax.csv reporting values above the bridge deck when 2D map output reports water level lower than the top of the bridge deck.

TUFLOW is a 2D solution (not 3D), in the 2d_lfcsh layer the percent blockage and form loss coefficient applied to the cell faces is depth averaged across the entire cell face (across Layer 1, 2 and 3): 
*For bridges, where Layer 2 has a 100% blockage applied, the minimum flow width of 0.001m is used and is averaged with the Layer 1 blockage (based on the depth of the water). This may result in a water level being reported within or above the bridge deck, which would represent the pressure head.
*Layered flow constriction works by adjusting the flow area of the cell faces by any blockages to generate the correct depth averaged velocity at each face at which the form losses are applied as a fraction of the V2/2g kinetic energy. Calculating the correct velocity is critical for determining the losses as the losses are proportional to the velocity squared. 
*For a layered flow constriction cell face the flow area cannot be zero above the invert of Layer 1 to avoid a divide by zero in the computations, therefore a minimum average flow width after applying blockages of 0.001 m is applied. if Layer 1 is 100% blocked, a very small amount of water will flow through Layer 1. If this is unacceptable, instead of applying 100% blockage of Layer 1, the preferred approach is to start the layered flow constriction at the top of Layer 1 or raise the ground elevation to the top of Layer 1 using one of the Z Shape modification functions (e.g. a breakline). 
<ol>
[[File:100% Blockage Diagram.png | 500px]]
</ol>

== Can I model bridge piers explicitly in 2D using very small cells? ==
It isn't recommended to explicitly model bridge piers by blocking out the pier faces in TUFLOW, or in any hydraulic modelling software based on solving Shallow Water Equations(SWE). Due to the 3-dimentiality of the flow and turbulence around a pier, computational fluid dynamics (CFD) approach is often required to simulate the flow around piers explicitly. The wake turbulence behind a simple-shape pier can be resolved to some extent using extremely fine mesh in TUFLOW (see calibration example to a flume experiment in the [https://www.tuflow.com/library/webinars/#structures webinar on Energy Losses at Structures]), however the predictions for head losses show notable sensitivities to the mesh size, the mesh design, and the choice of turbulence model. The extremely fine mesh resolution also results in significantly higher computational costs.

Therefore, the safest and strongly recommended approach with regard to establishing head losses and consequently flood levels, is to model the effects of such obstructions with form loss coefficients (applied to selected mesh cells) that have been derived from physical testing. This approach has been shown to provide the most consistent results across various mesh resolutions. It also has the added benefit that, by avoiding small cells in the mesh, it will provide much more efficient run times for flow solvers.

[[File:Flow round a cylinder.png]]

''The point of flow separation around an object has a major bearing on the drag coefficient and is not reliably reproduced by 2D or 3D software.''


== How to best convert flow constriction data (2d_fc or 2d_fcsh) into newer formats (2d_lfcsh or 2d_bg)? ==
The form loss parameters can be transferred from the flow constriction (2d_fc or 2d_fcsh) to the first layer of the layered flow constriction (2d_lfcsh) or pier layer of the 2d_bg. Definition of the remaining form loss and blockage layer inputs should follow the guidance outlined in [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 | 2D Layered Flow Constriction]] and [[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 | 2D BG Shape]] paragraphs. 
When using floating pontoon (type FD in the 2d_fc or 2d_fcsh) different setup might need to be used for different events. For large events when floating pontoon becomes fixed at the top of the supporting piles, standard 2d_lfcsh setup can be used. Smaller events when the pontoon is floating at different heights might require more sensitivity testing of the structure parameters to find out a setup the matches the reality as close as possible. 

== Should I model bridges in 1D or 2D Domain? ==
The recommended approach typically depends on the study objectives and if the channel upstream and downstream of the bridge is modelled in 1D or 2D. To preserve the momentum as accurately as possible the bridge should be modelled in the same dimension as the channel, e.g. 1d_nwk bridge if the channels is in 1D and 2d_bg or 2d_lfcsh if the channel is modelled in 2D. 
In 2D, the expansion/contraction losses are modelled based on the topography and don't need to be estimated as attributes as for 1D modelling. Also, for higher flows where the bridge is overtopped, 2D is preferable approach.

== What is the difference between downstream and upstream controlled flow? ==
Downstream control means a change in downstream water level will cause a change in upstream water level. Upstream control means the upstream water level is insensitive to the downstream water level and usually indicates the occurrence of supercritical flow.

== What FLC values should be used for 2d_bg bridge if hB/T is below 2 or above 6? ==
TMR has extended the CFD simulation to hB/T ratios of 1 to 10. Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for details.

If hB/T is outside this ratio:
* hB/T ratios of less than 1 represent a very unusual bridge sitting low to the ground, and the peak FLC may increase above the end value (FLC of 0.6) in a way that doesn't follow the research trend or extrapolation. For these cases we would recommend using CFD modelling to obtain a more informed value. Alternatively, computing an FLC based on pressure flow or using 1D culvert might be considered.
* For hB/T ratios of greater than 10, the FLC is likely to continue to decrease, but probably not significantly. Clamping to the end value (FLC of 0.16) might be considered the more conservative approach (if the primary concern is flood levels upstream of the bridge). 
 
{{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

File:2d lfcsh attributes 02.jpg

2026-04-21T23:42:06Z

Emilie Nielsen:

1D Pumps

2026-04-21T03:58:33Z

Emilie Nielsen: /* 2D-2D Configuration */

=Introduction=
This post provides a modelling example for a 1D pump using a pump curve. For this example we will set up a pump in two common situations (2D-2D & 1D-2D).

=Pump Attributes=
A pump needs to first be digitised in a 1d_nwke layer. The direction of the polyline must go from inlet to outlet as a pump is unidirectional. The attributes required for a pump in your 1d_nwk layer can be found in the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 
In the 1d_nwk layer, the following attributes are required: 
#ID = ID of the pump channel. 
#Type = "P" or "PO". 
#US_Invert = Intake elevation of the pump. 
#DS_Invert = Outlet elevation of the receptor. 
#Inlet_Type = Used to specify the pump curve in the Depth Discharge database. 
#Width_or_D = Diameter of the pump’s outlet pipe/hose. 
#Number_of = Number of (identical) pumps.
 
[[File:1d_nwk_pump_pipe.PNG|border|300px]] 

=2D-2D Configuration=
As pumps are zero length channels, they do not create automatic nodes at the upstream and downstream end. If you ran the model with just a pump polyline and SX connection, you will get [[TUFLOW_Message_1353| ERROR 1353]]. To remove this error, the most efficient schematisation is to digitise a 1d_nwk 'NODE' at the upstream and downstream end of the pump (no need for a separate 2d_bc SX layer). Unlike NODEs connected to pipes and channels, NODEs connected to zero length pumps require the following attributes: 
#Type = "NODE". 
#Len_or_NA = The 'NODE' requires a nominal storage amount. This can be estimated from the pipe length and diameter attached to the pump. 
#US_Invert = The upper elevation of the automatically created NA table. Make sure these values are set higher than the expected water levels at the intake and outlet of the pump. 
#DS_Invert = The bottom elevation of the pump nodes. As the pump does not create automatic nodes, the bottom elevation of the pump nodes must be specified. Note that this does not change the intake or outlet elevations of the pump, but only sets the bottom elevation of the nodes for storing water. 
#Conn_1D_2D = Set to "SX" to connect the 1D pump with the 2D domain. Without the SX connection, water will build up within the node and cause instabilities. 

See the example below. 

[[File:1d_nwk_pump_SX_node.png|600px]] 

A simple 2D-2D pump configuration will look like the below schematisation. 

[[File:Pump_schematic.PNG|600px]] 

=1D-2D Configuration=
Connecting a pump from a 1d network to the 2d domain or vice versa is similar to the configuration above, the only difference is that the connection with a 1d structure does not require a 1d nwk ‘Node’. A storage chamber in the 1d network can also be modelled using a 1d_na node with an elevation vs area .csv assigned to the node. 
[[File:1D-2D_pump_schematisation.PNG|border|600px]] 

=Estry Control File Setup=
Within the *.ecf the following commands and files are required to run a pump with no logical controls: 
<tt>Read GIS Network</tt> <tt>==</tt><tt>..\model\mi\1d_nwke_xxxxx.MIF</tt> 
<tt>Depth Discharge Database</tt> <tt>==</tt><tt>..\bc_dbase\xxxxx.csv</tt> 
If you do not specify a Depth-Discharge database then you will be faced with [[TUFLOW Message 1118 | ERROR 1118]]. 

=TUFLOW Operating Control File (.TOC)=
For guidance on setting up the operating controls for pumps, refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 

.ecf command required: 

<tt>Read Operating Controls File</tt> <tt>==</tt><tt> xxxxx.toc</tt> 

=Depth Discharge Database=
The depth discharge database is set up in the same way as a pit inlet database (refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]). Each pump ‘Inlet_type’ must reference a name within the depth discharge database, otherwise [[TUFLOW_Message_1118 | ERROR 1118]] - Could not find pit inlet type ",a," in the pit inlet database. The ‘Area (m2)’ column is the area of the pump offtake and ‘Width (m)’ column is the width of the pump offtake. Without information in the Area(m2) or Width(m) columns in the depth discharge database [[TUFLOW Message 1092|ERROR 1092]] and [[TUFLOW Message 1093|ERROR 1093]] will appear. 

==Pump Curve==
The performance of pumps is a function of suction head at the inlet and the level of the discharge location. The resultant total head between the water level at the inlet and outlet is what determines the flow rate through the pump. If the suction level is low the pump will need to provide more energy in the form of pressure to maintain the water elevation at the outlet, the opposite is also true if the water depth at the pump inlet is high. 

[[File:pump_fundamentals_total_head.jpg|thumb|none|500px|www.pumpfundamentals.com]]

That being the case it is important to consider what total head is required to achieve the modelling objectives and what flow rates you may require. Once you have an idea on any limits in total head you can start to research an appropriate pump and then extract the performance curve that is often incorporated as part of the technical specifications. An example is shown below. 

[[File:Manufacturer pump curve.JPG|border|600px]]

==Creating a TUFLOW pump curve==
The setup of the Depth Discharge database for a pump curve is similar to reading in inflow hydrographs, hyetographs etc, that is; a source .csv, and the two corresponding headings within the 3rd and 4th column. 

[[File:depth-discharge_pump.PNG |border|500px]] 

Once you have your manufacturer curve for your given pump it is now necessary to create the curve .csv for TUFLOW to read in. The manufacturer specifications will need to be translated into a total head vs pump rate chart. Although reading in the depth discharge database is the same process as other boundary conditions within TUFLOW, the curve itself is fundamentally different as you no longer need to start the csv file with 0,0. If the curve did start at 0,0 this would not make sense because at a total head difference of 0m the pump should effectively be operating at peak performance so the flow rate would be greater than 0 m3. The image below shows a csv file for the pump performance curve given in the previous section. 
 
[[File:Pump_curve_csv_example.png|border|600px]] 

==Using a Pump Curve in a TUFLOW Operating Control (TOC) File==

With the pump curve defined in the depth-discharge database it can either be specified within the pump 1d_nwk fields in the inlet_type field, for non-operational pumps, or it can be defined with the TOC file, for operational pumps. When defining with a TOC file, the pump curve is defined at the top of the structure control definition block and then the subsequent rules can turn the pump on/off. See the below TOC structure control definition for an example. In this case, the pump curve is used when the pump switches on once upstream water levels reach 2.75m AD. The pump curve is then used until the upstream water levels are reduced to 2.25m AD at which point the pump is switched off.

<tt>Define Pump Control</tt><tt> ==</tt> Pump_1
<tt>Pump Capacity</tt><tt> ==</tt> pump_1
HU <tt>==</tt> H1D Pump1.1
<tt>If </tt>HU <= 2.25
<tt>Pump Operation</tt><tt> ==</tt> Off
<tt>Else if</tt> HU > 2.25 <tt>AND</tt> HU < 2.75
<tt>Pump operation</tt><tt> ==</tt> <tt> No Change </tt>
<tt>Else if</tt> HU <tt>>=</tt> 2.75
<tt>Pump Operation</tt><tt> ==</tt> On
<tt>End if</tt>
<tt>End define</tt>

=1D Result File=
Although strictly not a check file, the operation of the pump can be confirmed by opening the *_1d_O.csv which is found within the csv folder where the results are written. The *_1d_O.csv monitors the operation of structures, this file can be quite useful in checking how the structure is performing with the given .toc file and GIS inputs. 
{| align="center" class="wikitable" width="75%"
! style="background-color:#005581; font-weight:bold; color:white;"| Filename prefix / suffix
! style="background-color:#005581; font-weight:bold; color:white;" width=75%| Brief Description
|-
| [[Pump_Results_1d_O | _1d_O.csv]]|| This csv displays the status of the pump, whether that is closed or fully open, results for any logic parameter specified in the TOC file and the flow through the pump if it is in operation.
|}
 
Any further questions please email TUFLOW support: [mailto:support@tuflow.com?Subject=TUFLOW%201D%20pumps%20help support@tuflow.com]
 
{{Tips Navigation
|uplink=[[ TUFLOW 1D Channels and Hydraulic Structures | Back to 1D Channels and Hydraulic Structures]]
}}

Advection Dispersion Modelling

2026-04-20T00:57:19Z

Emilie Nielsen: /* Introduction */

=Introduction=
TUFLOW’s Advection Dispersion (AD) functionality is an extension of the TUFLOW Classic/HPC engines available within the TUFLOW CATCH module. It adds to the hydrodynamic capabilities of TUFLOW Classic/HPC by simulating depth-averaged, two and one-dimensional constituent fate and transport. An example of such a constituent might include salinity. Both dissolved and particulate constituents can be simulated. TUFLOW AD takes depth and velocity fields computed by the TUFLOW Classic and HPC solvers and uses this information, together with initial and boundary conditions, to simulate the advection and dispersion of user-defined constituents.

TUFLOW AD is specifically oriented towards such analyses in systems including coastal waters, estuaries, rivers, floodplains and urban areas. The AD functionality is discussed in detail in the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual - Chapter 9].

TUFLOW FV also has Advection Dispersion functionality. In many cases, it's preferable to use TUFLOW FV for AD modelling due to its functionality with flexible mesh. See the [https://docs.tuflow.com/fv/manual/latest/ TUFLOW FV Manual] for details.

=Model Development=
==Setting Up a New Model==
The steps below describe the process for setting up a TUFLOW AD model. It is assumed that the user is familiar with TUFLOW Classic/HPC and that the folder structure for TUFLOW has been setup with all required files. The user should run the TUFLOW Classic/HPC model without the AD functionality first to make sure that it is appropriately configured and stable.

<ol>
<li>Create a TUFLOW AD control file with the extension .adcf
<li>Use a text editor to create an empty .adcf file and save it to the “runs” folder.

<li>Set up the AD global database (.csv file).
<li>Set up the TUFLOW AD global database in the “bc_dbase” folder which defines the constituent of interest and a number of characteristics, for example the decay rate and dispersion coefficient. The resulting file should look similar to the below: 
[[File:EG17 AD Consit 001.png]] 

<li>In the .adcf file use the "AD Global Database" command to set the location of the global database as follows. <tt>AD Global Database</tt><tt> == </tt><tt>..\bc dbase\my_ad_global_dbase.csv</tt>

<li>Set up the boundary condition tables (.csv file(s)) to define the time-varying constituent concentrations at any input boundaries.
<ul><li>Set up the constituent boundary condition table(s) in the “bc_dbase” folder. For example in the below, the time-varying concentration of constituents Conc_AD1 and Conc_AD2 are set: 
[[File:EG17 conc 001.png]] </ul>
<li>Set up up the boundary condition database (.csv file)
<ul><li>Set up the boundary condition database in the “bc_dbase” folder that references the tables set up in the previous step. 
[[File:EG17 AD 001.png]] 
<li>In the .adcf file use the "AD BC Database" command to set the location of the bc database as follows. <tt>AD BC Database</tt><tt> == </tt><tt>..\bc dbase\my_ad_bc_dbase.csv</tt></ul>
<li>Setup up TUFLOW to activate the AD functionality (.tcf file)
<ul><li>In the .tcf file use the command "AD Control File" to set the location of the adcf and activate execution of the AD functionality as follows. <tt>AD Control File</tt><tt> == </tt><tt>ad_run.adcf</tt></ul>
<li>Run the model
<li>Run TUFLOW as normal. The AD functionality will be utilised and appropriate constituent result output files written.

</ol>

==Example Models==
Example TUFLOW AD models, including settling and decay, are available via the [[TUFLOW_Example_Models#Advection_Dispersion | TUFLOW Example Model Dataset]].

= Common Questions Answered (FAQ) =

== How can the Advection Dispersion functionality be used to determine the time of concentration in a 1D-2D TUFLOW model? ==
The Advection Dispersion functionality can track particles and determine the time of concentration by simulating how a particle of water travels from an upstream to a downstream location. However, the AD functionality is only available for 2D domains and cannot directly operate within a 1D channel.

To utilise the AD functionality in this case, the 1D channel would need to be converted into a 2D domain using a Quadtree grid. This conversion involves refining the 2D cells within the channel to smaller sizes, ensuring the model accurately represents the flow behaviour. Once this modification is complete, the AD functionality can provide detailed insights into particle travel times and help demonstrate the effects of reprofiling or attenuation measures on downstream areas.

== Can TUFLOW generate 2D Plot (Time-Series) Output for Advection Dispersion results? ==
Currently, TUFLOW does not support 2D Plot (Time-Series) Output for Advection Dispersion results at specific point locations.

However, results can be extracted using output zones. Defining smaller output zones allows high-frequency data to be generated for areas of interest while managing file sizes efficiently. Multiple output zones can also be used to monitor widely separated locations.

== How can initial tracer concentrations and SGS parameters be managed in the Advection Dispersion functionality? ==
Initial tracer concentrations can be applied to dry cells, and these concentrations are mobilised as the cells become wet during a simulation. The initial water level in dry cells is set as the bed elevation plus the Cell Wet/Dry Depth. This depth determines the initial tracer volume available for advection once the cell becomes inundated.

When SGS (Sub-Grid Sampling) is used, the initial water volume is derived from a pre-calculated “level vs cell volume” curve. Tracer concentrations are distributed across this calculated volume. This ensures accurate representation of tracer movement, even in partially wet cells.

== How can the Advection Dispersion functionality be used to determine water residency time? ==
The Advection Dispersion functionality in TUFLOW can be used to calculate water residency time by modelling it as a scalar variable. This approach provides a method for tracking the duration water has spent within a specific area, such as a wetland, and is visualised in the model output as a time-based scalar field. This approach has some limitations:
* Output Capabilities: While TUFLOW supports various output formats (e.g., XMDF, DAT, NC), extracting detailed time-series data for specific constituents at individual locations may require additional post-processing. The current AD functionality does not explicitly support direct Point Output (PO) functionality for constituent data.
* Post-Processing Requirements: To obtain detailed residency time information at specific points, output zones may be required along with refined post-processing techniques. Defining output zones allows high-frequency scalar data to be captured in areas of interest, which can then be analysed to estimate residency times.
* Engine-Specific Features: Unlike the TUFLOW FV engine, which includes a particle tracking module for explicit tracking of water age, the fixed grid engine’s AD module relies on scalar-based methods to approximate residency time. For calculating water residency time with the AD functionality, properly configuring scalar outputs and planning post-processing steps are essential for accurate results.

== How can the Advection Dispersion functionality simplify firewater containment modelling? ==
The Advection Dispersion functionality in TUFLOW can simplify firewater containment modelling by using passive tracers to track firewater flow and concentration. Instead of running separate simulations for rainfall and firewater scenarios, the AD functionality enables a single simulation where tracers represent the firewater. This approach reduces modelling complexity while maintaining accuracy.

For example, a model with direct rainfall over the entire domain applies a passive tracer via 2d source area (2d_sa) polygons. The output can be set up to identify areas with tracer concentrations above a certain threshold, distinguishing firewater extents from other inundated areas. Areas outside of this represent zones with zero tracer concentration. Tracers can also include decay and settling parameters for added flexibility. This method not only simplifies the process but also ensures compliance with the UK CIRIA (Construction Industry Research and Information Association) guidance by integrating rainfall and firewater scenarios into a single simulation.

== What guidance is available for Non-Newtonian mixing exponents and dispersion coefficients in the Advection Dispersion functionality? ==
The Non-Newtonian Mixing Exponents (m, o, and p) were introduced in the 2023-03-AC release to improve how TUFLOW models non-Newtonian fluids. These exponents control how yield stress and density change as fluid concentration varies.

Previously, using a single exponent for all properties was ineffective for fluids with high solids content. For example, yield stress can increase rapidly with small changes in solids, while density changes more gradually.

It is recommended that these exponents range between 1 and 5. However, the optimal values depend on the specific fluid being modelled, and should be selected based on the fluid’s properties. TUFLOW does not provide specific default values.

For dispersion coefficients:

* In pure water, the longitudinal dispersion coefficient (KL) is usually between 6 and 13, and the transverse dispersion coefficient (KT) is between 0.15 and 1.6.

* Extremely high values, like 7500, only occur in special conditions such as estuarine environments with a halocline and are not typical for most cases.

Currently, there is no guidance for dispersion coefficients when mixing pure water with non-Newtonian fluids. Suitable values should be determined based on laboratory tests or studies specific to the fluid being modelled.

== What are the limitations of the Advection Dispersion functionality when modelling Non-Newtonian flow through 1D elements? ==
When using the Advection Dispersion functionality for non-Newtonian flow in models that include 1D elements, the following simplifications and limitations apply:

Flow Calculation:
* The flow through 1D elements (e.g., culverts) is calculated based on the assumption of pure water.
* Non-Newtonian properties, such as viscosity or yield stress, are not considered in the 1D engine. This simplification can lead to an overestimation of flow rates when dealing with non-Newtonian fluids.
Tracer Transport:
* By default, the concentration of the non-Newtonian fluid is passed instantly from the upstream to the downstream node in 1D channels.
* The transport equation is not calculated for the 1D elements. This can cause an underestimation of travel time for non-Newtonian fluids, particularly in long 1D elements.

These limitations mean that while the AD module can be used in models with 1D elements, it does not fully capture the complexities of non-Newtonian fluid behaviour in those elements. If higher accuracy is required, 2D elements where non-Newtonian properties are more comprehensively represented may be considered.

== Can the Advection Dispersion functionality be used in a model to simulate salinity? ==
Yes, the Advection Dispersion functionality can be used with models to simulate salinity transport, as long as the system is relatively well mixed vertically.

TUFLOW HPC is a 2D shallow water equation solver, so it does not account for vertical salinity gradients. This means it is best suited for rivers, shallow lakes, and estuaries where haloclines are weak or absent. Different boundary inflows can be assigned varying time series of salinity concentrations, and the module will simulate how these mix over space and time.

If the system has strong density stratification or distinctly three dimensional flow behaviour, a fully 3D solver such as TUFLOW FV is recommended.

== Can the Advection Dispersion functionality simulate pollutant runoff and transport from catchments? ==
Yes, the Advection Dispersion functionality can also be used to simulate pollutant runoff from catchments. This includes modelling the generation, transport, and fate of pollutants such as suspended sediment, nitrogen, and phosphorus.

Pollutants can be generated based on modelled bed shear stress, then transported through the domain using the flow field. The model can also apply decay and settling rates as part of the simulation.

The TUFLOW CATCH module, with which the Advection-Dispersion functionality is included, provides the capability to simulate pollutant runoff and transport from catchments. See the [https://www.tuflow.com/products/tuflow-catch-module/ TUFLOW Website] for further information.

 {{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

Tutorial M02

2026-04-10T05:20:53Z

Emilie Nielsen: /* Impact Assessment */

= Introduction =
In the first part of this module, breaklines are added to ensure that the key hydraulic controls are correctly represented in the 5m cell size model. The second part involves simple and more complex development topographic modifications. 

The GIS layers are: 
:*TGC layers:
<ol><ol><li>2d_zsh: A layer used to modify Zpt elevations using points, lines and polygons.</li>
<li>2d_mat: A layer used to define the land use (material) types within the developmental area.</li></ol></ol>
'''Module 2 builds from the model created in [[Tutorial_M01 | Module 1]]. The completed Module 1 model is provided in the Module_02\TUFLOW folder.''' 
 

=Part 1 - Breaklines=
The first part of this module introduces breaklines for road crests.

There are a few ways to model breaklines based on the models cell size. The Shape_Width attribute controls the width of the breakline: 
:*Thin Breakline: Shape_Width equal to 0 - only elevations on the cell sides and cell corners are modified, no change in storage.
:*Thick Breakline: Shape_Width less than or equal to 1.5 times the cell size - entire cells are modified, storage changes with changing elevation of the cell centres.
:*Wide Breakline: Shape_Width greater the 1.5 times the cell size - any elevation points within a distance of half the Shape_Width attribute are modified, storage changes.

== GIS Inputs ==
Create, import and view input data: 
:*[[Tutorial_M02_001_GIS_Inputs_QGIS | QGIS - SHP]]
:*[[Tutorial_M02_001_GIS_Inputs_QGIS_GPKG | QGIS - GPKG]]

== Simulation Control Files ==
=== TUFLOW Geometry Control File (TGC) ===
<ol>
<li>Save a copy of '''M01_001.tgc''' as '''M02_001.tgc''' in the '''Module_02\TUFLOW\model''' folder. 
<li>Open the '''M02_001.tgc''' in a text editor and add the following line after the '<tt>Read GRID Zpts</tt> <tt> == </tt> <tt>grid\DEM.tif</tt>' command. Note, the points and lines are in separate layers, but are part of the same breakline, therefore they are input on the same line with a vertical bar '|' to tell TUFLOW the layers are linked. The TUFLOW modelling convention is to list the lines first and then points. 
'''QGIS - SHP''' 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>gis\2d_zsh_M02_rd_crest_001_L.shp | gis\2d_zsh_M02_rd_crest_001_P.shp </tt> <tt> ! Defines the road crest</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>2d_zsh_M02_rd_crest_001_L | 2d_zsh_M02_rd_crest_001_P </tt> <tt> ! Defines the road crest</tt> 
<li>Save the TGC.
</ol>

=== TUFLOW Control File (TCF) ===
<ol>
<li>Save a copy of '''M01_5m_001.tcf''' as '''M02_5m_001.tcf''' in the '''Module_02\TUFLOW\runs''' folder.
<li>Open the file '''M02_5m_001.tcf''' in a text editor and make the following reference updates: 
'''QGIS - SHP''' 
<tt>Geometry Control File </tt> <tt>== </tt> <tt>..\model\M02_001.tgc </tt> <tt> ! Reference the TUFLOW Geometry Control File</tt> 
'''QGIS - GPKG''' 
<tt>Spatial Database </tt> <tt>== </tt> <tt>..\model\gis\M02_001.gpkg </tt> <tt> ! Specify the location of the GeoPackage Spatial Database</tt> 
<tt>Geometry Control File </tt> <tt>== </tt> <tt>..\model\M02_001.tgc </tt> <tt> ! Reference the TUFLOW Geometry Control File</tt> 
<li>Save the TCF.
</ol>

== Running the Simulation ==
Run the model using a batch file. Batch files include a wide array of TUFLOW options and functions, such as running multiple simulations in series or parallel, testing model initialisation and even copying models for transfer between modellers or organisations. For more information, see [[Run_TUFLOW_From_a_Batch-file | Run TUFLOW From a Batch file]]. 
<ol>
<li>Save a copy of '''_run_M01_HPC.bat''' as'''_run_M02_HPC.bat''' in the '''Module_02\TUFLOW\runs''' folder.
<li>Open the '''_run_M02_HPC.bat''' in a text editor and update the text: 
<tt>'''set'''</tt> <tt>exe</tt><tt>=</tt><tt>"..\..\..\exe\2026.0.0\TUFLOW_iSP_w64.exe"</tt> 
<tt>'''set'''</tt> <tt>run</tt><tt>=</tt><tt>start "TUFLOW" /wait</tt> <tt> %exe%</tt> <tt> -b</tt> 
<tt>%run% </tt> <tt>M02_5m_001.tcf </tt> 
:*The '<tt>'''set'''</tt> <tt>exe</tt>' command specifies the link to the TUFLOW executable. This file path may need to be changed depending on the folder set up. 
:*The '<tt>'''set'''</tt> <tt>run</tt>' command contains a series of commands:
::*<tt>start</tt>: Opens each simulation in a separate console window.
::*<tt>"TUFLOW"</tt>: Sets 'TUFLOW' as the title of the console window.
::*<tt>/wait</tt>: If multiple simulations are to be run, it is often desirable to run these in series, i.e. the second simulation starts after the first finishes. The /wait switch makes the batch file wait until the process is finished before moving onto the next command.
::*<tt>%exe%</tt>: executes tasks specified in the variable called ‘exe’, in this case the TUFLOW executable.
::*<tt>-b</tt>: The use of the –b (batch mode) switch suppresses the need to press the return key at the end of a simulation. This ensures that one simulation proceeds on to the next without any need for user input. This is required for running multiple simulations in series (one after the other).
:*The '<tt>%run%</tt>' executes tasks specified in the variable called ‘run’.
<li>Save the batch file and double click it in file explorer to run the simulation.
</ol>

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

== Check Files ==
While the model is running, check that the added features are specified correctly:
:*[[Tutorial_M02_001_Check_Files_QGIS | QGIS - SHP]]
:*[[Tutorial_M02_001_Check_Files_QGIS_GPKG | QGIS - GPKG]]

== Results ==
For viewing of the 2D map results, see [[Tutorial_M01#Results | Module 1]]. 

Suggestions for an investigation: 
:*Does the flooding still overtop the roads? 
<ol>Tip: check the maximum 2D results. </ol>
:*What is the difference in peak water level at the upstream of the roads compared to the Module 1 run? 
<ol>Tip: Use the ‘Plot Time Series from Map Output’ tool in the TUFLOW Viewer QGIS Plugin. </ol> 

=Part 2 - Other Topographic Updates=
The second part of this module introduces a range of options to make both simple and complex topography modifications. It also introduces an additional materials file to reflect the changes of land use based on the complex topography modifications. 
There are a few ways to create polygon topographic modifications based on the Shape_Option attribute:
:*Merge - merges the elevations at polygon perimeter vertices with the topography Zpt values.
:*No merge - assigns a single elevation to all Zpts falling within the polygon.
:*Add - raises or lowers the polygon by a fixed value.
:*TIN functionality - uses combination of points, lines and polygons to create complex topographic modifications.

== GIS Inputs ==
Create, import and view input data:
:*[[Tutorial_M02_002_GIS_Inputs_QGIS | QGIS - SHP]]
:*[[Tutorial_M02_002_GIS_Inputs_QGIS_GPKG | QGIS - GPKG]]

== Simulation Control Files ==
=== TUFLOW Geometry Control File (TGC) ===
<ol>
<li>Save a copy of the '''M02_001.tgc''' as '''M02_002.tgc''' in the '''Module_02\TUFLOW\model''' folder.
<li>Open the '''M02_002.tgc''' in a text editor and add the following lines after the road crest input. 
'''QGIS - SHP''' 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>gis\2d_zsh_M02_fill_002_R.shp </tt> <tt> ! Defines areas of imported fill</tt> 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>gis\2d_zsh_M02_merge_002_R.shp </tt> <tt> ! Defines areas of merging topography</tt> 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>gis\2d_zsh_M02_cut_002_R.shp </tt> <tt> ! Defines excavation through embankment</tt> 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>gis\2d_zsh_M02_landscape_002_R.shp | gis\2d_zsh_M02_landscape_002_L.shp | gis\2d_zsh_M02_landscape_002_P.shp </tt> <tt> ! Defines areas of complex landscaping</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>2d_zsh_M02_fill_002_R </tt> <tt> ! Defines areas of imported fill</tt> 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>2d_zsh_M02_merge_002_R </tt> <tt> ! Defines areas of merging topography</tt> 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>2d_zsh_M02_cut_002_R </tt> <tt> ! Defines excavation through embankment</tt> 
<tt>Read GIS Z Shape </tt> <tt>== </tt> <tt>2d_zsh_M02_landscape_002_R | 2d_zsh_M02_landscape_002_L | 2d_zsh_M02_landscape_002_P </tt> <tt>
! Defines areas of complex landscaping</tt> 
As the points, lines and regions are in separate files, but are part of the same topographic modification, they are input on the same line with a vertical bar '|' to tell TUFLOW the layers are linked. The TUFLOW modelling convention is to list the polygons first, then lines and points last.
<li>Add in the following line after the '<tt>Read GIS Mat</tt>' command. 
'''QGIS - SHP''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>gis\2d_mat_M02_landscape_002_R.shp </tt> <tt> ! Sets the material values according to attributes in the GIS layer</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>2d_mat_M02_landscape_002_R </tt> <tt> ! Sets the material values according to attributes in the GIS layer</tt> 
Assigns the updated materials values due to the development. As the order of commands in the TGC is critical, ensure this command is written after the original <tt>Read GIS Mat</tt> command.
<li>Save the TGC.
</ol>

=== TUFLOW Control File (TCF) ===
<ol>
<li>Save a copy of '''M02_5m_001.tcf''' as '''M02_5m_002.tcf''' in the '''Module_02\TUFLOW\runs''' folder.
<li>Open the file '''M02_5m_002.tcf''' in a text editor and make the following reference updates: 
'''QGIS - SHP''' 
<tt>Geometry Control File </tt> <tt>== </tt> <tt>..\model\M02_002.tgc </tt> <tt> ! Reference the TUFLOW Geometry Control File</tt> 
'''QGIS - GPKG''' 
<tt>Spatial Database </tt> <tt>== </tt> <tt>..\model\gis\M02_002.gpkg </tt> <tt> ! Specify the location of the GeoPackage Spatial Database</tt> 
<tt>Geometry Control File </tt> <tt>== </tt> <tt>..\model\M02_002.tgc </tt> <tt> ! Reference the TUFLOW Geometry Control File</tt> 
<li>Save the TCF.
</ol>

== Running the Simulation ==
Update the batch file created in the first part of Module 2 to reference the '''M02_5m_002.tcf''' file. Save the batch file and double click it in file explorer to run the simulation. 

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

== Check Files ==
While the model is running, review the added features are specified correctly:
:*[[Tutorial_M02_002_Check_Files_QGIS | QGIS - SHP]]
:*[[Tutorial_M02_002_Check_Files_QGIS_GPKG | QGIS - GPKG]]

== Results ==
For viewing of the 2D map results, see [[Tutorial_M01#Results | Module 1]]. 
=== Impact Assessment ===
The [[ASC_to_ASC| asc_to_asc]] utility with difference flag is used to plot the flood level changes resulting from the topography updates. The utility is provided in the '''exe\asc_to_asc''' folder. It can also be downloaded from the [https://www.tuflow.com/downloads/ TUFLOW website] and saved into a folder with other utilities. 
<ol>
<li>Create a new batch file '''_M02_asc_to_asc_Level_Difference.bat''' in the '''Module_02\TUFLOW\results\grids''' folder and open it in a text editor.
<li>Input the following (Note: Utility location may differ): 
<tt>'''set''' </tt> <tt>asc_to_asc</tt><tt>=</tt><tt>"..\..\..\exe\asc_to_asc.2024-06-AF\asc_to_asc_w64.exe"</tt> 
<li>Use the -dif flag to call the difference function. The utility then expects two grid files, it subtracts the first grid from the second. Add the following syntax below the 'set asc_to_asc' command. 
<tt>%asc_to_asc% </tt> <tt>-b -dif M02_5m_002_h_Max.tif M02_5m_001_h_Max.tif </tt> 
<li>Optional is to use the -out flag to specify the name of the output grids. 
<tt>%asc_to_asc% </tt> <tt>-b -dif -out M02_Level_Difference M02_5m_002_h_Max.tif M02_5m_001_h_Max.tif </tt> 
<li>Save the batch file and double click it in file explorer to run the utility.
<li>The resulting difference grids appear in the same folder location, open these in a GIS software to see the effects of the topography changes on the flood levels.
*M02_Level_Difference.tif = difference in maximum flood level.
*M02_Level_Difference_wd.tif = change in flood extent, identifying cells that were once wet, now dry (-99) and once dry, now wet (99). 
 

[[File:M02_ImpactMap_c.png]] </ol>
 

= Conclusion =
:*Breaklines and different polygon topographic modifications were added to the model.
:*Check files were assessed to view the changes on the underlying topographic model.
:*Impact assessment was conducted using the asc_to_asc utility.
:*For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
 
{{Tips Navigation
|uplink=[[Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

File:M02 ImpactMap c.png

2026-04-10T05:20:17Z

Emilie Nielsen:

HPC Introduction

2026-04-10T02:05:29Z

Emilie Nielsen: /* Introduction */

=Introduction=
Since the 2017-09-AA version, TUFLOW offers HPC (Heavily Parallelised Compute) as an alternate 2D Shallow Water Equation (SWE) solver to TUFLOW Classic.

TUFLOW HPC is now industry standard. While TUFLOW Classic is still supported, it is recommended to use TUFLOW HPC.

TUFLOW Classic is limited to running a simulation on a single CPU core, whereas HPC provides parallelisation of the TUFLOW model allowing modellers to run a single TUFLOW model across multiple CPU cores or GPU graphics cards (which utilise thousands of smaller CUDA* cores). Simulations using GPU hardware has shown to provide significantly quicker model run times for TUFLOW users. 

In general, most of the functionality and features of TUFLOW Classic are available in HPC. Additionally, HPC offers several advanced features not supported in Classic, including:
* Quadtree and sub-grid sampling
* High resolution map output grids
* Groundwater infiltration and sub-surface flows
* Wu turbulence formulation
* TMR bridge inputs (2d_bg) and simulation methods

===Solution Scheme, Cell Discretisation and Parallelisation===
TUFLOW HPC is an explicit solver for the full 2D Shallow Water Equations (SWE), including a sub-grid scale eddy viscosity model. The scheme is both volume and momentum conserving, is 2nd order in space and 4th order in time, with adaptive or fixed timestepping. It is unconditionally stable. TUFLOW HPC's computational approach differs from TUFLOW Classic, which is a 2nd order (space) implicit finite difference solver. Both TUFLOW HPC and Classic solve the 2D SWE on the same uniform Cartesian grid configuration. Computationally each 2D cell includes 9 sub-grid points. 

[[File: HPC Cell Design.PNG |300px]] 

The ZC point:
* Defines the volume of active water (cell volume is based on a flat square cell that wets and dries at a height of ZC plus the Cell Wet/Dry Depth);
* Controls when a cell becomes wet and dry (note that cell sides can also wet and dry); and
* Determines the bed slope when testing for the upstream controlled flow regime.
The ZU and ZV points:
* Control how water is conveyed from one cell to another;
* Represent where the momentum equation terms are centred and where upstream controlled flow regimes are applied;
* Deactivate if the cell has dried (based on the ZC point) and cannot flow; and
* Wet and dry independently of the cell wetting or drying (see Cell Wet/Dry Depth). This allows for the modelling of “thin” obstructions such as fences and thin embankments relative to the cell size (e.g. a concrete levee).
ZH points:
* Play no role hydraulically. This point location is used for output processing;
* The only elevations written to the .2dm mesh file (by default, binary output is interpolated/extrapolated to the cell corners).

Within the above sub-grid framework, using TUFLOW HPC time derivatives of cell averaged water depth, u-velocity and v-velocity are computed on a cell-by-cell basis and the model evolved using an explicit ODE solver. Calculation of the cell based derivatives are highly independent of each other making it possible to run this solution scheme across multiple processors or GPU cards. Parallelisation is done by breaking up the model into vertical ribbons. Each ribbon of the model is run on a different processor (or GPU card) with boundary information shared between processors at each timestep. 

[[File: Mesh_Ribbon_Splitting.png |360px]] 

===Mass Conservation and Timestep===

The explicit finite volume solution scheme utilised in HPC is mass conserving by construction (0% mass error). This differs to TUFLOW Classic, which can continue to simulate a model with some volume error due to it being an implicit finite difference scheme. The stability of the explicit finite volume scheme used in TUFLOW HPC is linked to the timestep, flow velocities, water depth, and eddy viscosity. The maximum timestep that can be used while maintaining model stability changes as the model evolves. While it is possible to choose a fixed timestep ahead of time (similarly to TUFLOW Classic), shorter run times and guaranteed model stability from start to finish may be achieved through the use of adaptive timestepping where the solver continually modifies the timestep based on various stability criteria. This is explained in more detail in our [[HPC_Adaptive_Timestepping | Adaptive Timestepping]] page. 

===Compatible Graphic Cards (GPU) ===
TUFLOW HPC’s GPU hardware module is only compatible with NVIDIA architecture CUDA enabled GPU cards. AMD GPU cards are NOT compatible. A list of CUDA enabled GPUs can be found on the following website: http://developer.nvidia.com/cuda-gpus .
To check if your computer has an NVIDA GPU and if it is CUDA enabled:
* Right click on the Windows desktop;
* If you see “NVIDIA Control Panel” or “NVIDIA Display” in the pop up dialogue, the computer has an NVIDIA GPU;
* Click on “NVIDIA Control Panel” or “NVIDIA Display” in the pop up dialogue;
* The GPU model should be displayed in the graphics card information;
* Check to see if the graphics card is listed on the following website: http://developer.nvidia.com/cuda-gpus
On the NVIDA website each CUDA enabled graphics card has a “Compute Capability” listed. For cards with a compute capability of 1.2 or less, only the single precision version of the GPU Module can be utilised. However, benchmarking has indicated that the double precision version is NOT required and that the TUFLOW_iSP exe should be used for all TUFLOW HPC GPU simulations. Extensive GPU hardware benchmarking has been undertaken to assist users who are upgrading hardware for TUFLOW modelling. Over 50 different hardware options have been tested for their speed performance. The results are provided on the [[Hardware_Benchmarking | Hardware Benchmarking]] page.

===Benefits of HPC===
So what does this mean for modellers? 
By providing the ability to run models on Graphics Cards, we can achieve significantly shorter model run times, increasing our modelling capabilities to be able to run continuous hydraulic models, with higher cell resolution, across larger extents and more scenarios. Common TUFLOW HPC applications include:
* Monte Carlo design assessments
* Rainfall ensemble design assessments
* High resolution 1D underground / 2D above ground integrated urban drainage
* High resolution floodplain lumped hydrology / hydraulic modelling (either fully 2D or including nested 1D open channels and pipes)
* Whole of catchment direct rainfall
* Flood forecast modelling
* Long-term water resource management modelling

The unconditional stability and higher order accuracy of TUFLOW HPC also lends itself well to highly transient situations, such as dam break assessments, where other solvers would either become unstable, lose accuracy or experience impractical simulation slow-down due to the need to solve at an extremely small timestep. 
 
{{Tips Navigation
|uplink=[[ HPC_Modelling_Guidance | Back to HPC Modelling Guidance]]
}}

TUFLOW 2D Hydraulic Structures

2026-04-10T02:03:26Z

Emilie Nielsen: /* 2D BG Shape (2d_bg) */

= 2D Structure Modelling Theory =
The theory behind the modelling of energy losses and affluxes of hydraulic structures is presented in the following webinars by Bill Syme and Greg Collecutt (TUFLOW Developers).

*[https://www.tuflow.com/library/webinars/#structures Webinar Link: Modelling Energy Losses at Structures] 
*[https://www.tuflow.com/library/webinars/#nov2022_hydraulic_modelling_bridge Webinar Link: 1D, 2D & 3D Hydraulic Modelling of Bridges]
 

= 2D Bridge Modelling in TUFLOW - Overview =
The TUFLOW 2D solution explicitly predicts the majority of “macro” losses due to the expansion and contraction of water through a constriction, or around a bend, provided the resolution of the grid is sufficiently fine ([https://www.tuflow.com/Download/Publications/Flow%20Through%20an%20Abrupt%20Constriction%20-%202D%20Hydrodynamic%20Performance%20and%20Influence%20of%20Spatial%20Resolution,%20Barton,%202001.pdf Barton, 2001]; [https://www.tuflow.com/Download/Publications/Modelling%20of%20Bends%20and%20Hydraulic%20Structures%20in%20a%202D%20Scheme,%20Syme,%202001.pdf Syme, 2001]; [https://www.tuflow.com/Download/Technical_Memos/Modelling%20Bridge%20Piers%20in%202D%20using%20TUFLOW.pdf Ryan, 2013]). Where the 2D model is not of fine enough resolution to simulate the “micro” losses (e.g. from bridge piers, vena contracta, losses in the vertical (3rd) dimension), additional form loss coefficients and/or modifications to the cells widths and flow height need to be added.
==Contraction/Expansion Losses (“Macro” Losses)==
Loss of energy is caused by the flow contraction during the expansion of water after the vena-contracta inside a bridge section and the flow expansion downstream a bridge. As discussed above, this type of "macro" losses can be explicitly resolved by the TUFLOW 2D solver, provided that a proper turbulence model and mesh size are used. Below is an example of the 2D modelling of flow contraction/expansion at a pair of bridge abutments.
 
[[File:FC_Velocity_Example.PNG|600px]] 

==Pier Losses==
Piers are usually smaller than the 2D cell size in real-world flood models. Although flexible mesh solver or quadtree refinement can be applied to reduce the local cell size around the pier, it also comes with an expensive computational cost that could significantly increase the simulation time. More practically, the backwater effect of piers can be modelled as sub-grid form losses.

Pier form loss coefficients can be derived from information in publications such as [https://www.fhwa.dot.gov/engineering/hydraulics/library_arc.cfm?pub_number=1&id=5 ''Hydraulics of Bridge Waterways'' (Bradly, 1978)] or [https://austroads.com.au/publications/bridges/agbt08 ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018)]. Energy loss estimated from bridge piers or other obstructions, vertical or horizontal, that do not cause upstream controlled flow regimes like pressure flow, are dependent on the ratio of the obstruction's area perpendicular to the flow direction to the gross flow area of the bridge opening, the shape of the piers or obstruction, and the angularity of the piers/obstruction to the flow direction. For example, using Hydraulics of Bridge Waterways (Bradly, 1978) the approach is:
<ol>
<li>Calculate the ratio of the water area occupied by piers to the gross water area of the constriction (both based on the normal water surface) and the angularity of the piers. These inputs are used to calculate "J" in the FHA documentation.</li>
<li>Use the Figure 4.10 ''Incremental Backwater Coefficient for Piers'' data to calculate Kp. 
[[File:incremental_backwater_coefficient_2018_pier_losses.png]]
 
'''NOTE''': the pier form loss coefficients in Hydraulics of Bridge Waterways are derived based on the cross-sectional averaged velocity through the bridge opening in the absence of piers. It's not necessary to specify a blockage value if a pier form loss coefficient estimated from this method is used.
</li>
</ol>

==Bridge Deck and Rail (Super Structure)==
When a bridge deck become partially or completely submerged, the deck could generate extra afflux resulting in increased water levels and flood extents upstream of the structure. The flow around the deck is highly 3-dimentional and complexed due to the different deck designs/profiles and/or the occurrence of pressure flow. In 2D SWE solver, depth-varying form loss values are often needed to reproduce the afflux caused by such structure. Due to the complexity of the flow, guidelines on how to set the form loss coefficient for the bridge deck are rare. We have carried out a joint research with QLD TMR (Queensland Department of Transport and Main Roads) regarding how to choose a proper form loss value for the bridge deck [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)] . In the research, CFD modelling was conducted to investigate the characteristics of energy loss of a simple bridge with a flat bottomed deck and guardrails.
 
[[File:CFD_study.png|600px]]

Below are the key findings from the study:
*The results displayed a characteristic shape for head loss coefficient as a function of downstream water level over the deck thickness (TW/T).
*The head loss (afflux) peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out.
[[File:FormLoss_vs_TWT.png|600px]]
 

=== Bridge Design (hB/T) vs Form Loss Coefficient Table===
The peak loss coefficient value is a function of the ratio of the depth underneath the deck (hB) and the thickness of the deck (T). This table can be used to estimate the deck form loss coefficient based on the bridge design (hB/T).
<ol>
{| style="text-align: center;" class="wikitable" width="35%"
! style="background-color:#005581; font-weight:bold; color:white;" width=55%| Deck Height to Thickness Ratio
! style="background-color:#005581; font-weight:bold; color:white;" width=45%| Peak Form Loss Coefficient
|-
| Scenario A (hB/T) = 2 || 0.42
|-
| Scenario B (hB/T) = 4 || 0.28
|-
| Scenario C (hB/T) = 6 || 0.20
|}
</ol>

*The solid portion of the guard rails (blockage * rail depth) can be added to T in addition to the deck thickness to calculate hB/T.
*For bridge with more complicated designs (e.g. girders), higher form loss might be required due to the higher surface roughness of the bridge.
*If the hB/T ratio is less than 2 or greater than 6, use a peak form loss coefficient of 0.42 (minimum) or 0.20 (maximum), respectively.

'''NOTE''': This form loss value should not be confused with the value of 1.56 used in the pressure flow approached adopted in [[1D_Bridges | TUFLOW 1D "B" and "BB" bridge]]. TUFLOW 1D bridge pressure flow approach is based on the section 4.13.2 "All Girders in Contact with Flow (Case II)" of ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018). The original hydraulic experiment conducted by [https://hdl.handle.net/10217/39009 Liu et al (1957)] in a laboratory flume with a pair of bridge abutments and a deck. The flow conditions were similar to orifice flow due to the high blockage ratio caused by the abutments and the deck. When modelling bridges in 2D, the contraction/expansion losses caused by the abutments would be handled explicitly by the 2D solver, so a value 1.56 can lead to duplication of the contraction/expansion losses caused by the bridge abutments. 
 

=TUFLOW 2D Bridge Setup=
There are two methods available to model depth varying form loss of a bridge structure:
* [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 |2D Layered Flow Constriction (2d_lfcsh)]]
:The traditional method used to model depth-varying form loss through bridge components such as piers, decks, and rails.

*[[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 |2D BG Shape (2d_bg)]] (introduced in the 2023 release)
:A simplified approach developed to simplify the model input based on the findings from the joint TMR Study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

Both methods provide options for representing flow surcharging, the pressure flow of bridge decks and eventually submerged bridge flow at higher water levels. During the surcharging of bridge decks, higher energy losses can be specified to simulate the pressure flow.

Examples for how to configure both approaches are provided in the 2D structures section of the [[TUFLOW_Example_Models#2D_Structures |TUFLOW Wiki Example Models]] and [[Tutorial_M04 |Tutorial Module 4]] - 2D Bridges.

==2D Layered Flow Constriction (2d_lfcsh)==
Four flow constriction layers are represented in a 2d_lfcsh layer. The lower three layers represents the pier, the bridge deck and the rails. Each layer has its own attributes to specify the blockage and the form loss coefficient. The top (fourth) layer assumes the flow is unimpeded, representative of flow over the top of a bridge. Within the same shape, the invert of the bed, and thickness of each layer can vary in 3D.

The following table provides an overview for how to determine the blockage and form loss coefficient for each layer. Note that this is just an overview and additional guidelines may need to be considered. 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || Use calibration data, if available, to determine FLC. If no calibration is available, estimate using [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table || Full blockage, no flow through the deck
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 3 || Bridge rails || 10% – 100% || Use calibration data, if available, to determine FLC. 
If no calibration data is available, combined FLC for Layers 2 and 3 should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = L2_Depth + (pBlockage × L3_Depth)
*(pBlockage × L3_Depth) represents the solid portion of the rails
*L2 FLC and L3 FLC should sum to the combined FLC
|Blockage and FLC depends on rail type Sensitivity testing with 100% blockage is recommended due to potential for debris during flood
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}
<ol>
[[File:2d_lfcsh_attributes.png | 500px ]]
</ol>
 

===Blockage===

The 2d_lfcsh functions by adjusting the flow width and the form loss of 2D cell faces. The combined blockage across the 4 layers is calculated at each simulation timesteps:
<ol>
 
[[File: Blockage_total_equation_01.png|600px]]
 
where 
'''''yi''''' is the actual depth of water in layer '''''i''''' 
'''''ytotal''''' is the total water depth 
</ol>

===Form Loss Approach===

The combined form loss coefficient is determined using one of three methods. The form loss coefficient method can be specified either individually using the 2d_lfcsh “Shape_Options” attribute or globally using the .tcf command: 
<tt>Layered FLC Default Approach == [ METHOD A | {METHOD B} | METHOD C | METHOD D]</tt> 

:METHOD A: The losses are accumulated as the water level rises through the layers. 
<ol>
[[File:Eq_flc_cumulate.png |450px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Applies the full accumulated form loss continuously, even when overtopping begins (no reduction)
:Note: Simpler method but tends to overestimate losses when the structure is submerged or overtopped 

:METHOD B (default): the losses are applied pro-rata according to the depth of water in each layer. 
<ol>
[[File:Eq_flc_portion.png |430px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure
:Note: Maintains backward compatibility but may underrepresent losses during pressurised or overtopped flows 

:METHOD C (recommended): hybrid approach combining Method A and Method B. 
<ol>
[[File:Eq_flc_methodC.png |520px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Gradual increase in form loss with water level, following Method A
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure, following Method B
:Note: Recommended method; aligns closest to CFD modelling results and TUFLOW HPC behaviour.

:METHOD D: Allows the modeller to control the depth at which the losses start to reduce when the flow transitions between pressure flow and drowned flow.
:This approach is the same used by the 2d_bg layer (introduced in the 2023-03 release). It is recommended to use the 2d_bg layer as it has the benefit of a simplified attribute table, for easier user input.

===Form Loss Calibration Example - Iowa River Flood Study===

In this study, a combined form loss coefficient of 0.35 was used to match observed head loss during slight overtopping of a bridge. The FLC values for each layer were adjusted to achieve the correct combined form loss. The table and plot show how each layer contributes to the total form loss and highlight the differences in calculated form loss between the three methods.

{| style="text-align: left; margin-left: 0;" class="wikitable" width="60%"
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=6%| Layer
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=10%| Depth (m)
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=12%| Blockage (%)
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method A
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method B
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method C
|-
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
|-
| 1 || 5.0 || 5 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07
|-
| 2 || 1.5 || 100 || 0.15 || 0.22 || 1.05 || 0.30 || 0.15 || 0.22
|-
| 3 || 1.0 || 50 || 0.13 || 0.35 || 0.70 || 0.35 || 0.13 || 0.35
|}

</ol>
 
<ol>
[[File:FLC_vs_height_updated.png | 600px ]]
</ol>

==2D BG Shape (2d_bg)==
2D BG Shape is similar to the Layered Flow Constriction, but has several updates to simplify the input based on the findings from the joint study with TMR [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

The following table provides an overview of how to determine the blockage and form loss coefficient for each layer. Note that this is just an overview and additional guidelines may need to be considered. 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || rowspan="2" | The Super Structure (Super_S) is the bridge deck and rails layers combined. 
Use calibration data, if available, to determine FLC. 
If no calibration data is available, the Super_S FLC should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = Deck_Depth + (Rail_pBlockage*Rail_Depth)
*(Rail_pBlockage*Rail_Depth) represents the solid portion of the rails
|| Full blockage, no flow through the deck
|-
| 3 || Bridge rails || 10% – 100% || Sensitivity testing with 100% blockage is recommended due to potential for debris during flood events
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}

<ol>
[[File:Bridge block.jpg | 800px]]
</ol>

===Inflection Point===

Based on findings from the joint study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)], the head loss peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out. The 'SuperS_IPf' attribute (inflection point factor, default = 1.6) can be used to define the height of the inflection point. The solid portion of the rail layer is also added to the deck thickness to calculate the depth to the inflection point (DIP), i.e.:
<ol>
[[File:eq_flc_bg_infection_point.png | 520px ]]
</ol>

===Form Loss Approach===
The form loss approach is similar to the FLC approach METHOD C, with L2/L3 replaced by a single super structure layer:
<ol>
[[File:eq_flc_bg.png | 480px ]]
</ol>

===Form Loss Calibration Example - Iowa River Flood Study===
This example uses the same bridge setup described in the[[TUFLOW_2D_Hydraulic_Structures#Form_Loss_Calibration_Example_-_Iowa_River_Flood_Study | 2D Layered Flow Constriction]] section, with the following parameters applied:
*SuperS_FLC = 0.28
*SuperS_Ipf = 1.6,
The Depth to Inflection Point (DIP) is calculated as 3.2m above the bridge soffit.

The table and figure below show how the form loss value varies with water depth.
<ol>
{| style="text-align: center;" class="wikitable" width="32%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Depth (m)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Form Loss
|-
| Pier || 5.0 || 5 || 0.07
|-
| Deck || 1.5 || 100 || rowspan="2" | 0.28
|-
| Rail || 1.0 || 50
|}

[[File:FLC_vs_height_bg.png | 600px ]]
</ol>

== 2D Bridges Line vs Polygon Layer ==
The form loss coefficient (FLC) is applied differently when using a line compared to a polygon for both 2d_lfcsh and 2d_bg inputs. The FLC is applied at cell sides (u and v faces) as this is where velocities are calculated. 
For larger bridges that spread across multiple cells, it is recommended to use a polygon layer, which selects all u and v faces falling within the polygon.
 
 
'''2D Layered Flow Constriction (2d_lfcsh)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides
| This approach is cell size independent. It is the easiest setup and the preferred / recommended approach when using 2d_lfcsh.
|-
| Thick
| between zero and 1.5 times the cell size
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| A cell is selected if the polyline intersects the cell crosshair. Caution should be taken when using a "thick" line, as changes in cell size can cause it to become a "wide" line. If this occurs, the FLC attribute may need to be recalculated to avoid overestimating or underestimating losses.
|-
| Wide
| larger than 1.5 times the cell size
| Total form loss of the bridge ''(may need to be recalculated, see notes)''
| FLC divided by number of cell sides in the direction of flow 
''(number of cell sides in the direction of flow is calculated as line width divided by cell size)''
| Polygon shapes are recommended if more than 3 rows of faces must be selected.. 
Caution should be taken when using a "wide" line. The cell size and alignment of the 2d_lfcsh line may result in selecting too many or too few cell faces in the direction of the flow. The FLC input may need to be recalculated to ensure FLC Applied multiplied by the number of cell sides in the direction of flow equates to the intended total form loss.
|-
!rowspan="1" | Polygon
| -
| -
| Total loss per unit length (meters or feet) in the direction of flow
| FLC * cell size applied to all sides of selected cells
|
|}

'''2D Bridge (2d_bg)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides.
| This approach is cell size independent.
|-
| Thick
| larger than zero
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| This approach is cell size independent. A cell is selected if the polyline intersects the cell crosshair.
|-
| Wide
| Not supported
| –
| –
| BG polygon shapes are recommended if more than 3 rows of faces must be selected.
|-
!rowspan="1" |Polygon
| -
| ''(used to automatically distribute the total FLC to the selected faces)''
| Total form loss of the bridge
| FLC / Deck_Width * cell size applied to all sides of selected cells
| For bridges modelled using a 2d_bg polygon the relative ratio of the bridge width to the 2D cell size should be 4 or greater. For more information on this see [https://downloads.tuflow.com/Other/2d_bg_R_Bridge_Configuration_Advice_202503.pdf 2d_bg_R_Bridge_Configuration_Advice.pdf].
|}
 
The following diagrams demonstrate how the input FLC is applied for the four geometry options for 2d_lfcsh and 2d_bg layers: 
[[File:2dlfcsh 2dbg combined v2.png|1200px]]

It is good modelling practice to check the [[Check_Files_2d_lfcsh_uvpt | lfcsh_uvpt_check]] and [[Check Files 2d bg uvpt check | bg_uvpt_check]] files to confirm the number of faces selected and the FLC values assigned. It is also strongly recommended to undertake a sensitivity analysis on the applied form losses in the model to check if it makes any difference to the results and/or double check against other methods (hand calculations, other software, CFD modelling), especially if the bridge is near an area of interest. If calibration data is available, this should be used to guide the form loss value specification. 
 

= Common Questions Answered (FAQ)=
== What blockage values should I use for bridge guard rails? ==
The blockage of bridge guard rails can be anything from 100% blocked (solid concrete rails) to 10% blocked (very open rails). In addition, the accumulation of debris during a flood can be substantial as shown in the image below. Sensitivity testing with 100% blockage is recommended.
 
[[File:Bridge rail debris.jpg | 500px]]

== How to conduct sensitivity test for 2D bridges? ==
General recommendations to cross-check the results are:
* Compare computed affluxes against desktop methods (e.g. Hydraulics of Bridge Waterways, 1978) and/or other software including CFD, especially for unusual bridge designs.
* Use any recorded flood marks or general observations from past events to check and calibrate FLC values.
* Conduct sensitivity testing by assessing the impact and influence of FLC values on your modelling objectives. The afflux resulting from the FLC values will be proportional to the velocity head, i.e. ∆h=FLC*(v^2/2g). As such, if velocities are low (e.g. 1 m/s), the results may not be overly sensitive to uncertainties in the FLC values. If completing a check using this equation for a long skew bridge it is best to calculate the total structure velocity from a PO line digitised in the same location as the bridge.

Finally, after completing sensitivity testing and understanding the range of uncertainty due to unknowns like the degree of blockage and influence of FLC values (e.g. +/-20%), you are in a position to discuss with your client how best to proceed. For example, if the modelling is to set planning levels for a development upstream then it may be appropriate to choose values on the higher side (higher FLC values and/or blockage assumptions), noting that the uncertainty may be amply covered by a regulatory freeboard. Conversely, if the development is on the downstream side the conservative approach would be to use the results at the lower end of your FLC/blockage values. 
[[File:Bridge Flood Debris Loading.jpg | 500px]] 

== Should I use both FLC and blockage for layer one in 2D bridge layered flow constriction? ==
When applying FLC and blockage values to model obstructions such as piers, the following considerations need to be taken into account:
* The FLC value applies an energy loss along 1D channels or across 2D cell faces equivalent to FLC*V2/2g where V is the 1D channel velocity or the 2D cell face velocity.
* FLC values are often sourced from publications such as Hydraulics of Bridge Waterways or AustRoads (e.g. Kp chart for piers).
* If possible, establish whether the source of the FLC value is based on the approach velocity (the velocity in the absence of piers) or structure velocity (the velocity with area blocked out by the piers) noting that it often isn’t clear or stated.
** If it is the structure velocity, this is usually the velocity at the vena-contracta (point of greatest contraction within the entrance to the structure and therefore highest velocity) - see image below. Bluff or sharp-edged obstructions will have a much more pronounced vena-contracta, and therefore higher velocity compared with a round-edged obstruction.
** FLC values based on the approach velocity will be higher than those based on the structure velocity to achieve the same energy loss.
* Applying a blockage equivalent to the obstruction width will increase, usually very slightly, the velocity of the 1D channel or 2D cell face. This won’t be the vena-contracta velocity, but a velocity between the approach velocity and the vena-contracta velocity. A greater blockage will need to be applied to emulate the vena-contracta velocity.
* If the FLC source value is based on:
** The approach velocity then there is no need to apply a blockage value.
** The structure velocity then the blockage value should be applied noting that it may be appropriate to apply a larger blockage to take into account the vena-contracta.
* If it is not clear or unknown whether the FLC source value is based on the approach or structure velocity, the recommendation would be to apply the blockage in the interests of being slightly conservative on the upstream flood level calculation.
* For most minor obstructions such as bridge piers, the blockage is usually relatively small and whether included or not has a negligible or minor affect on flood levels compared with other factors such as the approach embankments and the bridge deck.
* Blockage from debris wrapped around piers can have a greater influence on the results than the effect of applying or not applying a blockage. Debris wrapped around piers can be accounted for in the FLC value calculated for the pier layer.
* As always, sensitivity testing with and without blockage and +/- the FLC value is highly recommended to understand their importance in regard to the broader modelling objectives and the effects of uncertainties in the input data, boundaries, other parameters such as Manning’s n values, and the accuracy of the numerical solution scheme (see [https://www.tuflow.com/library/webinars/#maximise_accuracy Maximising the Accuracy of Hydraulic Models webinar]).
[[File: Vena_contracta.png]] 
''Image showing the formation of the vena-contracta.'' 
 

==I don't see results that I expect when using 2d_lfcsh layer==
The 2d_lfcsh layer is a versatile feature that was designed to model bridges in 2D, but can also be used for other applications like fences, buildings raised on pillars and so on.
Some of the unexpected results could be:
* Water level going through the bridge deck in 2D map output.
* Water transiting through 100% blocked Layer 1, e.g. fences with solid base.
* SHMax.csv reporting values above the bridge deck when 2D map output reports water level lower than the top of the bridge deck.

TUFLOW is a 2D solution (not 3D), in the 2d_lfcsh layer the percent blockage and form loss coefficient applied to the cell faces is depth averaged across the entire cell face (across Layer 1, 2 and 3): 
*For bridges, where Layer 2 has a 100% blockage applied, the minimum flow width of 0.001m is used and is averaged with the Layer 1 blockage (based on the depth of the water). This may result in a water level being reported within or above the bridge deck, which would represent the pressure head.
*Layered flow constriction works by adjusting the flow area of the cell faces by any blockages to generate the correct depth averaged velocity at each face at which the form losses are applied as a fraction of the V2/2g kinetic energy. Calculating the correct velocity is critical for determining the losses as the losses are proportional to the velocity squared. 
*For a layered flow constriction cell face the flow area cannot be zero above the invert of Layer 1 to avoid a divide by zero in the computations, therefore a minimum average flow width after applying blockages of 0.001 m is applied. if Layer 1 is 100% blocked, a very small amount of water will flow through Layer 1. If this is unacceptable, instead of applying 100% blockage of Layer 1, the preferred approach is to start the layered flow constriction at the top of Layer 1 or raise the ground elevation to the top of Layer 1 using one of the Z Shape modification functions (e.g. a breakline). 
<ol>
[[File:100% Blockage Diagram.png | 500px]]
</ol>

== Can I model bridge piers explicitly in 2D using very small cells? ==
It isn't recommended to explicitly model bridge piers by blocking out the pier faces in TUFLOW, or in any hydraulic modelling software based on solving Shallow Water Equations(SWE). Due to the 3-dimentiality of the flow and turbulence around a pier, computational fluid dynamics (CFD) approach is often required to simulate the flow around piers explicitly. The wake turbulence behind a simple-shape pier can be resolved to some extent using extremely fine mesh in TUFLOW (see calibration example to a flume experiment in the [https://www.tuflow.com/library/webinars/#structures webinar on Energy Losses at Structures]), however the predictions for head losses show notable sensitivities to the mesh size, the mesh design, and the choice of turbulence model. The extremely fine mesh resolution also results in significantly higher computational costs.

Therefore, the safest and strongly recommended approach with regard to establishing head losses and consequently flood levels, is to model the effects of such obstructions with form loss coefficients (applied to selected mesh cells) that have been derived from physical testing. This approach has been shown to provide the most consistent results across various mesh resolutions. It also has the added benefit that, by avoiding small cells in the mesh, it will provide much more efficient run times for flow solvers.

[[File:Flow round a cylinder.png]]

''The point of flow separation around an object has a major bearing on the drag coefficient and is not reliably reproduced by 2D or 3D software.''


== How to best convert flow constriction data (2d_fc or 2d_fcsh) into newer formats (2d_lfcsh or 2d_bg)? ==
The form loss parameters can be transferred from the flow constriction (2d_fc or 2d_fcsh) to the first layer of the layered flow constriction (2d_lfcsh) or pier layer of the 2d_bg. Definition of the remaining form loss and blockage layer inputs should follow the guidance outlined in [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 | 2D Layered Flow Constriction]] and [[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 | 2D BG Shape]] paragraphs. 
When using floating pontoon (type FD in the 2d_fc or 2d_fcsh) different setup might need to be used for different events. For large events when floating pontoon becomes fixed at the top of the supporting piles, standard 2d_lfcsh setup can be used. Smaller events when the pontoon is floating at different heights might require more sensitivity testing of the structure parameters to find out a setup the matches the reality as close as possible. 

== Should I model bridges in 1D or 2D Domain? ==
The recommended approach typically depends on the study objectives and if the channel upstream and downstream of the bridge is modelled in 1D or 2D. To preserve the momentum as accurately as possible the bridge should be modelled in the same dimension as the channel, e.g. 1d_nwk bridge if the channels is in 1D and 2d_bg or 2d_lfcsh if the channel is modelled in 2D. 
In 2D, the expansion/contraction losses are modelled based on the topography and don't need to be estimated as attributes as for 1D modelling. Also, for higher flows where the bridge is overtopped, 2D is preferable approach.

== What is the difference between downstream and upstream controlled flow? ==
Downstream control means a change in downstream water level will cause a change in upstream water level. Upstream control means the upstream water level is insensitive to the downstream water level and usually indicates the occurrence of supercritical flow.

== What FLC values should be used for 2d_bg bridge if hB/T is below 2 or above 6? ==
TMR has extended the CFD simulation to hB/T ratios of 1 to 10. Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for details.

If hB/T is outside this ratio:
* hB/T ratios of less than 1 represent a very unusual bridge sitting low to the ground, and the peak FLC may increase above the end value (FLC of 0.6) in a way that doesn't follow the research trend or extrapolation. For these cases we would recommend using CFD modelling to obtain a more informed value. Alternatively, computing an FLC based on pressure flow or using 1D culvert might be considered.
* For hB/T ratios of greater than 10, the FLC is likely to continue to decrease, but probably not significantly. Clamping to the end value (FLC of 0.16) might be considered the more conservative approach (if the primary concern is flood levels upstream of the bridge). 
 
{{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

TUFLOW 2D Hydraulic Structures

2026-04-10T02:03:08Z

Emilie Nielsen: /* 2D Layered Flow Constriction (2d_lfcsh) */

= 2D Structure Modelling Theory =
The theory behind the modelling of energy losses and affluxes of hydraulic structures is presented in the following webinars by Bill Syme and Greg Collecutt (TUFLOW Developers).

*[https://www.tuflow.com/library/webinars/#structures Webinar Link: Modelling Energy Losses at Structures] 
*[https://www.tuflow.com/library/webinars/#nov2022_hydraulic_modelling_bridge Webinar Link: 1D, 2D & 3D Hydraulic Modelling of Bridges]
 

= 2D Bridge Modelling in TUFLOW - Overview =
The TUFLOW 2D solution explicitly predicts the majority of “macro” losses due to the expansion and contraction of water through a constriction, or around a bend, provided the resolution of the grid is sufficiently fine ([https://www.tuflow.com/Download/Publications/Flow%20Through%20an%20Abrupt%20Constriction%20-%202D%20Hydrodynamic%20Performance%20and%20Influence%20of%20Spatial%20Resolution,%20Barton,%202001.pdf Barton, 2001]; [https://www.tuflow.com/Download/Publications/Modelling%20of%20Bends%20and%20Hydraulic%20Structures%20in%20a%202D%20Scheme,%20Syme,%202001.pdf Syme, 2001]; [https://www.tuflow.com/Download/Technical_Memos/Modelling%20Bridge%20Piers%20in%202D%20using%20TUFLOW.pdf Ryan, 2013]). Where the 2D model is not of fine enough resolution to simulate the “micro” losses (e.g. from bridge piers, vena contracta, losses in the vertical (3rd) dimension), additional form loss coefficients and/or modifications to the cells widths and flow height need to be added.
==Contraction/Expansion Losses (“Macro” Losses)==
Loss of energy is caused by the flow contraction during the expansion of water after the vena-contracta inside a bridge section and the flow expansion downstream a bridge. As discussed above, this type of "macro" losses can be explicitly resolved by the TUFLOW 2D solver, provided that a proper turbulence model and mesh size are used. Below is an example of the 2D modelling of flow contraction/expansion at a pair of bridge abutments.
 
[[File:FC_Velocity_Example.PNG|600px]] 

==Pier Losses==
Piers are usually smaller than the 2D cell size in real-world flood models. Although flexible mesh solver or quadtree refinement can be applied to reduce the local cell size around the pier, it also comes with an expensive computational cost that could significantly increase the simulation time. More practically, the backwater effect of piers can be modelled as sub-grid form losses.

Pier form loss coefficients can be derived from information in publications such as [https://www.fhwa.dot.gov/engineering/hydraulics/library_arc.cfm?pub_number=1&id=5 ''Hydraulics of Bridge Waterways'' (Bradly, 1978)] or [https://austroads.com.au/publications/bridges/agbt08 ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018)]. Energy loss estimated from bridge piers or other obstructions, vertical or horizontal, that do not cause upstream controlled flow regimes like pressure flow, are dependent on the ratio of the obstruction's area perpendicular to the flow direction to the gross flow area of the bridge opening, the shape of the piers or obstruction, and the angularity of the piers/obstruction to the flow direction. For example, using Hydraulics of Bridge Waterways (Bradly, 1978) the approach is:
<ol>
<li>Calculate the ratio of the water area occupied by piers to the gross water area of the constriction (both based on the normal water surface) and the angularity of the piers. These inputs are used to calculate "J" in the FHA documentation.</li>
<li>Use the Figure 4.10 ''Incremental Backwater Coefficient for Piers'' data to calculate Kp. 
[[File:incremental_backwater_coefficient_2018_pier_losses.png]]
 
'''NOTE''': the pier form loss coefficients in Hydraulics of Bridge Waterways are derived based on the cross-sectional averaged velocity through the bridge opening in the absence of piers. It's not necessary to specify a blockage value if a pier form loss coefficient estimated from this method is used.
</li>
</ol>

==Bridge Deck and Rail (Super Structure)==
When a bridge deck become partially or completely submerged, the deck could generate extra afflux resulting in increased water levels and flood extents upstream of the structure. The flow around the deck is highly 3-dimentional and complexed due to the different deck designs/profiles and/or the occurrence of pressure flow. In 2D SWE solver, depth-varying form loss values are often needed to reproduce the afflux caused by such structure. Due to the complexity of the flow, guidelines on how to set the form loss coefficient for the bridge deck are rare. We have carried out a joint research with QLD TMR (Queensland Department of Transport and Main Roads) regarding how to choose a proper form loss value for the bridge deck [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)] . In the research, CFD modelling was conducted to investigate the characteristics of energy loss of a simple bridge with a flat bottomed deck and guardrails.
 
[[File:CFD_study.png|600px]]

Below are the key findings from the study:
*The results displayed a characteristic shape for head loss coefficient as a function of downstream water level over the deck thickness (TW/T).
*The head loss (afflux) peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out.
[[File:FormLoss_vs_TWT.png|600px]]
 

=== Bridge Design (hB/T) vs Form Loss Coefficient Table===
The peak loss coefficient value is a function of the ratio of the depth underneath the deck (hB) and the thickness of the deck (T). This table can be used to estimate the deck form loss coefficient based on the bridge design (hB/T).
<ol>
{| style="text-align: center;" class="wikitable" width="35%"
! style="background-color:#005581; font-weight:bold; color:white;" width=55%| Deck Height to Thickness Ratio
! style="background-color:#005581; font-weight:bold; color:white;" width=45%| Peak Form Loss Coefficient
|-
| Scenario A (hB/T) = 2 || 0.42
|-
| Scenario B (hB/T) = 4 || 0.28
|-
| Scenario C (hB/T) = 6 || 0.20
|}
</ol>

*The solid portion of the guard rails (blockage * rail depth) can be added to T in addition to the deck thickness to calculate hB/T.
*For bridge with more complicated designs (e.g. girders), higher form loss might be required due to the higher surface roughness of the bridge.
*If the hB/T ratio is less than 2 or greater than 6, use a peak form loss coefficient of 0.42 (minimum) or 0.20 (maximum), respectively.

'''NOTE''': This form loss value should not be confused with the value of 1.56 used in the pressure flow approached adopted in [[1D_Bridges | TUFLOW 1D "B" and "BB" bridge]]. TUFLOW 1D bridge pressure flow approach is based on the section 4.13.2 "All Girders in Contact with Flow (Case II)" of ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018). The original hydraulic experiment conducted by [https://hdl.handle.net/10217/39009 Liu et al (1957)] in a laboratory flume with a pair of bridge abutments and a deck. The flow conditions were similar to orifice flow due to the high blockage ratio caused by the abutments and the deck. When modelling bridges in 2D, the contraction/expansion losses caused by the abutments would be handled explicitly by the 2D solver, so a value 1.56 can lead to duplication of the contraction/expansion losses caused by the bridge abutments. 
 

=TUFLOW 2D Bridge Setup=
There are two methods available to model depth varying form loss of a bridge structure:
* [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 |2D Layered Flow Constriction (2d_lfcsh)]]
:The traditional method used to model depth-varying form loss through bridge components such as piers, decks, and rails.

*[[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 |2D BG Shape (2d_bg)]] (introduced in the 2023 release)
:A simplified approach developed to simplify the model input based on the findings from the joint TMR Study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

Both methods provide options for representing flow surcharging, the pressure flow of bridge decks and eventually submerged bridge flow at higher water levels. During the surcharging of bridge decks, higher energy losses can be specified to simulate the pressure flow.

Examples for how to configure both approaches are provided in the 2D structures section of the [[TUFLOW_Example_Models#2D_Structures |TUFLOW Wiki Example Models]] and [[Tutorial_M04 |Tutorial Module 4]] - 2D Bridges.

==2D Layered Flow Constriction (2d_lfcsh)==
Four flow constriction layers are represented in a 2d_lfcsh layer. The lower three layers represents the pier, the bridge deck and the rails. Each layer has its own attributes to specify the blockage and the form loss coefficient. The top (fourth) layer assumes the flow is unimpeded, representative of flow over the top of a bridge. Within the same shape, the invert of the bed, and thickness of each layer can vary in 3D.

The following table provides an overview for how to determine the blockage and form loss coefficient for each layer. Note that this is just an overview and additional guidelines may need to be considered. 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || Use calibration data, if available, to determine FLC. If no calibration is available, estimate using [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table || Full blockage, no flow through the deck
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 3 || Bridge rails || 10% – 100% || Use calibration data, if available, to determine FLC. 
If no calibration data is available, combined FLC for Layers 2 and 3 should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = L2_Depth + (pBlockage × L3_Depth)
*(pBlockage × L3_Depth) represents the solid portion of the rails
*L2 FLC and L3 FLC should sum to the combined FLC
|Blockage and FLC depends on rail type Sensitivity testing with 100% blockage is recommended due to potential for debris during flood
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}
<ol>
[[File:2d_lfcsh_attributes.png | 500px ]]
</ol>
 

===Blockage===

The 2d_lfcsh functions by adjusting the flow width and the form loss of 2D cell faces. The combined blockage across the 4 layers is calculated at each simulation timesteps:
<ol>
 
[[File: Blockage_total_equation_01.png|600px]]
 
where 
'''''yi''''' is the actual depth of water in layer '''''i''''' 
'''''ytotal''''' is the total water depth 
</ol>

===Form Loss Approach===

The combined form loss coefficient is determined using one of three methods. The form loss coefficient method can be specified either individually using the 2d_lfcsh “Shape_Options” attribute or globally using the .tcf command: 
<tt>Layered FLC Default Approach == [ METHOD A | {METHOD B} | METHOD C | METHOD D]</tt> 

:METHOD A: The losses are accumulated as the water level rises through the layers. 
<ol>
[[File:Eq_flc_cumulate.png |450px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Applies the full accumulated form loss continuously, even when overtopping begins (no reduction)
:Note: Simpler method but tends to overestimate losses when the structure is submerged or overtopped 

:METHOD B (default): the losses are applied pro-rata according to the depth of water in each layer. 
<ol>
[[File:Eq_flc_portion.png |430px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure
:Note: Maintains backward compatibility but may underrepresent losses during pressurised or overtopped flows 

:METHOD C (recommended): hybrid approach combining Method A and Method B. 
<ol>
[[File:Eq_flc_methodC.png |520px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Gradual increase in form loss with water level, following Method A
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure, following Method B
:Note: Recommended method; aligns closest to CFD modelling results and TUFLOW HPC behaviour.

:METHOD D: Allows the modeller to control the depth at which the losses start to reduce when the flow transitions between pressure flow and drowned flow.
:This approach is the same used by the 2d_bg layer (introduced in the 2023-03 release). It is recommended to use the 2d_bg layer as it has the benefit of a simplified attribute table, for easier user input.

===Form Loss Calibration Example - Iowa River Flood Study===

In this study, a combined form loss coefficient of 0.35 was used to match observed head loss during slight overtopping of a bridge. The FLC values for each layer were adjusted to achieve the correct combined form loss. The table and plot show how each layer contributes to the total form loss and highlight the differences in calculated form loss between the three methods.

{| style="text-align: left; margin-left: 0;" class="wikitable" width="60%"
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=6%| Layer
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=10%| Depth (m)
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=12%| Blockage (%)
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method A
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method B
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method C
|-
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
|-
| 1 || 5.0 || 5 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07
|-
| 2 || 1.5 || 100 || 0.15 || 0.22 || 1.05 || 0.30 || 0.15 || 0.22
|-
| 3 || 1.0 || 50 || 0.13 || 0.35 || 0.70 || 0.35 || 0.13 || 0.35
|}

</ol>
 
<ol>
[[File:FLC_vs_height_updated.png | 600px ]]
</ol>

==2D BG Shape (2d_bg)==
2D BG Shape is similar to the Layered Flow Constriction, but has several updates to simplify the input based on the findings from the joint study with TMR [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

The following table provides an overview of how to determine the blockage and form loss coefficient for each layer: 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || rowspan="2" | The Super Structure (Super_S) is the bridge deck and rails layers combined. 
Use calibration data, if available, to determine FLC. 
If no calibration data is available, the Super_S FLC should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = Deck_Depth + (Rail_pBlockage*Rail_Depth)
*(Rail_pBlockage*Rail_Depth) represents the solid portion of the rails
|| Full blockage, no flow through the deck
|-
| 3 || Bridge rails || 10% – 100% || Sensitivity testing with 100% blockage is recommended due to potential for debris during flood events
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}

<ol>
[[File:Bridge block.jpg | 800px]]
</ol>

===Inflection Point===

Based on findings from the joint study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)], the head loss peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out. The 'SuperS_IPf' attribute (inflection point factor, default = 1.6) can be used to define the height of the inflection point. The solid portion of the rail layer is also added to the deck thickness to calculate the depth to the inflection point (DIP), i.e.:
<ol>
[[File:eq_flc_bg_infection_point.png | 520px ]]
</ol>

===Form Loss Approach===
The form loss approach is similar to the FLC approach METHOD C, with L2/L3 replaced by a single super structure layer:
<ol>
[[File:eq_flc_bg.png | 480px ]]
</ol>

===Form Loss Calibration Example - Iowa River Flood Study===
This example uses the same bridge setup described in the[[TUFLOW_2D_Hydraulic_Structures#Form_Loss_Calibration_Example_-_Iowa_River_Flood_Study | 2D Layered Flow Constriction]] section, with the following parameters applied:
*SuperS_FLC = 0.28
*SuperS_Ipf = 1.6,
The Depth to Inflection Point (DIP) is calculated as 3.2m above the bridge soffit.

The table and figure below show how the form loss value varies with water depth.
<ol>
{| style="text-align: center;" class="wikitable" width="32%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Depth (m)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Form Loss
|-
| Pier || 5.0 || 5 || 0.07
|-
| Deck || 1.5 || 100 || rowspan="2" | 0.28
|-
| Rail || 1.0 || 50
|}

[[File:FLC_vs_height_bg.png | 600px ]]
</ol>

== 2D Bridges Line vs Polygon Layer ==
The form loss coefficient (FLC) is applied differently when using a line compared to a polygon for both 2d_lfcsh and 2d_bg inputs. The FLC is applied at cell sides (u and v faces) as this is where velocities are calculated. 
For larger bridges that spread across multiple cells, it is recommended to use a polygon layer, which selects all u and v faces falling within the polygon.
 
 
'''2D Layered Flow Constriction (2d_lfcsh)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides
| This approach is cell size independent. It is the easiest setup and the preferred / recommended approach when using 2d_lfcsh.
|-
| Thick
| between zero and 1.5 times the cell size
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| A cell is selected if the polyline intersects the cell crosshair. Caution should be taken when using a "thick" line, as changes in cell size can cause it to become a "wide" line. If this occurs, the FLC attribute may need to be recalculated to avoid overestimating or underestimating losses.
|-
| Wide
| larger than 1.5 times the cell size
| Total form loss of the bridge ''(may need to be recalculated, see notes)''
| FLC divided by number of cell sides in the direction of flow 
''(number of cell sides in the direction of flow is calculated as line width divided by cell size)''
| Polygon shapes are recommended if more than 3 rows of faces must be selected.. 
Caution should be taken when using a "wide" line. The cell size and alignment of the 2d_lfcsh line may result in selecting too many or too few cell faces in the direction of the flow. The FLC input may need to be recalculated to ensure FLC Applied multiplied by the number of cell sides in the direction of flow equates to the intended total form loss.
|-
!rowspan="1" | Polygon
| -
| -
| Total loss per unit length (meters or feet) in the direction of flow
| FLC * cell size applied to all sides of selected cells
|
|}

'''2D Bridge (2d_bg)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides.
| This approach is cell size independent.
|-
| Thick
| larger than zero
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| This approach is cell size independent. A cell is selected if the polyline intersects the cell crosshair.
|-
| Wide
| Not supported
| –
| –
| BG polygon shapes are recommended if more than 3 rows of faces must be selected.
|-
!rowspan="1" |Polygon
| -
| ''(used to automatically distribute the total FLC to the selected faces)''
| Total form loss of the bridge
| FLC / Deck_Width * cell size applied to all sides of selected cells
| For bridges modelled using a 2d_bg polygon the relative ratio of the bridge width to the 2D cell size should be 4 or greater. For more information on this see [https://downloads.tuflow.com/Other/2d_bg_R_Bridge_Configuration_Advice_202503.pdf 2d_bg_R_Bridge_Configuration_Advice.pdf].
|}
 
The following diagrams demonstrate how the input FLC is applied for the four geometry options for 2d_lfcsh and 2d_bg layers: 
[[File:2dlfcsh 2dbg combined v2.png|1200px]]

It is good modelling practice to check the [[Check_Files_2d_lfcsh_uvpt | lfcsh_uvpt_check]] and [[Check Files 2d bg uvpt check | bg_uvpt_check]] files to confirm the number of faces selected and the FLC values assigned. It is also strongly recommended to undertake a sensitivity analysis on the applied form losses in the model to check if it makes any difference to the results and/or double check against other methods (hand calculations, other software, CFD modelling), especially if the bridge is near an area of interest. If calibration data is available, this should be used to guide the form loss value specification. 
 

= Common Questions Answered (FAQ)=
== What blockage values should I use for bridge guard rails? ==
The blockage of bridge guard rails can be anything from 100% blocked (solid concrete rails) to 10% blocked (very open rails). In addition, the accumulation of debris during a flood can be substantial as shown in the image below. Sensitivity testing with 100% blockage is recommended.
 
[[File:Bridge rail debris.jpg | 500px]]

== How to conduct sensitivity test for 2D bridges? ==
General recommendations to cross-check the results are:
* Compare computed affluxes against desktop methods (e.g. Hydraulics of Bridge Waterways, 1978) and/or other software including CFD, especially for unusual bridge designs.
* Use any recorded flood marks or general observations from past events to check and calibrate FLC values.
* Conduct sensitivity testing by assessing the impact and influence of FLC values on your modelling objectives. The afflux resulting from the FLC values will be proportional to the velocity head, i.e. ∆h=FLC*(v^2/2g). As such, if velocities are low (e.g. 1 m/s), the results may not be overly sensitive to uncertainties in the FLC values. If completing a check using this equation for a long skew bridge it is best to calculate the total structure velocity from a PO line digitised in the same location as the bridge.

Finally, after completing sensitivity testing and understanding the range of uncertainty due to unknowns like the degree of blockage and influence of FLC values (e.g. +/-20%), you are in a position to discuss with your client how best to proceed. For example, if the modelling is to set planning levels for a development upstream then it may be appropriate to choose values on the higher side (higher FLC values and/or blockage assumptions), noting that the uncertainty may be amply covered by a regulatory freeboard. Conversely, if the development is on the downstream side the conservative approach would be to use the results at the lower end of your FLC/blockage values. 
[[File:Bridge Flood Debris Loading.jpg | 500px]] 

== Should I use both FLC and blockage for layer one in 2D bridge layered flow constriction? ==
When applying FLC and blockage values to model obstructions such as piers, the following considerations need to be taken into account:
* The FLC value applies an energy loss along 1D channels or across 2D cell faces equivalent to FLC*V2/2g where V is the 1D channel velocity or the 2D cell face velocity.
* FLC values are often sourced from publications such as Hydraulics of Bridge Waterways or AustRoads (e.g. Kp chart for piers).
* If possible, establish whether the source of the FLC value is based on the approach velocity (the velocity in the absence of piers) or structure velocity (the velocity with area blocked out by the piers) noting that it often isn’t clear or stated.
** If it is the structure velocity, this is usually the velocity at the vena-contracta (point of greatest contraction within the entrance to the structure and therefore highest velocity) - see image below. Bluff or sharp-edged obstructions will have a much more pronounced vena-contracta, and therefore higher velocity compared with a round-edged obstruction.
** FLC values based on the approach velocity will be higher than those based on the structure velocity to achieve the same energy loss.
* Applying a blockage equivalent to the obstruction width will increase, usually very slightly, the velocity of the 1D channel or 2D cell face. This won’t be the vena-contracta velocity, but a velocity between the approach velocity and the vena-contracta velocity. A greater blockage will need to be applied to emulate the vena-contracta velocity.
* If the FLC source value is based on:
** The approach velocity then there is no need to apply a blockage value.
** The structure velocity then the blockage value should be applied noting that it may be appropriate to apply a larger blockage to take into account the vena-contracta.
* If it is not clear or unknown whether the FLC source value is based on the approach or structure velocity, the recommendation would be to apply the blockage in the interests of being slightly conservative on the upstream flood level calculation.
* For most minor obstructions such as bridge piers, the blockage is usually relatively small and whether included or not has a negligible or minor affect on flood levels compared with other factors such as the approach embankments and the bridge deck.
* Blockage from debris wrapped around piers can have a greater influence on the results than the effect of applying or not applying a blockage. Debris wrapped around piers can be accounted for in the FLC value calculated for the pier layer.
* As always, sensitivity testing with and without blockage and +/- the FLC value is highly recommended to understand their importance in regard to the broader modelling objectives and the effects of uncertainties in the input data, boundaries, other parameters such as Manning’s n values, and the accuracy of the numerical solution scheme (see [https://www.tuflow.com/library/webinars/#maximise_accuracy Maximising the Accuracy of Hydraulic Models webinar]).
[[File: Vena_contracta.png]] 
''Image showing the formation of the vena-contracta.'' 
 

==I don't see results that I expect when using 2d_lfcsh layer==
The 2d_lfcsh layer is a versatile feature that was designed to model bridges in 2D, but can also be used for other applications like fences, buildings raised on pillars and so on.
Some of the unexpected results could be:
* Water level going through the bridge deck in 2D map output.
* Water transiting through 100% blocked Layer 1, e.g. fences with solid base.
* SHMax.csv reporting values above the bridge deck when 2D map output reports water level lower than the top of the bridge deck.

TUFLOW is a 2D solution (not 3D), in the 2d_lfcsh layer the percent blockage and form loss coefficient applied to the cell faces is depth averaged across the entire cell face (across Layer 1, 2 and 3): 
*For bridges, where Layer 2 has a 100% blockage applied, the minimum flow width of 0.001m is used and is averaged with the Layer 1 blockage (based on the depth of the water). This may result in a water level being reported within or above the bridge deck, which would represent the pressure head.
*Layered flow constriction works by adjusting the flow area of the cell faces by any blockages to generate the correct depth averaged velocity at each face at which the form losses are applied as a fraction of the V2/2g kinetic energy. Calculating the correct velocity is critical for determining the losses as the losses are proportional to the velocity squared. 
*For a layered flow constriction cell face the flow area cannot be zero above the invert of Layer 1 to avoid a divide by zero in the computations, therefore a minimum average flow width after applying blockages of 0.001 m is applied. if Layer 1 is 100% blocked, a very small amount of water will flow through Layer 1. If this is unacceptable, instead of applying 100% blockage of Layer 1, the preferred approach is to start the layered flow constriction at the top of Layer 1 or raise the ground elevation to the top of Layer 1 using one of the Z Shape modification functions (e.g. a breakline). 
<ol>
[[File:100% Blockage Diagram.png | 500px]]
</ol>

== Can I model bridge piers explicitly in 2D using very small cells? ==
It isn't recommended to explicitly model bridge piers by blocking out the pier faces in TUFLOW, or in any hydraulic modelling software based on solving Shallow Water Equations(SWE). Due to the 3-dimentiality of the flow and turbulence around a pier, computational fluid dynamics (CFD) approach is often required to simulate the flow around piers explicitly. The wake turbulence behind a simple-shape pier can be resolved to some extent using extremely fine mesh in TUFLOW (see calibration example to a flume experiment in the [https://www.tuflow.com/library/webinars/#structures webinar on Energy Losses at Structures]), however the predictions for head losses show notable sensitivities to the mesh size, the mesh design, and the choice of turbulence model. The extremely fine mesh resolution also results in significantly higher computational costs.

Therefore, the safest and strongly recommended approach with regard to establishing head losses and consequently flood levels, is to model the effects of such obstructions with form loss coefficients (applied to selected mesh cells) that have been derived from physical testing. This approach has been shown to provide the most consistent results across various mesh resolutions. It also has the added benefit that, by avoiding small cells in the mesh, it will provide much more efficient run times for flow solvers.

[[File:Flow round a cylinder.png]]

''The point of flow separation around an object has a major bearing on the drag coefficient and is not reliably reproduced by 2D or 3D software.''


== How to best convert flow constriction data (2d_fc or 2d_fcsh) into newer formats (2d_lfcsh or 2d_bg)? ==
The form loss parameters can be transferred from the flow constriction (2d_fc or 2d_fcsh) to the first layer of the layered flow constriction (2d_lfcsh) or pier layer of the 2d_bg. Definition of the remaining form loss and blockage layer inputs should follow the guidance outlined in [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 | 2D Layered Flow Constriction]] and [[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 | 2D BG Shape]] paragraphs. 
When using floating pontoon (type FD in the 2d_fc or 2d_fcsh) different setup might need to be used for different events. For large events when floating pontoon becomes fixed at the top of the supporting piles, standard 2d_lfcsh setup can be used. Smaller events when the pontoon is floating at different heights might require more sensitivity testing of the structure parameters to find out a setup the matches the reality as close as possible. 

== Should I model bridges in 1D or 2D Domain? ==
The recommended approach typically depends on the study objectives and if the channel upstream and downstream of the bridge is modelled in 1D or 2D. To preserve the momentum as accurately as possible the bridge should be modelled in the same dimension as the channel, e.g. 1d_nwk bridge if the channels is in 1D and 2d_bg or 2d_lfcsh if the channel is modelled in 2D. 
In 2D, the expansion/contraction losses are modelled based on the topography and don't need to be estimated as attributes as for 1D modelling. Also, for higher flows where the bridge is overtopped, 2D is preferable approach.

== What is the difference between downstream and upstream controlled flow? ==
Downstream control means a change in downstream water level will cause a change in upstream water level. Upstream control means the upstream water level is insensitive to the downstream water level and usually indicates the occurrence of supercritical flow.

== What FLC values should be used for 2d_bg bridge if hB/T is below 2 or above 6? ==
TMR has extended the CFD simulation to hB/T ratios of 1 to 10. Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for details.

If hB/T is outside this ratio:
* hB/T ratios of less than 1 represent a very unusual bridge sitting low to the ground, and the peak FLC may increase above the end value (FLC of 0.6) in a way that doesn't follow the research trend or extrapolation. For these cases we would recommend using CFD modelling to obtain a more informed value. Alternatively, computing an FLC based on pressure flow or using 1D culvert might be considered.
* For hB/T ratios of greater than 10, the FLC is likely to continue to decrease, but probably not significantly. Clamping to the end value (FLC of 0.16) might be considered the more conservative approach (if the primary concern is flood levels upstream of the bridge). 
 
{{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

TUFLOW Version Backward Compatibility

2026-04-09T23:57:18Z

Emilie Nielsen: /* Backward Compatibility Change Register */

=Backward Compatibility Change Register=

For a list of new features and changes for each TUFLOW release, refer to the [https://docs.tuflow.com/classic-hpc/changelog/ TUFLOW Classic/HPC Changelog] (for versions since 2023-03-AF). For versions 2023-03-AF and prior, see the relevant release notes in the [https://www.tuflow.com/downloads/tuflow-classichpc-archive/ TUFLOW Downloads Archive].

For backward compatibility and default changes, please see Chapter 18 (Default Changes) of the [https://docs.tuflow.com/classic-hpc/manual/latest TUFLOW Manual].

=Frequently Asked Questions (FAQ)=
== Why are model results developed in an older release different to a newer release? ==
If comparing a Classic model with HPC, also check the [[HPC_FAQ#Will_TUFLOW_HPC_and_TUFLOW_Classic_results_match.3F | Will TUFLOW HPC and TUFLOW Classic results match?]] page in addition to this answer. 
In addition to the above, there are reasons why model results would be different between different TUFLOW releases, whether it is the Classic or HPC solver, as follows:
* General improvements and fine-tuning of the solution scheme, especially for the more complex hydraulic physical terms and situations such as: sub-grid turbulence representation; treatment of shocks (e.g. hydraulic jumps); and transitioning between sub-critical and super-critical flow on steep slopes.
* Some new functionality can cause a significant change in results. For example:
** Sub-Grid Sampling (SGS) applied to an existing model that used a too coarse cell resolution in high flow areas of highly variable topography (relative to the 2D cell size). SGS will greatly improve the model's ability to convey water accurately in these situations with vastly improved results.
** New default sub-grid turbulence scheme in the 2020 release of TUFLOW HPC that is cell size independent and allows modellers to use cell sizes much smaller than the flow depth across all scales from flume to large rivers. For more information on differences between Smagorinsky scheme (HPC releases up to 2020) and the Wu turbulence scheme (2020 onwards) see [[HPC_FAQ#With_Wu_turbulence_scheme_being_the_new_default.2C_are_old_models_using_Smagorinsky_wrong.3F | here]].
* Changes to the default settings and values, e.g.:
**different default eddy viscosity formulation and/or coefficients,
**improved data pre-processing approaches such as sampling materials on cell mid-sides instead of cell centres,
** and many others.
** For backward compatibility the <tt>Defaults</tt> <tt>== </tt> command is available to run old models on new releases to replicate past results (note, sometimes full backward compatibility cannot be catered for due to different code compiler and updates that can't be reverted, especially for several releases earlier).
* New features that use GIS attributes previously reserved (i.e. unused). If these attributes were not populated with the recommended “reserved” value (usually 0 or blank), then they can cause unpredictable results in later releases.
* Bug fixes noting that most bug fixes are input/output related and rarely affect the model's hydraulic calculations.
* Change in timestepping can also produce a small change in results. HPC uses the Runge-Kutta 4th order integrator, which is usually fairly insensitive to time step provided the model is running stably. However when a region is filled by flow that only just overtops an embankment, a 10 mm difference in water levels upstream of the embankment can create a much larger difference in levels downstream. Hence, small differences in time-stepping (along with many other aspects of model setup) can trigger local differences in model results.
* Model orientation (if changed) could also mean slight change in results. This is mostly given by interpolating values from different calculation points. Every cell has nine calculation points. Based on the model origin, all or most of the calculation points would have different topography elevation sampled, which translates to slightly different results.
* If using 1D channel, possibly different cells have been selected as HX boundary and might have different elevations. This can be reviewed in [[Check_Files_1d_to_2d_bc | 1d_to_2d check file]].

Generally, there should not be substantial differences as the fundamental equations being solved are unchanged and TUFLOW Classic and HPC solvers have always solved all the physical terms using a 2nd order spatial approach. The one exception is the turbulence (eddy viscosity) representation, which is the most complex and challenging to solve of all the physical terms (many 2D schemes simply omit this term). If significant differences (>10% of depth change across the whole model) are observed then it’s most likely due to the first four dot points above. To identify in which release(s) the significant changes occurred, the model can be run with the latest build and for past releases. The changes for each release are documented in their release notes. Past releases and release notes are all available [https://www.tuflow.com/downloads/tuflow-classichpc-archive/. here]. Once the exact release where the changes occurred is tracked down, individual features can be turned off to narrow down the cause. 

The recommendation is usually for new or reworked models to use the newest build to take advantage of the latest features and enhancements, some level of calibration might be required for reworked models. The new TUFLOW executable is not different from the previous ones in the meaning that any existing model should be re-calibrated if there are available calibration data. However, particularly if a model is already calibrated, using prior builds of TUFLOW or winding back default settings using <tt>Defaults</tt> <tt>== </tt> command is considered reasonable for established models that are to be used for minor tasks where an update of the model would not be cost effective. 

== How can differences in model results between TUFLOW builds be investigated? ==
Running TUFLOW on a later build from which it was originally calibrated will not necessarily produce the same results, as discussed in [[TUFLOW_Version_Backward_Compatibility#Why_are_model_results_developed_in_an_older_release_different_to_a_newer_release.3F | Why are model results developed in an older release different to a newer release?]].

The following is an example of steps that can be taken when upgrading a TUFLOW model’s executable build, checking for consistency to original results each time.
<ol>
<li> Confirm you are able to run the original model with the original build that would have been used to initially produce results.
* This may be particularly relevant when a model has been externally supplied, for example from a government body.
* Confirm if reproduced results are consistent with supplied results.
<li> Run the original model with the newer build, along with a relevant <tt>Defaults</tt> <tt>== </tt> command (e.g. <tt>Defaults</tt> <tt>== </tt> Pre 2011 when the original build was 2010-10).
* Any differences in results compared to the original results may highlight if there are any changes over time where no backward compatibility had been provided for.
<li> Run the original model with the newer build, and without the <tt>Defaults</tt> <tt>== </tt> command.
* This is more likely to see changes in results compared to the original results, which may require justification to the client or resolution by investigating, isolating and remedying the causes, especially if recalibration is not intended as a subsequent step.
<li> Iteratively run the original model with the newer build, stepping through the different release version options for <tt>Defaults</tt> <tt>== </tt> command.
* This will allow the modeller to investigate and isolate what changes to TUFLOW builds may be affecting results, and when changes appear.
* Then, individually reverting settings that make up a Default group (see Chapter 18 of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]).
* This can help isolate the primary drivers for any differences in results.
* The [https://docs.tuflow.com/classic-hpc/changelog// TUFLOW Classic/HPC Changelog] accompanying build releases are also a key reference.
<li> Develop new improved or updated model version, with the newer build (and any grouped or individual defaults that are deemed necessary to retain from the iterative testing in the prior step).
*Continue to verify results against the original results as you then iteratively add in or update to any newer functionality or formats that may be available in the later build, a good quality assurance check that changes are behaving as expected.
</ol>
 
{{Tips Navigation
|uplink=[[TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

TUFLOW Version Backward Compatibility

2026-04-09T23:57:09Z

Emilie Nielsen: /* Backward Compatibility Change Register */

=Backward Compatibility Change Register=

For a list of new features and changes for each TUFLOW release, refer to the [https://docs.tuflow.com/classic-hpc/changelog/ TUFLOW Classic/HPC Changelog] (for versions since 2023-03-AF). For versions 2023-03-AF and prior, see the relevant release notes in the [https://www.tuflow.com/downloads/tuflow-classichpc-archive/ TUFLOW Downloads Archive].

For backward compatibility and default changes, please see Chapter 18 (Default Changes) of the [https://docs.tuflow.com/classic-hpc/manual/latest TUFLOW Manual] 

=Frequently Asked Questions (FAQ)=
== Why are model results developed in an older release different to a newer release? ==
If comparing a Classic model with HPC, also check the [[HPC_FAQ#Will_TUFLOW_HPC_and_TUFLOW_Classic_results_match.3F | Will TUFLOW HPC and TUFLOW Classic results match?]] page in addition to this answer. 
In addition to the above, there are reasons why model results would be different between different TUFLOW releases, whether it is the Classic or HPC solver, as follows:
* General improvements and fine-tuning of the solution scheme, especially for the more complex hydraulic physical terms and situations such as: sub-grid turbulence representation; treatment of shocks (e.g. hydraulic jumps); and transitioning between sub-critical and super-critical flow on steep slopes.
* Some new functionality can cause a significant change in results. For example:
** Sub-Grid Sampling (SGS) applied to an existing model that used a too coarse cell resolution in high flow areas of highly variable topography (relative to the 2D cell size). SGS will greatly improve the model's ability to convey water accurately in these situations with vastly improved results.
** New default sub-grid turbulence scheme in the 2020 release of TUFLOW HPC that is cell size independent and allows modellers to use cell sizes much smaller than the flow depth across all scales from flume to large rivers. For more information on differences between Smagorinsky scheme (HPC releases up to 2020) and the Wu turbulence scheme (2020 onwards) see [[HPC_FAQ#With_Wu_turbulence_scheme_being_the_new_default.2C_are_old_models_using_Smagorinsky_wrong.3F | here]].
* Changes to the default settings and values, e.g.:
**different default eddy viscosity formulation and/or coefficients,
**improved data pre-processing approaches such as sampling materials on cell mid-sides instead of cell centres,
** and many others.
** For backward compatibility the <tt>Defaults</tt> <tt>== </tt> command is available to run old models on new releases to replicate past results (note, sometimes full backward compatibility cannot be catered for due to different code compiler and updates that can't be reverted, especially for several releases earlier).
* New features that use GIS attributes previously reserved (i.e. unused). If these attributes were not populated with the recommended “reserved” value (usually 0 or blank), then they can cause unpredictable results in later releases.
* Bug fixes noting that most bug fixes are input/output related and rarely affect the model's hydraulic calculations.
* Change in timestepping can also produce a small change in results. HPC uses the Runge-Kutta 4th order integrator, which is usually fairly insensitive to time step provided the model is running stably. However when a region is filled by flow that only just overtops an embankment, a 10 mm difference in water levels upstream of the embankment can create a much larger difference in levels downstream. Hence, small differences in time-stepping (along with many other aspects of model setup) can trigger local differences in model results.
* Model orientation (if changed) could also mean slight change in results. This is mostly given by interpolating values from different calculation points. Every cell has nine calculation points. Based on the model origin, all or most of the calculation points would have different topography elevation sampled, which translates to slightly different results.
* If using 1D channel, possibly different cells have been selected as HX boundary and might have different elevations. This can be reviewed in [[Check_Files_1d_to_2d_bc | 1d_to_2d check file]].

Generally, there should not be substantial differences as the fundamental equations being solved are unchanged and TUFLOW Classic and HPC solvers have always solved all the physical terms using a 2nd order spatial approach. The one exception is the turbulence (eddy viscosity) representation, which is the most complex and challenging to solve of all the physical terms (many 2D schemes simply omit this term). If significant differences (>10% of depth change across the whole model) are observed then it’s most likely due to the first four dot points above. To identify in which release(s) the significant changes occurred, the model can be run with the latest build and for past releases. The changes for each release are documented in their release notes. Past releases and release notes are all available [https://www.tuflow.com/downloads/tuflow-classichpc-archive/. here]. Once the exact release where the changes occurred is tracked down, individual features can be turned off to narrow down the cause. 

The recommendation is usually for new or reworked models to use the newest build to take advantage of the latest features and enhancements, some level of calibration might be required for reworked models. The new TUFLOW executable is not different from the previous ones in the meaning that any existing model should be re-calibrated if there are available calibration data. However, particularly if a model is already calibrated, using prior builds of TUFLOW or winding back default settings using <tt>Defaults</tt> <tt>== </tt> command is considered reasonable for established models that are to be used for minor tasks where an update of the model would not be cost effective. 

== How can differences in model results between TUFLOW builds be investigated? ==
Running TUFLOW on a later build from which it was originally calibrated will not necessarily produce the same results, as discussed in [[TUFLOW_Version_Backward_Compatibility#Why_are_model_results_developed_in_an_older_release_different_to_a_newer_release.3F | Why are model results developed in an older release different to a newer release?]].

The following is an example of steps that can be taken when upgrading a TUFLOW model’s executable build, checking for consistency to original results each time.
<ol>
<li> Confirm you are able to run the original model with the original build that would have been used to initially produce results.
* This may be particularly relevant when a model has been externally supplied, for example from a government body.
* Confirm if reproduced results are consistent with supplied results.
<li> Run the original model with the newer build, along with a relevant <tt>Defaults</tt> <tt>== </tt> command (e.g. <tt>Defaults</tt> <tt>== </tt> Pre 2011 when the original build was 2010-10).
* Any differences in results compared to the original results may highlight if there are any changes over time where no backward compatibility had been provided for.
<li> Run the original model with the newer build, and without the <tt>Defaults</tt> <tt>== </tt> command.
* This is more likely to see changes in results compared to the original results, which may require justification to the client or resolution by investigating, isolating and remedying the causes, especially if recalibration is not intended as a subsequent step.
<li> Iteratively run the original model with the newer build, stepping through the different release version options for <tt>Defaults</tt> <tt>== </tt> command.
* This will allow the modeller to investigate and isolate what changes to TUFLOW builds may be affecting results, and when changes appear.
* Then, individually reverting settings that make up a Default group (see Chapter 18 of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]).
* This can help isolate the primary drivers for any differences in results.
* The [https://docs.tuflow.com/classic-hpc/changelog// TUFLOW Classic/HPC Changelog] accompanying build releases are also a key reference.
<li> Develop new improved or updated model version, with the newer build (and any grouped or individual defaults that are deemed necessary to retain from the iterative testing in the prior step).
*Continue to verify results against the original results as you then iteratively add in or update to any newer functionality or formats that may be available in the later build, a good quality assurance check that changes are behaving as expected.
</ol>
 
{{Tips Navigation
|uplink=[[TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

TUFLOW Version Backward Compatibility

2026-04-09T23:52:17Z

Emilie Nielsen: /* Backward Compatibility Change Register */

=Backward Compatibility Change Register=

For backward compatibility and release notes, please see Chapter 18 (Default Changes) of the [https://docs.tuflow.com/classic-hpc/manual/latest TUFLOW Manual] 

=Frequently Asked Questions (FAQ)=
== Why are model results developed in an older release different to a newer release? ==
If comparing a Classic model with HPC, also check the [[HPC_FAQ#Will_TUFLOW_HPC_and_TUFLOW_Classic_results_match.3F | Will TUFLOW HPC and TUFLOW Classic results match?]] page in addition to this answer. 
In addition to the above, there are reasons why model results would be different between different TUFLOW releases, whether it is the Classic or HPC solver, as follows:
* General improvements and fine-tuning of the solution scheme, especially for the more complex hydraulic physical terms and situations such as: sub-grid turbulence representation; treatment of shocks (e.g. hydraulic jumps); and transitioning between sub-critical and super-critical flow on steep slopes.
* Some new functionality can cause a significant change in results. For example:
** Sub-Grid Sampling (SGS) applied to an existing model that used a too coarse cell resolution in high flow areas of highly variable topography (relative to the 2D cell size). SGS will greatly improve the model's ability to convey water accurately in these situations with vastly improved results.
** New default sub-grid turbulence scheme in the 2020 release of TUFLOW HPC that is cell size independent and allows modellers to use cell sizes much smaller than the flow depth across all scales from flume to large rivers. For more information on differences between Smagorinsky scheme (HPC releases up to 2020) and the Wu turbulence scheme (2020 onwards) see [[HPC_FAQ#With_Wu_turbulence_scheme_being_the_new_default.2C_are_old_models_using_Smagorinsky_wrong.3F | here]].
* Changes to the default settings and values, e.g.:
**different default eddy viscosity formulation and/or coefficients,
**improved data pre-processing approaches such as sampling materials on cell mid-sides instead of cell centres,
** and many others.
** For backward compatibility the <tt>Defaults</tt> <tt>== </tt> command is available to run old models on new releases to replicate past results (note, sometimes full backward compatibility cannot be catered for due to different code compiler and updates that can't be reverted, especially for several releases earlier).
* New features that use GIS attributes previously reserved (i.e. unused). If these attributes were not populated with the recommended “reserved” value (usually 0 or blank), then they can cause unpredictable results in later releases.
* Bug fixes noting that most bug fixes are input/output related and rarely affect the model's hydraulic calculations.
* Change in timestepping can also produce a small change in results. HPC uses the Runge-Kutta 4th order integrator, which is usually fairly insensitive to time step provided the model is running stably. However when a region is filled by flow that only just overtops an embankment, a 10 mm difference in water levels upstream of the embankment can create a much larger difference in levels downstream. Hence, small differences in time-stepping (along with many other aspects of model setup) can trigger local differences in model results.
* Model orientation (if changed) could also mean slight change in results. This is mostly given by interpolating values from different calculation points. Every cell has nine calculation points. Based on the model origin, all or most of the calculation points would have different topography elevation sampled, which translates to slightly different results.
* If using 1D channel, possibly different cells have been selected as HX boundary and might have different elevations. This can be reviewed in [[Check_Files_1d_to_2d_bc | 1d_to_2d check file]].

Generally, there should not be substantial differences as the fundamental equations being solved are unchanged and TUFLOW Classic and HPC solvers have always solved all the physical terms using a 2nd order spatial approach. The one exception is the turbulence (eddy viscosity) representation, which is the most complex and challenging to solve of all the physical terms (many 2D schemes simply omit this term). If significant differences (>10% of depth change across the whole model) are observed then it’s most likely due to the first four dot points above. To identify in which release(s) the significant changes occurred, the model can be run with the latest build and for past releases. The changes for each release are documented in their release notes. Past releases and release notes are all available [https://www.tuflow.com/downloads/tuflow-classichpc-archive/. here]. Once the exact release where the changes occurred is tracked down, individual features can be turned off to narrow down the cause. 

The recommendation is usually for new or reworked models to use the newest build to take advantage of the latest features and enhancements, some level of calibration might be required for reworked models. The new TUFLOW executable is not different from the previous ones in the meaning that any existing model should be re-calibrated if there are available calibration data. However, particularly if a model is already calibrated, using prior builds of TUFLOW or winding back default settings using <tt>Defaults</tt> <tt>== </tt> command is considered reasonable for established models that are to be used for minor tasks where an update of the model would not be cost effective. 

== How can differences in model results between TUFLOW builds be investigated? ==
Running TUFLOW on a later build from which it was originally calibrated will not necessarily produce the same results, as discussed in [[TUFLOW_Version_Backward_Compatibility#Why_are_model_results_developed_in_an_older_release_different_to_a_newer_release.3F | Why are model results developed in an older release different to a newer release?]].

The following is an example of steps that can be taken when upgrading a TUFLOW model’s executable build, checking for consistency to original results each time.
<ol>
<li> Confirm you are able to run the original model with the original build that would have been used to initially produce results.
* This may be particularly relevant when a model has been externally supplied, for example from a government body.
* Confirm if reproduced results are consistent with supplied results.
<li> Run the original model with the newer build, along with a relevant <tt>Defaults</tt> <tt>== </tt> command (e.g. <tt>Defaults</tt> <tt>== </tt> Pre 2011 when the original build was 2010-10).
* Any differences in results compared to the original results may highlight if there are any changes over time where no backward compatibility had been provided for.
<li> Run the original model with the newer build, and without the <tt>Defaults</tt> <tt>== </tt> command.
* This is more likely to see changes in results compared to the original results, which may require justification to the client or resolution by investigating, isolating and remedying the causes, especially if recalibration is not intended as a subsequent step.
<li> Iteratively run the original model with the newer build, stepping through the different release version options for <tt>Defaults</tt> <tt>== </tt> command.
* This will allow the modeller to investigate and isolate what changes to TUFLOW builds may be affecting results, and when changes appear.
* Then, individually reverting settings that make up a Default group (see Chapter 18 of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]).
* This can help isolate the primary drivers for any differences in results.
* The [https://docs.tuflow.com/classic-hpc/changelog// TUFLOW Classic/HPC Changelog] accompanying build releases are also a key reference.
<li> Develop new improved or updated model version, with the newer build (and any grouped or individual defaults that are deemed necessary to retain from the iterative testing in the prior step).
*Continue to verify results against the original results as you then iteratively add in or update to any newer functionality or formats that may be available in the later build, a good quality assurance check that changes are behaving as expected.
</ol>
 
{{Tips Navigation
|uplink=[[TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

HPC Introduction

2026-04-09T23:41:41Z

Emilie Nielsen: /* Introduction */

=Introduction=
Since the 2017-09-AA version, TUFLOW offers HPC (Heavily Parallelised Compute) as an alternate 2D Shallow Water Equation (SWE) solver to TUFLOW Classic. TUFLOW Classic is limited to running a simulation on a single CPU core, whereas HPC provides parallelisation of the TUFLOW model allowing modellers to run a single TUFLOW model across multiple CPU cores or GPU graphics cards (which utilise thousands of smaller CUDA* cores). Simulations using GPU hardware has shown to provide significantly quicker model run times for TUFLOW users. 

In general, most of the functionality and features of TUFLOW Classic are available in HPC. Additionally, HPC offers several advanced features not supported in Classic, including:
* Quadtree and sub-grid sampling
* High resolution map output grids
* Groundwater infiltration and sub-surface flows
* Wu turbulence formulation
* TMR bridge inputs (2d_bg) and simulation methods

===Solution Scheme, Cell Discretisation and Parallelisation===
TUFLOW HPC is an explicit solver for the full 2D Shallow Water Equations (SWE), including a sub-grid scale eddy viscosity model. The scheme is both volume and momentum conserving, is 2nd order in space and 4th order in time, with adaptive or fixed timestepping. It is unconditionally stable. TUFLOW HPC's computational approach differs from TUFLOW Classic, which is a 2nd order (space) implicit finite difference solver. Both TUFLOW HPC and Classic solve the 2D SWE on the same uniform Cartesian grid configuration. Computationally each 2D cell includes 9 sub-grid points. 

[[File: HPC Cell Design.PNG |300px]] 

The ZC point:
* Defines the volume of active water (cell volume is based on a flat square cell that wets and dries at a height of ZC plus the Cell Wet/Dry Depth);
* Controls when a cell becomes wet and dry (note that cell sides can also wet and dry); and
* Determines the bed slope when testing for the upstream controlled flow regime.
The ZU and ZV points:
* Control how water is conveyed from one cell to another;
* Represent where the momentum equation terms are centred and where upstream controlled flow regimes are applied;
* Deactivate if the cell has dried (based on the ZC point) and cannot flow; and
* Wet and dry independently of the cell wetting or drying (see Cell Wet/Dry Depth). This allows for the modelling of “thin” obstructions such as fences and thin embankments relative to the cell size (e.g. a concrete levee).
ZH points:
* Play no role hydraulically. This point location is used for output processing;
* The only elevations written to the .2dm mesh file (by default, binary output is interpolated/extrapolated to the cell corners).

Within the above sub-grid framework, using TUFLOW HPC time derivatives of cell averaged water depth, u-velocity and v-velocity are computed on a cell-by-cell basis and the model evolved using an explicit ODE solver. Calculation of the cell based derivatives are highly independent of each other making it possible to run this solution scheme across multiple processors or GPU cards. Parallelisation is done by breaking up the model into vertical ribbons. Each ribbon of the model is run on a different processor (or GPU card) with boundary information shared between processors at each timestep. 

[[File: Mesh_Ribbon_Splitting.png |360px]] 

===Mass Conservation and Timestep===

The explicit finite volume solution scheme utilised in HPC is mass conserving by construction (0% mass error). This differs to TUFLOW Classic, which can continue to simulate a model with some volume error due to it being an implicit finite difference scheme. The stability of the explicit finite volume scheme used in TUFLOW HPC is linked to the timestep, flow velocities, water depth, and eddy viscosity. The maximum timestep that can be used while maintaining model stability changes as the model evolves. While it is possible to choose a fixed timestep ahead of time (similarly to TUFLOW Classic), shorter run times and guaranteed model stability from start to finish may be achieved through the use of adaptive timestepping where the solver continually modifies the timestep based on various stability criteria. This is explained in more detail in our [[HPC_Adaptive_Timestepping | Adaptive Timestepping]] page. 

===Compatible Graphic Cards (GPU) ===
TUFLOW HPC’s GPU hardware module is only compatible with NVIDIA architecture CUDA enabled GPU cards. AMD GPU cards are NOT compatible. A list of CUDA enabled GPUs can be found on the following website: http://developer.nvidia.com/cuda-gpus .
To check if your computer has an NVIDA GPU and if it is CUDA enabled:
* Right click on the Windows desktop;
* If you see “NVIDIA Control Panel” or “NVIDIA Display” in the pop up dialogue, the computer has an NVIDIA GPU;
* Click on “NVIDIA Control Panel” or “NVIDIA Display” in the pop up dialogue;
* The GPU model should be displayed in the graphics card information;
* Check to see if the graphics card is listed on the following website: http://developer.nvidia.com/cuda-gpus
On the NVIDA website each CUDA enabled graphics card has a “Compute Capability” listed. For cards with a compute capability of 1.2 or less, only the single precision version of the GPU Module can be utilised. However, benchmarking has indicated that the double precision version is NOT required and that the TUFLOW_iSP exe should be used for all TUFLOW HPC GPU simulations. Extensive GPU hardware benchmarking has been undertaken to assist users who are upgrading hardware for TUFLOW modelling. Over 50 different hardware options have been tested for their speed performance. The results are provided on the [[Hardware_Benchmarking | Hardware Benchmarking]] page.

===Benefits of HPC===
So what does this mean for modellers? 
By providing the ability to run models on Graphics Cards, we can achieve significantly shorter model run times, increasing our modelling capabilities to be able to run continuous hydraulic models, with higher cell resolution, across larger extents and more scenarios. Common TUFLOW HPC applications include:
* Monte Carlo design assessments
* Rainfall ensemble design assessments
* High resolution 1D underground / 2D above ground integrated urban drainage
* High resolution floodplain lumped hydrology / hydraulic modelling (either fully 2D or including nested 1D open channels and pipes)
* Whole of catchment direct rainfall
* Flood forecast modelling
* Long-term water resource management modelling

The unconditional stability and higher order accuracy of TUFLOW HPC also lends itself well to highly transient situations, such as dam break assessments, where other solvers would either become unstable, lose accuracy or experience impractical simulation slow-down due to the need to solve at an extremely small timestep. 
 
{{Tips Navigation
|uplink=[[ HPC_Modelling_Guidance | Back to HPC Modelling Guidance]]
}}

TUFLOW Viewer

2026-04-09T23:18:21Z

Emilie Nielsen:

TUFLOW Viewer replaces Crayfish and TUPLOT as the TUFLOW result viewer for [[QGIS_Tips | QGIS]] (version 3.6 onwards). It uses the Mesh Data Abstraction Library (MDAL) available in QGIS to display and interact with TUFLOW map output results, and the TUFLOW results python library (the same library used by TUPLOT in earlier versions of QGIS) for viewing TUFLOW time series results. 

The TUFLOW Viewer tool has been significantly updated in the 2026.0.0 QGIS TUFLOW Plugin release. Refer to the [https://docs.tuflow.com/qgis-tuflow-plugin/latest/tuflow-viewer/ TUFLOW Viewer Documentation] for more information. 
 
__TOC__

=Getting Started=
==QGIS Version==
''A few notes on the recommended QGIS version:'' 

It is recommended to use the latest version of QGIS. The reasons for this are:
* TUFLOW Viewer is developed using the latest version, and although backwards compatibility is maintained as best as possible, TUFLOW Viewer is tested more frequently on the latest QGIS version.
* The mesh data provider (MDAL) and the temporal controller (which now underpins the mesh datasets in QGIS) are both relatively new in comparison to other libraries (e.g. GDAL) and are therefore more regularly updated with new features, enhancements, and bug fixes by the QGIS developers. TUFLOW Viewer takes advantage of these updates. 

Although TUFLOW Viewer has been developed to be consistent across QGIS versions, it is not always possible. Some QGIS developments and behaviour changes have led to TUFLOW Viewer behaviour also changing either through necessity or to keep in-line with the QGIS development direction. The below is a current list of known behaviour changes due to QGIS version: 
<ol>
<li> '''Date-time format within TUFLOW Viewer''' - QGIS 3.14 introduced the '''temporal controller''' 
* Prior to QGIS 3.14, TUFLOW Viewer stored all results internally as relative time. The user could display as date-time and the reference time by changing '''Zero Date''' in '''Settings >> Options'''.
* QGIS 3.14, TUFLOW Viewer tried to mimic the behaviour of previous versions but the reference time could also be altered natively in the mesh layer '''Properties'''. Note on this version, this is the first QGIS release with the '''temporal controller''' and as a consequence some of the functionality matured and changed in subsequent versions. Users may experience strange behaviour when using TUFLOW Viewer with the QGIS 3.14 if using date-time format. It is recommended to upgrade to later versions of QGIS if date-time format is required.
* Post QGIS 3.14 TUFLOW Viewer stores all results internally as absolute time and the user must change the reference time in the native properties of the mesh layer to alter the dates being displayed. '''Zero Date''' now only changes how the relative time is displayed in TUFLOW Viewer and doesn't change the mesh layer reference time.
* Please follow the link below on how to use isodate (date-time) format in TUFLOW Viewer in QGIS 3.16+ (recommended minimum version if using date-time format): [[TUFLOW_Viewer_-_Isodate_(Date-Time)_Format | Working With Isodate (Date-Time) format]].
</ol>

'''Other Known Issues''' 
* QGIS 3.24 uses Matplotlib v3.5.1 which contains the following known bug which may affect users when re-labelling datasets within the TUFLOW Viewer plot window: 
: [[TUFLOW_Viewer_Matplotlib_v3.5.1_Bug | TUFLOW Viewer - Matplotlib v3.5.1 bug]] 
* "ValueError: Failed to find font DejaVu Sans:style=normal:variant=normal:weight=normal:stretch=normal:size=10.0, and fallback to the default font was disabled"
: [[TUFLOW_Viewer_Matplotlib_Font_Error | TUFLOW Viewer - Matplotlib Font Error]] 

==Installation or Version Upgrade==
===Installation===
TUFLOW Viewer is a free tool that comes as part of the TUFLOW plugin in QGIS. For instructions on how to install the plugin, please follow these steps: [[TUFLOW_QGIS_Plugin#Installation_of_Plugin |Installation of Plugin]]. 
There are also instructions on installing plugins in the QGIS documentation - if you choose to follow the QGIS documentation, the plugin is called "TUFLOW" in the repository: [https://docs.qgis.org/3.16/en/docs/training_manual/qgis_plugins/fetching_plugins.html Link to QGIS Documentation - Installing and Managing Plugins]. 

===Plugin Upgrades===
It's recommended to upgrade the plugin whenever a new version is released. The upgrade process is typically done via the Plugin Manager ('''QGIS Drop Menu: Plugins >> Manage and Install Plugins'''). 
 
[[File: TUFLOW_Plugin_Update_01.png]] 
If you encounter an error while upgrading the plugin please follow these steps: [[ TUFLOW_QGIS_Plugin#Error_While_Upgrading_Plugin | Error While Upgrading Plugin ]].

==Development Version==
It's possible to test out the latest development version of the plugin and TUFLOW Viewer by following the instructions here: [[Installing_the_Latest_Development_Version_of_the_TUFLOW_Plugin | Installing the Latest Development Version of the TUFLOW Plugin]].

=Using TUFLOW Viewer=
==Opening the TUFLOW Viewer==
After installing the QGIS TUFLOW plugin, the TUFLOW Viewer tool can be opened by clicking the following icon in the plugin toolbar: 
 
[[File: TUFLOW_Plugin_Toolbar_TUFLOW_Viewer_01.png]] 

==Loading Results==
TUFLOW simulation results can be loaded two ways: 
<ol>
<li> Select '''File >> Load Results''' from the TUFLOW Viewer drop down menu. 
 
[[File:TUFLOW_Viewer_Load_Results_01a.png]] 
 
<li> Right Click in the '''Open Results''' panel and select '''Load Results'''. 
 
[[File: TUFLOW_Viewer_Load_Results_02a.png]] 
 
</ol>
Using either of the above methods, the following result load options are available:
<ol>
<li> '''[[TUFLOW_Viewer_-_Load_Results | Load All Results]]''' --> This is done via a TCF or TLF file and will load in all results (Map Outputs and ESTRY Time Series). ''Note: the Load All Results feature is not yet enabled for TUFLOW FV FVC files.''
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_Map_Outputs | Load Results - Map Outputs]]''' --> Select map output mesh results file ('''*.xmdf, *.dat, *.2dm, *.xmdf.sup, *.dat.sup, *.nc''' ''(supports netCDF format from TUFLOW FV output only)'').
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_Time_Series | Load Results - Time Series]]''' --> Select ESTRY / SWMM time series output results ('''*.tpc *.gpkg''').
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_Time_Series_FM | Load Results - Flood Modeller Time Series]]''' --> Load Flood Modeller results. This requires a '''*.gxy''' and result '''*.csv''' file to be exported from Flood Modeller.
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_Particles | Load Results - Particle Tracking Module]]''' --> Select output from particle module ('''*.nc''') which will typically be suffixed with '''_ptm'''.
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_NetCDF_Grid | Load Results - NetCDF Grid]]''' --> Load TUFLOW NC or HRNC map output results.
<li> '''[[TUFLOW_Viewer_-_Import_1D_Hydraulic_Tables | Import 1D Hydraulic Tables]]''' --> Select a '''_1d_ta_tables_check.csv''' check file.
<li> '''[[TUFLOW_Viewer_-_Import_2D_BC_Tables | Import 2D BC Tables]]''' --> Select a '''_2d_bc_tables_check.csv''' check file.
<li> '''[[TUFLOW_Viewer_-_Import_1D_ESTRY_Cross_-_Sections | Import 1D ESTRY Cross-Sections]]''' --> This will automatically happen if an appropriate TUFLOW input is opened in QGIS while TUFLOW Viewer is open (e.g. 1d_xs).
<li> '''[[TUFLOW_Viewer_-_Importing_a_User_Defined_Time_Series_To_Display_On_The_Plot | Importing a User Defined Time Series Dataset To Display In The Plot Window]]'''
<li> '''[[TUFLOW_Viewer_-_Import_FV_Tide_BC_NetCDF | Import FV Tide BC NetCDF]]'''
<li> '''[[TUFLOW_Viewer_-_Loading_Results_While_TUFLOW_is_Running | Loading Results While TUFLOW is Running]]'''
</ol>

===Troubleshooting===
If you receive an error similar to that shown below when attempting to load results from a TCF you will need to fix the encoding of your TUFLOW control files: 
<pre>
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x92 in position 626: invalid start byte
</pre>
This error is caused by incompatible encoding of the TUFLOW control files. You can resolve this issue by changing the encoding of all your TUFLOW control files to a single type (typically UTF-8). You can do this using Notepad++. Please see the following link for instructions on how to do this (refer last image): [[TUFLOW_Message_0060 | TUFLOW Message 0060]]. 

== TUFLOW-SWMM Results ==
Results from a linked TUFLOW-SWMM model can be loaded via the standard menu options (available from the TUFLOW plugin version 3.10):
* '''[[TUFLOW_Viewer_-_Load_Results_-_Time_Series | Load Results - Time Series]]''' To load the GPKG time series format (_swmm_ts.gpkg) by itself. The GPKG time series format is a new format similar to the .tpc with some additional functionality. More information can be found in the [[#GPKG_Time_Series_Format | GPKG Time Series Format]] section.
* '''[[TUFLOW_Viewer_-_Load_Results_-_Map_Outputs | Load Results - Map Outputs]]''' To load in 2D map output results
* '''[[TUFLOW_Viewer_-_Load_Results | Load Results]]''' To load all available results from the model. This includes .xmdf, .tpc, and .gpkg results which could all be available for a given model run. Note that .tpc and .gpkg are both time series type results and will load separate GIS _PLOT_ layers.

== GPKG Time Series Format ==
The GPKG time series format is a new format similar to the .tpc with enhanced temporal functionality. Currently the GPKG time series format is only supported as an output from SWMM in TUFLOW-SWMM linked models and only supported in TUFLOW Plugin version 3.10+ and QGIS 3.16+. 
 
The GPKG format is different from the TPC format as it supports temporal styling in QGIS. As an example, the line width of the channels can be varied by both time and flow, with wider lines showing higher flow than thinner lines at a particular timestep. The format is fully compatible with the QGIS temporal controller and reacts dynamically as the temporal controller is updated. This results in a dynamic, and intuitive, method of showing the user the flood progression in the 1D system. Another benefit of being compatible with the core QGIS temporal capabilities is that the styling will also be dynamically updated if included in an animation export. TUFLOW Viewer's animation export tool has been updated to enable GPKG results to be exported with 2D results or even by itself. 
 
The layer's styling can be automatically set using the TUFLOW Plugin via the layer's right-click context menu (under the TUFLOW submenu) or will automatically by styled if the results are loaded via TUFLOW Viewer. Examples of this format in QGIS are linked below:
* [[Automatically_Styling_GPKG_Time_Series | Styling layers from the GPKG time series output]]
* [[TUFLOW_Viewer_-_Load_Results_-_GPKG_Time_Series | Loading results via TUFLOW Viewer]]
The GPKG time series format is an open format and the specification is detailed at the below link:
* [[GPKG_Time_Series_Format_Specification | GPKG Time Series Format Specification]]

== Data Selection, Display and Styling==
===Map Output===
Map Outputs are the time varying 2D result outputs from TUFLOW (or 3D outputs from TUFLOW FV). Data selection, display, styling and plotting instructions for Map Output results in TUFLOW Viewer are described below:
<ol>
<li> Load Map Output results either via:
<ol>
<li> '''[[TUFLOW_Viewer_-_Load_Results | Load All Results]]''', or
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_Map_Outputs | Load Results - Map Outputs]]'''
</ol>
<li> '''[[TUFLOW_Viewer_-_Reload_Results | Reload Results]]''' --> Reload and update results
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Change_Result_Selection | Change Simulation Result Selection]]''' --> Changing between different simulation results is done by selecting the result name(s) in the 'Open Results' widget.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Changing_Result_Type | Change Result Type Selection]]''' --> Changing between different result types is done using the 'Result Type' widget.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Displaying_Maximum | Display Result Maximum]]''' --> If available, maximums can be toggled on/off for the different result types.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Displaying_Vectors | Display Vectors]]''' --> Vector results can be displayed in combination with any of the scalar result types (e.g. velocity vectors can be displayed with depth).
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Styling_Scalar_Types | Style Scalar Map Outputs]]''' --> Styling scalar map output results is similar to styling raster layers in QGIS.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Styling_Vector_Types | Style Vector Map Outputs]]''' --> Similar to the styling the scalar map outputs, there are a range of options for styling the vector layers.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Saving_Default_Styles | Save Default Styles]]''' --> Users can save default styles for result types so they are automatically applied each time results are imported using TUFLOW Viewer.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Displaying_The_Mesh | Display The Mesh]]''' --> The quickest way to toggle the mesh is to click the grid box in TUFLOW Viewer.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_3D_to_2D_Depth_Averaging_Method | 3D to 2D Depth Averaging]]''' --> For 3D map output results, the 3D to 2D depth averaging method can be changed in the layer properties.
<li> '''[[TUFLOW_Viewer_-_Toggling_Between_Output_Timesteps | Lock/Unlock Output Time Steps from Different Result Datasets]]''' --> Locking Plot Output Timesteps to the Map Output Interval.
<li> '''[[TUFLOW_Viewer_-_Isodate_(Date-Time)_Format | Working With Isodate (Date-Time) Format]]''' --> View results using absolute time format (dd/mm/yyyy hh:mm:ss) instead of relative time format (hh:mm:ss).
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Plotting_Time_Series | Map Output Plot - Plotting Time Series]]''' --> Plotting Map Output results.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Plotting_Cross-Sections_And_Longitudinal_Profiles | Map Output Plot - Plotting Cross-Sections and Longitudinal Profiles]]''' --> Plotting Map Output results.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Plotting_Flow | Map Output Plot - Plotting Flow]]''' --> Plotting Map Output results.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Curtain_Plot | Map Output Plot - 3D Curtain Plot]]''' --> Plotting Map Output results.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Vertical_Profile | Map Output Plot - 3D Vertical Profile]]''' --> Plotting Map Output results --> Plotting Map Output results.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_3D_to_2D_Depth_Averaged_Time_Series | Map Output Plot - Plotting 3D to 2D Depth Averaged Time Series]]''' --> Plotting Map Output results.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_3D_to_2D_Depth_Averaged_Cross-Sections | Map Output Plot - Plotting 3D to 2D Depth Averaged Cross-Sections]]''' --> Plotting Map Output results.
<li> '''[[TUFLOW_Viewer_-_Map_Outputs_-_Plotting_From_Vector_Layer | Map Output Plot - Plotting From Vector a Layer (e.g. shp file)]]''' --> Plotting Map Output results.

</ol>
 
[[file: MapOutputs HeaderImg.PNG|650px]] 
 

===Time Series Output===
Time series outputs are typically 1D result outputs or 2D time series results (plot outputs or reporting locations). Time series results consist of two elements, the result datasets and GIS layers that the user can interact with to customise the plot selection in TUFLOW Viewer.
<ol>
<li> Load time series output results either via:
<ol>
<li> '''[[TUFLOW_Viewer_-_Load_Results | Load All Results]]''', or
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_Time_Series | Load Results - Time Series]]''' for TUFLOW models, or:
<li> '''[[TUFLOW_Viewer_-_Load_Results_-_Time_Series_FM | Load Results - Time Series Flood Modeller]]''' for TUFLOW linked Flood Modeller 1D models.
</ol>
<li> '''[[TUFLOW_Viewer_-_Time_Series_Outputs_GIS_Data | Time Series Output - GIS Data]]'''
<li> '''[[TUFLOW_Viewer_-_Time_Series_Outputs_-_Plotting_Time_Series | Time Series Output - Plotting Time Series]]'''
<li> '''[[TUFLOW_Viewer_-_Time_Series_Outputs_-_Plotting_Longitudinal_Profiles | Time Series Output - Plotting Longitudinal Profiles]]'''
<li> '''[[TUFLOW_Viewer_-_Showing_Selected_Elements_And_Selecting_Sub-Sets | Identifying Selected Elements and Selecting Sub-Sets]]'''
<li> '''[[TUFLOW_Viewer_-_Time_Series_Outputs_-_Plotting_1D_Cross-Section_Inputs | Plotting 1D Cross-Section Inputs (with / without results)]]'''
<li> '''[[TUFLOW_Viewer_-_Time_Series_Outputs_-_Plotting_1D_Hydraulic_Table_Check_Files | Plotting 1D Hydraulic Table Check Files]]'''
<li> '''[[TUFLOW_Viewer_-_Extracting_Median_And_Mean_Time_Series | Extracting Median and Mean Time Series - Australian Rainfall and Runoff]]'''
<li> '''[[TUFLOW_Viewer_-_Plotting_1D_Flow_Regime | Plotting 1D Flow Regime]]'''
<li> '''[[TUFLOW_Viewer_-_Import_2D_BC_Tables | Plotting 2D Boundary Condition Tables]]'''
<li> '''[[TUFLOW_Viewer_-_Toggling_Between_Output_Timesteps | Lock/Unlock Output Time Steps from Different Result Datasets]]'''
<li> '''[[TUFLOW_Viewer_-_Isodate_(Date-Time)_Format | Working With Isodate (Date-Time) Format]]'''
</ol> 
[[File: TimeSeries_HeaderImg.PNG|650px]] 
 

===Particle Tracking Output===
<ol>
<li> '''[[TUFLOW_Viewer_-_Particle_Outputs | Particle Tracking Outputs]]'''
<li>'''[[TUFLOW_Viewer_-_Isodate_(Date-Time)_Format | Working With Isodate (Date-Time) Format]]'''
<li> '''[[TUFLOW_Viewer_-_Toggling_Between_Output_Timesteps | Lock/Unlock Output Time Steps from Different Result Datasets]]'''
</ol>
[[File: Particles HeaderImg.PNG|650px]] 

==General Plot Display Options==
<ol>
<li> '''[[TUFLOW_Viewer_-_Summary_of_Plotting_Toolbar | Summary of Plotting Toolbar Options]]''' 
<li> '''[[TUFLOW_Viewer_-_Using_A_Secondary_Axis | Using a Secondary Axis]]'''
<li> '''[[TUFLOW_Viewer_-_Using_A_Date_Axis | Using a Date Axis]]'''
<li> '''[[TUFLOW_Viewer_-_Showing_The_Current_Time | Displaying the Current Time]]'''
<li> '''[[TUFLOW_Viewer_-_Customising_The_Plot_Legend | Customising The Legend]]'''
<li> '''[[TUFLOW_Viewer_-_Customising_The_Plotting_Styles | Customising The Plotting Styles]]'''
<li> '''[[TUFLOW_Viewer_-_Customising_The_Plot_Axes | Customising The Plot Axes]]'''
<li> '''[[TUFLOW_Viewer_-_Toggling_Plot_Grid_Lines | Plot Grid Line Display]]'''
<li> '''[[TUFLOW_Viewer_-_Importing_a_Custom_Colour_Ramp_For_The_Curtain_Plot | Importing a Custom Colour Ramp For The Curtain Plot]]'''
<li> '''[[TUFLOW_Viewer_-_Navigating_And_Querying_The_Plot | Navigating And Querying The Plot]]'''
<li> '''[[TUFLOW_Viewer_-_Auto_Update_Plot_From_Cursor_Location | Auto Update Plot From Cursor Location]]'''
<li> '''[[TUFLOW_Viewer_-_Viewing_The_Vertical_Mesh | 3D Mesh Vertical Layer Display]]'''
<li> '''[[TUFLOW_Viewer_-_Hiding_The_Plotting_Window | Hiding the Plot Window]]'''
<li> '''[[TUFLOW_Viewer_-_Customising_The_Plot_Background_Colour | Customising the Plot Background Colour]]'''
<li> '''[[TUFLOW_Viewer_-_Setting_The_Plot_Default_Font_Size | Setting the Default Font Size For the Plot]]'''
<li> '''[[TUFLOW_Viewer_-_Toggling_Between_Output_Timesteps | Lock/Unlock Output Time Steps from Different Result Datasets]]'''
<li> '''[[TUFLOW_Viewer_-_Changing_Icon_Size | Changing the Icon Size]]'''
<li> '''[[TUFLOW_Viewer_-_Summary_Of_Options | Settings Options]]'''
</ol>

[[File: Plotting_HeaderImg.PNG | 650px ]] 
 

==Exporting Animations, Data, Plots and Maps ==
TUFLOW Viewer offers the ability to export animations, data interegation points/lines, maps and plots: 
<ol>
<li> '''[[TUFLOW_Viewer_-_Exporting_An_Animation | Exporting An Animation]]''' 
: [[File: Animation_cover.gif]] 
<li> '''[[TUFLOW_Viewer_-_Exporting_And_Copying_A_Plot | Exporting and Copying a Plot]]'''
<li> '''[[TUFLOW_Viewer_-_Exporting_The_Drawn_GIS_Plot_Features | Exporting The Drawn GIS Plot Points / Lines]]'''
<li> '''[[TUFLOW_Viewer_-_Batch_Exporting_Maps | Batch Exporting Maps]]'''
<li> '''[[TUFLOW_Viewer_-_Batch_Exporting_Plots | Batch Exporting Plots]]'''
</ol>
: [[File: Maps_Cover_Image.PNG | 550px]] 

= Python Error Troubleshooting =
Occasionally the TUFLOW plugin will throw an exception and this will produce a '''Python Error''' which is displayed either as a yellow banner at the top of the map window or a window may appear stating than an 'Error has occurred while executing Python code'. 
[[File: PythonError.PNG]] 
When this occurs it means that the TUFLOW plugin has encountered something unusual or a situation that it does not know how to handle (i.e. it has reached a line in the code that has failed to execute and as a consequence Python has bailed out). This means all the code below this point that was meant to execute has not. This can have knock-on consequences as variables may not exist or be set to incorrect values and signal handling (e.g. what happens when a menu item is clicked) may be broken. As such, a python error can lead to further python errors that would normally not have occurred. Because of this flow-on effect the first python error is usually the most important. 

If you encounter a python error please:
<ol>
<li> Email the '''Stack Trace''' to [mailto:support@tuflow.com support@tuflow.com] with a description of the steps that produced the python error (as best you can describe it). This is to help us identify bugs and fix the plugin so that it catches this exception in the future.
<li> If you find that you are now experiencing further python errors (probably caused by the initial error) you can try the following alternative in order of severity (least to worst):
<ol>
<li> On the TUFLOW Viewer menu bar '''File >> Reload TUFLOW Viewer''' - this will reload TUFLOW Viewer, resetting all variables and signals. You will be required to load in any time series results again and other settings may also be reset. Map output results will remain in the workspace and be reloaded into TUFLOW Viewer.
<li> Save the QGIS workspace (.qgz) and restart QGIS.
<li> Restart QGIS - you can save the workspace (.qgz), however you should first select on the TUFLOW Viewer menu bar '''File >> Close TUFLOW Viewer Completely''' - this will close the Viewer and also remove all settings associated with it from the workspace so that the problematic variable is not accidentally reloaded with the workspace.
<li> The last resort option is to restart QGIS and load and create a new workspace from scratch (do not load a saved workspace).
</ol>
</ol>
 
{{Tips Navigation
|uplink=[[TUFLOW_QGIS_Plugin#Usage| Back to TUFLOW QGIS Plugin Main Page]]
}}
 
 
 
{{Tips Navigation
|uplink=[[Main_Page| Back to Wiki Main Page]]
}}

TUFLOW QGIS Plugin

2026-04-09T23:14:28Z

Emilie Nielsen: /* Introduction */

=Introduction=
If you are using QGIS as your model development or result viewing environment we strongly recommend installing the TUFLOW QGIS Plugin. It includes numerous tools to increase workflow efficiency. It also includes powerful result viewing functionality via its [[TUFLOW_Viewer | TUFLOW Viewer]]. This page describes the process of installing and using the Plugin.
 
See the [https://docs.tuflow.com/qgis-tuflow-plugin/changelog/ TUFLOW QGIS Plugin Changelog] for changes between versions of the plugin (since version 3.2).

=Installation of Plugin=
To enable the plugin please follow the instructions below:
<ol>
<li>Download the plugin from the QGIS official repository, '''Plugins >> Manage and Install Plugins'''</li>
[[File:QGIS_TUFLOW_000.PNG|400px]]
<li>In the manager, search for "TUFLOW".</li>
<li>Select TUFLOW, and "Install Plugin".</li>
[[File:QGIS_TUFLOW_001.PNG|400px]]
<li>Once enabled the plugin should be accessible from the '''Plugins >> TUFLOW''' menu item:</li>
[[File:QGIS_TUFLOW_003.PNG|400px]]
<li>Before using, check that the prerequisite python modules are also installed (see below).
</ol> 

=Development Version=
It's possible to test out the latest development version of the plugin and TUFLOW Viewer by following the instructions below: 
[[Installing_the_Latest_Development_Version_of_the_TUFLOW_Plugin | Installing the Latest Development Version of the TUFLOW Plugin]]
 

= Prerequisites=
The TUFLOW plugin uses the following python modules which '''may''' need to be separately installed. These may have been installed with other software, to check if they are installed on your machine:
<ol>
<li> Install the TUFLOW plugin (see instructions above)</li>
<li> Open the TUFLOW plugin '''Plugins >> TUFLOW''' </li>
<li> Check that the required dependencies are installed from the menu. '''TUFLOW >> About >> Check Python Dependencies Installed'''. </li>
[[File:QGIS_TUFLOW_004.PNG|600px]]
</ol>

All going well you will get a notification to tell you that the required modules are installed. If not, you will be notified if you need to install either of the python modules below: 
Please ensure QGIS / python is installed before installing the below. 
* numpy (see https://sourceforge.net/projects/numpy/files/NumPy/1.6.1/numpy-1.6.1-win32-superpack-python2.7.exe/download)
* matplotlib (see https://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.1.0/matplotlib-1.1.0.win32-py2.7.exe/download)
 

=Usage=
Each function in the utility has a separate page documenting the usage.

The first step for a project is to create the project / save the settings with the [[QGIS_TUFLOW_Create_Project | Create or Configure TUFLOW Project]] tool. Subsequent tools rely on the information stored at this stage to work best.

=== Editing Tools ===
<ol>
<li> [[QGIS_TUFLOW_Create_Project | Create or Configure TUFLOW Project]]</li>
<li> [[QGIS_TUFLOW_Import_Empty | Import Empty (template GIS file)]]</li>
<li> [[QGIS_TUFLOW_Insert_TUFLOW_Attributes_to_Existing_Layer | Insert TUFLOW Attributes to Existing Layer]]</li>
<li> [[QGIS_TUFLOW_Increment_Layer | Increment Selected Layer]]</li>
<li> [[QGIS_TUFLOW_Reload_Data | Reload Data]]
<li> [[QGIS_TUFLOW_Arch_Bridge_Editor | Arch Bridge Editor]]
<li> [[QGIS_TUFLOW_Copy_TUFLOW_Command | Copy TUFLOW Command]]
</ol>
=== Run Tools ===
<ol>
<li> [[QGIS_TUFLOW_Run_TUFLOW | Run TUFLOW simulation]]</li>
<li> [[TUFLOW_Runner | TUFLOW Runner]]</li>
<li> [[QGIS_TUFLOW_Run_TUFLOW_Utilities | Running TUFLOW Utilities]]</li>
</ol>

=== Visualisation Tools ===
<ol>
<li> [[TUFLOW_Viewer | TUFLOW Viewer ]](result visualisation toolkit)
<li> [[QGIS_TUFLOW_Styles | Applying TUFLOW styles]]
<li> [[QGIS_TUFLOW_Import_Check_Files_From_Folder | Import Check Files From Folder]]
<li> [[QGIS_TUFLOW_Load_Layers_From_TCF | Load TUFLOW Layers From TCF]]
<li> [[QGIS_TUFLOW_Filter_and_Sort_TUFLOW_Layers | Filter and Sort TUFLOW Layers]]
<li> [[QGIS_TUFLOW_Apply_GPKG_Layer_Names | Apply GPKG Layer Names]]
<li> [[QGIS_TUFLOW_Apply_Label_to_Current_Layer | Apply Label to Current Layer]]
<li> [[QGIS_TUFLOW_Apply_Stability_Styling | Apply Stability Styling]]
</ol>
=== Hydrology Tools ===
<ol>
<li> [[QGIS_ARR_to_TUFLOW | ARR to TUFLOW]]
<li> [[QGIS_ReFH2_to_TUFLOW | ReFH2 to TUFLOW]]
<li> [[QGIS_SCS_to_TUFLOW | SCS to TUFLOW]]
</ol>
=== Integrity Tools ===
<ol>
<li> [[1D_Integrity_Tool | 1D Integrity Tool]]
</ol>
=== SWAN GIS Tools ===
For more information on SWAN GIS Tools please visit the following TUFLOW FV Wiki page: '''[https://fvwiki.tuflow.com/index.php?title=SWAN_GIS_Tools SWAN GIS Tools]'''. Links to the individual tools on the TUFLOW FV Wiki area also provided below:
<ol>
<li> [https://fvwiki.tuflow.com/index.php?title=SWAN_GIS_Model_Builder SWAN GIS Model Builder]
<li> [https://fvwiki.tuflow.com/index.php?title=SWAN_GIS_Post_Processing SWAN GIS Post Processing]
</ol>
=== Processing Toolbox ===
<ol>
<li> [[Convert_TUFLOW_Model_GIS_Format | Convert TUFLOW Model GIS Format]]
<li> [[Create_TUFLOW_Project | Create TUFLOW Project]]
<li> [[Package_Model_in_QGIS | Package Model]]
<li> [[QGIS_TIN_Polygons_Assign_Elevations | TIN Polygons - Assign Elevations]]
<li> SWMM Tools:
<ol><li>[[QGIS_SWMM_BC_Create_Channel_Endpoint_1D/2D_Connections | BC - Create channel endpoint 1D/2D connections]]
<li> [[QGIS_SWMM_Conduits_Assign_Losses | Conduits - Assign losses]]
<li> [[QGIS_SWMM_Conduits_Assign_Node_Fields | Conduits - Assign node fields]]
<li> [[QGIS_SWMM_Convert_ESTRY_Layers_To_SWMM | Convert - ESTRY layers to SWMM]]
<li> [[QGIS_SWMM_Convert_XPSWMM_GIS_Inlet_Layers_to_SWMM | Convert - XPSWMM GIS inlet layers to SWMM]]
<li> [[QGIS_SWMM_Convert_XPSWMM_Hydrology_(beta) | Convert - XPSWMM Hydrology (beta)]]
<li> [[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX | Convert - XPSWMM model from XPX (beta)]]
<li> [[QGIS_SWMM_GeoPackage_Add_Sections | GeoPackage - Add sections]]
<li> [[QGIS_SWMM_GeoPackage_Create | GeoPackage - Create]]
<li> [[QGIS_SWMM_GeoPackage_Create_from_SWMM_inp | GeoPackage - Create from SWMM inp]]
<li> [[QGIS_SWMM_GeoPackage_Write_to_SWMM_inp | GeoPackage - Write to SWMM inp]]
<li> [[QGIS_SWMM_Integrity_Make_Object_Names_Unique| Integrity - Make object names unique]]
<li> [[QGIS_SWMM_Junctions_Convert_HX_Nodes_to_Storage| Junctions - Convert HX nodes to storage]]
<li> [[QGIS_SWMM_Junctions_Downstream_Junctions_to_Outfalls| Junctions - Downstream junctions to outfalls]]
<li> [[QGIS_SWMM_Junctions_Set_Attributes| Junctions - Set attributes]]
<li> [[QGIS_SWMM_Outfalls_Fix_Multiply_Connected_Links| Outfalls - Fix multiply connected links]]

</ol>
</ol>

If you encounter any issues with the plugin please contact [mailto:support@tuflow.com support@tuflow.com]. 
 

=Error While Upgrading Plugin=
[[File:Plugin_uninstall_failed.PNG]] 
If you receive an error while trying to upgrade the TUFLOW plugin you may need to either: 
<ol>
<li> Restart QGIS and try upgrading the plugin again
<li> Manually remove the old version
</ol>

Errors are most likely caused by an issue with deleting the old version of the plugin as some part of the plugin is still being used somewhere in memory (RAM) and locking permissions. This is a known issue that occur with the ReFH2 to TUFLOW tool in older versions of the plugin. Simply restarting QGIS and retrying the upgrade process should fix the issue.

=== Manually removing the TUFLOW plugin ===
To manually remove the TUFLOW plugin simply delete the 'tuflow' folder from the QGIS plugin directory (you may need to close QGIS first): 
<ol>
<li>'''Windows''' - %appdata%\QGIS\QGIS3\profiles\default\python\plugins
<li>'''Linux''' - /home/USER/.local/share/QGIS/QGIS3/profiles/default/python/plugins
</ol>

=Changelog=

[https://docs.tuflow.com/qgis-tuflow-plugin/changelog/ https://docs.tuflow.com/qgis-tuflow-plugin/changelog/]

 
{{Tips Navigation
|uplink=[[QGIS_Tips| Back to QGIS Tips Main Page]]
}}
 
{{Tips Navigation
|uplink=[[Main_Page| Back to Wiki Main Page]]
}}

TUFLOW 2D Hydraulic Structures

2026-04-08T05:53:36Z

Emilie Nielsen: /* 2D BG Shape (2d_bg) */

= 2D Structure Modelling Theory =
The theory behind the modelling of energy losses and affluxes of hydraulic structures is presented in the following webinars by Bill Syme and Greg Collecutt (TUFLOW Developers).

*[https://www.tuflow.com/library/webinars/#structures Webinar Link: Modelling Energy Losses at Structures] 
*[https://www.tuflow.com/library/webinars/#nov2022_hydraulic_modelling_bridge Webinar Link: 1D, 2D & 3D Hydraulic Modelling of Bridges]
 

= 2D Bridge Modelling in TUFLOW - Overview =
The TUFLOW 2D solution explicitly predicts the majority of “macro” losses due to the expansion and contraction of water through a constriction, or around a bend, provided the resolution of the grid is sufficiently fine ([https://www.tuflow.com/Download/Publications/Flow%20Through%20an%20Abrupt%20Constriction%20-%202D%20Hydrodynamic%20Performance%20and%20Influence%20of%20Spatial%20Resolution,%20Barton,%202001.pdf Barton, 2001]; [https://www.tuflow.com/Download/Publications/Modelling%20of%20Bends%20and%20Hydraulic%20Structures%20in%20a%202D%20Scheme,%20Syme,%202001.pdf Syme, 2001]; [https://www.tuflow.com/Download/Technical_Memos/Modelling%20Bridge%20Piers%20in%202D%20using%20TUFLOW.pdf Ryan, 2013]). Where the 2D model is not of fine enough resolution to simulate the “micro” losses (e.g. from bridge piers, vena contracta, losses in the vertical (3rd) dimension), additional form loss coefficients and/or modifications to the cells widths and flow height need to be added.
==Contraction/Expansion Losses (“Macro” Losses)==
Loss of energy is caused by the flow contraction during the expansion of water after the vena-contracta inside a bridge section and the flow expansion downstream a bridge. As discussed above, this type of "macro" losses can be explicitly resolved by the TUFLOW 2D solver, provided that a proper turbulence model and mesh size are used. Below is an example of the 2D modelling of flow contraction/expansion at a pair of bridge abutments.
 
[[File:FC_Velocity_Example.PNG|600px]] 

==Pier Losses==
Piers are usually smaller than the 2D cell size in real-world flood models. Although flexible mesh solver or quadtree refinement can be applied to reduce the local cell size around the pier, it also comes with an expensive computational cost that could significantly increase the simulation time. More practically, the backwater effect of piers can be modelled as sub-grid form losses.

Pier form loss coefficients can be derived from information in publications such as [https://www.fhwa.dot.gov/engineering/hydraulics/library_arc.cfm?pub_number=1&id=5 ''Hydraulics of Bridge Waterways'' (Bradly, 1978)] or [https://austroads.com.au/publications/bridges/agbt08 ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018)]. Energy loss estimated from bridge piers or other obstructions, vertical or horizontal, that do not cause upstream controlled flow regimes like pressure flow, are dependent on the ratio of the obstruction's area perpendicular to the flow direction to the gross flow area of the bridge opening, the shape of the piers or obstruction, and the angularity of the piers/obstruction to the flow direction. For example, using Hydraulics of Bridge Waterways (Bradly, 1978) the approach is:
<ol>
<li>Calculate the ratio of the water area occupied by piers to the gross water area of the constriction (both based on the normal water surface) and the angularity of the piers. These inputs are used to calculate "J" in the FHA documentation.</li>
<li>Use the Figure 4.10 ''Incremental Backwater Coefficient for Piers'' data to calculate Kp. 
[[File:incremental_backwater_coefficient_2018_pier_losses.png]]
 
'''NOTE''': the pier form loss coefficients in Hydraulics of Bridge Waterways are derived based on the cross-sectional averaged velocity through the bridge opening in the absence of piers. It's not necessary to specify a blockage value if a pier form loss coefficient estimated from this method is used.
</li>
</ol>

==Bridge Deck and Rail (Super Structure)==
When a bridge deck become partially or completely submerged, the deck could generate extra afflux resulting in increased water levels and flood extents upstream of the structure. The flow around the deck is highly 3-dimentional and complexed due to the different deck designs/profiles and/or the occurrence of pressure flow. In 2D SWE solver, depth-varying form loss values are often needed to reproduce the afflux caused by such structure. Due to the complexity of the flow, guidelines on how to set the form loss coefficient for the bridge deck are rare. We have carried out a joint research with QLD TMR (Queensland Department of Transport and Main Roads) regarding how to choose a proper form loss value for the bridge deck [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)] . In the research, CFD modelling was conducted to investigate the characteristics of energy loss of a simple bridge with a flat bottomed deck and guardrails.
 
[[File:CFD_study.png|600px]]

Below are the key findings from the study:
*The results displayed a characteristic shape for head loss coefficient as a function of downstream water level over the deck thickness (TW/T).
*The head loss (afflux) peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out.
[[File:FormLoss_vs_TWT.png|600px]]
 

=== Bridge Design (hB/T) vs Form Loss Coefficient Table===
The peak loss coefficient value is a function of the ratio of the depth underneath the deck (hB) and the thickness of the deck (T). This table can be used to estimate the deck form loss coefficient based on the bridge design (hB/T).
<ol>
{| style="text-align: center;" class="wikitable" width="35%"
! style="background-color:#005581; font-weight:bold; color:white;" width=55%| Deck Height to Thickness Ratio
! style="background-color:#005581; font-weight:bold; color:white;" width=45%| Peak Form Loss Coefficient
|-
| Scenario A (hB/T) = 2 || 0.42
|-
| Scenario B (hB/T) = 4 || 0.28
|-
| Scenario C (hB/T) = 6 || 0.20
|}
</ol>

*The solid portion of the guard rails (blockage * rail depth) can be added to T in addition to the deck thickness to calculate hB/T.
*For bridge with more complicated designs (e.g. girders), higher form loss might be required due to the higher surface roughness of the bridge.
*If the hB/T ratio is less than 2 or greater than 6, use a peak form loss coefficient of 0.42 (minimum) or 0.20 (maximum), respectively.

'''NOTE''': This form loss value should not be confused with the value of 1.56 used in the pressure flow approached adopted in [[1D_Bridges | TUFLOW 1D "B" and "BB" bridge]]. TUFLOW 1D bridge pressure flow approach is based on the section 4.13.2 "All Girders in Contact with Flow (Case II)" of ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018). The original hydraulic experiment conducted by [https://hdl.handle.net/10217/39009 Liu et al (1957)] in a laboratory flume with a pair of bridge abutments and a deck. The flow conditions were similar to orifice flow due to the high blockage ratio caused by the abutments and the deck. When modelling bridges in 2D, the contraction/expansion losses caused by the abutments would be handled explicitly by the 2D solver, so a value 1.56 can lead to duplication of the contraction/expansion losses caused by the bridge abutments. 
 

=TUFLOW 2D Bridge Setup=
There are two methods available to model depth varying form loss of a bridge structure:
* [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 |2D Layered Flow Constriction (2d_lfcsh)]]
:The traditional method used to model depth-varying form loss through bridge components such as piers, decks, and rails.

*[[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 |2D BG Shape (2d_bg)]] (introduced in the 2023 release)
:A simplified approach developed to simplify the model input based on the findings from the joint TMR Study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

Both methods provide options for representing flow surcharging, the pressure flow of bridge decks and eventually submerged bridge flow at higher water levels. During the surcharging of bridge decks, higher energy losses can be specified to simulate the pressure flow.

Examples for how to configure both approaches are provided in the 2D structures section of the [[TUFLOW_Example_Models#2D_Structures |TUFLOW Wiki Example Models]] and [[Tutorial_M04 |Tutorial Module 4]] - 2D Bridges.

==2D Layered Flow Constriction (2d_lfcsh)==
Four flow constriction layers are represented in a 2d_lfcsh layer. The lower three layers represents the pier, the bridge deck and the rails. Each layer has its own attributes to specify the blockage and the form loss coefficient. The top (fourth) layer assumes the flow is unimpeded, representative of flow over the top of a bridge. Within the same shape, the invert of the bed, and thickness of each layer can vary in 3D.

The following table provides an overview for how to determine the blockage and form loss coefficient for each layer: 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || Use calibration data, if available, to determine FLC. If no calibration is available, estimate using [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table || Full blockage, no flow through the deck
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 3 || Bridge rails || 10% – 100% || Use calibration data, if available, to determine FLC. 
If no calibration data is available, combined FLC for Layers 2 and 3 should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = L2_Depth + (pBlockage × L3_Depth)
*(pBlockage × L3_Depth) represents the solid portion of the rails
*L2 FLC and L3 FLC should sum to the combined FLC
|Blockage and FLC depends on rail type Sensitivity testing with 100% blockage is recommended due to potential for debris during flood
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}
<ol>
[[File:2d_lfcsh_attributes.png | 500px ]]
</ol>
 

===Blockage===

The 2d_lfcsh functions by adjusting the flow width and the form loss of 2D cell faces. The combined blockage across the 4 layers is calculated at each simulation timesteps:
<ol>
 
[[File: Blockage_total_equation_01.png|600px]]
 
where 
'''''yi''''' is the actual depth of water in layer '''''i''''' 
'''''ytotal''''' is the total water depth 
</ol>

===Form Loss Approach===

The combined form loss coefficient is determined using one of three methods. The form loss coefficient method can be specified either individually using the 2d_lfcsh “Shape_Options” attribute or globally using the .tcf command: 
<tt>Layered FLC Default Approach == [ METHOD A | {METHOD B} | METHOD C | METHOD D]</tt> 

:METHOD A: The losses are accumulated as the water level rises through the layers. 
<ol>
[[File:Eq_flc_cumulate.png |450px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Applies the full accumulated form loss continuously, even when overtopping begins (no reduction)
:Note: Simpler method but tends to overestimate losses when the structure is submerged or overtopped 

:METHOD B (default): the losses are applied pro-rata according to the depth of water in each layer. 
<ol>
[[File:Eq_flc_portion.png |430px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure
:Note: Maintains backward compatibility but may underrepresent losses during pressurised or overtopped flows 

:METHOD C (recommended): hybrid approach combining Method A and Method B. 
<ol>
[[File:Eq_flc_methodC.png |520px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Gradual increase in form loss with water level, following Method A
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure, following Method B
:Note: Recommended method; aligns closest to CFD modelling results and TUFLOW HPC behaviour.

:METHOD D: Allows the modeller to control the depth at which the losses start to reduce when the flow transitions between pressure flow and drowned flow.
:This approach is the same used by the 2d_bg layer (introduced in the 2023-03 release). It is recommended to use the 2d_bg layer as it has the benefit of a simplified attribute table, for easier user input.

===Form Loss Calibration Example - Iowa River Flood Study===

In this study, a combined form loss coefficient of 0.35 was used to match observed head loss during slight overtopping of a bridge. The FLC values for each layer were adjusted to achieve the correct combined form loss. The table and plot show how each layer contributes to the total form loss and highlight the differences in calculated form loss between the three methods.

{| style="text-align: left; margin-left: 0;" class="wikitable" width="60%"
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=6%| Layer
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=10%| Depth (m)
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=12%| Blockage (%)
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method A
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method B
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method C
|-
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
|-
| 1 || 5.0 || 5 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07
|-
| 2 || 1.5 || 100 || 0.15 || 0.22 || 1.05 || 0.30 || 0.15 || 0.22
|-
| 3 || 1.0 || 50 || 0.13 || 0.35 || 0.70 || 0.35 || 0.13 || 0.35
|}

</ol>
 
<ol>
[[File:FLC_vs_height_updated.png | 600px ]]
</ol>

==2D BG Shape (2d_bg)==
2D BG Shape is similar to the Layered Flow Constriction, but has several updates to simplify the input based on the findings from the joint study with TMR [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

The following table provides an overview of how to determine the blockage and form loss coefficient for each layer: 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || rowspan="2" | The Super Structure (Super_S) is the bridge deck and rails layers combined. 
Use calibration data, if available, to determine FLC. 
If no calibration data is available, the Super_S FLC should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = Deck_Depth + (Rail_pBlockage*Rail_Depth)
*(Rail_pBlockage*Rail_Depth) represents the solid portion of the rails
|| Full blockage, no flow through the deck
|-
| 3 || Bridge rails || 10% – 100% || Sensitivity testing with 100% blockage is recommended due to potential for debris during flood events
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}

<ol>
[[File:Bridge block.jpg | 800px]]
</ol>

===Inflection Point===

Based on findings from the joint study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)], the head loss peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out. The 'SuperS_IPf' attribute (inflection point factor, default = 1.6) can be used to define the height of the inflection point. The solid portion of the rail layer is also added to the deck thickness to calculate the depth to the inflection point (DIP), i.e.:
<ol>
[[File:eq_flc_bg_infection_point.png | 520px ]]
</ol>

===Form Loss Approach===
The form loss approach is similar to the FLC approach METHOD C, with L2/L3 replaced by a single super structure layer:
<ol>
[[File:eq_flc_bg.png | 480px ]]
</ol>

===Form Loss Calibration Example - Iowa River Flood Study===
This example uses the same bridge setup described in the[[TUFLOW_2D_Hydraulic_Structures#Form_Loss_Calibration_Example_-_Iowa_River_Flood_Study | 2D Layered Flow Constriction]] section, with the following parameters applied:
*SuperS_FLC = 0.28
*SuperS_Ipf = 1.6,
The Depth to Inflection Point (DIP) is calculated as 3.2m above the bridge soffit.

The table and figure below show how the form loss value varies with water depth.
<ol>
{| style="text-align: center;" class="wikitable" width="32%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Depth (m)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Form Loss
|-
| Pier || 5.0 || 5 || 0.07
|-
| Deck || 1.5 || 100 || rowspan="2" | 0.28
|-
| Rail || 1.0 || 50
|}

[[File:FLC_vs_height_bg.png | 600px ]]
</ol>

== 2D Bridges Line vs Polygon Layer ==
The form loss coefficient (FLC) is applied differently when using a line compared to a polygon for both 2d_lfcsh and 2d_bg inputs. The FLC is applied at cell sides (u and v faces) as this is where velocities are calculated. 
For larger bridges that spread across multiple cells, it is recommended to use a polygon layer, which selects all u and v faces falling within the polygon.
 
 
'''2D Layered Flow Constriction (2d_lfcsh)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides
| This approach is cell size independent. It is the easiest setup and the preferred / recommended approach when using 2d_lfcsh.
|-
| Thick
| between zero and 1.5 times the cell size
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| A cell is selected if the polyline intersects the cell crosshair. Caution should be taken when using a "thick" line, as changes in cell size can cause it to become a "wide" line. If this occurs, the FLC attribute may need to be recalculated to avoid overestimating or underestimating losses.
|-
| Wide
| larger than 1.5 times the cell size
| Total form loss of the bridge ''(may need to be recalculated, see notes)''
| FLC divided by number of cell sides in the direction of flow 
''(number of cell sides in the direction of flow is calculated as line width divided by cell size)''
| Polygon shapes are recommended if more than 3 rows of faces must be selected.. 
Caution should be taken when using a "wide" line. The cell size and alignment of the 2d_lfcsh line may result in selecting too many or too few cell faces in the direction of the flow. The FLC input may need to be recalculated to ensure FLC Applied multiplied by the number of cell sides in the direction of flow equates to the intended total form loss.
|-
!rowspan="1" | Polygon
| -
| -
| Total loss per unit length (meters or feet) in the direction of flow
| FLC * cell size applied to all sides of selected cells
|
|}

'''2D Bridge (2d_bg)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides.
| This approach is cell size independent.
|-
| Thick
| larger than zero
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| This approach is cell size independent. A cell is selected if the polyline intersects the cell crosshair.
|-
| Wide
| Not supported
| –
| –
| BG polygon shapes are recommended if more than 3 rows of faces must be selected.
|-
!rowspan="1" |Polygon
| -
| ''(used to automatically distribute the total FLC to the selected faces)''
| Total form loss of the bridge
| FLC / Deck_Width * cell size applied to all sides of selected cells
| For bridges modelled using a 2d_bg polygon the relative ratio of the bridge width to the 2D cell size should be 4 or greater. For more information on this see [https://downloads.tuflow.com/Other/2d_bg_R_Bridge_Configuration_Advice_202503.pdf 2d_bg_R_Bridge_Configuration_Advice.pdf].
|}
 
The following diagrams demonstrate how the input FLC is applied for the four geometry options for 2d_lfcsh and 2d_bg layers: 
[[File:2dlfcsh 2dbg combined v2.png|1200px]]

It is good modelling practice to check the [[Check_Files_2d_lfcsh_uvpt | lfcsh_uvpt_check]] and [[Check Files 2d bg uvpt check | bg_uvpt_check]] files to confirm the number of faces selected and the FLC values assigned. It is also strongly recommended to undertake a sensitivity analysis on the applied form losses in the model to check if it makes any difference to the results and/or double check against other methods (hand calculations, other software, CFD modelling), especially if the bridge is near an area of interest. If calibration data is available, this should be used to guide the form loss value specification. 
 

= Common Questions Answered (FAQ)=
== What blockage values should I use for bridge guard rails? ==
The blockage of bridge guard rails can be anything from 100% blocked (solid concrete rails) to 10% blocked (very open rails). In addition, the accumulation of debris during a flood can be substantial as shown in the image below. Sensitivity testing with 100% blockage is recommended.
 
[[File:Bridge rail debris.jpg | 500px]]

== How to conduct sensitivity test for 2D bridges? ==
General recommendations to cross-check the results are:
* Compare computed affluxes against desktop methods (e.g. Hydraulics of Bridge Waterways, 1978) and/or other software including CFD, especially for unusual bridge designs.
* Use any recorded flood marks or general observations from past events to check and calibrate FLC values.
* Conduct sensitivity testing by assessing the impact and influence of FLC values on your modelling objectives. The afflux resulting from the FLC values will be proportional to the velocity head, i.e. ∆h=FLC*(v^2/2g). As such, if velocities are low (e.g. 1 m/s), the results may not be overly sensitive to uncertainties in the FLC values. If completing a check using this equation for a long skew bridge it is best to calculate the total structure velocity from a PO line digitised in the same location as the bridge.

Finally, after completing sensitivity testing and understanding the range of uncertainty due to unknowns like the degree of blockage and influence of FLC values (e.g. +/-20%), you are in a position to discuss with your client how best to proceed. For example, if the modelling is to set planning levels for a development upstream then it may be appropriate to choose values on the higher side (higher FLC values and/or blockage assumptions), noting that the uncertainty may be amply covered by a regulatory freeboard. Conversely, if the development is on the downstream side the conservative approach would be to use the results at the lower end of your FLC/blockage values. 
[[File:Bridge Flood Debris Loading.jpg | 500px]] 

== Should I use both FLC and blockage for layer one in 2D bridge layered flow constriction? ==
When applying FLC and blockage values to model obstructions such as piers, the following considerations need to be taken into account:
* The FLC value applies an energy loss along 1D channels or across 2D cell faces equivalent to FLC*V2/2g where V is the 1D channel velocity or the 2D cell face velocity.
* FLC values are often sourced from publications such as Hydraulics of Bridge Waterways or AustRoads (e.g. Kp chart for piers).
* If possible, establish whether the source of the FLC value is based on the approach velocity (the velocity in the absence of piers) or structure velocity (the velocity with area blocked out by the piers) noting that it often isn’t clear or stated.
** If it is the structure velocity, this is usually the velocity at the vena-contracta (point of greatest contraction within the entrance to the structure and therefore highest velocity) - see image below. Bluff or sharp-edged obstructions will have a much more pronounced vena-contracta, and therefore higher velocity compared with a round-edged obstruction.
** FLC values based on the approach velocity will be higher than those based on the structure velocity to achieve the same energy loss.
* Applying a blockage equivalent to the obstruction width will increase, usually very slightly, the velocity of the 1D channel or 2D cell face. This won’t be the vena-contracta velocity, but a velocity between the approach velocity and the vena-contracta velocity. A greater blockage will need to be applied to emulate the vena-contracta velocity.
* If the FLC source value is based on:
** The approach velocity then there is no need to apply a blockage value.
** The structure velocity then the blockage value should be applied noting that it may be appropriate to apply a larger blockage to take into account the vena-contracta.
* If it is not clear or unknown whether the FLC source value is based on the approach or structure velocity, the recommendation would be to apply the blockage in the interests of being slightly conservative on the upstream flood level calculation.
* For most minor obstructions such as bridge piers, the blockage is usually relatively small and whether included or not has a negligible or minor affect on flood levels compared with other factors such as the approach embankments and the bridge deck.
* Blockage from debris wrapped around piers can have a greater influence on the results than the effect of applying or not applying a blockage. Debris wrapped around piers can be accounted for in the FLC value calculated for the pier layer.
* As always, sensitivity testing with and without blockage and +/- the FLC value is highly recommended to understand their importance in regard to the broader modelling objectives and the effects of uncertainties in the input data, boundaries, other parameters such as Manning’s n values, and the accuracy of the numerical solution scheme (see [https://www.tuflow.com/library/webinars/#maximise_accuracy Maximising the Accuracy of Hydraulic Models webinar]).
[[File: Vena_contracta.png]] 
''Image showing the formation of the vena-contracta.'' 
 

==I don't see results that I expect when using 2d_lfcsh layer==
The 2d_lfcsh layer is a versatile feature that was designed to model bridges in 2D, but can also be used for other applications like fences, buildings raised on pillars and so on.
Some of the unexpected results could be:
* Water level going through the bridge deck in 2D map output.
* Water transiting through 100% blocked Layer 1, e.g. fences with solid base.
* SHMax.csv reporting values above the bridge deck when 2D map output reports water level lower than the top of the bridge deck.

TUFLOW is a 2D solution (not 3D), in the 2d_lfcsh layer the percent blockage and form loss coefficient applied to the cell faces is depth averaged across the entire cell face (across Layer 1, 2 and 3): 
*For bridges, where Layer 2 has a 100% blockage applied, the minimum flow width of 0.001m is used and is averaged with the Layer 1 blockage (based on the depth of the water). This may result in a water level being reported within or above the bridge deck, which would represent the pressure head.
*Layered flow constriction works by adjusting the flow area of the cell faces by any blockages to generate the correct depth averaged velocity at each face at which the form losses are applied as a fraction of the V2/2g kinetic energy. Calculating the correct velocity is critical for determining the losses as the losses are proportional to the velocity squared. 
*For a layered flow constriction cell face the flow area cannot be zero above the invert of Layer 1 to avoid a divide by zero in the computations, therefore a minimum average flow width after applying blockages of 0.001 m is applied. if Layer 1 is 100% blocked, a very small amount of water will flow through Layer 1. If this is unacceptable, instead of applying 100% blockage of Layer 1, the preferred approach is to start the layered flow constriction at the top of Layer 1 or raise the ground elevation to the top of Layer 1 using one of the Z Shape modification functions (e.g. a breakline). 
<ol>
[[File:100% Blockage Diagram.png | 500px]]
</ol>

== Can I model bridge piers explicitly in 2D using very small cells? ==
It isn't recommended to explicitly model bridge piers by blocking out the pier faces in TUFLOW, or in any hydraulic modelling software based on solving Shallow Water Equations(SWE). Due to the 3-dimentiality of the flow and turbulence around a pier, computational fluid dynamics (CFD) approach is often required to simulate the flow around piers explicitly. The wake turbulence behind a simple-shape pier can be resolved to some extent using extremely fine mesh in TUFLOW (see calibration example to a flume experiment in the [https://www.tuflow.com/library/webinars/#structures webinar on Energy Losses at Structures]), however the predictions for head losses show notable sensitivities to the mesh size, the mesh design, and the choice of turbulence model. The extremely fine mesh resolution also results in significantly higher computational costs.

Therefore, the safest and strongly recommended approach with regard to establishing head losses and consequently flood levels, is to model the effects of such obstructions with form loss coefficients (applied to selected mesh cells) that have been derived from physical testing. This approach has been shown to provide the most consistent results across various mesh resolutions. It also has the added benefit that, by avoiding small cells in the mesh, it will provide much more efficient run times for flow solvers.

[[File:Flow round a cylinder.png]]

''The point of flow separation around an object has a major bearing on the drag coefficient and is not reliably reproduced by 2D or 3D software.''


== How to best convert flow constriction data (2d_fc or 2d_fcsh) into newer formats (2d_lfcsh or 2d_bg)? ==
The form loss parameters can be transferred from the flow constriction (2d_fc or 2d_fcsh) to the first layer of the layered flow constriction (2d_lfcsh) or pier layer of the 2d_bg. Definition of the remaining form loss and blockage layer inputs should follow the guidance outlined in [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 | 2D Layered Flow Constriction]] and [[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 | 2D BG Shape]] paragraphs. 
When using floating pontoon (type FD in the 2d_fc or 2d_fcsh) different setup might need to be used for different events. For large events when floating pontoon becomes fixed at the top of the supporting piles, standard 2d_lfcsh setup can be used. Smaller events when the pontoon is floating at different heights might require more sensitivity testing of the structure parameters to find out a setup the matches the reality as close as possible. 

== Should I model bridges in 1D or 2D Domain? ==
The recommended approach typically depends on the study objectives and if the channel upstream and downstream of the bridge is modelled in 1D or 2D. To preserve the momentum as accurately as possible the bridge should be modelled in the same dimension as the channel, e.g. 1d_nwk bridge if the channels is in 1D and 2d_bg or 2d_lfcsh if the channel is modelled in 2D. 
In 2D, the expansion/contraction losses are modelled based on the topography and don't need to be estimated as attributes as for 1D modelling. Also, for higher flows where the bridge is overtopped, 2D is preferable approach.

== What is the difference between downstream and upstream controlled flow? ==
Downstream control means a change in downstream water level will cause a change in upstream water level. Upstream control means the upstream water level is insensitive to the downstream water level and usually indicates the occurrence of supercritical flow.

== What FLC values should be used for 2d_bg bridge if hB/T is below 2 or above 6? ==
TMR has extended the CFD simulation to hB/T ratios of 1 to 10. Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for details.

If hB/T is outside this ratio:
* hB/T ratios of less than 1 represent a very unusual bridge sitting low to the ground, and the peak FLC may increase above the end value (FLC of 0.6) in a way that doesn't follow the research trend or extrapolation. For these cases we would recommend using CFD modelling to obtain a more informed value. Alternatively, computing an FLC based on pressure flow or using 1D culvert might be considered.
* For hB/T ratios of greater than 10, the FLC is likely to continue to decrease, but probably not significantly. Clamping to the end value (FLC of 0.16) might be considered the more conservative approach (if the primary concern is flood levels upstream of the bridge). 
 
{{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

File:Bridge block.jpg

2026-04-08T05:52:37Z

Emilie Nielsen:

TUFLOW 2D Hydraulic Structures

2026-04-08T05:47:37Z

Emilie Nielsen: /* Pier Losses */

= 2D Structure Modelling Theory =
The theory behind the modelling of energy losses and affluxes of hydraulic structures is presented in the following webinars by Bill Syme and Greg Collecutt (TUFLOW Developers).

*[https://www.tuflow.com/library/webinars/#structures Webinar Link: Modelling Energy Losses at Structures] 
*[https://www.tuflow.com/library/webinars/#nov2022_hydraulic_modelling_bridge Webinar Link: 1D, 2D & 3D Hydraulic Modelling of Bridges]
 

= 2D Bridge Modelling in TUFLOW - Overview =
The TUFLOW 2D solution explicitly predicts the majority of “macro” losses due to the expansion and contraction of water through a constriction, or around a bend, provided the resolution of the grid is sufficiently fine ([https://www.tuflow.com/Download/Publications/Flow%20Through%20an%20Abrupt%20Constriction%20-%202D%20Hydrodynamic%20Performance%20and%20Influence%20of%20Spatial%20Resolution,%20Barton,%202001.pdf Barton, 2001]; [https://www.tuflow.com/Download/Publications/Modelling%20of%20Bends%20and%20Hydraulic%20Structures%20in%20a%202D%20Scheme,%20Syme,%202001.pdf Syme, 2001]; [https://www.tuflow.com/Download/Technical_Memos/Modelling%20Bridge%20Piers%20in%202D%20using%20TUFLOW.pdf Ryan, 2013]). Where the 2D model is not of fine enough resolution to simulate the “micro” losses (e.g. from bridge piers, vena contracta, losses in the vertical (3rd) dimension), additional form loss coefficients and/or modifications to the cells widths and flow height need to be added.
==Contraction/Expansion Losses (“Macro” Losses)==
Loss of energy is caused by the flow contraction during the expansion of water after the vena-contracta inside a bridge section and the flow expansion downstream a bridge. As discussed above, this type of "macro" losses can be explicitly resolved by the TUFLOW 2D solver, provided that a proper turbulence model and mesh size are used. Below is an example of the 2D modelling of flow contraction/expansion at a pair of bridge abutments.
 
[[File:FC_Velocity_Example.PNG|600px]] 

==Pier Losses==
Piers are usually smaller than the 2D cell size in real-world flood models. Although flexible mesh solver or quadtree refinement can be applied to reduce the local cell size around the pier, it also comes with an expensive computational cost that could significantly increase the simulation time. More practically, the backwater effect of piers can be modelled as sub-grid form losses.

Pier form loss coefficients can be derived from information in publications such as [https://www.fhwa.dot.gov/engineering/hydraulics/library_arc.cfm?pub_number=1&id=5 ''Hydraulics of Bridge Waterways'' (Bradly, 1978)] or [https://austroads.com.au/publications/bridges/agbt08 ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018)]. Energy loss estimated from bridge piers or other obstructions, vertical or horizontal, that do not cause upstream controlled flow regimes like pressure flow, are dependent on the ratio of the obstruction's area perpendicular to the flow direction to the gross flow area of the bridge opening, the shape of the piers or obstruction, and the angularity of the piers/obstruction to the flow direction. For example, using Hydraulics of Bridge Waterways (Bradly, 1978) the approach is:
<ol>
<li>Calculate the ratio of the water area occupied by piers to the gross water area of the constriction (both based on the normal water surface) and the angularity of the piers. These inputs are used to calculate "J" in the FHA documentation.</li>
<li>Use the Figure 4.10 ''Incremental Backwater Coefficient for Piers'' data to calculate Kp. 
[[File:incremental_backwater_coefficient_2018_pier_losses.png]]
 
'''NOTE''': the pier form loss coefficients in Hydraulics of Bridge Waterways are derived based on the cross-sectional averaged velocity through the bridge opening in the absence of piers. It's not necessary to specify a blockage value if a pier form loss coefficient estimated from this method is used.
</li>
</ol>

==Bridge Deck and Rail (Super Structure)==
When a bridge deck become partially or completely submerged, the deck could generate extra afflux resulting in increased water levels and flood extents upstream of the structure. The flow around the deck is highly 3-dimentional and complexed due to the different deck designs/profiles and/or the occurrence of pressure flow. In 2D SWE solver, depth-varying form loss values are often needed to reproduce the afflux caused by such structure. Due to the complexity of the flow, guidelines on how to set the form loss coefficient for the bridge deck are rare. We have carried out a joint research with QLD TMR (Queensland Department of Transport and Main Roads) regarding how to choose a proper form loss value for the bridge deck [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)] . In the research, CFD modelling was conducted to investigate the characteristics of energy loss of a simple bridge with a flat bottomed deck and guardrails.
 
[[File:CFD_study.png|600px]]

Below are the key findings from the study:
*The results displayed a characteristic shape for head loss coefficient as a function of downstream water level over the deck thickness (TW/T).
*The head loss (afflux) peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out.
[[File:FormLoss_vs_TWT.png|600px]]
 

=== Bridge Design (hB/T) vs Form Loss Coefficient Table===
The peak loss coefficient value is a function of the ratio of the depth underneath the deck (hB) and the thickness of the deck (T). This table can be used to estimate the deck form loss coefficient based on the bridge design (hB/T).
<ol>
{| style="text-align: center;" class="wikitable" width="35%"
! style="background-color:#005581; font-weight:bold; color:white;" width=55%| Deck Height to Thickness Ratio
! style="background-color:#005581; font-weight:bold; color:white;" width=45%| Peak Form Loss Coefficient
|-
| Scenario A (hB/T) = 2 || 0.42
|-
| Scenario B (hB/T) = 4 || 0.28
|-
| Scenario C (hB/T) = 6 || 0.20
|}
</ol>

*The solid portion of the guard rails (blockage * rail depth) can be added to T in addition to the deck thickness to calculate hB/T.
*For bridge with more complicated designs (e.g. girders), higher form loss might be required due to the higher surface roughness of the bridge.
*If the hB/T ratio is less than 2 or greater than 6, use a peak form loss coefficient of 0.42 (minimum) or 0.20 (maximum), respectively.

'''NOTE''': This form loss value should not be confused with the value of 1.56 used in the pressure flow approached adopted in [[1D_Bridges | TUFLOW 1D "B" and "BB" bridge]]. TUFLOW 1D bridge pressure flow approach is based on the section 4.13.2 "All Girders in Contact with Flow (Case II)" of ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018). The original hydraulic experiment conducted by [https://hdl.handle.net/10217/39009 Liu et al (1957)] in a laboratory flume with a pair of bridge abutments and a deck. The flow conditions were similar to orifice flow due to the high blockage ratio caused by the abutments and the deck. When modelling bridges in 2D, the contraction/expansion losses caused by the abutments would be handled explicitly by the 2D solver, so a value 1.56 can lead to duplication of the contraction/expansion losses caused by the bridge abutments. 
 

=TUFLOW 2D Bridge Setup=
There are two methods available to model depth varying form loss of a bridge structure:
* [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 |2D Layered Flow Constriction (2d_lfcsh)]]
:The traditional method used to model depth-varying form loss through bridge components such as piers, decks, and rails.

*[[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 |2D BG Shape (2d_bg)]] (introduced in the 2023 release)
:A simplified approach developed to simplify the model input based on the findings from the joint TMR Study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

Both methods provide options for representing flow surcharging, the pressure flow of bridge decks and eventually submerged bridge flow at higher water levels. During the surcharging of bridge decks, higher energy losses can be specified to simulate the pressure flow.

Examples for how to configure both approaches are provided in the 2D structures section of the [[TUFLOW_Example_Models#2D_Structures |TUFLOW Wiki Example Models]] and [[Tutorial_M04 |Tutorial Module 4]] - 2D Bridges.

==2D Layered Flow Constriction (2d_lfcsh)==
Four flow constriction layers are represented in a 2d_lfcsh layer. The lower three layers represents the pier, the bridge deck and the rails. Each layer has its own attributes to specify the blockage and the form loss coefficient. The top (fourth) layer assumes the flow is unimpeded, representative of flow over the top of a bridge. Within the same shape, the invert of the bed, and thickness of each layer can vary in 3D.

The following table provides an overview for how to determine the blockage and form loss coefficient for each layer: 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || Use calibration data, if available, to determine FLC. If no calibration is available, estimate using [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table || Full blockage, no flow through the deck
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 3 || Bridge rails || 10% – 100% || Use calibration data, if available, to determine FLC. 
If no calibration data is available, combined FLC for Layers 2 and 3 should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = L2_Depth + (pBlockage × L3_Depth)
*(pBlockage × L3_Depth) represents the solid portion of the rails
*L2 FLC and L3 FLC should sum to the combined FLC
|Blockage and FLC depends on rail type Sensitivity testing with 100% blockage is recommended due to potential for debris during flood
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}
<ol>
[[File:2d_lfcsh_attributes.png | 500px ]]
</ol>
 

===Blockage===

The 2d_lfcsh functions by adjusting the flow width and the form loss of 2D cell faces. The combined blockage across the 4 layers is calculated at each simulation timesteps:
<ol>
 
[[File: Blockage_total_equation_01.png|600px]]
 
where 
'''''yi''''' is the actual depth of water in layer '''''i''''' 
'''''ytotal''''' is the total water depth 
</ol>

===Form Loss Approach===

The combined form loss coefficient is determined using one of three methods. The form loss coefficient method can be specified either individually using the 2d_lfcsh “Shape_Options” attribute or globally using the .tcf command: 
<tt>Layered FLC Default Approach == [ METHOD A | {METHOD B} | METHOD C | METHOD D]</tt> 

:METHOD A: The losses are accumulated as the water level rises through the layers. 
<ol>
[[File:Eq_flc_cumulate.png |450px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Applies the full accumulated form loss continuously, even when overtopping begins (no reduction)
:Note: Simpler method but tends to overestimate losses when the structure is submerged or overtopped 

:METHOD B (default): the losses are applied pro-rata according to the depth of water in each layer. 
<ol>
[[File:Eq_flc_portion.png |430px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure
:Note: Maintains backward compatibility but may underrepresent losses during pressurised or overtopped flows 

:METHOD C (recommended): hybrid approach combining Method A and Method B. 
<ol>
[[File:Eq_flc_methodC.png |520px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Gradual increase in form loss with water level, following Method A
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure, following Method B
:Note: Recommended method; aligns closest to CFD modelling results and TUFLOW HPC behaviour.

:METHOD D: Allows the modeller to control the depth at which the losses start to reduce when the flow transitions between pressure flow and drowned flow.
:This approach is the same used by the 2d_bg layer (introduced in the 2023-03 release). It is recommended to use the 2d_bg layer as it has the benefit of a simplified attribute table, for easier user input.

===Form Loss Calibration Example - Iowa River Flood Study===

In this study, a combined form loss coefficient of 0.35 was used to match observed head loss during slight overtopping of a bridge. The FLC values for each layer were adjusted to achieve the correct combined form loss. The table and plot show how each layer contributes to the total form loss and highlight the differences in calculated form loss between the three methods.

{| style="text-align: left; margin-left: 0;" class="wikitable" width="60%"
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=6%| Layer
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=10%| Depth (m)
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=12%| Blockage (%)
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method A
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method B
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method C
|-
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
|-
| 1 || 5.0 || 5 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07
|-
| 2 || 1.5 || 100 || 0.15 || 0.22 || 1.05 || 0.30 || 0.15 || 0.22
|-
| 3 || 1.0 || 50 || 0.13 || 0.35 || 0.70 || 0.35 || 0.13 || 0.35
|}

</ol>
 
<ol>
[[File:FLC_vs_height_updated.png | 600px ]]
</ol>

==2D BG Shape (2d_bg)==
2D BG Shape is similar to the Layered Flow Constriction, but has several updates to simplify the input based on the findings from the joint study with TMR [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

The following table provides an overview of how to determine the blockage and form loss coefficient for each layer: 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || rowspan="2" | The Super Structure (Super_S) is the bridge deck and rails layers combined. 
Use calibration data, if available, to determine FLC. 
If no calibration data is available, the Super_S FLC should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = Deck_Depth + (Rail_pBlockage*Rail_Depth)
*(Rail_pBlockage*Rail_Depth) represents the solid portion of the rails
|| Full blockage, no flow through the deck
|-
| 3 || Bridge rails || 10% – 100% || Sensitivity testing with 100% blockage is recommended due to potential for debris during flood events
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}

<ol>
[[File:2d_bg_attributes.png | 700px ]]
</ol>

===Inflection Point===

Based on findings from the joint study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)], the head loss peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out. The 'SuperS_IPf' attribute (inflection point factor, default = 1.6) can be used to define the height of the inflection point. The solid portion of the rail layer is also added to the deck thickness to calculate the depth to the inflection point (DIP), i.e.:
<ol>
[[File:eq_flc_bg_infection_point.png | 520px ]]
</ol>

===Form Loss Approach===
The form loss approach is similar to the FLC approach METHOD C, with L2/L3 replaced by a single super structure layer:
<ol>
[[File:eq_flc_bg.png | 480px ]]
</ol>

===Form Loss Calibration Example - Iowa River Flood Study===
This example uses the same bridge setup described in the[[TUFLOW_2D_Hydraulic_Structures#Form_Loss_Calibration_Example_-_Iowa_River_Flood_Study | 2D Layered Flow Constriction]] section, with the following parameters applied:
*SuperS_FLC = 0.28
*SuperS_Ipf = 1.6,
The Depth to Inflection Point (DIP) is calculated as 3.2m above the bridge soffit.

The table and figure below show how the form loss value varies with water depth.
<ol>
{| style="text-align: center;" class="wikitable" width="32%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Depth (m)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Form Loss
|-
| Pier || 5.0 || 5 || 0.07
|-
| Deck || 1.5 || 100 || rowspan="2" | 0.28
|-
| Rail || 1.0 || 50
|}

[[File:FLC_vs_height_bg.png | 600px ]]
</ol>

== 2D Bridges Line vs Polygon Layer ==
The form loss coefficient (FLC) is applied differently when using a line compared to a polygon for both 2d_lfcsh and 2d_bg inputs. The FLC is applied at cell sides (u and v faces) as this is where velocities are calculated. 
For larger bridges that spread across multiple cells, it is recommended to use a polygon layer, which selects all u and v faces falling within the polygon.
 
 
'''2D Layered Flow Constriction (2d_lfcsh)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides
| This approach is cell size independent. It is the easiest setup and the preferred / recommended approach when using 2d_lfcsh.
|-
| Thick
| between zero and 1.5 times the cell size
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| A cell is selected if the polyline intersects the cell crosshair. Caution should be taken when using a "thick" line, as changes in cell size can cause it to become a "wide" line. If this occurs, the FLC attribute may need to be recalculated to avoid overestimating or underestimating losses.
|-
| Wide
| larger than 1.5 times the cell size
| Total form loss of the bridge ''(may need to be recalculated, see notes)''
| FLC divided by number of cell sides in the direction of flow 
''(number of cell sides in the direction of flow is calculated as line width divided by cell size)''
| Polygon shapes are recommended if more than 3 rows of faces must be selected.. 
Caution should be taken when using a "wide" line. The cell size and alignment of the 2d_lfcsh line may result in selecting too many or too few cell faces in the direction of the flow. The FLC input may need to be recalculated to ensure FLC Applied multiplied by the number of cell sides in the direction of flow equates to the intended total form loss.
|-
!rowspan="1" | Polygon
| -
| -
| Total loss per unit length (meters or feet) in the direction of flow
| FLC * cell size applied to all sides of selected cells
|
|}

'''2D Bridge (2d_bg)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides.
| This approach is cell size independent.
|-
| Thick
| larger than zero
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| This approach is cell size independent. A cell is selected if the polyline intersects the cell crosshair.
|-
| Wide
| Not supported
| –
| –
| BG polygon shapes are recommended if more than 3 rows of faces must be selected.
|-
!rowspan="1" |Polygon
| -
| ''(used to automatically distribute the total FLC to the selected faces)''
| Total form loss of the bridge
| FLC / Deck_Width * cell size applied to all sides of selected cells
| For bridges modelled using a 2d_bg polygon the relative ratio of the bridge width to the 2D cell size should be 4 or greater. For more information on this see [https://downloads.tuflow.com/Other/2d_bg_R_Bridge_Configuration_Advice_202503.pdf 2d_bg_R_Bridge_Configuration_Advice.pdf].
|}
 
The following diagrams demonstrate how the input FLC is applied for the four geometry options for 2d_lfcsh and 2d_bg layers: 
[[File:2dlfcsh 2dbg combined v2.png|1200px]]

It is good modelling practice to check the [[Check_Files_2d_lfcsh_uvpt | lfcsh_uvpt_check]] and [[Check Files 2d bg uvpt check | bg_uvpt_check]] files to confirm the number of faces selected and the FLC values assigned. It is also strongly recommended to undertake a sensitivity analysis on the applied form losses in the model to check if it makes any difference to the results and/or double check against other methods (hand calculations, other software, CFD modelling), especially if the bridge is near an area of interest. If calibration data is available, this should be used to guide the form loss value specification. 
 

= Common Questions Answered (FAQ)=
== What blockage values should I use for bridge guard rails? ==
The blockage of bridge guard rails can be anything from 100% blocked (solid concrete rails) to 10% blocked (very open rails). In addition, the accumulation of debris during a flood can be substantial as shown in the image below. Sensitivity testing with 100% blockage is recommended.
 
[[File:Bridge rail debris.jpg | 500px]]

== How to conduct sensitivity test for 2D bridges? ==
General recommendations to cross-check the results are:
* Compare computed affluxes against desktop methods (e.g. Hydraulics of Bridge Waterways, 1978) and/or other software including CFD, especially for unusual bridge designs.
* Use any recorded flood marks or general observations from past events to check and calibrate FLC values.
* Conduct sensitivity testing by assessing the impact and influence of FLC values on your modelling objectives. The afflux resulting from the FLC values will be proportional to the velocity head, i.e. ∆h=FLC*(v^2/2g). As such, if velocities are low (e.g. 1 m/s), the results may not be overly sensitive to uncertainties in the FLC values. If completing a check using this equation for a long skew bridge it is best to calculate the total structure velocity from a PO line digitised in the same location as the bridge.

Finally, after completing sensitivity testing and understanding the range of uncertainty due to unknowns like the degree of blockage and influence of FLC values (e.g. +/-20%), you are in a position to discuss with your client how best to proceed. For example, if the modelling is to set planning levels for a development upstream then it may be appropriate to choose values on the higher side (higher FLC values and/or blockage assumptions), noting that the uncertainty may be amply covered by a regulatory freeboard. Conversely, if the development is on the downstream side the conservative approach would be to use the results at the lower end of your FLC/blockage values. 
[[File:Bridge Flood Debris Loading.jpg | 500px]] 

== Should I use both FLC and blockage for layer one in 2D bridge layered flow constriction? ==
When applying FLC and blockage values to model obstructions such as piers, the following considerations need to be taken into account:
* The FLC value applies an energy loss along 1D channels or across 2D cell faces equivalent to FLC*V2/2g where V is the 1D channel velocity or the 2D cell face velocity.
* FLC values are often sourced from publications such as Hydraulics of Bridge Waterways or AustRoads (e.g. Kp chart for piers).
* If possible, establish whether the source of the FLC value is based on the approach velocity (the velocity in the absence of piers) or structure velocity (the velocity with area blocked out by the piers) noting that it often isn’t clear or stated.
** If it is the structure velocity, this is usually the velocity at the vena-contracta (point of greatest contraction within the entrance to the structure and therefore highest velocity) - see image below. Bluff or sharp-edged obstructions will have a much more pronounced vena-contracta, and therefore higher velocity compared with a round-edged obstruction.
** FLC values based on the approach velocity will be higher than those based on the structure velocity to achieve the same energy loss.
* Applying a blockage equivalent to the obstruction width will increase, usually very slightly, the velocity of the 1D channel or 2D cell face. This won’t be the vena-contracta velocity, but a velocity between the approach velocity and the vena-contracta velocity. A greater blockage will need to be applied to emulate the vena-contracta velocity.
* If the FLC source value is based on:
** The approach velocity then there is no need to apply a blockage value.
** The structure velocity then the blockage value should be applied noting that it may be appropriate to apply a larger blockage to take into account the vena-contracta.
* If it is not clear or unknown whether the FLC source value is based on the approach or structure velocity, the recommendation would be to apply the blockage in the interests of being slightly conservative on the upstream flood level calculation.
* For most minor obstructions such as bridge piers, the blockage is usually relatively small and whether included or not has a negligible or minor affect on flood levels compared with other factors such as the approach embankments and the bridge deck.
* Blockage from debris wrapped around piers can have a greater influence on the results than the effect of applying or not applying a blockage. Debris wrapped around piers can be accounted for in the FLC value calculated for the pier layer.
* As always, sensitivity testing with and without blockage and +/- the FLC value is highly recommended to understand their importance in regard to the broader modelling objectives and the effects of uncertainties in the input data, boundaries, other parameters such as Manning’s n values, and the accuracy of the numerical solution scheme (see [https://www.tuflow.com/library/webinars/#maximise_accuracy Maximising the Accuracy of Hydraulic Models webinar]).
[[File: Vena_contracta.png]] 
''Image showing the formation of the vena-contracta.'' 
 

==I don't see results that I expect when using 2d_lfcsh layer==
The 2d_lfcsh layer is a versatile feature that was designed to model bridges in 2D, but can also be used for other applications like fences, buildings raised on pillars and so on.
Some of the unexpected results could be:
* Water level going through the bridge deck in 2D map output.
* Water transiting through 100% blocked Layer 1, e.g. fences with solid base.
* SHMax.csv reporting values above the bridge deck when 2D map output reports water level lower than the top of the bridge deck.

TUFLOW is a 2D solution (not 3D), in the 2d_lfcsh layer the percent blockage and form loss coefficient applied to the cell faces is depth averaged across the entire cell face (across Layer 1, 2 and 3): 
*For bridges, where Layer 2 has a 100% blockage applied, the minimum flow width of 0.001m is used and is averaged with the Layer 1 blockage (based on the depth of the water). This may result in a water level being reported within or above the bridge deck, which would represent the pressure head.
*Layered flow constriction works by adjusting the flow area of the cell faces by any blockages to generate the correct depth averaged velocity at each face at which the form losses are applied as a fraction of the V2/2g kinetic energy. Calculating the correct velocity is critical for determining the losses as the losses are proportional to the velocity squared. 
*For a layered flow constriction cell face the flow area cannot be zero above the invert of Layer 1 to avoid a divide by zero in the computations, therefore a minimum average flow width after applying blockages of 0.001 m is applied. if Layer 1 is 100% blocked, a very small amount of water will flow through Layer 1. If this is unacceptable, instead of applying 100% blockage of Layer 1, the preferred approach is to start the layered flow constriction at the top of Layer 1 or raise the ground elevation to the top of Layer 1 using one of the Z Shape modification functions (e.g. a breakline). 
<ol>
[[File:100% Blockage Diagram.png | 500px]]
</ol>

== Can I model bridge piers explicitly in 2D using very small cells? ==
It isn't recommended to explicitly model bridge piers by blocking out the pier faces in TUFLOW, or in any hydraulic modelling software based on solving Shallow Water Equations(SWE). Due to the 3-dimentiality of the flow and turbulence around a pier, computational fluid dynamics (CFD) approach is often required to simulate the flow around piers explicitly. The wake turbulence behind a simple-shape pier can be resolved to some extent using extremely fine mesh in TUFLOW (see calibration example to a flume experiment in the [https://www.tuflow.com/library/webinars/#structures webinar on Energy Losses at Structures]), however the predictions for head losses show notable sensitivities to the mesh size, the mesh design, and the choice of turbulence model. The extremely fine mesh resolution also results in significantly higher computational costs.

Therefore, the safest and strongly recommended approach with regard to establishing head losses and consequently flood levels, is to model the effects of such obstructions with form loss coefficients (applied to selected mesh cells) that have been derived from physical testing. This approach has been shown to provide the most consistent results across various mesh resolutions. It also has the added benefit that, by avoiding small cells in the mesh, it will provide much more efficient run times for flow solvers.

[[File:Flow round a cylinder.png]]

''The point of flow separation around an object has a major bearing on the drag coefficient and is not reliably reproduced by 2D or 3D software.''


== How to best convert flow constriction data (2d_fc or 2d_fcsh) into newer formats (2d_lfcsh or 2d_bg)? ==
The form loss parameters can be transferred from the flow constriction (2d_fc or 2d_fcsh) to the first layer of the layered flow constriction (2d_lfcsh) or pier layer of the 2d_bg. Definition of the remaining form loss and blockage layer inputs should follow the guidance outlined in [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 | 2D Layered Flow Constriction]] and [[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 | 2D BG Shape]] paragraphs. 
When using floating pontoon (type FD in the 2d_fc or 2d_fcsh) different setup might need to be used for different events. For large events when floating pontoon becomes fixed at the top of the supporting piles, standard 2d_lfcsh setup can be used. Smaller events when the pontoon is floating at different heights might require more sensitivity testing of the structure parameters to find out a setup the matches the reality as close as possible. 

== Should I model bridges in 1D or 2D Domain? ==
The recommended approach typically depends on the study objectives and if the channel upstream and downstream of the bridge is modelled in 1D or 2D. To preserve the momentum as accurately as possible the bridge should be modelled in the same dimension as the channel, e.g. 1d_nwk bridge if the channels is in 1D and 2d_bg or 2d_lfcsh if the channel is modelled in 2D. 
In 2D, the expansion/contraction losses are modelled based on the topography and don't need to be estimated as attributes as for 1D modelling. Also, for higher flows where the bridge is overtopped, 2D is preferable approach.

== What is the difference between downstream and upstream controlled flow? ==
Downstream control means a change in downstream water level will cause a change in upstream water level. Upstream control means the upstream water level is insensitive to the downstream water level and usually indicates the occurrence of supercritical flow.

== What FLC values should be used for 2d_bg bridge if hB/T is below 2 or above 6? ==
TMR has extended the CFD simulation to hB/T ratios of 1 to 10. Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for details.

If hB/T is outside this ratio:
* hB/T ratios of less than 1 represent a very unusual bridge sitting low to the ground, and the peak FLC may increase above the end value (FLC of 0.6) in a way that doesn't follow the research trend or extrapolation. For these cases we would recommend using CFD modelling to obtain a more informed value. Alternatively, computing an FLC based on pressure flow or using 1D culvert might be considered.
* For hB/T ratios of greater than 10, the FLC is likely to continue to decrease, but probably not significantly. Clamping to the end value (FLC of 0.16) might be considered the more conservative approach (if the primary concern is flood levels upstream of the bridge). 
 
{{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

File:Incremental backwater coefficient 2018 pier losses.png

2026-04-08T05:47:21Z

Emilie Nielsen:

TUFLOW BC Advice

2026-04-08T05:35:07Z

Emilie Nielsen: /* I wish to use a PO line to monitor the flow exiting a model. Should I snap the PO line to the downstream boundary for this purpose? */

The following links provide useful boundary condition guidance to TUFLOW users.

* [[TS1_File_Format | TS1 File Format]]
* [[TUFLOW_NetCDF_Rainfall_Format|TUFLOW NetCDF Rainfall Format]]
* [[TUFLOW_Rainfall_Control_File_Examples | TUFLOW Rainfall Control File Examples]]
* [[TUFLOW_2D2D_BC_Advice| Multiple Domain 2D/2D Boundary Configuration Guidance]]
* [[TUFLOW_1D2D_Boundary_Configuration_Guidance| 1D/2D Boundary Configuration Guidance (SX and HX)]]
=Frequently Asked Questions (FAQ)=
==I wish to use a PO line to monitor the flow exiting a model. Should I snap the PO line to the downstream boundary for this purpose?==
Plot Output (PO) Q lines report model flow results for water crossing the digitised line. Computationally, TUFLOW transposes the digitised PO line to the closest adjacent cell face for the output calculation. In addition to this, TUFLOW requires an active 2D cell on either side (upstream and downstream) of the cell face for the calculation. Collectively, these requirements are necessary for accurate flow calculations irrespective of the orientation of the PO line relative to the cell alignment. 
It is best practice to snap 2D boundary condition lines, such as HT, QT and HQ, to the extent of the 2D code active area polygon at an orientation roughly perpendicular to the expected flow direction. This model design requirement means the 2D boundary condition lines are located along the outermost 2D cells in a model. Snapping a 2D PO line to the 2D boundary condition may align segments of the Plot Output (PO) Q result inspection line along the outermost cell faces of the model. This does not comply with TUFLOW’s requirement for an active 2D cell on either side of the Plot Output (PO) Q result inspection line. As a result, snapping a 2D PO line to the 2D boundary condition line may underestimate the flow exiting a model. For this reason, Plot Output (PO) Q lines should NOT be snapped to 2D boundary condition lines. The PO line should be defined immediately upstream of the downstream boundary. Use the [[Check_Files_2d_PO|po_check]] and [[Check_Files_2d_grd|grd_check]] files to review the PO line location to ensure there are active cells each side of the PO line.

The image below shows a downstream 2d_bc boundary condition line (HQ) in purple, snapped to the edge of the 2d_code polygon. A 2d_po line (blue arrow) has been digitised just upstream of the boundary. The [[Check_Files_2d_PO|po_check]] and [[Check_Files_2d_grd|grd_check]] files have been loaded in to confirm that there is an active 2D cell on either side of the 2d_po line. 
 
[[File:BC_advice_01.png]]

== Can TUFLOW model a waterfall? ==
Yes, TUFLOW can model waterfalls, but it requires careful handling of supercritical flow conditions.

As water approaches a waterfall, it speeds up and transitions into free fall. To ensure realistic behaviour, the model must allow for this acceleration rather than imposing an artificial depth at the brink.

Here are three suggested approaches in TUFLOW:

# '''HQ (Water Level versus Flow) Boundary:''' Defining a custom HQ curve ensures the model correctly represents the flow acceleration before the waterfall.
# '''Steep Slope HQ Boundary:''' Setting a higher slope value in the automatic HQ boundary can also generate supercritical conditions near the outlet.
# '''2D HPC Weir:''' Modelling a small drop in 2D cell elevations with a weir structure can better reflect natural waterfall hydraulics.

It is also recommended to run sensitivity tests with different boundary setups to check how the downstream conditions influence the model results.{{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

File:BC advice 01.png

2026-04-08T05:34:30Z

Emilie Nielsen:

TUFLOW Example Models

2026-04-08T05:05:49Z

Emilie Nielsen: /* Example Model Catalogue */

=Introduction=
These example models have been developed to demonstrate the most common TUFLOW model design features and applications. This dataset is useful for experienced modellers wishing to further develop their skills via demonstration examples. Although the models are based on the TUFLOW tutorial model dataset, new users are encouraged to familiarise themselves with TUFLOW through the [[Tutorial_Introduction |Tutorial Model Introduction]] before using this dataset. Unlike the tutorials, this dataset does not include step-by-step instructions / documentation. Users of this dataset are expected to have a basic knowledge TUFLOW, and have suitable skills to open the model files by referencing the TUFLOW Control File (TCF) referenced in the feature catalogue list below. 

=Example Model Data=
The model data is available for download from https://downloads.tuflow.com/TUFLOW/Wiki_Example_Models/TUFLOW_Example_Model_Dataset.zip 
The dataset only includes model input files. The models can be run to create simulation check and result files. Batch files (*.bat) for each of the example feature categories has been provided within the "runs" folder of the TUFLOW project. 

If you are unfamiliar with using batch files, additional information explaining how to use them to execute multiple simulations is available here: [[Run_TUFLOW_From_a_Batch-file| Run TUFLOW From a Batch-file]].

=Example Model Catalogue=
Below is a complete list of the example models. This dataset uses TUFLOW HPC as the computational engine.

Click on the following shortcuts to skip directly to the targeted major feature category in the table below: 
*[[TUFLOW_Example_Models#Project Initiation| Project Initiation]]
*[[TUFLOW_Example_Models#Model Units| Model Units]]
*[[TUFLOW_Example_Models#Solver Options| Solver Options]]
*[[TUFLOW_Example_Models#Output Options| Output Options]]
*[[TUFLOW_Example_Models#Boundary Condition Options| Boundary Condition Options]] (Inflows, Outflows, Losses)
*[[TUFLOW_Example_Models#Topography Features| Topography Features]] (Static Updates, Dynamic Updates, Sub-Grid Sampling)
*[[TUFLOW_Example_Models#Structures| Structures]] (Bridges, Weirs, Culverts, Operational Controls)
*[[TUFLOW_Example_Models#Multiple Domain Model Design| Multiple Domain Model Design]] (2D/2D Quadtree, 1D open channel / 2D floodplain, 1D pipe network / 2D floodplain)
*[[TUFLOW_Example_Models#Bulk Simulation Management| Bulk Simulation Management]]
*[[TUFLOW_Example_Models#Advection Dispersion| Advection Dispersion]]
*[[TUFLOW_Example_Models#Non-Newtonian | Non-Newtonian]]
*[[TUFLOW_Example_Models#Mathematical Operations| Mathematical Operations]]

{| class="wikitable" style="text-align:center;"
! colspan="4" style="position:sticky; top:0; background-color:#005581; font-weight:bold; color:white; z-index:2;" | Example Model Catalogue
|-
! colspan="2" style="position:sticky; top:2.2em; background-color:#fff; font-weight:bold; z-index:2;" | Model Category
! style="position:sticky; top:2.2em; background-color:#fff; font-weight:bold; z-index:2;" | Description
! style="position:sticky; top:2.2em; background-color:#fff; font-weight:bold; z-index:2;" | Model Name
|-
| colspan="2" id="Project Initiation" | Project Initiation
| Write empty files
| Create_Empties.tcf
|-

|-
| colspan="2" rowspan="2" id="Model Units" |Model Units
|Basic 2D model (SI units - m)
|EG00_001.tcf
|-
|Basic 2D model (US units - ft)
|EG00_002.tcf
|-

|-
| colspan="2" rowspan="8" id="Solver Options" |Solver Options
|TUFLOW Classic
|Refer to [[TUFLOW_Classic_Example_Model_Archive| TUFLOW Classic Example Model Archive]]
|-
|TUFLOW HPC - Sub-Grid Sampled (SGS) topography enabled
|EG01_002.tcf
|-
|TUFLOW HPC - Sub-Grid Sampled (SGS) topography disabled
|EG01_003.tcf
|-
|TUFLOW HPC - Multiple GPU cards
|EG01_004.tcf
|-
|TUFLOW HPC - Newtonian Viscosity (Wu Turbulence)
|EG01_006.tcf
|-
|TUFLOW HPC - Newtonian Viscosity (Smagorinsky)
|EG01_007.tcf
|-
|TUFLOW HPC - Quadtree
|See Section [[TUFLOW_Example_Models#Multiple Domain Model Design| EG13]]
|-
|ESTRY
|See Section [[TUFLOW_Example_Models#1D Culverts, Bridges, Weirs| EG11]], [[TUFLOW_Example_Models#1D Operating Structures| EG12]], [[TUFLOW_Example_Models#1D Pipe Network / 2D Floodplain Modelling| EG15]]
|-

| colspan="2" rowspan="19" id="Output Options" |Output Options
|2D xmdf (binary time series) and grid (maximums) output
|EG02_001.tcf
|-
|Time and duration of inundation (Time Output Cut-off = Depth)
|EG02_002.tcf
|-
|Time and duration of inundation (Time Output Cut-off = VxD)
|EG02_003.tcf
|-
|Time and duration of inundation (Time Output Cut-off = Hazard)
|EG02_004.tcf
|-
|Gauge level map output interval control (2d_glo)
|EG02_005.tcf
|-
|2D SGS high resolution grid output
|EG02_006.tcf
|-
|2D SGS high resolution grid output with manual specification of output resolution
|EG02_007.tcf
|-
|Output Zone (2d_oz)
|EG02_008.tcf
|-
|Write Restart File (See EG06_004.tcf for Read Restart File)
|EG02_009.tcf
|-
|2D plot output (2d_po point, line and region)
|EG02_010.tcf
|-
|2D structure outputs
|EG02_011.tcf
|-
|2D Long Profile (2d_lp)
|EG02_012.tcf
|-
|1D/2D Reporting locations - 1D river (1d_nwk), 2D floodplain
|EG02_013.tcf
|-
|1D/2D Reporting locations - 1D pipe network (1d_nwk), 2D floodplain
|EG02_014.tcf
|-
|Evacuation route inundation reporting (2d_zshr) (Route Cut Off Type = Depth)
|EG02_015.tcf
|-
|Evacuation route inundation reporting (2d_zshr) (Route Cut Off Type = Velocity)
|EG02_016.tcf
|-
|Evacuation route inundation reporting (2d_zshr) (Route Cut Off Type = VxD)
|EG02_017.tcf
|-
|Evacuation route inundation reporting (2d_zshr) (Route Cut Off Type = Hazard)
|EG02_018.tcf
|-
|Translating gauge data information to catchment receptors (Read GIS Objects)
|EG02_019.tcf

|-
| rowspan="52" id="Boundary Condition Options" |Boundary Condition Options
| rowspan="19" id="Inflows" |Inflows
|2D flow (m^3/s) vs time upstream inflow (2d_bc, QT)
|EG03_001.tcf
|-
|2D head (m) vs time upstream inflow (2d_bc, HT)
|EG03_002.tcf
|-
|Internal catchment inflow (m^3/s)(2d_sa)
|EG03_003.tcf
|-
|Internal catchment inflow (m^3/s) with streamlines (2d_sa, 2d_strm)
|EG03_004.tcf
|-
|Internal catchment rainfall (mm) (2d_sa_rf)
|EG03_005.tcf
|-
|Direct rainfall (mm) (2D Global Rainfall)
|EG03_006.tcf
|-
|Direct rainfall (mm) (2d_rf)
|EG03_007.tcf
|-
|Direct rainfall (mm) (Rainfall Control File - IDW)
|EG03_008.tcf
|-
|Direct rainfall (mm) (Rainfall Control File - TIN)
|EG03_009.tcf
|-
|Direct rainfall (mm) (Rainfall Control File - Poly)
|EG03_010.tcf
|-
|Direct rainfall (mm) (time varying gridded rainfall) - netcdf format
|EG03_011.tcf
|-
|Direct rainfall (mm) (time varying gridded rainfall) - flt format
|EG03_012.tcf
|-
|Direct rainfall (mm) (2d_rf) - negative rainfall
|EG03_013.tcf
|-
|Direct rainfall (2d_rf) and internal catchment rainfall (2d_sa_rf) for buildings
|EG03_014.tcf
|-
|HEC-DSS flow (m^3/s) vs time upstream inflow (2d_bc, QT)
|EG03_015.tcf
|-
|HEC-DSS flow (m^3/s) vs time upstream inflow (2d_bc, QT, multiple events)
|EG03_016.tcf
|-
|1D flow (m^3/s) vs time upstream inflow (1d_bc, QT)
|EG14_001.tcf
|-
|1D flow (m^3/s) vs time internal inflow (1d_bc, QT)
|EG14_002.tcf
|-
|1D flow (m^3/s) vs time internal inflow to 1D pits (1d_bc, QT)
|EG14_003.tcf
|-

| rowspan="6" id="Outflows" |Outflows
|2D Automatic stage discharge downstream boundary (2d_bc, HQ)
|EG04_001.tcf
|-
|2D User-specified stage discharge downstream boundary (2d_bc, HQ)
|EG04_002.tcf
|-
|2D Stage time downstream boundary (2d_bc, HT)
|EG04_003.tcf
|-
|1D Automatic stage discharge downstream boundary (1d_bc, HQ)
|EG04_004.tcf
|-
|1D User-specified stage discharge downstream boundary (1d_bc, HQ)
|EG04_005.tcf
|-
|1D Stage time downstream boundary (1d_bc, HT)
|EG04_006.tcf
|-

| rowspan="19" id="Loss Options" |Loss Options
|Rainfall excess loss approach - IL/CL (Global loss applied via the TBC file)
|EG05_001.tcf
|-
|Rainfall excess loss approach - IL/CL (applied via the materials file)
|EG05_002.tcf
|-
|Infiltration loss approach - IL/CL
|EG05_003.tcf
|-
|Infiltration loss approach - IL/CL, porosity
|EG05_004.tcf
|-
|Infiltration loss approach - IL/CL, porosity, initial moisture
|EG05_005.tcf
|-
|Infiltration loss approach - Green Ampt (USDA soil type)
|EG05_006.tcf
|-
|Infiltration loss approach - Green Ampt (USDA soil type), initial moisture
|EG05_007.tcf
|-
|Infiltration loss approach - Green Ampt (USDA soil type), initial moisture, ponding
|EG05_008.tcf
|-
|Infiltration loss approach - Green Ampt (User specified soil properties)
|EG05_009.tcf
|-
|Infiltration loss approach - Green Ampt (User specified soil properties), initial moisture
|EG05_010.tcf
|-
|Infiltration loss approach - Green Ampt (User specified soil properties), initial moisture, ponding
|EG05_011.tcf
|-
|Infiltration loss approach - Horton
|EG05_012.tcf
|-
|Infiltration loss approach - Horton, porosity
|EG05_013.tcf
|-
|Infiltration loss approach - Horton, porosity, initial moisture
|EG05_014.tcf
|-
|Groundwater - no horizontal infiltration
|EG05_015.tcf
|-
|Groundwater - 1 soil layer, horizontal hydraulic conductivity
|EG05_016.tcf
|-
|Groundwater - 2 soil layers, horizontal hydraulic conductivity
|EG05_017.tcf
|-
|Groundwater level versus time downstream boundary (2d_bc, GT)
|EG05_018.tcf
|-
|Groundwater linking to 1D
|EG05_019.tcf
|-

| rowspan="8" id="Other" |Other
|Spatially varied initial water level commands (2d_iwl)
|EG06_001.tcf
|-
|Spatially varied initial water level commands (Grid 2d_iwl)
|EG06_002.tcf
|-
|2D pump (2d_bc, SH)
|EG06_003.tcf
|-
|Read Restart File (See EG02_009.tcf for Write Restart File)
|EG06_004.tcf
|-
|Storage Reduction Factor (global specification)
|EG06_005.tcf
|-
|Storage Reduction Factor (2d_srf) (location specific update)
|EG06_006.tcf
|-
|External Stress - Wind (global specification)
|EG06_007.tcf
|-
|Dynamic Topography Options (Dam / Levee Failure)
|See Section [[TUFLOW_Example_Models#Dynamic Topography Updates| EG08]]

|-
| rowspan="28" id="Topography Features" |Topography Features
| rowspan="12" id="Static Topography Updates" |Static Topography Updates
|Cell resolution change
|EG07_001.tcf
|-
|Thin breakline topography update (2d_zsh_L, 2d_zsh_P)
|EG07_002.tcf
|-
|Thick breakline topography update (2d_zsh_L, 2d_zsh_P)
|EG07_003.tcf
|-
|Gully (Min) breakline topography update (2d_zsh_L, 2d_zsh_P)
|EG07_004.tcf
|-
|Ridge (Max) breakline topography update (2d_zsh_L, 2d_zsh_P)
|EG07_005.tcf
|-
|Region update - Absolute value change, No merge (2d_zsh_R)
|EG07_006.tcf
|-
|Region update - Relative value change, No merge (2d_zsh_R)
|EG07_007.tcf
|-
|Region update - Absolute value change, Partial merge (2d_zsh_R, 2d_zsh_P)
|EG07_008.tcf
|-
|Region update - Feature removal (2d_zsh_R)
|EG07_009.tcf
|-
|Advanced topography update - TIN (2d_ztin_R, 2d_ztin_P)
|EG07_010.tcf
|-
|Advanced topography update - TIN (2d_ztin_R, 2d_ztin_L, 2d_ztin_P)
|EG07_011.tcf
|-
|Depth varying Manning's n
|EG07_012.tcf
|-
| rowspan="13" id="Dynamic Topography Updates" |Dynamic Topography Options (Dam / Levee Failure)
|2D embankment failure - Time trigger, linear evolution
|EG08_001.tcf
|-
|2D embankment failure - Time trigger, non-linear evolution
|EG08_002.tcf
|-
|2D embankment failure - Water level trigger, linear evolution
|EG08_003.tcf
|-
|2D embankment failure - Water level trigger, non-linear evolution
|EG08_004.tcf
|-
|2D embankment failure - Water level difference trigger, linear evolution
|EG08_005.tcf
|-
|2D embankment failure - Water level difference trigger, non-linear evolution
|EG08_006.tcf
|-
|2D flood barrier reinstatement - Time trigger
|EG08_007.tcf
|-
|2D flood barrier reinstatement - Water level trigger
|EG08_008.tcf
|-
|2D flood barrier reinstatement - Water level difference trigger
|EG08_009.tcf
|-
|1D piping failure transitioning to 1D dam failure - Time trigger
|EG08_010.tcf
|-
|1D dam failure - Time trigger
|EG08_011.tcf
|-
|1D piping failure transitioning to 1D dam failure - Water level trigger
|EG08_012.tcf
|-
|1D dam failure - Water level trigger
|EG08_013.tcf
|-
| rowspan="3" id="Sub Grid Sampling" |Sub Grid Sampling
|Breakline detection delta tool
|EG09_001.tcf
|-
|2D SGS high resolution grid output
|EG09_002.tcf
|-
|2D SGS high resolution grid output with manual specification of output resolution
|EG09_003.tcf
|-
| rowspan="37" id="Structures" |Structures
| rowspan="9" id="2D Structures" |2D Structures
|Bridge (2d_fc)
|Refer to [[TUFLOW_Classic_Example_Model_Archive| TUFLOW Classic Example Model Archive]]
|-
|Bridge (2d_fcsh)
|Refer to [[TUFLOW_Classic_Example_Model_Archive| TUFLOW Classic Example Model Archive]]
|-
|Bridge - horizontal deck (2d_lfcsh)
|EG10_003.tcf
|-
|Bridge - variable deck form geometry (2d_lfcsh)
|EG10_004.tcf
|-
|Bridge - horizontal deck (2d_bg)
|EG10_005.tcf
|-
|2D weir coefficient change (global specification)
|EG10_006.tcf
|-
|2D weir coefficient change (location specific update)
|EG10_007.tcf
|-
|Bridge (2d_bg) - horizontal deck, auto superstructure FLC
|EG10_008.tcf
|-
|Fences (2d_lfcsh)
|EG10_009.tcf
|-

| rowspan="14" id="1D Structures" |1D Structures
|1D culverts - Circular and Box type. SX point, line and region 1D/2D examples
|EG11_001.tcf
|-
|1D culverts - Irregular shape (e.g. Arch)
|EG11_002.tcf
|-
|1D culverts - Unidirectional structures (flapgate) (1d_nwk)
|EG11_003.tcf
|-
|1D culverts - ARR2019 blockage matrix (1d_nwk)
|EG11_~e1~_~e2~_004.tcf
|-
|1D M channel - User defined flow matrix (1d_nwk)
|EG11_005.tcf
|-
|1D Q channel - Upstream Depth-Discharge Relationship (1d_nwk)
|EG11_006.tcf
|-
|Bridge (1d_nwk, 1d_bg)
|EG11_007.tcf
|-
|Weir (1d_nwk)
|EG11_008.tcf
|-
|Pump (1d_nwk) - pump curve
|EG11_009.tcf
|-
|Sluice gate (1d_nwk)
|EG11_010.tcf
|-
|Gated spillway (1d_nwk)
|EG11_011.tcf
|-
|Arch bridge (1D), no orifice flow
|EG11_012.tcf
|-
|Arch bridge (1D), orifice flow enabled
|EG11_013.tcf
|-
|Arch bridge (1D), orifice flow enabled with calibration factor
|EG11_014.tcf
|-

| rowspan="14" id="1D Operating Structures" |1D Operating Structures
|Pump operational (1d_nwk) - time trigger
|EG12_001.tcf
|-
|Pump operational - 1D water level trigger (1d_nwk)
|EG12_002.tcf
|-
|Pump operational - 2D water level trigger (1d_nwk)
|EG12_003.tcf
|-
|Pump operational - Depth above structure invert trigger (1d_nwk)
|EG12_004.tcf
|-
|Q flow matrix - Operation based on water level trigger (1d_nwk)
|EG12_005.tcf
|-
|Q flow matrix - Operation based on water level trigger and time delay (1d_nwk)
|EG12_006.tcf
|-
|Sluice gate operational - Time trigger (simulation time) (1d_nwk)
|EG12_007.tcf
|-
|Sluice gate operational - Water level trigger(1d_nwk)
|EG12_008.tcf
|-
|Gated spillway operational - Time trigger (Day) (1d_nwk)
|EG12_009.tcf
|-
|Gated spillway operational - Water level trigger (1d_nwk)
|EG12_010.tcf
|-
|Coordinated operation (multiple interacting structures) - Pump and Gated Spillway
|EG12_011.tcf
|-
|Coordinated operation controlled by status of another structure
|EG12_012.tcf
|-
|Pump operational (1d_nwk) - pump curve
|EG12_013.tcf
|-
|Pump operational (1d_nwk) - Time stamp after water level trigger
|EG12_014.tcf
|-

| rowspan="17" id="Multiple Domain Model Design" |Multiple Domain Model Design
| rowspan="5" id="2D/2D Modelling" |2D/2D Modelling
|TUFLOW HPC - Quadtree: Sample target distance
|EG13_001.tcf
|-
|TUFLOW HPC - Quadtree: Sample frequency nesting
|EG13_002.tcf
|-
|TUFLOW HPC - Quadtree: Memory efficient pre-processing
|EG13_003.tcf
|-
|TUFLOW HPC - Quadtree: Sample frequency
|EG13_004.tcf
|-
|TUFLOW Classic - M2D
|Refer to [[TUFLOW_Classic_Example_Model_Archive| TUFLOW Classic Example Model Archive]]
|-
| rowspan="1" id="1D Open Channel / 2D Floodplain Modelling" |1D Open Channel / 2D Floodplain Modelling
|1D river (1d_nwk), 2D floodplain
|EG14_001.tcf
|-

| rowspan="11" id="1D Pipe Network / 2D Floodplain Modelling" |1D Pipe Network / 2D Floodplain Modelling
|1D pipe network (1d_nwk), 2D floodplain, 2d_sa_rf inflow (mm) to 1D pits
|EG15_000.tcf
|-
|1D pipe network (1d_nwk), 2D floodplain, 2d_sa inflow (m^3/s) to 1D pits
|EG15_001.tcf
|-
|1D pipe network (1d_nwk), 2D floodplain, 2d_rf direct rainfall
|EG15_002.tcf
|-
|1D pipe network (1d_nwk), 2D / 2D floodplain quadtree
|EG15_003.tcf
|-
|1D pipe network (1d_nwk), manually specified manholes (1d_mh), 2D floodplain
|EG15_004.tcf
|-
|1D pipe network (1d_nwk), non-default (fixed) manhole loss method, 2D floodplain
|EG15_005.tcf
|-
|1D pipe network (1d_nwk), localised manually specified manhole losses, 2D floodplain
|EG15_006.tcf
|-
|1D virtual pipes, 2D floodplain
|EG15_007.tcf
|-
|1D virtual pipes connected to 1D pipe network (trunk drainage line), 2D floodplain
|EG15_008.tcf
|-
|1D storage tank (1d_na)
|EG15_009.tcf
|-
|1D storage tank (1d_nwk)
|EG15_010.tcf
|-

| rowspan="6" id="Bulk Simulation Management" |Bulk Simulation Management
| rowspan="6" id="Scenario / Event Management" |Scenario / Event Management
|Scenario (single)
|EG16_~s1~_001.tcf
|-
|Scenario (multiple)
|EG16_~s1~_~s2~_002.tcf
|-
|Set Variable
|EG16_~s1~_~s2~_003.tcf
|-
|Event (single)
|EG16_~e1~_004.tcf
|-
|Event (multiple)
|EG16_~e1~_~e2~_005.tcf
|-
|Scenario (multiple), Event (multiple), Set Variable
|EG16_~s1~_~s2~_~e1~_~e2~_006.tcf
|-

| rowspan="10" id="Other" |Other
| rowspan="3" id="Advection Dispersion" |Advection Dispersion
|Advection Dispersion
|EG17_001.tcf
|-
|Advection Dispersion with settling
|EG17_002.tcf
|-
|Advection Dispersion with decay
|EG17_003.tcf
|-
| rowspan="2" id="Non-Newtonian" |Non-Newtonian
|Non-newtonian viscosity
|EG18_001.tcf
|-
|Non-newtonian mixing (dam failure scenario)
|EG18_002.tcf
|-
| rowspan="5" id="Mathematical Operations" |Mathematical Operations
|Unit Conversion
|EG19_001.tcf
|-
|Using Variables
|EG19_~e1~_~e2~_002.tcf
|-
|Adjust Event Variables
|EG19_~e1~_~e2~_003.tcf
|-
|Apply Loss Factors
|EG19_~e1~_~e2~_004.tcf
|-
|Logic Control
|EG19_005.tcf
|}

=Archive Dataset=
Historic example model datasets can be accessed via the following link: [[TUFLOW_Classic_Example_Model_Archive| TUFLOW Classic Example Model Archive]].

=Contact=
For comments, requests and feedback contact [mailto:support@tuflow.com support@tuflow.com]. 
For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 

 
{{Tips Navigation
|uplink=[[Main_Page| Back to Wiki Main Page]]
}}

TUFLOW 2D Hydraulic Structures

2026-04-07T23:27:15Z

Emilie Nielsen: /* 2D Structure Modelling Theory */

= 2D Structure Modelling Theory =
The theory behind the modelling of energy losses and affluxes of hydraulic structures is presented in the following webinars by Bill Syme and Greg Collecutt (TUFLOW Developers).

*[https://www.tuflow.com/library/webinars/#structures Webinar Link: Modelling Energy Losses at Structures] 
*[https://www.tuflow.com/library/webinars/#nov2022_hydraulic_modelling_bridge Webinar Link: 1D, 2D & 3D Hydraulic Modelling of Bridges]
 

= 2D Bridge Modelling in TUFLOW - Overview =
The TUFLOW 2D solution explicitly predicts the majority of “macro” losses due to the expansion and contraction of water through a constriction, or around a bend, provided the resolution of the grid is sufficiently fine ([https://www.tuflow.com/Download/Publications/Flow%20Through%20an%20Abrupt%20Constriction%20-%202D%20Hydrodynamic%20Performance%20and%20Influence%20of%20Spatial%20Resolution,%20Barton,%202001.pdf Barton, 2001]; [https://www.tuflow.com/Download/Publications/Modelling%20of%20Bends%20and%20Hydraulic%20Structures%20in%20a%202D%20Scheme,%20Syme,%202001.pdf Syme, 2001]; [https://www.tuflow.com/Download/Technical_Memos/Modelling%20Bridge%20Piers%20in%202D%20using%20TUFLOW.pdf Ryan, 2013]). Where the 2D model is not of fine enough resolution to simulate the “micro” losses (e.g. from bridge piers, vena contracta, losses in the vertical (3rd) dimension), additional form loss coefficients and/or modifications to the cells widths and flow height need to be added.
==Contraction/Expansion Losses (“Macro” Losses)==
Loss of energy is caused by the flow contraction during the expansion of water after the vena-contracta inside a bridge section and the flow expansion downstream a bridge. As discussed above, this type of "macro" losses can be explicitly resolved by the TUFLOW 2D solver, provided that a proper turbulence model and mesh size are used. Below is an example of the 2D modelling of flow contraction/expansion at a pair of bridge abutments.
 
[[File:FC_Velocity_Example.PNG|600px]] 

==Pier Losses==
Piers are usually smaller than the 2D cell size in real-world flood models. Although flexible mesh solver or quadtree refinement can be applied to reduce the local cell size around the pier, it also comes with an expensive computational cost that could significantly increase the simulation time. More practically, the backwater effect of piers can be modelled as sub-grid form losses.

Pier form loss coefficients can be derived from information in publications such as [https://www.fhwa.dot.gov/engineering/hydraulics/library_arc.cfm?pub_number=1&id=5 ''Hydraulics of Bridge Waterways'' (Bradly, 1978)] or [https://austroads.com.au/publications/bridges/agbt08 ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018)]. Energy loss estimated from bridge piers or other obstructions, vertical or horizontal, that do not cause upstream controlled flow regimes like pressure flow, are dependent on the ratio of the obstruction's area perpendicular to the flow direction to the gross flow area of the bridge opening, the shape of the piers or obstruction, and the angularity of the piers/obstruction to the flow direction. For example, using Hydraulics of Bridge Waterways (Bradly, 1978) the approach is:
<ol>
<li>Calculate the ratio of the water area occupied by piers to the gross water area of the constriction (both based on the normal water surface) and the angularity of the piers. These inputs are used to calculate "J" in the FHA documentation.</li>
<li>Use the Figure 7 ''Incremental Backwater Coefficient for Piers'' data to calculate Kp. 
[[File:FHA_Kp_arrow_crop.png|400px]]
 
'''NOTE''': the pier form loss coefficients in Hydraulics of Bridge Waterways are derived based on the cross-sectional averaged velocity through the bridge opening in the absence of piers. It's not necessary to specify a blockage value if a pier form loss coefficient estimated from this method is used.
</li>
</ol>

==Bridge Deck and Rail (Super Structure)==
When a bridge deck become partially or completely submerged, the deck could generate extra afflux resulting in increased water levels and flood extents upstream of the structure. The flow around the deck is highly 3-dimentional and complexed due to the different deck designs/profiles and/or the occurrence of pressure flow. In 2D SWE solver, depth-varying form loss values are often needed to reproduce the afflux caused by such structure. Due to the complexity of the flow, guidelines on how to set the form loss coefficient for the bridge deck are rare. We have carried out a joint research with QLD TMR (Queensland Department of Transport and Main Roads) regarding how to choose a proper form loss value for the bridge deck [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)] . In the research, CFD modelling was conducted to investigate the characteristics of energy loss of a simple bridge with a flat bottomed deck and guardrails.
 
[[File:CFD_study.png|600px]]

Below are the key findings from the study:
*The results displayed a characteristic shape for head loss coefficient as a function of downstream water level over the deck thickness (TW/T).
*The head loss (afflux) peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out.
[[File:FormLoss_vs_TWT.png|600px]]
 

=== Bridge Design (hB/T) vs Form Loss Coefficient Table===
The peak loss coefficient value is a function of the ratio of the depth underneath the deck (hB) and the thickness of the deck (T). This table can be used to estimate the deck form loss coefficient based on the bridge design (hB/T).
<ol>
{| style="text-align: center;" class="wikitable" width="35%"
! style="background-color:#005581; font-weight:bold; color:white;" width=55%| Deck Height to Thickness Ratio
! style="background-color:#005581; font-weight:bold; color:white;" width=45%| Peak Form Loss Coefficient
|-
| Scenario A (hB/T) = 2 || 0.42
|-
| Scenario B (hB/T) = 4 || 0.28
|-
| Scenario C (hB/T) = 6 || 0.20
|}
</ol>

*The solid portion of the guard rails (blockage * rail depth) can be added to T in addition to the deck thickness to calculate hB/T.
*For bridge with more complicated designs (e.g. girders), higher form loss might be required due to the higher surface roughness of the bridge.
*If the hB/T ratio is less than 2 or greater than 6, use a peak form loss coefficient of 0.42 (minimum) or 0.20 (maximum), respectively.

'''NOTE''': This form loss value should not be confused with the value of 1.56 used in the pressure flow approached adopted in [[1D_Bridges | TUFLOW 1D "B" and "BB" bridge]]. TUFLOW 1D bridge pressure flow approach is based on the section 4.13.2 "All Girders in Contact with Flow (Case II)" of ''Guide to Bridge Technology Part 8: Hydraulic Design of Waterway Structures'' (AUSTROADS, 2018). The original hydraulic experiment conducted by [https://hdl.handle.net/10217/39009 Liu et al (1957)] in a laboratory flume with a pair of bridge abutments and a deck. The flow conditions were similar to orifice flow due to the high blockage ratio caused by the abutments and the deck. When modelling bridges in 2D, the contraction/expansion losses caused by the abutments would be handled explicitly by the 2D solver, so a value 1.56 can lead to duplication of the contraction/expansion losses caused by the bridge abutments. 
 

=TUFLOW 2D Bridge Setup=
There are two methods available to model depth varying form loss of a bridge structure:
* [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 |2D Layered Flow Constriction (2d_lfcsh)]]
:The traditional method used to model depth-varying form loss through bridge components such as piers, decks, and rails.

*[[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 |2D BG Shape (2d_bg)]] (introduced in the 2023 release)
:A simplified approach developed to simplify the model input based on the findings from the joint TMR Study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

Both methods provide options for representing flow surcharging, the pressure flow of bridge decks and eventually submerged bridge flow at higher water levels. During the surcharging of bridge decks, higher energy losses can be specified to simulate the pressure flow.

Examples for how to configure both approaches are provided in the 2D structures section of the [[TUFLOW_Example_Models#2D_Structures |TUFLOW Wiki Example Models]] and [[Tutorial_M04 |Tutorial Module 4]] - 2D Bridges.

==2D Layered Flow Constriction (2d_lfcsh)==
Four flow constriction layers are represented in a 2d_lfcsh layer. The lower three layers represents the pier, the bridge deck and the rails. Each layer has its own attributes to specify the blockage and the form loss coefficient. The top (fourth) layer assumes the flow is unimpeded, representative of flow over the top of a bridge. Within the same shape, the invert of the bed, and thickness of each layer can vary in 3D.

The following table provides an overview for how to determine the blockage and form loss coefficient for each layer: 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || Use calibration data, if available, to determine FLC. If no calibration is available, estimate using [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table || Full blockage, no flow through the deck
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 3 || Bridge rails || 10% – 100% || Use calibration data, if available, to determine FLC. 
If no calibration data is available, combined FLC for Layers 2 and 3 should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = L2_Depth + (pBlockage × L3_Depth)
*(pBlockage × L3_Depth) represents the solid portion of the rails
*L2 FLC and L3 FLC should sum to the combined FLC
|Blockage and FLC depends on rail type Sensitivity testing with 100% blockage is recommended due to potential for debris during flood
If using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, it is recommended to enable the Method C Form Loss Approach
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}
<ol>
[[File:2d_lfcsh_attributes.png | 500px ]]
</ol>
 

===Blockage===

The 2d_lfcsh functions by adjusting the flow width and the form loss of 2D cell faces. The combined blockage across the 4 layers is calculated at each simulation timesteps:
<ol>
 
[[File: Blockage_total_equation_01.png|600px]]
 
where 
'''''yi''''' is the actual depth of water in layer '''''i''''' 
'''''ytotal''''' is the total water depth 
</ol>

===Form Loss Approach===

The combined form loss coefficient is determined using one of three methods. The form loss coefficient method can be specified either individually using the 2d_lfcsh “Shape_Options” attribute or globally using the .tcf command: 
<tt>Layered FLC Default Approach == [ METHOD A | {METHOD B} | METHOD C | METHOD D]</tt> 

:METHOD A: The losses are accumulated as the water level rises through the layers. 
<ol>
[[File:Eq_flc_cumulate.png |450px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Applies the full accumulated form loss continuously, even when overtopping begins (no reduction)
:Note: Simpler method but tends to overestimate losses when the structure is submerged or overtopped 

:METHOD B (default): the losses are applied pro-rata according to the depth of water in each layer. 
<ol>
[[File:Eq_flc_portion.png |430px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Form loss increases based on the depth of water in layer 2 & 3; peak form loss at top of Layer 3
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure
:Note: Maintains backward compatibility but may underrepresent losses during pressurised or overtopped flows 

:METHOD C (recommended): hybrid approach combining Method A and Method B. 
<ol>
[[File:Eq_flc_methodC.png |520px]]
</ol>
:*Layer 1: Constant form loss (L1_FLC)
:*Layers 2 & 3: Gradual increase in form loss with water level, following Method A
:*Above Layer 3: Total form loss gradually reduces as water overtops the structure, following Method B
:Note: Recommended method; aligns closest to CFD modelling results and TUFLOW HPC behaviour.

:METHOD D: Allows the modeller to control the depth at which the losses start to reduce when the flow transitions between pressure flow and drowned flow.
:This approach is the same used by the 2d_bg layer (introduced in the 2023-03 release). It is recommended to use the 2d_bg layer as it has the benefit of a simplified attribute table, for easier user input.

===Form Loss Calibration Example - Iowa River Flood Study===

In this study, a combined form loss coefficient of 0.35 was used to match observed head loss during slight overtopping of a bridge. The FLC values for each layer were adjusted to achieve the correct combined form loss. The table and plot show how each layer contributes to the total form loss and highlight the differences in calculated form loss between the three methods.

{| style="text-align: left; margin-left: 0;" class="wikitable" width="60%"
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=6%| Layer
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=10%| Depth (m)
!colspan="1" rowspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=12%| Blockage (%)
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method A
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method B
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;" width=20%| Method C
|-
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Layer FLC
! style="background-color:#005581; font-weight:bold; color:white;"| Combined FLC
|-
| 1 || 5.0 || 5 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07 || 0.07
|-
| 2 || 1.5 || 100 || 0.15 || 0.22 || 1.05 || 0.30 || 0.15 || 0.22
|-
| 3 || 1.0 || 50 || 0.13 || 0.35 || 0.70 || 0.35 || 0.13 || 0.35
|}

</ol>
 
<ol>
[[File:FLC_vs_height_updated.png | 600px ]]
</ol>

==2D BG Shape (2d_bg)==
2D BG Shape is similar to the Layered Flow Constriction, but has several updates to simplify the input based on the findings from the joint study with TMR [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)].

The following table provides an overview of how to determine the blockage and form loss coefficient for each layer: 
{| style="text-align: left; margin-left: 0; " class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Description
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Form Loss Coefficient (FLC)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;"| Notes
|-

| 1 || Pier layer || ~5% (can be omitted if included in FLC) || Estimate using [[TUFLOW_2D_Hydraulic_Structures#Pier_Losses | Pier Losses]] || Represents flow obstruction from piers beneath the bridge deck
|-
| 2 || Bridge deck || 100% || rowspan="2" | The Super Structure (Super_S) is the bridge deck and rails layers combined. 
Use calibration data, if available, to determine FLC. 
If no calibration data is available, the Super_S FLC should be estimated using the [[TUFLOW_2D_Hydraulic_Structures#Bridge_Design_.28hB.2FT.29_vs_Form_Loss_Coefficient_Table | hB/T vs FLC]] table, where T = Deck_Depth + (Rail_pBlockage*Rail_Depth)
*(Rail_pBlockage*Rail_Depth) represents the solid portion of the rails
|| Full blockage, no flow through the deck
|-
| 3 || Bridge rails || 10% – 100% || Sensitivity testing with 100% blockage is recommended due to potential for debris during flood events
|-
| 4 || Above rails || 0% || 0 || Represents unimpeded overtopping flow
|}

<ol>
[[File:2d_bg_attributes.png | 700px ]]
</ol>

===Inflection Point===

Based on findings from the joint study [https://tuflow.com/media/7554/2022-bridge-deck-afflux-modelling-benchmarking-of-cfd-and-swe-codes-to-real-world-data-collecutt-et-al-hwrs.pdf (Collecutt et al, 2022)], the head loss peaks when the water level is approximately 1.6*T above the bridge soffit, and decays slowly as the bridge becomes progressively drowned out. The 'SuperS_IPf' attribute (inflection point factor, default = 1.6) can be used to define the height of the inflection point. The solid portion of the rail layer is also added to the deck thickness to calculate the depth to the inflection point (DIP), i.e.:
<ol>
[[File:eq_flc_bg_infection_point.png | 520px ]]
</ol>

===Form Loss Approach===
The form loss approach is similar to the FLC approach METHOD C, with L2/L3 replaced by a single super structure layer:
<ol>
[[File:eq_flc_bg.png | 480px ]]
</ol>

===Form Loss Calibration Example - Iowa River Flood Study===
This example uses the same bridge setup described in the[[TUFLOW_2D_Hydraulic_Structures#Form_Loss_Calibration_Example_-_Iowa_River_Flood_Study | 2D Layered Flow Constriction]] section, with the following parameters applied:
*SuperS_FLC = 0.28
*SuperS_Ipf = 1.6,
The Depth to Inflection Point (DIP) is calculated as 3.2m above the bridge soffit.

The table and figure below show how the form loss value varies with water depth.
<ol>
{| style="text-align: center;" class="wikitable" width="32%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Layer
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Depth (m)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Blockage (%)
!colspan="1" style="background-color:#005581; font-weight:bold; color:white;" width=8%| Form Loss
|-
| Pier || 5.0 || 5 || 0.07
|-
| Deck || 1.5 || 100 || rowspan="2" | 0.28
|-
| Rail || 1.0 || 50
|}

[[File:FLC_vs_height_bg.png | 600px ]]
</ol>

== 2D Bridges Line vs Polygon Layer ==
The form loss coefficient (FLC) is applied differently when using a line compared to a polygon for both 2d_lfcsh and 2d_bg inputs. The FLC is applied at cell sides (u and v faces) as this is where velocities are calculated. 
For larger bridges that spread across multiple cells, it is recommended to use a polygon layer, which selects all u and v faces falling within the polygon.
 
 
'''2D Layered Flow Constriction (2d_lfcsh)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides
| This approach is cell size independent. It is the easiest setup and the preferred / recommended approach when using 2d_lfcsh.
|-
| Thick
| between zero and 1.5 times the cell size
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| A cell is selected if the polyline intersects the cell crosshair. Caution should be taken when using a "thick" line, as changes in cell size can cause it to become a "wide" line. If this occurs, the FLC attribute may need to be recalculated to avoid overestimating or underestimating losses.
|-
| Wide
| larger than 1.5 times the cell size
| Total form loss of the bridge ''(may need to be recalculated, see notes)''
| FLC divided by number of cell sides in the direction of flow 
''(number of cell sides in the direction of flow is calculated as line width divided by cell size)''
| Polygon shapes are recommended if more than 3 rows of faces must be selected.. 
Caution should be taken when using a "wide" line. The cell size and alignment of the 2d_lfcsh line may result in selecting too many or too few cell faces in the direction of the flow. The FLC input may need to be recalculated to ensure FLC Applied multiplied by the number of cell sides in the direction of flow equates to the intended total form loss.
|-
!rowspan="1" | Polygon
| -
| -
| Total loss per unit length (meters or feet) in the direction of flow
| FLC * cell size applied to all sides of selected cells
|
|}

'''2D Bridge (2d_bg)'''
{| style="text-align: left; margin-left: 0;" class="wikitable" width="80%"
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Geometry
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 7.5%;"| Line Type
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 11%;"| Width Attribute
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Input
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 22%;"| FLC Applied
!colspan="1" style="background-color:#005581; font-weight:bold; color:white; width: 30%;"| Notes
|-
!rowspan="3" | Line
| Thin
| zero
| Total form loss of the bridge
| Applies the FLC to a single row of cell sides.
| This approach is cell size independent.
|-
| Thick
| larger than zero
| Total form loss of the bridge
| FLC/2 applied to all sides of the selected cells
| This approach is cell size independent. A cell is selected if the polyline intersects the cell crosshair.
|-
| Wide
| Not supported
| –
| –
| BG polygon shapes are recommended if more than 3 rows of faces must be selected.
|-
!rowspan="1" |Polygon
| -
| ''(used to automatically distribute the total FLC to the selected faces)''
| Total form loss of the bridge
| FLC / Deck_Width * cell size applied to all sides of selected cells
| For bridges modelled using a 2d_bg polygon the relative ratio of the bridge width to the 2D cell size should be 4 or greater. For more information on this see [https://downloads.tuflow.com/Other/2d_bg_R_Bridge_Configuration_Advice_202503.pdf 2d_bg_R_Bridge_Configuration_Advice.pdf].
|}
 
The following diagrams demonstrate how the input FLC is applied for the four geometry options for 2d_lfcsh and 2d_bg layers: 
[[File:2dlfcsh 2dbg combined v2.png|1200px]]

It is good modelling practice to check the [[Check_Files_2d_lfcsh_uvpt | lfcsh_uvpt_check]] and [[Check Files 2d bg uvpt check | bg_uvpt_check]] files to confirm the number of faces selected and the FLC values assigned. It is also strongly recommended to undertake a sensitivity analysis on the applied form losses in the model to check if it makes any difference to the results and/or double check against other methods (hand calculations, other software, CFD modelling), especially if the bridge is near an area of interest. If calibration data is available, this should be used to guide the form loss value specification. 
 

= Common Questions Answered (FAQ)=
== What blockage values should I use for bridge guard rails? ==
The blockage of bridge guard rails can be anything from 100% blocked (solid concrete rails) to 10% blocked (very open rails). In addition, the accumulation of debris during a flood can be substantial as shown in the image below. Sensitivity testing with 100% blockage is recommended.
 
[[File:Bridge rail debris.jpg | 500px]]

== How to conduct sensitivity test for 2D bridges? ==
General recommendations to cross-check the results are:
* Compare computed affluxes against desktop methods (e.g. Hydraulics of Bridge Waterways, 1978) and/or other software including CFD, especially for unusual bridge designs.
* Use any recorded flood marks or general observations from past events to check and calibrate FLC values.
* Conduct sensitivity testing by assessing the impact and influence of FLC values on your modelling objectives. The afflux resulting from the FLC values will be proportional to the velocity head, i.e. ∆h=FLC*(v^2/2g). As such, if velocities are low (e.g. 1 m/s), the results may not be overly sensitive to uncertainties in the FLC values. If completing a check using this equation for a long skew bridge it is best to calculate the total structure velocity from a PO line digitised in the same location as the bridge.

Finally, after completing sensitivity testing and understanding the range of uncertainty due to unknowns like the degree of blockage and influence of FLC values (e.g. +/-20%), you are in a position to discuss with your client how best to proceed. For example, if the modelling is to set planning levels for a development upstream then it may be appropriate to choose values on the higher side (higher FLC values and/or blockage assumptions), noting that the uncertainty may be amply covered by a regulatory freeboard. Conversely, if the development is on the downstream side the conservative approach would be to use the results at the lower end of your FLC/blockage values. 
[[File:Bridge Flood Debris Loading.jpg | 500px]] 

== Should I use both FLC and blockage for layer one in 2D bridge layered flow constriction? ==
When applying FLC and blockage values to model obstructions such as piers, the following considerations need to be taken into account:
* The FLC value applies an energy loss along 1D channels or across 2D cell faces equivalent to FLC*V2/2g where V is the 1D channel velocity or the 2D cell face velocity.
* FLC values are often sourced from publications such as Hydraulics of Bridge Waterways or AustRoads (e.g. Kp chart for piers).
* If possible, establish whether the source of the FLC value is based on the approach velocity (the velocity in the absence of piers) or structure velocity (the velocity with area blocked out by the piers) noting that it often isn’t clear or stated.
** If it is the structure velocity, this is usually the velocity at the vena-contracta (point of greatest contraction within the entrance to the structure and therefore highest velocity) - see image below. Bluff or sharp-edged obstructions will have a much more pronounced vena-contracta, and therefore higher velocity compared with a round-edged obstruction.
** FLC values based on the approach velocity will be higher than those based on the structure velocity to achieve the same energy loss.
* Applying a blockage equivalent to the obstruction width will increase, usually very slightly, the velocity of the 1D channel or 2D cell face. This won’t be the vena-contracta velocity, but a velocity between the approach velocity and the vena-contracta velocity. A greater blockage will need to be applied to emulate the vena-contracta velocity.
* If the FLC source value is based on:
** The approach velocity then there is no need to apply a blockage value.
** The structure velocity then the blockage value should be applied noting that it may be appropriate to apply a larger blockage to take into account the vena-contracta.
* If it is not clear or unknown whether the FLC source value is based on the approach or structure velocity, the recommendation would be to apply the blockage in the interests of being slightly conservative on the upstream flood level calculation.
* For most minor obstructions such as bridge piers, the blockage is usually relatively small and whether included or not has a negligible or minor affect on flood levels compared with other factors such as the approach embankments and the bridge deck.
* Blockage from debris wrapped around piers can have a greater influence on the results than the effect of applying or not applying a blockage. Debris wrapped around piers can be accounted for in the FLC value calculated for the pier layer.
* As always, sensitivity testing with and without blockage and +/- the FLC value is highly recommended to understand their importance in regard to the broader modelling objectives and the effects of uncertainties in the input data, boundaries, other parameters such as Manning’s n values, and the accuracy of the numerical solution scheme (see [https://www.tuflow.com/library/webinars/#maximise_accuracy Maximising the Accuracy of Hydraulic Models webinar]).
[[File: Vena_contracta.png]] 
''Image showing the formation of the vena-contracta.'' 
 

==I don't see results that I expect when using 2d_lfcsh layer==
The 2d_lfcsh layer is a versatile feature that was designed to model bridges in 2D, but can also be used for other applications like fences, buildings raised on pillars and so on.
Some of the unexpected results could be:
* Water level going through the bridge deck in 2D map output.
* Water transiting through 100% blocked Layer 1, e.g. fences with solid base.
* SHMax.csv reporting values above the bridge deck when 2D map output reports water level lower than the top of the bridge deck.

TUFLOW is a 2D solution (not 3D), in the 2d_lfcsh layer the percent blockage and form loss coefficient applied to the cell faces is depth averaged across the entire cell face (across Layer 1, 2 and 3): 
*For bridges, where Layer 2 has a 100% blockage applied, the minimum flow width of 0.001m is used and is averaged with the Layer 1 blockage (based on the depth of the water). This may result in a water level being reported within or above the bridge deck, which would represent the pressure head.
*Layered flow constriction works by adjusting the flow area of the cell faces by any blockages to generate the correct depth averaged velocity at each face at which the form losses are applied as a fraction of the V2/2g kinetic energy. Calculating the correct velocity is critical for determining the losses as the losses are proportional to the velocity squared. 
*For a layered flow constriction cell face the flow area cannot be zero above the invert of Layer 1 to avoid a divide by zero in the computations, therefore a minimum average flow width after applying blockages of 0.001 m is applied. if Layer 1 is 100% blocked, a very small amount of water will flow through Layer 1. If this is unacceptable, instead of applying 100% blockage of Layer 1, the preferred approach is to start the layered flow constriction at the top of Layer 1 or raise the ground elevation to the top of Layer 1 using one of the Z Shape modification functions (e.g. a breakline). 
<ol>
[[File:100% Blockage Diagram.png | 500px]]
</ol>

== Can I model bridge piers explicitly in 2D using very small cells? ==
It isn't recommended to explicitly model bridge piers by blocking out the pier faces in TUFLOW, or in any hydraulic modelling software based on solving Shallow Water Equations(SWE). Due to the 3-dimentiality of the flow and turbulence around a pier, computational fluid dynamics (CFD) approach is often required to simulate the flow around piers explicitly. The wake turbulence behind a simple-shape pier can be resolved to some extent using extremely fine mesh in TUFLOW (see calibration example to a flume experiment in the [https://www.tuflow.com/library/webinars/#structures webinar on Energy Losses at Structures]), however the predictions for head losses show notable sensitivities to the mesh size, the mesh design, and the choice of turbulence model. The extremely fine mesh resolution also results in significantly higher computational costs.

Therefore, the safest and strongly recommended approach with regard to establishing head losses and consequently flood levels, is to model the effects of such obstructions with form loss coefficients (applied to selected mesh cells) that have been derived from physical testing. This approach has been shown to provide the most consistent results across various mesh resolutions. It also has the added benefit that, by avoiding small cells in the mesh, it will provide much more efficient run times for flow solvers.

[[File:Flow round a cylinder.png]]

''The point of flow separation around an object has a major bearing on the drag coefficient and is not reliably reproduced by 2D or 3D software.''


== How to best convert flow constriction data (2d_fc or 2d_fcsh) into newer formats (2d_lfcsh or 2d_bg)? ==
The form loss parameters can be transferred from the flow constriction (2d_fc or 2d_fcsh) to the first layer of the layered flow constriction (2d_lfcsh) or pier layer of the 2d_bg. Definition of the remaining form loss and blockage layer inputs should follow the guidance outlined in [[TUFLOW_2D_Hydraulic_Structures#2D_Layered_Flow_Constriction_.282d_lfcsh.29 | 2D Layered Flow Constriction]] and [[TUFLOW_2D_Hydraulic_Structures#2D_BG_Shape_.282d_bg.29 | 2D BG Shape]] paragraphs. 
When using floating pontoon (type FD in the 2d_fc or 2d_fcsh) different setup might need to be used for different events. For large events when floating pontoon becomes fixed at the top of the supporting piles, standard 2d_lfcsh setup can be used. Smaller events when the pontoon is floating at different heights might require more sensitivity testing of the structure parameters to find out a setup the matches the reality as close as possible. 

== Should I model bridges in 1D or 2D Domain? ==
The recommended approach typically depends on the study objectives and if the channel upstream and downstream of the bridge is modelled in 1D or 2D. To preserve the momentum as accurately as possible the bridge should be modelled in the same dimension as the channel, e.g. 1d_nwk bridge if the channels is in 1D and 2d_bg or 2d_lfcsh if the channel is modelled in 2D. 
In 2D, the expansion/contraction losses are modelled based on the topography and don't need to be estimated as attributes as for 1D modelling. Also, for higher flows where the bridge is overtopped, 2D is preferable approach.

== What is the difference between downstream and upstream controlled flow? ==
Downstream control means a change in downstream water level will cause a change in upstream water level. Upstream control means the upstream water level is insensitive to the downstream water level and usually indicates the occurrence of supercritical flow.

== What FLC values should be used for 2d_bg bridge if hB/T is below 2 or above 6? ==
TMR has extended the CFD simulation to hB/T ratios of 1 to 10. Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for details.

If hB/T is outside this ratio:
* hB/T ratios of less than 1 represent a very unusual bridge sitting low to the ground, and the peak FLC may increase above the end value (FLC of 0.6) in a way that doesn't follow the research trend or extrapolation. For these cases we would recommend using CFD modelling to obtain a more informed value. Alternatively, computing an FLC based on pressure flow or using 1D culvert might be considered.
* For hB/T ratios of greater than 10, the FLC is likely to continue to decrease, but probably not significantly. Clamping to the end value (FLC of 0.16) might be considered the more conservative approach (if the primary concern is flood levels upstream of the bridge). 
 
{{Tips Navigation
|uplink=[[ TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

TUFLOW Viewer - Plotting 1D Flow Regime

2026-04-07T23:19:06Z

Emilie Nielsen:

===Tool Description===
Flow regime can be a very useful output to understand and debug 1D results, in particular, culverts. 

Flow regime results are output from ESTRY by default (i.e. there is no special output type or command required in the ECF). Since the 2020-01-AA TUFLOW release, flow regime results will be imported into TUFLOW Viewer when time series results are loaded. There are several methods to view the flow regime results:
<ol>
<li>Select 'Flow Regime' in the '''Result Type''' widget (underneath 'Time Series'). 
[[File: TUFLOW Viewer_Plotting 1D Flow Regime_1a.png]] 
This will display the flow regime as points and lock the y-axis to the available flow regime types as per the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. The plot will group the types by outlet and inlet control regimes - 'G' is no flow, everything below 'G' on the plot will be inlet control and everything above 'G' is outlet control. 
[[File: TUFLOW Viewer_Plotting 1D Flow Regime_2a_03.png]] 

<li>Right clicking certain time series results [[File:results_2.png | 15px]] (e.g. 'Flow', 'Level', or 'Velocity') will give the user the option of checking on '''Flow Regime'''. 
[[File: TUFLOW Viewer_Plotting 1D Flow Regime_3a.png]] 

This will plot the flow regime as letters and map it to the chosen result type, making visualising the results a lot easier. For example, in the image below the jump in velocity at approximately 0.55 hrs to 0.7 hrs is shown to be a change in flow regime (it goes from 'A' to 'B' then to 'L'. 
[[File: TUFLOW Viewer_Plotting 1D Flow Regime_4a.png]]
</ol>

'''Flow Regimes (Source: TUFLOW Manual)''' 
[[File:Plotting_TimeSeries_FlowRegime_Legend.PNG]] 

===Example===
{{Video|name=TUFLOW Viewer_Plotting 1D Flow Regime_1a.mp4|width=1350}}
 

{{Tips Navigation
|uplink=[[TUFLOW_Viewer#Time_Series_Output| Back to TUFLOW Viewer Main Page]]
}}

1D Pits

2026-03-31T22:51:53Z

Emilie Nielsen: /* Pit Inlet Data Sources */

=Introduction=
There are predominantly two types of stormwater pits (drains/gullies) used as inlets to collect overland runoff and transfer that water to the underlying drainage/culvert/pipe network;
* Grated inlets
* Kerb Inlets (side entry pits / lintel inlets).
This page of the Wiki describes how pit inlet data is incorporated into a TUFLOW model.

= Pit Inlet Types =
{|class="wikitable"
|-
! Inlet Type !! Example !! Description !! Dimensioned Example
|-
! Q
| [[File:Q pit inlet.jpg|thumb|none|300px|Depth-Discharge Pit or Channel]] || Depth-Discharge Pit or Channel, pit inlet inflow information is defined within TUFLOW via a user-defined Pit Inlet Database and associated pit inlet curves. This approach allows for unlimited flexibility. Any pit design or configuration can be incorporated into a TUFLOW model if the inlet depth-discharge relationship is known. || [[1D_Pits#TUFLOW_Model_Inputs | See TUFLOW Model Inputs]]
|-
! R
| [[File:Side_Entry_pit.jpg|thumb|none|300px|Kerb Inlet]]
|| Kerb inlets, also known as side entry pits or lintels, are common in Australia. The pit chamber can vary depending on overall depth, length, and the addition of any haunched riser units. 
Width_or_Dia: Sets the width of the pit inlet section in the vertical plane. 
Height_or_WF: Sets the height of the pit inlet channel in the vertical plane.
|| [[File:003 Side Entry pit dimensions.jpg|alt=|left|thumb|300x300px|Kerb Inlet with dimensions]]
|-
! C
| [[File:Circular pit inlet.jpg|thumb|none|300px|Circular Pit Inlet]]
|| Circular pit inlet. 
Width_or_Dia: Sets the diameter of the pit inlet cross-section in the vertical plane. 
Height_or_WF: Not used.
|| [[File:003 Circular pit inlet dimensions.jpg|alt=|left|thumb|300x300px|Circular Pit Inlet with dimensions]]
|-
! W
| [[File:Gully pit.jpg|thumb|none|300px|Grate (London, UK)]]
|| Grates, also known as Gully Pits, are common in the United Kingdom and are generally a square grate on top of a circular chamber and a riser outlet. The outlet will then feed into a larger culvert that forms part of the larger urban drainage network. 
Width_or_Dia: Sets the width of the pit inlet section in the vertical plane. The width is the total width in the direction of flow to the pit. For example: 
* Case 1 - a gully pit may include all sides of the pit.
* Case 2 - an on grade pit may only include one side. 
Height_or_WF: Not used. 
|| [[File:006 CASE 1 Gully pit dimensions.jpg|alt=|left|thumb|300x300px|Case 1 - Grate with dimensions]][[File:006 CASE 2 Gully pit dimensions.jpg|alt=|left|thumb|300x300px|Case 2 - Grate with dimensions]]
|}

= Pit Inlet Data Sources =
Pit inlet depth-discharge data can be obtained from a variety of sources. The most common typically being from suppliers or local agencies who enforce consistent design standards within their jurisdiction. For demonstration purposes, examples from Sutherland Shire Council and Brisbane City Council are provided below.

== Sutherland Shire Council ==
The Sutherland Shire Council Urban Drainage Manual (1992) includes summary tables and graphs documenting pit grate and lintel capacity information (derived from Department of Main Roads testing). The guidelines are compatible with the standard pit grate and lintel design shown below: 
[[File: Pit_Inlet_Curves_SSC000.JPG|700px]] 
The capacity of a pit depends on three factors:
* The clear opening area of the grate
* The depth of water ponding over the grate
* The length of kerb inlet (lintel) opening
The following graphs summarise grate and lintel discharge estimates for a range of water depths and blockage factors, derived from the Sutherland Shire Council design standards. 
[[File: Pit_Inlet_Curves_SSC001.JPG|700px]]
[[File: Pit_Inlet_Curves_SSC002.JPG|700px]] 

The above graphs estimate unit length and area flow estimates. These unit values can be multiplied by real pit dimensions to define at site depth-discharge characteristics.

TUFLOW modelling requires the derivation of a unique depth-discharge curve for each pit type within the modelled area. An example is provided below for a single pit location. 

[[File: Pit_Inlet_Curves_SSC003.JPG|700px]]

== Brisbane City Council==
The pit inlet curve examples below originate from Brisbane City Council 8000 series standard drawings: https://www.brisbane.qld.gov.au/planning-building/planning-guidelines-tools/planning-guidelines/standard-drawings 
[[File: BCC_BSD-8077.JPG|border|700px]]
[[File: BCC_BSD-8051.JPG|border|700px]] 
[[File: BCC_BSD-8082.JPG|border|700px]]
[[File: BCC_BSD-8052.JPG|border|700px]] 

== Spacing of Road Gullies (UK standards: BS EN 124 and BS7903) ==
The following section describes the [https://www.standardsforhighways.co.uk/tses/attachments/a869ed8e-4470-4286-aef4-7d11af24a597 Spacing of Road Gullies] guidance (UK standards: '''BS EN 124''' and '''BS 7903''') which provides a method for determining road gulley capture rates.

The method depends on the following '''Hydraulic parameters:'''
* Longitudinal gradient, ''SL'', along the length of the scheme (expressed as fraction).

* Cross-fall, ''Sc'' (also expressed as a fraction).

* Manning’s roughness coefficient, ''n''. Usually ''n'' = 0.017 for a conventional road surface. Other values are given in the following '''Table 1'''. (For more details, please see Section: 5, Table 5.3N of the [https://www.standardsforhighways.co.uk/tses/attachments/a869ed8e-4470-4286-aef4-7d11af24a597 guidance]).

'''Table 1:''' Values of Manning's ''n''
 [[File:Table1N.jpg|750px|]] 

* The grating type (P, Q, R, S or T), or the size and angle of kerb inlet.

* The maximum allowable flow width (as shown below by ''B'' in m) against the kerb.
 [[File:Figures 1 2.jpg|850px|]] 

'''Calculation of Gully Flow Capture Rates based on Equations'''
 The equations given in Appendix C (p.g: 25) of the [https://www.standardsforhighways.co.uk/tses/attachments/a869ed8e-4470-4286-aef4-7d11af24a597 guidance] can be used to determine flow capture rates at different depths, to determine the depth-discharge curve for use within TUFLOW. The method requires the calculations of the flow capacity of the kerb channel and flow collection efficiency of the gully grate.
*As a first step, a gully grate type: P, Q, R, S or T should be selected. The selection of the grating type will determine the design value ''Gd'' (grating parameter) from '''Table 2'''. (For more details, please see Table A.2, Appendix A of the [https://www.standardsforhighways.co.uk/tses/attachments/a869ed8e-4470-4286-aef4-7d11af24a597 guidance]).

'''Table 2:''' Determination of grating type ''Gd''
 [[File:Determination of grating type.jpg|650px|]] 

*Road (longitudinal) gradient (''SL''), Crossfall (''Sc'') and Manning's (''n'') should then be determined. Parameter values can be obtained from '''Table 3'''.

'''Table 3:''' Determination of ''SL'', ''Sc'' and Manning's ''n''
 [[File:Table SL SC N Range.jpg|750px|]] 

*Further, a Water Depth against the kerb ''H'' (m) range should be provided. (Please note: The depth range can be changed, but the following equations that are used to calculate the flow capacity are only valid up to the kerb height).

*With the above parameters, the calculations of the i) Flow width (''B'' in m), ii) Cross-sectional area (''Af'' in m2), iii) Hydraulic radius (''R'' in m), iv) Flow rate (''Q'' in m3/s) and v) Flow collection efficiency (''ŋ'' (%)) based on the Equations C.1-C.5 which are presented in Appendix C of the [https://www.standardsforhighways.co.uk/tses/attachments/a869ed8e-4470-4286-aef4-7d11af24a597 guidance] can be completed.

*Finally, the resulting depth-discharge data can be used in the TUFLOW pit inlet curves. 

The Gully Flow Capture Rates template [https://downloads.tuflow.com/Other/Inlet_Spreadsheets/Gully%20Flow%20Capture%20Rates_v3.xlsx here], includes a calculation tab which can be used for the completion of the above calculation processes. Based on calculations and Equations C.6 and C.7 of the [https://www.standardsforhighways.co.uk/tses/attachments/a869ed8e-4470-4286-aef4-7d11af24a597 guidance] the maximum allowable spacings upstream of the gully can be further calculated (For more details, please see Appendix C, p.g: 25).

'''Key assumption''' '''Note:''' This method assumes that the route the flow takes around the trap limits the discharge from the gully pot to 10 l/s. This limit is effective in both directions, so any negative head on the gully would create -10 l/s flow back up through the gully and flood onto the road. 

== UK Water Industry Research (UKWIR) Inlet Capture Tool ==
In 2023, the UK Water Industry Research (UKWIR) Limited released the Modelling Sewer Inlet Capacity Restrictions Report [https://ukwir.org/modelling-sewer-inlet-capacity-restrictions Modelling Sewer Inlet Capacity Restrictions Report]. The main aim was to develop a sewer modelling methodology to enable the representation of inlet inflow restrictions, focusing on the development of a new 1D model approach to provide more accurate model sewer flooding predictions. The new modelling approach has been devised by combining the findings from a literature review and the development of semi-empirical relationships from academic studies which investigated factors affecting inlet capacity. The new approach allows for 2 types of gully response reflecting 2 flow conditions: Subcritical flow on a shallow road gradient and Supercritical flow on a steep road gradients. A threshold of 0.02 is used to distinguish between shallow and steep road gradients. The reported equations can be used for the production of input inlet curves for TUFLOW 1D pit inlet modelling.

A template for the generation of the UKWIR Inlet Curve can be downloaded from [https://downloads.tuflow.com/Other/Inlet_Spreadsheets/Inlet%20Curve%20Capture%20tool%20v4.xlsx here]. The template determines both Subcritical Head-Discharge and Supercritical Head-Discharge relationships obtained from the Modelling Sewer Inlet Capacity Restrictions Report based on user input values of water depth (in metres). Two sets of curves can be generated, curves based on default parameters, and those based on user-defined parameters. Note, the report is not clear what inlet capacity cap should be applied, so these are not applied within the spreadsheet currently. However, the user can edit the resulting Head-Discharge relationship to apply a required cap on the inlet capacity.

=TUFLOW Model Inputs=
The steps required to represent pit inlet information within a TUFLOW model is summarised below:
<ol>
<li> Import an empty 1d_nwk GIS file from the TUFLOW file template folder (model\gis\empty).
<li> Digitise points to represent pit locations. The points should be snapped to the start or end of 1d_nwk line features that define the underground pipe network.
<li> Update the field attributes for each Pit point. Refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. The most commonly used attributes are:
* Type = Q (C, R and W are also options if pit inlets based on structure dimension is required instead of using a Pit Inlet Database approach).
* US_Invert = Used to specify the ground elevation of the pit. If Conn_1D_2D is set to “SXL”, US_Invert is used as the amount by which to lower the 2D cell and the pit channel invert is set to this level.
* DS_Invert = The bottom elevation of the pit. This input can also be used to set the upstream and downstream inverts of connected pipes/channels.
* Inlet_Type = For Q pit channels, the name of a pit inlet type in the Pit Inlet Database. Multiple Pits can use the same Inlet_Type ID if they have the same design dimensions.
* Conn_1D_2D = SXL can be specified to connect the 1D pit or node to the 2D domain and lower the 2D cell by the amount of the US_Invert attribute. The invert of the pit channel is set to the lowered 2D cell level. This is useful to help trap the water into the pit as it flows overland in the 2D domain. This feature works well in combination with the new Read GIS SA PITS option.
<li> Update the Estry Control File (*.ecf) to include reference to the new 1d_nwk GIS file. 
<tt>Read GIS Network</tt> <tt>==</tt><tt>..\model\mi\Estry\1d_nwk_****.MIF</tt> 
<li> Create a Pit Inlet Database csv file. This file lists each type of pit (matching the names listed in the 1d_nwk "Inlet_Type" field). It also provides reference to the depth-discharge curve information. 
[[File:M05 pit inlet dbase 01.png]]
<li> Create the Source file referenced in the Pit Inlet Database. The source file defines the depth-discharge information for each pit (determined from the relevant design standards). The column headers must match the entries in the Pit Inlet Database. 
[[File:M05 pit inlet v2.png]]
<li> Update the Estry Control File (*.ecf) to include reference to the Pit Inlet Database. 
<tt>Pit Inlet Database</tt> <tt>==</tt><tt>..\pit_dbase\EG_pit_dbase.csv</tt> 
</ol>

An example model including Pits is available for download: https://wiki.tuflow.com/index.php?title=TUFLOW_Example_Models

==Pit Search Distance==
Some agency pit datasets may not have all pit point features snapped to the associated pipe line features. The *.ecf command "Pit Search Distance" can be useful in this instance. It automatically connects floating nodes to the 1D pipe network where connectors are not snapped to channel ends: 

<tt>Pit Search Distance</tt> <tt>==</tt><tt>xxx</tt> 
<tt>Read GIS Network</tt> <tt>==</tt><tt>..\model\mi\1d_nwke_*****.MIF</tt> 
 
The order of the "Pit Search Distance" command is important as it can be repeated multiple times with different values that are assigned to the 1d_nwke(s) below the ''Pit Search Distance'' command. The pit search command should be included above the the GIS layer containing the pits.

To check if the ''Pit Search Distance'' is working as expected, import the [[Check_Files_1d_nwk_C | *_nwk_C_check]] file to visually see if the pits are automatically connecting to a culvert. The image below is an example of the *_nwk_C_check file and the connections TUFLOW has made to each pit. 

 
[[File:Pit_search_distance_check.JPG|border|500px]]

 
Should you have any further questions, please email TUFLOW support: [mailto:support@tuflow.com?Subject=TUFLOW%201D%20pits%20help support@tuflow.com]
 
{{Tips Navigation
|uplink=[[ TUFLOW 1D Channels and Hydraulic Structures | Back to 1D Channels and Hydraulic Structures]]
}}

TUFLOW Version Backward Compatibility

2026-03-31T01:57:47Z

Emilie Nielsen: /* How can differences in model results between TUFLOW builds be investigated? */

=Backward Compatibility Change Register=

==Default changes post 2017-09 Build==
 
'''For changes in defaults post the 2017-09 build, see Chapter 18 of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual].'''
 
==Default changes pre 2017-09 Build==
 

{|class="wikitable"

|-
|colspan="3"|'''2017-09-XX Builds'''
|-

| rowspan=6|2017-09-AA
| New SX boundaries defaults.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2017</tt> if similar results are required to the 2016-03-AE release. 
|-
| XF files are now being processed for boundaries.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2017</tt> or use <tt>XF Files Boundaries</tt> <tt>== </tt><tt>OFF</tt> if similar results are required to the 2016-03-AE release. 
|-
|Regions in 2d_bc layers now applied as regions (previously only cell over region centroid selected).
|No backward compatible workaround provided. 
|-
|Material IL and CL now applied to gridded rainfall (previously not applied).
|No backward compatible workaround provided.
|-
|SA regions now always select a 2D cell even if there are no cell centres falling within the region (previously a SA region would not select any cell if no cell centres fell within the region).
|No backward compatible workaround provided. 
|-
|If using “<tt>Reveal 1D Nodes</tt> <tt>==</tt><tt> ON</tt>”, “<tt>Time Series Output Interval</tt> <tt>==</tt> ” must be specified.
|No backward compatible workaround provided. 
|-

|-
|colspan="3"|'''2016-03-XX Builds'''
|-

| rowspan=7|2016-03-AA
| New operational 1D structure defaults.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> if similar results are required to the 2013-12-AC release. 
|-
| Primary upstream and downstream 1D channels now correctly take into account bed slope.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> if similar results are required to the 2013-12-AC release. 
|-
| A new layered 2D FC calculation method has been implemented.
| Set <tt>Layered FLC Default Approach </tt> <tt>== </tt><tt>CUMULATE</tt> or use <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> if similar results are required to the 2013-12-AC release. 
|-
| The SX Flow Distribution Cutoff Depth has been raised to 0.005m from 0.0m.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> or use <tt>SX Flow Distribution Cutoff Depth </tt> <tt>== </tt><tt>0.0</tt> if similar results are required to the 2013-12-AC release. 
|-
|The End After Maximum tolerance has been increased to 0.001m from 0.0m.
|Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> if similar results are required to the 2013-12-AC release. 
|-
|A new ERROR message has been added to cross-check the 1D timestep is a multiple of the timestep for all 2D domains.
|Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> if similar results are required to the 2013-12-AC release. 
|-
|WARNING 2460 has been escalated to an ERROR and stricter command line syntax rules have been introduced ("=" will now return an ERROR message if TUFLOW is expecting "<tt>==</tt>")
|Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> if similar results are required to the 2013-12-AC release. 
|-

| rowspan=1|2016-03-AD
| The treatment of the eddy viscosity term in the GPU Solver has been enhanced with slightly improved results in areas of rapidly changing velocity patterns.
| Set <tt>GPU Viscosity Method </tt> <tt>== </tt><tt>Method A</tt> or use <tt>Defaults </tt> <tt>== </tt><tt>PRE 2016</tt> to achieve the same results as Build 2013-12-AC and prior.
|-

|-
|colspan="3"|'''2013-12-XX Builds'''
|-

| rowspan=1|2013-12-AA
| New default settings – see <tt>Defaults </tt> <tt>==</tt><tt> PRE 2013-12</tt> in the user manual for a list of the commands that have changed in their default setting.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2013-12</tt> if similar results are required to the 2012-05 release.
|-

| rowspan=1|2013-12-AC
| The default setting for Link 2D2D Approach has changed.
| Set <tt>Link 2D2D Approach </tt> <tt>== </tt><tt>METHOD B</tt> to achieve the same results as Builds 2013-12-AA and 2013-12-AB. See Link 2D2D Approach for more information.

|-
|colspan="3"| '''2011-09-XX and 2012-05-XX Builds'''
|-

| rowspan=2| 2012-05-AA
| New default settings – see <tt>Defaults </tt> <tt>== </tt><tt>PRE 2012-05</tt> for a list of the commands that have changed in their default setting.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2012-05</tt> if similar results are required to the 2011-09 or 2010-10 releases.
|-
| The approach to the sizing of automatic manholes and the application of losses has been enhanced.
| Set <tt>Manhole Approach </tt> <tt>== </tt><tt>Method A</tt> to achieve the same results as Build 2011-09-AA.
|-

| rowspan=1| 2011-09-AA
| The optimised compiler code is treated differently for Single Precision builds producing slightly different results (fractions of a mm) for some models.
| No workaround.
|-

|-
|colspan="3"| '''2010-10-XX Builds'''
|-

| rowspan=4| 2010-10-AA
| New Intel Fortran Compiler version produces slightly different results (usually fractions of a mm).
| No workaround.
|-
| w32 and w64 versions will give slightly different results for the same simulation.
| No workaround. Use the same platform (w32 or w64) for all simulations. Use Model Platform to force which platform should be used.
|-
| New default settings – see <tt>Defaults </tt> <tt>== </tt><tt> PRE 2010-10</tt> for a list of the commands that have changed in their default setting.
| Set <tt>Defaults </tt> <tt>== </tt><tt>PRE 2010-10</tt> if similar results are required to the 2008-08 or 2009 07 releases.
|-
| Generation of TINs for polygons in Read GIS Shape layers is more robust and uses an improved approach. In rare cases, the TIN would fail and TUFLOW would abort the start-up.
| No workaround.
|-

|-
|colspan="3"| '''2008-08-XX and 2009-07-XX Builds'''
|-

| rowspan=1| 2008-08-AC
| The default setting for Shallow Depth Stability Factor has changed.
| Set <tt>Shallow Depth Stability Factor </tt> <tt>== </tt><tt> 3</tt> for models without direct rainfall to achieve the same results as Builds 2008-08-AA and 2008-08-AB. See Shallow Depth Stability Factor for more information.
|-

| rowspan=8| 2008-08-AA
|-
| Uses a new set of defaults for a number of commands (see Defaults ).
| The new defaults produce slightly different results, and very slight differences also occur between the three versions offered. For established models run using the 2007-07-XX builds, use <tt>Defaults </tt> <tt>== </tt><tt>PRE 2008-08</tt> to use the default settings used by the 2007-07-XX builds. Testing of a range of models has shown zero change in results if <tt>Defaults </tt> <tt>== </tt><tt> PRE 2008-08</tt> switch is set, and the Compaq Fortran compiled version (cSP) is used. Each of the new default settings and their effects are discussed in the rows below.
|-
| The method for interpolating n values where the 2D Manning’s n varies with depth has been enhanced from a linear interpolation of the M (1/n) value to a spline interpolation of the n value. See Bed Resistance Depth Interpolation.
| Generally has little effect other than when the flow is predominantly in the depth range that the n value is varying. The new approach offers a smoother transition in n values from one depth to the other.
|-
| The default viscosity coefficient is now a combination of a 0.2 Smagorinsky and 0.1 constant coefficient, and there are some enhancements to the application of the viscosity term. See Viscosity Coefficient.
| This has slight effect for the majority of models. For fine grid models (<2m cell size) with low bed resistance and significant variations in velocity vectors the effect is more pronounced but is still slight.
|-
| Inertia and viscosity terms are now not transferred across dry cell sides when constructing the coefficients for the solution arrays. This was having the effect of generating a circulation on the other side of the wall (albeit a very weak one), which of course shouldn’t happen!
| Generally little effect, but can have some minor influence for urban models where buildings and fences are modelled as solid thin Z lines.
|-
| 1D weir flow has been improved as the water level difference across the weir approaches zero. The new method is more stable. See Weir Flow.
| Very little difference other than improved stability.
|-
| Incorporates minor improvements for transitioning between Regimes A and B, and between inlet and outlet controlled regimes, for circular culverts.
| Very little difference other than improved stability.
|-
| The new automatic selection of cells for 2D SX connections using the 1d_nwk Conn_1D_2D attribute may choose more than one 2D cell.
| Very little difference other than improved stability at the pit 2D connections.
|-

|-
|colspan="3"| '''2007-07-XX Builds'''
|-

| rowspan=12| 2007-07-AA
|-
| Uses a new set of defaults for a number of commands (see Defaults).
| The new defaults may produce slightly different results. For established models run using the 2006-06-XX builds, use <tt>Defaults </tt> <tt>== </tt><tt>PRE 2007-07-AA</tt> to use the default settings used by the 2006-06-XX builds. Each of the new default settings and their affects are discussed in the rows below.
|-
| Change <tt>Zero Material Values to One </tt> <tt>== </tt><tt> OFF</tt> (previously ON)
| Will not cause different results if a <tt>Set Mat </tt> <tt>== </tt><tt> 1</tt> is specified before other material settings in the .tgc file, or if every cell has been assigned a material value.
|-
| <tt>Inside Region </tt> <tt>== </tt><tt> Method B</tt> (previously Method A)
| Testing thus far has not shown any difference between the two methods (other than the substantial gains in processing time of polygons).
|-
| <tt>Line Cell Selection </tt> <tt>== </tt><tt> Method D</tt> (previously Method C)
| May change results slightly, but improved stability and a smoother water levels along HX lines result.
|-
| <tt>VG Z Adjustment </tt> <tt>== </tt><tt> MAX ZC</tt> (previously ZC)
| May change results slightly, but stability should be significantly enhanced in some situations.
|-
| <tt>Bed Resistance Cell Sides </tt> <tt>== </tt><tt> INTERROGATE</tt> (previously AVERAGE M)
| Will influence results, usually slightly, but more pronounced where there are sudden changes in Manning’s n values such as in the urban environment.
|-
| <tt>Culvert Flow </tt> <tt>== </tt><tt> Method D</tt> (previously Method C)
<tt>Culvert Critical H/D </tt> <tt>== </tt><tt> OFF</tt> (previously <tt>Culvert Critical H/D </tt> <tt>== </tt><tt> 1.5</tt>)
| The most significant influences are the selection of upstream or downstream controlled regimes depending on the H/D ratio, and the bug fix relating to Regime E if <tt>Structure Losses </tt> <tt>== </tt><tt> ADJUST</tt>. Offers improved stability, better convergence for Regime C and smoother transitioning between some regimes.
|-
| Changed the setting of the default width (if eN1 < 0.001) of automatic weirs over R and C channels (i.e. RW and CW) to be the diameter/width multiplied by the number of culverts (previously, the width was not multiplied by the number of culverts).
| For backward compatibility, original weir width can be set by manually setting the eN1 attribute to the Diameter_or_Width attribute value of the culvert.
|-
| Bug fix that when using a restart file TUFLOW occasionally set the 2D FC bridge deck additional loss value incorrectly.
| No backward compatible workaround provided.
|-
| Bug fix that incorrectly set the water levels on dried VG cells (only applies to simulations with source inflows, e.g. SA or RF, somewhere within in the model).
| May cause slight changes in results. Backward compatibility provided if <tt>Defaults </tt> <tt>== </tt><tt> PRE 2007-07-AA</tt> is set (noting that setting this command reinstates the bug). This bug also causes the mass error calculations to falsely give a mass error that is not occurring.
|-
| Fixed bug that did not correctly apply the reduction in conveyance for a FC BD (bridge deck) of FD (floating deck) cell using the 2d_fc Mannings_n attribute.
| Backward compatibility applied if <tt>Defaults </tt> <tt>== </tt><tt>PRE 2007-07-AA</tt> is set, however, note that this reinstates the bug and the resistance to flow at FC BD and FD cells may need to be reviewed. Indications are that only minor changes in results occur. The flow area under 2D FC BD and FD cells is correctly calculated.

|-
|colspan="3"| '''2006-06-XX Builds'''
|-
| rowspan=16| 2006-06-AA
|-
| Uses a new set of defaults for a number of commands.
| The new defaults will produce different results. For established models run using the 2005-05-XX builds, use <tt>Defaults </tt> <tt>== </tt><tt> PRE 2006-06-AA</tt> to use the previous default settings. Each of the new default settings and their affects are discussed in the rows below.
|-
| <tt>Cell Wet/Dry Depth </tt> <tt>== </tt><tt> 0.002</tt> (previously 0.05) and <tt>Cell Side Wet/Dry Depth </tt> <tt>== </tt><tt> 0.001</tt> (previously 0.03)
| The most pronounced effect of the shallower wet/dry depths is likely to occur in areas that are still filling at the flood peak, such as behind a levee that is only just overtopped. The shallower wet/dry depths provides a greater flow depth for a longer period over the levee.
|-
| <tt>Adjust Head at ESTRY Interface </tt> <tt>== </tt><tt> OFF</tt> (previously ON)
| Usually does not have a major influence on results except where very high velocities occur.
|-
| <tt>Boundary Cell Selection </tt> <tt>== </tt><tt> Method C</tt> (previously Method A) and <tt>Line Cell Selection </tt> <tt>== </tt><tt> Method C</tt> (previously Method A)
| May select slightly different cells along boundary/link lines. This may cause a difference where the line is along the top of levee, possibly creating a “hole” in embankment.
|-
| <tt>Viscosity Formulation </tt> <tt>== </tt><tt> Smagorinsky</tt> (previously Constant) and <tt>Viscosity Coefficient </tt> <tt>== </tt><tt> 0.2</tt> (previously 1.0)
| Can have a significant effect where the viscosity term is influential. This occurs where the friction term is less dominant (i.e. low Manning’s n and/or deeper water such as the lower, tidal, reaches of rivers).
|-
| <tt>Structure Losses </tt> <tt>== </tt><tt> ADJUST</tt> (previously FIX)
| Can have a significant affect in the vicinity of structures within a 1D network and for culvert networks. Does not affect 1D structures linked to a 2D domain or at the structure ends not connected to another 1D channel.
|-
| <tt>Storage Above Structure Obvert (%) </tt> <tt>== </tt><tt> 5</tt> (previously CHANNEL WIDTH)
| Usually negligible effect unless the model storage is predominantly within 1D closed sections (i.e. B, C and R channels). The 1D domain is likely to be more sensitive to instabilities due to the much smaller storage above the top of the closed sections, therefore, a smaller 1D timestep may be required and/or the Storage Above Structure Obvert (%) increased.
|-
| <tt>Depth Limit Factor </tt> <tt>== </tt><tt> 10</tt> (previously 1)
| No effect as previously the model would have become “unstable” as the trigger for an instability was the top of the channel/node.
|-
| <tt>Culvert Flow </tt> <tt>== </tt><tt> Method C</tt> (previously Method B)
| Usually only minor effects plus improved stability.
|-
| <tt>Culvert Add Dynamic Head </tt> <tt>== </tt><tt> ON</tt> (previously OFF)
| Minor influence.
|-
| <tt>Bridge Flow </tt> <tt>== </tt><tt> Method B</tt> (previously Method A)
| Negligible influence plus improved stability. However, note the different treatment of energy losses once the bridge deck obvert/soffit is submerged if a BG or LC table is specified.
|-
| <tt>WLL Approach </tt> <tt>== </tt><tt> Method B</tt> (previously Method A)
| Only affects the presentation of results. Note, that Method A is no longer recommended or supported.
|-
| <tt>Apply All Inverts </tt> <tt>== </tt><tt> ON</tt> (previously OFF)
Does not affect hydraulic calculations, however, if a Blank, B or W channel is now lowered/raised because the inverts are now used, this will affect results/stability - see note at end of Apply All Inverts).
|-
| <tt>Conveyance Calculation </tt> <tt>== </tt><tt> ALL PARALLEL</tt> (previously CHANGE IN RESISTANCE)
| Will affect results as ALL PARALLEL can be around 10% more “slippery” than CHANGE IN RESISTANCE. For calibrated or established models developed using build prior to Build 2006-06-AA , recommend setting to CHANGE IN RESISTANCE
|-
| <tt>Flow Calculation </tt> <tt>== </tt><tt> Method B</tt> (previously Method A)
| Negligible effect.

|-
|'''Builds prior to 2006-06-XX'''
| Contact [mailto:support@tuflow.com support@tuflow.com]
|
|}
 
=Frequently Asked Questions (FAQ)=
== Why are model results developed in an older release different to a newer release? ==
If comparing a Classic model with HPC, also check the [[HPC_FAQ#Will_TUFLOW_HPC_and_TUFLOW_Classic_results_match.3F | Will TUFLOW HPC and TUFLOW Classic results match?]] page in addition to this answer. 
In addition to the above, there are reasons why model results would be different between different TUFLOW releases, whether it is the Classic or HPC solver, as follows:
* General improvements and fine-tuning of the solution scheme, especially for the more complex hydraulic physical terms and situations such as: sub-grid turbulence representation; treatment of shocks (e.g. hydraulic jumps); and transitioning between sub-critical and super-critical flow on steep slopes.
* Some new functionality can cause a significant change in results. For example:
** Sub-Grid Sampling (SGS) applied to an existing model that used a too coarse cell resolution in high flow areas of highly variable topography (relative to the 2D cell size). SGS will greatly improve the model's ability to convey water accurately in these situations with vastly improved results.
** New default sub-grid turbulence scheme in the 2020 release of TUFLOW HPC that is cell size independent and allows modellers to use cell sizes much smaller than the flow depth across all scales from flume to large rivers. For more information on differences between Smagorinsky scheme (HPC releases up to 2020) and the Wu turbulence scheme (2020 onwards) see [[HPC_FAQ#With_Wu_turbulence_scheme_being_the_new_default.2C_are_old_models_using_Smagorinsky_wrong.3F | here]].
* Changes to the default settings and values, e.g.:
**different default eddy viscosity formulation and/or coefficients,
**improved data pre-processing approaches such as sampling materials on cell mid-sides instead of cell centres,
** and many others.
** For backward compatibility the <tt>Defaults</tt> <tt>== </tt> command is available to run old models on new releases to replicate past results (note, sometimes full backward compatibility cannot be catered for due to different code compiler and updates that can't be reverted, especially for several releases earlier).
* New features that use GIS attributes previously reserved (i.e. unused). If these attributes were not populated with the recommended “reserved” value (usually 0 or blank), then they can cause unpredictable results in later releases.
* Bug fixes noting that most bug fixes are input/output related and rarely affect the model's hydraulic calculations.
* Change in timestepping can also produce a small change in results. HPC uses the Runge-Kutta 4th order integrator, which is usually fairly insensitive to time step provided the model is running stably. However when a region is filled by flow that only just overtops an embankment, a 10 mm difference in water levels upstream of the embankment can create a much larger difference in levels downstream. Hence, small differences in time-stepping (along with many other aspects of model setup) can trigger local differences in model results.
* Model orientation (if changed) could also mean slight change in results. This is mostly given by interpolating values from different calculation points. Every cell has nine calculation points. Based on the model origin, all or most of the calculation points would have different topography elevation sampled, which translates to slightly different results.
* If using 1D channel, possibly different cells have been selected as HX boundary and might have different elevations. This can be reviewed in [[Check_Files_1d_to_2d_bc | 1d_to_2d check file]].

Generally, there should not be substantial differences as the fundamental equations being solved are unchanged and TUFLOW Classic and HPC solvers have always solved all the physical terms using a 2nd order spatial approach. The one exception is the turbulence (eddy viscosity) representation, which is the most complex and challenging to solve of all the physical terms (many 2D schemes simply omit this term). If significant differences (>10% of depth change across the whole model) are observed then it’s most likely due to the first four dot points above. To identify in which release(s) the significant changes occurred, the model can be run with the latest build and for past releases. The changes for each release are documented in their release notes. Past releases and release notes are all available [https://www.tuflow.com/downloads/tuflow-classichpc-archive/. here]. Once the exact release where the changes occurred is tracked down, individual features can be turned off to narrow down the cause. 

The recommendation is usually for new or reworked models to use the newest build to take advantage of the latest features and enhancements, some level of calibration might be required for reworked models. The new TUFLOW executable is not different from the previous ones in the meaning that any existing model should be re-calibrated if there are available calibration data. However, particularly if a model is already calibrated, using prior builds of TUFLOW or winding back default settings using <tt>Defaults</tt> <tt>== </tt> command is considered reasonable for established models that are to be used for minor tasks where an update of the model would not be cost effective. 

== How can differences in model results between TUFLOW builds be investigated? ==
Running TUFLOW on a later Build from which it was originally calibrated will not necessarily produce the same results, as discussed in [[TUFLOW_Version_Backward_Compatibility#Why_are_model_results_developed_in_an_older_release_different_to_a_newer_release.3F | Why are model results developed in an older release different to a newer release?]].

The following is an example of steps that can be taken when upgrading a TUFLOW model’s executable Build, checking for consistency to original results each time.
<ol>
<li> Confirm you are able to run the original model with the original Build that would have been used to initially produce results.
* This may be particularly relevant when a model has been externally supplied, for example from a government body.
* Confirm if reproduced results are consistent with supplied results.
<li> Run the original model with the newer Build, along with a relevant <tt>Defaults</tt> <tt>== </tt> command (e.g. <tt>Defaults</tt> <tt>== </tt> Pre 2011 when the original Build was 2010-10).
* Any differences in results compared to the original results may highlight if there are any changes over time where no backward compatibility had been provided for.
<li> Run the original model with the newer Build, and without the <tt>Defaults</tt> <tt>== </tt> command.
* This more likely to see changes in results compared to the original results, which may require justification to the client or resolution by investigating, isolating and remedying the causes, especially if recalibration is not intended as a subsequent step.
<li> Iteratively run the original model with the newer Build, stepping through the different release version options for <tt>Defaults</tt> <tt>== </tt> command.
* This will allow the modeller to investigate and isolate what changes to TUFLOW Builds may be affecting results, and when changes appear.
* Then, individually reverting settings that make up a Default group (see Chapter 18 of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]).
* This can help isolate the primary drivers for any differences in results.
* The [https://docs.tuflow.com/classic-hpc/changelog// TUFLOW Classic/HPC Changelog] that accompanying Build releases are also a key reference.
<li> Develop new improved or updated model version, with the newer Build (and any grouped or individual defaults that are deemed necessary to retain from the iterative testing in the prior step).
*Continue to verify results against the original results as you then iteratively add in or update to any newer functionality or formats that may be available in the later Build, a good quality assurance check that changes are behaving as expected.
</ol>
 
{{Tips Navigation
|uplink=[[TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
}}

TUFLOW Message 2251

2026-03-30T05:38:42Z

Emilie Nielsen:

{{TUFLOW_Message
|tuflow_message=CHECK 2251 - HPC Infiltration Drying Depth not specified, set to Cell Wet/Dry Depth - 0.0001.
|alt_msg=ERROR 2251 - HPC Infiltration Drying Depth must be smaller than Cell Wet/Dry Depth. <dry_depth>, <wet_depth>
|type=[[CHECK]] [[ERROR ]]
|message_desc= When the <tt>HPC Infiltration Drying Approach </tt> <tt>== </tt> <tt>Method C</tt> (default), the drying depth to switch off the infiltration calculation is set to the <tt>Cell Wet/Dry Depth</tt> - <tt>0.0001</tt> by default.
|suggestions= The drying depth can be manually specified using the <tt>HPC Infiltration Drying Depth</tt> command.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

Tutorial M01

2026-03-30T04:47:57Z

Emilie Nielsen: /* Running the Simulation */

= Introduction =
Read the [[Tutorial_Introduction | Tutorial Model Introduction]] before starting this tutorial. It outlines programs requiring installation and provides the tutorial dataset download link. 

In this module, a fully two-dimensional (2D) model is built with a number of TUFLOW control files and Geographic Information System (GIS) layers. 

The TUFLOW control files are: 
:* TUFLOW Simulation Control File (TCF)
:* TUFLOW Geometry Control File (TGC)
:* TUFLOW Boundary Control File (TBC)
:* TUFLOW Boundary Condition Database (bc_dbase)
:* TUFLOW Materials File (materials) 

The GIS layers are: 
:*TGC layers:
<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> *.tif: A DEM dataset defining the ground elevations within the 2D study area.
<li> 2d_mat: A layer defining the land-use (material) types within the 2D study area.</ol></ol>
:*TBC layers:
<ol><ol><li> 2d_bc: A layer defining the locations of external 2D boundaries.
<li> 2d_sa: A layer to define internal 2D flow boundaries.
</ol></ol>
:*TCF layers:
<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 [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual].
 

= 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, refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 
<ol>
[[File:Tute M01 Directory Structure v3.png|left]]
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Sub-Folder
! style="background-color:#005581; font-weight:bold; color:white;" width=10%| Input / Output
! style="background-color:#005581; font-weight:bold; color:white;" width=75%| Description
|-
| bc_dbase|| Input || Boundary condition database(s) and input time-series data.
|-
| check|| Output || GIS and other check files to carry out quality control checks (use Write Check Files).
|-
| model|| Input ||Geometry (TGC), Boundary (TBC) and other model control text files (i.e. no GIS files).
|-
| model\gis|| Input || GIS layers that are inputs to the 2D and 1D model domains are contained within this folder, model\gis is typically used for all QGIS and ArcGIS files.
|-
| 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 specified formats.
|-
| runs|| Input|| TUFLOW Control Files (TCF).
|-
| runs\log|| Output || TUFLOW log files (TLF) and messages layers.
|}
</ol>
The TUFLOW folders can be set up manually, automatically running TUFLOW model with <tt> Write Empty GIS Files </tt> command or automatically through GIS programs:
:*[[Tutorial_M01_Configure_TUFLOW_Project_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Configure_TUFLOW_Project_QGIS_GPKG | QGIS - GPKG]]
:*SMS - the folder structure listed above is automatically created before running the model using the 'Export TUFLOW files' command (see [[Run TUFLOW from within SMS | Run TUFLOW from within SMS]]).
:*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.

The following points on TUFLOW folders and filenames are worth noting:
:*TUFLOW accepts any folder structure, though the above listed format is most commonly used and is recommended. 
:*TUFLOW accepts spaces and special characters (such as ! or #) in filenames and paths, but other software may not. It is recommended that spaces and other special characters are not used in the simulation path and filenames. 
:*Folder paths, filenames, file extensions and TUFLOW commands are not case sensitive in any TUFLOW control files. 
:*Any directories that don't apply can be omitted, for example, if using QGIS or ArcMap the model\mi directory is not required. 
 

= Model Familiarisation=
Become familiar with the model location, using an aerial image and DEM: 
:*[[Tutorial_Site_Familiarisation_QGIS | QGIS]]
 

= TUFLOW Geometry Control File (TGC) =
The TGC file is a series of commands that build the geometry model. At its minimum, the TGC contains:
:*Information on the size and orientation of the grid;
:*Grid cell codes (whether cells are active or inactive);
:*Bed / ground elevations; and
:*Bed material type or flow resistance value.

Commands in the TGC file are applied in sequential order; the order (layering) of these commands is critical. The last occurrence of a command prevails, it is possible to override previous information with new data to modify the model in selected areas. This is useful but is also something to be aware of as to not override commands by mistake.

=== 2D Domain ===
Grid formats currently supported by TUFLOW include the ESRI ASCII grid format (.asc), binary grids (.flt) and geodetic grids (.tif). The Digital Elevation Model (DEM) is provided in .tif format. 

Defining the location and orientation of the TUFLOW 2D domain can be undertaken using four different methods: 
:*Specifying origin coordinates and a second set of coordinates for a point along the X-axis of the domain; 
:*Specifying the origin coordinate and domain orientation angle; 
:*Digitising a line (2d_loc) to represent the bottom edge of the 2D domain (with the line starting at the origin and finishing at a secondary location along the X-axis); or 
:*Digitising location polygon. 

The first method is covered in this tutorial as it is required to use a licence-free version of TUFLOW. The third method is the most commonly used. 
<ol>
<li>Create a new text file called '''M01_001.tgc''' and save it in '''Module_01\TUFLOW\model''' folder. Notice the use of ‘001’ for numbering. This is part of a naming convention, allowing for the iteration of both GIS and TUFLOW control files. This way allows files to be recognised from a specific run and also reverted back to a working iteration in model development. 
<li>Open the created '''M01_001.tgc''' in a text editor and specify the location and dimensions of the TUFLOW domain (rectangular computational area) and the cell size: 

<tt>Origin </tt> <tt>== </tt> <tt>292725, 6177615</tt> <tt> ! Bottom left corner (origin) of the 2D grid</tt> 
<tt>Orientation </tt> <tt>== </tt> <tt>293580, 6177415</tt> <tt> ! Point along the X-axis determining the orientation of the 2D grid </tt> 
<tt>Cell Size </tt> <tt>== </tt> <tt>5</tt> <tt> ! 2D cell size in metres</tt> 
<tt>Grid Size (X,Y) </tt> <tt>== </tt> <tt>850, 1000</tt> <tt> ! 2D grid extent dimensions in metres</tt> 
</ol>

=== Active and Inactive Areas of the 2D Domain ===
By default, every grid cell in a TUFLOW model is set as active and TUFLOW allows water to flow anywhere within the extents of the 2D domain. It is rare for a catchment to be a perfect rectangle. To reduce output file sizes and run times, permanently dry areas can be removed from the model. This can be an iterative process (i.e. run the model initially and refine). For the purpose of the tutorial a polygon is provided to define the active area. 
<ol>
<li>Set all 2D cells within the model domain rectangle to inactive by adding the following command to the TGC file: 
<tt>Set Code </tt> <tt>== </tt> <tt>0</tt> <tt> ! Sets all cells to inactive</tt>
<li>Define active areas: 
:*[[Tutorial_M01_Define_Active_Area_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Define_Active_Area_QGIS_GPKG | QGIS - GPKG]]
<li>Set all cells within the code polygon to active. The command needs to be written after the <tt> Set Code </tt> <tt>== </tt> <tt>0 </tt> command to overwrite the inactive cells within the polygon: 
'''QGIS - SHP''' 
<tt>Read GIS Code </tt> <tt>== </tt> <tt>gis\2d_code_M01_001_R.shp</tt> <tt> ! Sets cell codes according to attributes in the GIS layer</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Code </tt> <tt>== </tt> <tt>2d_code_M01_001_R</tt> <tt> ! Sets cell codes according to attributes in the GIS layer</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 <tt>Read GIS Code </tt> was written before the <tt>Set Code </tt> 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. 

=== 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 [https://wiki.tuflow.com/Zpt_Description Zpt Description]. 

A DEM is used to assign elevations to the Zpts: 
<ol>
<li>Copy the DEM ('''DEM.tif''') from the '''DEM''' folder into a new '''Module_01\TUFLOW\model\grid''' folder. 
<li>Set a global elevation for the Zpts by adding the following line to the TGC file: 
<tt>Set Zpts </tt> <tt>== </tt> <tt> 100</tt> <tt> ! Sets every 2D elevation zpt to 100 metres</tt> 
<li>Assign elevations to the Zpts from the DEM. The command needs to be written after the <tt> Set Zpts </tt> <tt>== </tt> <tt>100 </tt> command to overwrite global Zpts where the DEM data are available: 
<tt>Read GRID Zpts </tt> <tt>== </tt> <tt> grid\DEM.tif</tt> <tt> ! Assigns the elevation of zpts from the grid</tt> 
</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). 

=== Materials ===
Surface roughness or bed resistance values (e.g. Manning’s n) are assigned to material IDs. In order for TUFLOW to associate the Manning’s n to the Material ID, a TUFLOW materials file is required. This can be either a text file format .tmf, or a .csv file. This tutorial model utilises the csv format. 
<ol>
<li>Copy the '''materials.csv''' file from the '''Module_01\Tutorial_Data''' folder into the '''Module_01\TUFLOW\model''' folder. As a minimum this file must contain two columns; the first being the Material ID (as specified in the GIS layer), and the second being the Manning’s n. Additional data such as loss parameters and depth varying Manning's n values (applicable for direct rainfall modelling) are covered in later modules. 
 
[[File:Materials 02.png]] 
 
<li>Set a global material ID for all cells by adding the following line to the TGC file: 
<tt>Set Mat </tt> <tt>== </tt> <tt>1</tt> <tt> ! Sets all cells to a material ID of 1</tt> 
<li>Define spatial material definition:
:*[[Tutorial_M01_Materials_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Materials_QGIS_GPKG | QGIS - GPKG]]
<li>Assign materials from the GIS layer to overwrite the global material at all cells that fall within the material polygons: 
'''QGIS - SHP''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>gis\2d_mat_M01_001_R.shp</tt> <tt> ! Sets material values according to attributes in the GIS layer</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>2d_mat_M01_001_R</tt> <tt> ! Sets material values according to attributes in the GIS layer</tt> 
<li>Save the TGC file.

</ol>
Note: As discussed in the previous sections, the order (layering) of these commands is important. 
 

= TUFLOW Boundary Control File (TBC) =
In this step the TBC and Boundary Condition Database (bc_dbase) are introduced. The TBC file contains information regarding the location of boundary conditions and internal links within the model. These include, but are not limited to: 

:*Upstream and downstream flow boundaries 
:*Downstream water level boundaries 
:*Water sources 
:*Direct rainfall
:*Infiltration 
:*1D/2D links 

=== Spatial Definition of Boundary Conditions ===
The following upstream and downstream boundaries are used in this tutorial: 

:*A flow vs time (QT) boundary and a source-area (SA) boundary is used for the inflows. 
:*A stage vs discharge (HQ) boundary is used for the outflow. 

Set up boundary condition layers: 

:*[[Tutorial_M01_Boundary_Conditions_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Boundary_Conditions_QGIS_GPKG | QGIS - GPKG]]

=== TUFLOW Boundary Control File (TBC) ===
The boundary condition layers are read into TUFLOW in a new text file, the TBC. 
<ol>
<li>Create a new text file and save as '''M01_001.tbc''' in the '''Module_01\TUFLOW\model''' folder. 
<li>Open the file in a text editor and add the boundary conditions: 
'''QGIS - SHP''' 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>gis\2d_bc_M01_001_L.shp</tt> <tt> ! Reads in 2D boundaries</tt> 
<tt>Read GIS SA </tt> <tt>== </tt> <tt>gis\2d_sa_M01_001_R.shp</tt> <tt> ! Reads in 2D source area boundaries</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>2d_bc_M01_001_L</tt> <tt> ! Reads in 2D boundaries</tt> 
<tt>Read GIS SA </tt> <tt>== </tt> <tt>2d_sa_M01_001_R</tt> <tt> ! Reads in 2D source area boundaries</tt> 
<li>Save the TBC.
</ol>
 

= TUFLOW Boundary Condition Database (bc_dbase) =
The bc_dbase is a comma delimited file with .csv extension. It can be opened in any spreadsheet software or a text editor. 
A hydrograph is associated with all of the upstream boundaries: 
<ol>
<li>Open the template bc database '''TUFLOW Tutorial Model BC Database.xlsx''' from the '''Module_01\Tutorial_Data''' folder. 
<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). 
<li>Enter the text '01p2hr.csv' under the 'Source' heading. It is a source file for TUFLOW to extract the timeseries data. 
<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. 
</ol>
<li>Repeat the above process for all of the boundary conditions (i.e. FC02, FC04, FC05, FC06 and FC07). Note, FC02 is used in a later tutorial and Columns E to I are to remain black. The final bc_dbase should show as below: 
 
[[File:M01 bc dbase 003.png]] 
 
<li>Switch to the '01p2hr' sheet, and review the provided hydrographs. Note: the 'Inflow_FC02' hydrograph is not used in this tutorial. 
 
[[File:M01 100y2hr 002.png]] 
 
<li>Save both of the sheets in a csv format that TUFLOW can read. In the '''Module_01\TUFLOW\bc_dbase''' directory, there should be two new files, '''bc_dbase.csv''' and '''01p2hr.csv'''. 
</ol>
 

= 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. 
:*[[Tutorial_M01_Time_Series_Plot_Output_QGIS | QGIS - SHP]] 
:*[[Tutorial_M01_Time_Series_Plot_Output_QGIS_GPKG | QGIS - GPKG]] 
 

= TUFLOW Control File (TCF) =
The TCF file references all the control files, specifies time and output controls. This is the last step before running the simulation. 
<ol>
<li>Create a new text file and save as '''M01_5m_001.tcf''' in the '''Module_01\TUFLOW\runs''' folder. 
<li>Open the file in a text editor and add the following commands: 
'''QGIS - SHP''' 
<tt>! MODEL INITIALISATION</tt> 
<tt>Tutorial Model </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Required command to run this tutorial model licence free </tt> 
<tt>GIS Format </tt> <tt>== </tt> <tt> SHP</tt> <tt> ! Specify SHP as the output format for all GIS files</tt> 
<tt>SHP Projection </tt> <tt>== </tt> <tt> ..\model\gis\projection.prj </tt> <tt> ! Sets the GIS projection for the TUFLOW Model</tt> 
<tt>TIF Projection </tt> <tt>== </tt> <tt> ..\model\grid\DEM.tif </tt> <tt> ! Sets the GIS projection for the output grid files</tt> 
<tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt> 
'''QGIS - GPKG''' 
<tt>! MODEL INITIALISATION</tt> 
<tt>Spatial Database </tt> <tt>== </tt> <tt> ..\model\gis\M01_001.gpkg </tt> <tt> ! Specify the location of the GeoPackage Spatial Database </tt> 
<tt>Tutorial Model </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Required command to run this tutorial model licence free </tt> 
<tt>GIS Format </tt> <tt>== </tt> <tt> GPKG</tt> <tt> ! Specify GPKG as the output format for all GIS files</tt> 
<tt>GPKG Projection </tt> <tt>== </tt> <tt> ..\model\gis\projection.gpkg </tt> <tt> ! Sets the GIS projection for the TUFLOW Model</tt> 
<tt>TIF Projection </tt> <tt>== </tt> <tt> ..\model\grid\DEM.tif </tt> <tt> ! Sets the GIS projection for the output grid files</tt> 
<tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt> 
<li> Define the solution scheme and specify Sub-Grid Sampling (SGS) commands: 
<tt>! SOLUTION SCHEME</tt> 
<tt>Solution Scheme </tt> <tt>== </tt> <tt> HPC</tt> <tt> ! Heavily Parallelised Compute, uses adaptive timestepping</tt> 
<tt>Hardware </tt> <tt>== </tt> <tt> GPU</tt> <tt> ! Comment out if GPU card is not available or replace with "Hardware == CPU" </tt> 
<tt>SGS </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Switches on Sub-Grid Sampling</tt> 
<tt>SGS Sample Target Distance</tt> <tt>== </tt> <tt> 0.5</tt> <tt> ! Sets SGS Sample Target Distance to 0.5m</tt> 
For information on SGS, see Section 3.2 of the latest [https://downloads.tuflow.com/TUFLOW/Releases/2020-10/TUFLOW%20Release%20Notes.2020-10-AD.pdf Release Notes])
 

<li> Update the model inputs section. These commands reference the TGC, TBC, bc_dbase and materials file created in the above steps: 
<tt>! MODEL INPUTS</tt> 
<tt>Geometry Control File </tt> <tt>== </tt> <tt>..\model\M01_001.tgc</tt> <tt> ! Reference the TUFLOW Geometry Control File</tt> 
<tt>BC Control File </tt> <tt>== </tt> <tt> ..\model\M01_001.tbc</tt> <tt> ! Reference the TUFLOW Boundary Conditions Control File</tt> 
<tt>BC Database </tt> <tt>== </tt> <tt> ..\bc_dbase\bc_dbase.csv</tt> <tt> ! Reference the Boundary Conditions Database</tt> 
<tt>Read Materials File </tt> <tt>== </tt> <tt>..\model\materials.csv</tt> <tt> ! Reference the Materials Definition File</tt> 

<li>Add the following time control commands: 
<tt>! TIME CONTROL</tt> 
<tt>Timestep </tt> <tt>== </tt> <tt> 1</tt> <tt> ! Specifies the first 2D computational timestep of 1 second</tt> 
<tt>Start Time </tt> <tt>== </tt> <tt> 0</tt> <tt> ! Specifies a simulation start time of 0 hours</tt> 
<tt>End Time </tt> <tt>== </tt> <tt> 3</tt> <tt> ! Specifies a simulation end time of 3 hours</tt> 

<li>Add the following output folder commands: 
<tt>! OUTPUT FOLDERS</tt> 
<tt>Log Folder </tt> <tt>== </tt> <tt> log</tt> <tt> ! Location of the log output files (e.g. .tlf and _messages files)</tt> 
<tt>Output Folder </tt> <tt>== </tt> <tt> ..\results\</tt> <tt> ! Location of the 2D output files and prefixes them with the .tcf filename</tt> 
<tt>Write Check Files </tt> <tt>== </tt> <tt> ..\check\</tt> <tt> ! Location of the 2D check files and prefixes them with the .tcf filename</tt> 

<li>Add the following output settings commands: 
<tt>! OUTPUT SETTINGS</tt> 
<tt>Map Output Format </tt> <tt>== </tt> <tt> XMDF TIF</tt> <tt> ! Result file types</tt> 
<tt>Map Output Data Types </tt> <tt>== </tt> <tt> h V d dt</tt> <tt> ! Outputs water levels, velocities, depths, minimum timestep</tt> 
<tt>Map Output Interval </tt> <tt>== </tt> <tt> 300</tt> <tt> ! Outputs map data every 300 seconds (5 minutes)</tt> 
<tt>TIF Map Output Interval </tt> <tt>== </tt> <tt> 0</tt> <tt> ! Outputs only maximums for grids</tt> 

<li>Reference the 2d_po layers. When reading in time-series layers, such as 2d_po files, its necessary to use a <tt>Time Series Output Interval </tt> command. This command specifies the output interval in seconds for the time-series based output: 
'''QGIS - SHP''' 
<tt>! TIME SERIES PLOT OUTPUT</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> ..\model\gis\2d_po_M01_001_L.shp</tt> <tt> ! Reads in plot output line</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> ..\model\gis\2d_po_M01_001_P.shp</tt> <tt> ! Reads in plot output point</tt> 
<tt>Time Series Output Interval </tt> <tt>== </tt> <tt> 60</tt> <tt> ! Outputs time series data every 60 seconds</tt> 
'''QGIS - GPKG''' 
<tt>! TIME SERIES PLOT OUTPUT</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> 2d_po_M01_001_L</tt> <tt> ! Reads in plot output line</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> 2d_po_M01_001_P</tt> <tt> ! Reads in plot output point</tt> 
<tt>Time Series Output Interval </tt> <tt>== </tt> <tt> 60</tt> <tt> ! Outputs time series data every 60 seconds</tt> 
<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 explanatory. For this tutorial model they are included to clarify the purpose of each line. 
 

= Running the Simulation =
Set up a simple batch file (.bat) to run TUFLOW. This approach calls the TUFLOW executable file (.exe) and runs the TCF file.
<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\2026.0.0''' folder and the TCF name: 
<tt>"..\..\..\exe\2026.0.0\TUFLOW_iSP_w64.exe" M01_5m_001.tcf</tt> 
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 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 [https://wiki.tuflow.com/TUFLOW_Modelling_Log here]. A template is included in the '''Module_01\Tutorial_Data''' folder. 
If the simulation is successful, the console window should look like the image below.
<ol>
 
[[File:simulation_finished_b.png]] 
 
</ol>

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

= Check Files =
TUFLOW writes a series of check files during the model initialisation process when the <tt>Write Check Files </tt> command is specified in the TCF. The files are either in a tabular form (.csv), GIS Vector format (.gpkg, .shp, .mif) or GIS Raster format (.tif, .flt, .asc) and contain information on the input data processed by TUFLOW. 
While the model is running, review the added features are specified correctly: 

:*[[Tutorial_M01_Check_Files_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Check_Files_QGIS_GPKG | QGIS - GPKG]]
 

= Results=
Two map output formats specified for this tutorial:
:*TIF - Grid based output format writing map output data types separately
:*XMDF - Mesh based output format containing all map output data types in a single file
When the model is finished, review the results: 
:*[[Tutorial_M01_Results_QGIS | QGIS]]
 

= Reviewing Model Performance =
There are a number of useful outputs from TUFLOW for reviewing the model performance. 
=== TUFLOW Log File ===
The first place to look is in the TUFLOW Log File (TLF). The <tt>Log Folder </tt> <tt>== </tt> <tt> log</tt> command in the TCF controls where the log file is written. 
Navigate to the '''Module_01\TUFLOW\runs\log''' folder and open the '''M01_5m_001.tlf''' file in a text editor. Scroll down to the bottom to 'Simulation Summary'. This includes information about the computation time, messages, volume calculations and mass error. 
<ol>
 
[[File:Simulation_Summary_02a.PNG]] 
 
</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 [https://wiki.tuflow.com/HPC_Adaptive_Timestepping here]. 
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. 
 
<ol>
[[File:Simulation HPC.PNG]] 
</ol>
 

=== Other Model Performance Indicators ===
For more information on how to review HPC models, see [[HPC_Model_Review | HPC Model Review]]. 
 

= Conclusion =
:*Simple 2D TUFLOW model was created with required GIS and text based inputs.
:*Check files were used to review the model setup.
:*Results were visualised and the performance of the model reviewed. 
:*For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
:*Alternatively, see the [[TUFLOW_Example_Models#Example_Model_Catalogue | TUFLOW Example Models]] to explore the full list of TUFLOW features.
 

= Increasing Model Resolution (Optional) =
This section includes an optional exercise to reduce the cell size from 5m to 2.5m. Consider the impact this has on the model results and the runtime. 
To reduce the cell size in the model: 
<ol>
<li>Save the TUFLOW control file '''M01_5m_001.tcf''' as '''M01_2.5m_001.tcf'''.
<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, update the reference to the new TGC.
<li>Update the batch file with the updated TCF file and run the simulation.
 </ol>
 
{{Tips Navigation
|uplink=[[Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

File:Simulation finished b.png

2026-03-30T04:47:40Z

Emilie Nielsen:

Tutorial M01

2026-03-30T02:42:10Z

Emilie Nielsen: /* Running the Simulation */

= Introduction =
Read the [[Tutorial_Introduction | Tutorial Model Introduction]] before starting this tutorial. It outlines programs requiring installation and provides the tutorial dataset download link. 

In this module, a fully two-dimensional (2D) model is built with a number of TUFLOW control files and Geographic Information System (GIS) layers. 

The TUFLOW control files are: 
:* TUFLOW Simulation Control File (TCF)
:* TUFLOW Geometry Control File (TGC)
:* TUFLOW Boundary Control File (TBC)
:* TUFLOW Boundary Condition Database (bc_dbase)
:* TUFLOW Materials File (materials) 

The GIS layers are: 
:*TGC layers:
<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> *.tif: A DEM dataset defining the ground elevations within the 2D study area.
<li> 2d_mat: A layer defining the land-use (material) types within the 2D study area.</ol></ol>
:*TBC layers:
<ol><ol><li> 2d_bc: A layer defining the locations of external 2D boundaries.
<li> 2d_sa: A layer to define internal 2D flow boundaries.
</ol></ol>
:*TCF layers:
<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 [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual].
 

= 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, refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 
<ol>
[[File:Tute M01 Directory Structure v3.png|left]]
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Sub-Folder
! style="background-color:#005581; font-weight:bold; color:white;" width=10%| Input / Output
! style="background-color:#005581; font-weight:bold; color:white;" width=75%| Description
|-
| bc_dbase|| Input || Boundary condition database(s) and input time-series data.
|-
| check|| Output || GIS and other check files to carry out quality control checks (use Write Check Files).
|-
| model|| Input ||Geometry (TGC), Boundary (TBC) and other model control text files (i.e. no GIS files).
|-
| model\gis|| Input || GIS layers that are inputs to the 2D and 1D model domains are contained within this folder, model\gis is typically used for all QGIS and ArcGIS files.
|-
| 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 specified formats.
|-
| runs|| Input|| TUFLOW Control Files (TCF).
|-
| runs\log|| Output || TUFLOW log files (TLF) and messages layers.
|}
</ol>
The TUFLOW folders can be set up manually, automatically running TUFLOW model with <tt> Write Empty GIS Files </tt> command or automatically through GIS programs:
:*[[Tutorial_M01_Configure_TUFLOW_Project_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Configure_TUFLOW_Project_QGIS_GPKG | QGIS - GPKG]]
:*SMS - the folder structure listed above is automatically created before running the model using the 'Export TUFLOW files' command (see [[Run TUFLOW from within SMS | Run TUFLOW from within SMS]]).
:*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.

The following points on TUFLOW folders and filenames are worth noting:
:*TUFLOW accepts any folder structure, though the above listed format is most commonly used and is recommended. 
:*TUFLOW accepts spaces and special characters (such as ! or #) in filenames and paths, but other software may not. It is recommended that spaces and other special characters are not used in the simulation path and filenames. 
:*Folder paths, filenames, file extensions and TUFLOW commands are not case sensitive in any TUFLOW control files. 
:*Any directories that don't apply can be omitted, for example, if using QGIS or ArcMap the model\mi directory is not required. 
 

= Model Familiarisation=
Become familiar with the model location, using an aerial image and DEM: 
:*[[Tutorial_Site_Familiarisation_QGIS | QGIS]]
 

= TUFLOW Geometry Control File (TGC) =
The TGC file is a series of commands that build the geometry model. At its minimum, the TGC contains:
:*Information on the size and orientation of the grid;
:*Grid cell codes (whether cells are active or inactive);
:*Bed / ground elevations; and
:*Bed material type or flow resistance value.

Commands in the TGC file are applied in sequential order; the order (layering) of these commands is critical. The last occurrence of a command prevails, it is possible to override previous information with new data to modify the model in selected areas. This is useful but is also something to be aware of as to not override commands by mistake.

=== 2D Domain ===
Grid formats currently supported by TUFLOW include the ESRI ASCII grid format (.asc), binary grids (.flt) and geodetic grids (.tif). The Digital Elevation Model (DEM) is provided in .tif format. 

Defining the location and orientation of the TUFLOW 2D domain can be undertaken using four different methods: 
:*Specifying origin coordinates and a second set of coordinates for a point along the X-axis of the domain; 
:*Specifying the origin coordinate and domain orientation angle; 
:*Digitising a line (2d_loc) to represent the bottom edge of the 2D domain (with the line starting at the origin and finishing at a secondary location along the X-axis); or 
:*Digitising location polygon. 

The first method is covered in this tutorial as it is required to use a licence-free version of TUFLOW. The third method is the most commonly used. 
<ol>
<li>Create a new text file called '''M01_001.tgc''' and save it in '''Module_01\TUFLOW\model''' folder. Notice the use of ‘001’ for numbering. This is part of a naming convention, allowing for the iteration of both GIS and TUFLOW control files. This way allows files to be recognised from a specific run and also reverted back to a working iteration in model development. 
<li>Open the created '''M01_001.tgc''' in a text editor and specify the location and dimensions of the TUFLOW domain (rectangular computational area) and the cell size: 

<tt>Origin </tt> <tt>== </tt> <tt>292725, 6177615</tt> <tt> ! Bottom left corner (origin) of the 2D grid</tt> 
<tt>Orientation </tt> <tt>== </tt> <tt>293580, 6177415</tt> <tt> ! Point along the X-axis determining the orientation of the 2D grid </tt> 
<tt>Cell Size </tt> <tt>== </tt> <tt>5</tt> <tt> ! 2D cell size in metres</tt> 
<tt>Grid Size (X,Y) </tt> <tt>== </tt> <tt>850, 1000</tt> <tt> ! 2D grid extent dimensions in metres</tt> 
</ol>

=== Active and Inactive Areas of the 2D Domain ===
By default, every grid cell in a TUFLOW model is set as active and TUFLOW allows water to flow anywhere within the extents of the 2D domain. It is rare for a catchment to be a perfect rectangle. To reduce output file sizes and run times, permanently dry areas can be removed from the model. This can be an iterative process (i.e. run the model initially and refine). For the purpose of the tutorial a polygon is provided to define the active area. 
<ol>
<li>Set all 2D cells within the model domain rectangle to inactive by adding the following command to the TGC file: 
<tt>Set Code </tt> <tt>== </tt> <tt>0</tt> <tt> ! Sets all cells to inactive</tt>
<li>Define active areas: 
:*[[Tutorial_M01_Define_Active_Area_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Define_Active_Area_QGIS_GPKG | QGIS - GPKG]]
<li>Set all cells within the code polygon to active. The command needs to be written after the <tt> Set Code </tt> <tt>== </tt> <tt>0 </tt> command to overwrite the inactive cells within the polygon: 
'''QGIS - SHP''' 
<tt>Read GIS Code </tt> <tt>== </tt> <tt>gis\2d_code_M01_001_R.shp</tt> <tt> ! Sets cell codes according to attributes in the GIS layer</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Code </tt> <tt>== </tt> <tt>2d_code_M01_001_R</tt> <tt> ! Sets cell codes according to attributes in the GIS layer</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 <tt>Read GIS Code </tt> was written before the <tt>Set Code </tt> 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. 

=== 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 [https://wiki.tuflow.com/Zpt_Description Zpt Description]. 

A DEM is used to assign elevations to the Zpts: 
<ol>
<li>Copy the DEM ('''DEM.tif''') from the '''DEM''' folder into a new '''Module_01\TUFLOW\model\grid''' folder. 
<li>Set a global elevation for the Zpts by adding the following line to the TGC file: 
<tt>Set Zpts </tt> <tt>== </tt> <tt> 100</tt> <tt> ! Sets every 2D elevation zpt to 100 metres</tt> 
<li>Assign elevations to the Zpts from the DEM. The command needs to be written after the <tt> Set Zpts </tt> <tt>== </tt> <tt>100 </tt> command to overwrite global Zpts where the DEM data are available: 
<tt>Read GRID Zpts </tt> <tt>== </tt> <tt> grid\DEM.tif</tt> <tt> ! Assigns the elevation of zpts from the grid</tt> 
</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). 

=== Materials ===
Surface roughness or bed resistance values (e.g. Manning’s n) are assigned to material IDs. In order for TUFLOW to associate the Manning’s n to the Material ID, a TUFLOW materials file is required. This can be either a text file format .tmf, or a .csv file. This tutorial model utilises the csv format. 
<ol>
<li>Copy the '''materials.csv''' file from the '''Module_01\Tutorial_Data''' folder into the '''Module_01\TUFLOW\model''' folder. As a minimum this file must contain two columns; the first being the Material ID (as specified in the GIS layer), and the second being the Manning’s n. Additional data such as loss parameters and depth varying Manning's n values (applicable for direct rainfall modelling) are covered in later modules. 
 
[[File:Materials 02.png]] 
 
<li>Set a global material ID for all cells by adding the following line to the TGC file: 
<tt>Set Mat </tt> <tt>== </tt> <tt>1</tt> <tt> ! Sets all cells to a material ID of 1</tt> 
<li>Define spatial material definition:
:*[[Tutorial_M01_Materials_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Materials_QGIS_GPKG | QGIS - GPKG]]
<li>Assign materials from the GIS layer to overwrite the global material at all cells that fall within the material polygons: 
'''QGIS - SHP''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>gis\2d_mat_M01_001_R.shp</tt> <tt> ! Sets material values according to attributes in the GIS layer</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>2d_mat_M01_001_R</tt> <tt> ! Sets material values according to attributes in the GIS layer</tt> 
<li>Save the TGC file.

</ol>
Note: As discussed in the previous sections, the order (layering) of these commands is important. 
 

= TUFLOW Boundary Control File (TBC) =
In this step the TBC and Boundary Condition Database (bc_dbase) are introduced. The TBC file contains information regarding the location of boundary conditions and internal links within the model. These include, but are not limited to: 

:*Upstream and downstream flow boundaries 
:*Downstream water level boundaries 
:*Water sources 
:*Direct rainfall
:*Infiltration 
:*1D/2D links 

=== Spatial Definition of Boundary Conditions ===
The following upstream and downstream boundaries are used in this tutorial: 

:*A flow vs time (QT) boundary and a source-area (SA) boundary is used for the inflows. 
:*A stage vs discharge (HQ) boundary is used for the outflow. 

Set up boundary condition layers: 

:*[[Tutorial_M01_Boundary_Conditions_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Boundary_Conditions_QGIS_GPKG | QGIS - GPKG]]

=== TUFLOW Boundary Control File (TBC) ===
The boundary condition layers are read into TUFLOW in a new text file, the TBC. 
<ol>
<li>Create a new text file and save as '''M01_001.tbc''' in the '''Module_01\TUFLOW\model''' folder. 
<li>Open the file in a text editor and add the boundary conditions: 
'''QGIS - SHP''' 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>gis\2d_bc_M01_001_L.shp</tt> <tt> ! Reads in 2D boundaries</tt> 
<tt>Read GIS SA </tt> <tt>== </tt> <tt>gis\2d_sa_M01_001_R.shp</tt> <tt> ! Reads in 2D source area boundaries</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>2d_bc_M01_001_L</tt> <tt> ! Reads in 2D boundaries</tt> 
<tt>Read GIS SA </tt> <tt>== </tt> <tt>2d_sa_M01_001_R</tt> <tt> ! Reads in 2D source area boundaries</tt> 
<li>Save the TBC.
</ol>
 

= TUFLOW Boundary Condition Database (bc_dbase) =
The bc_dbase is a comma delimited file with .csv extension. It can be opened in any spreadsheet software or a text editor. 
A hydrograph is associated with all of the upstream boundaries: 
<ol>
<li>Open the template bc database '''TUFLOW Tutorial Model BC Database.xlsx''' from the '''Module_01\Tutorial_Data''' folder. 
<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). 
<li>Enter the text '01p2hr.csv' under the 'Source' heading. It is a source file for TUFLOW to extract the timeseries data. 
<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. 
</ol>
<li>Repeat the above process for all of the boundary conditions (i.e. FC02, FC04, FC05, FC06 and FC07). Note, FC02 is used in a later tutorial and Columns E to I are to remain black. The final bc_dbase should show as below: 
 
[[File:M01 bc dbase 003.png]] 
 
<li>Switch to the '01p2hr' sheet, and review the provided hydrographs. Note: the 'Inflow_FC02' hydrograph is not used in this tutorial. 
 
[[File:M01 100y2hr 002.png]] 
 
<li>Save both of the sheets in a csv format that TUFLOW can read. In the '''Module_01\TUFLOW\bc_dbase''' directory, there should be two new files, '''bc_dbase.csv''' and '''01p2hr.csv'''. 
</ol>
 

= 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. 
:*[[Tutorial_M01_Time_Series_Plot_Output_QGIS | QGIS - SHP]] 
:*[[Tutorial_M01_Time_Series_Plot_Output_QGIS_GPKG | QGIS - GPKG]] 
 

= TUFLOW Control File (TCF) =
The TCF file references all the control files, specifies time and output controls. This is the last step before running the simulation. 
<ol>
<li>Create a new text file and save as '''M01_5m_001.tcf''' in the '''Module_01\TUFLOW\runs''' folder. 
<li>Open the file in a text editor and add the following commands: 
'''QGIS - SHP''' 
<tt>! MODEL INITIALISATION</tt> 
<tt>Tutorial Model </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Required command to run this tutorial model licence free </tt> 
<tt>GIS Format </tt> <tt>== </tt> <tt> SHP</tt> <tt> ! Specify SHP as the output format for all GIS files</tt> 
<tt>SHP Projection </tt> <tt>== </tt> <tt> ..\model\gis\projection.prj </tt> <tt> ! Sets the GIS projection for the TUFLOW Model</tt> 
<tt>TIF Projection </tt> <tt>== </tt> <tt> ..\model\grid\DEM.tif </tt> <tt> ! Sets the GIS projection for the output grid files</tt> 
<tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt> 
'''QGIS - GPKG''' 
<tt>! MODEL INITIALISATION</tt> 
<tt>Spatial Database </tt> <tt>== </tt> <tt> ..\model\gis\M01_001.gpkg </tt> <tt> ! Specify the location of the GeoPackage Spatial Database </tt> 
<tt>Tutorial Model </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Required command to run this tutorial model licence free </tt> 
<tt>GIS Format </tt> <tt>== </tt> <tt> GPKG</tt> <tt> ! Specify GPKG as the output format for all GIS files</tt> 
<tt>GPKG Projection </tt> <tt>== </tt> <tt> ..\model\gis\projection.gpkg </tt> <tt> ! Sets the GIS projection for the TUFLOW Model</tt> 
<tt>TIF Projection </tt> <tt>== </tt> <tt> ..\model\grid\DEM.tif </tt> <tt> ! Sets the GIS projection for the output grid files</tt> 
<tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt> 
<li> Define the solution scheme and specify Sub-Grid Sampling (SGS) commands: 
<tt>! SOLUTION SCHEME</tt> 
<tt>Solution Scheme </tt> <tt>== </tt> <tt> HPC</tt> <tt> ! Heavily Parallelised Compute, uses adaptive timestepping</tt> 
<tt>Hardware </tt> <tt>== </tt> <tt> GPU</tt> <tt> ! Comment out if GPU card is not available or replace with "Hardware == CPU" </tt> 
<tt>SGS </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Switches on Sub-Grid Sampling</tt> 
<tt>SGS Sample Target Distance</tt> <tt>== </tt> <tt> 0.5</tt> <tt> ! Sets SGS Sample Target Distance to 0.5m</tt> 
For information on SGS, see Section 3.2 of the latest [https://downloads.tuflow.com/TUFLOW/Releases/2020-10/TUFLOW%20Release%20Notes.2020-10-AD.pdf Release Notes])
 

<li> Update the model inputs section. These commands reference the TGC, TBC, bc_dbase and materials file created in the above steps: 
<tt>! MODEL INPUTS</tt> 
<tt>Geometry Control File </tt> <tt>== </tt> <tt>..\model\M01_001.tgc</tt> <tt> ! Reference the TUFLOW Geometry Control File</tt> 
<tt>BC Control File </tt> <tt>== </tt> <tt> ..\model\M01_001.tbc</tt> <tt> ! Reference the TUFLOW Boundary Conditions Control File</tt> 
<tt>BC Database </tt> <tt>== </tt> <tt> ..\bc_dbase\bc_dbase.csv</tt> <tt> ! Reference the Boundary Conditions Database</tt> 
<tt>Read Materials File </tt> <tt>== </tt> <tt>..\model\materials.csv</tt> <tt> ! Reference the Materials Definition File</tt> 

<li>Add the following time control commands: 
<tt>! TIME CONTROL</tt> 
<tt>Timestep </tt> <tt>== </tt> <tt> 1</tt> <tt> ! Specifies the first 2D computational timestep of 1 second</tt> 
<tt>Start Time </tt> <tt>== </tt> <tt> 0</tt> <tt> ! Specifies a simulation start time of 0 hours</tt> 
<tt>End Time </tt> <tt>== </tt> <tt> 3</tt> <tt> ! Specifies a simulation end time of 3 hours</tt> 

<li>Add the following output folder commands: 
<tt>! OUTPUT FOLDERS</tt> 
<tt>Log Folder </tt> <tt>== </tt> <tt> log</tt> <tt> ! Location of the log output files (e.g. .tlf and _messages files)</tt> 
<tt>Output Folder </tt> <tt>== </tt> <tt> ..\results\</tt> <tt> ! Location of the 2D output files and prefixes them with the .tcf filename</tt> 
<tt>Write Check Files </tt> <tt>== </tt> <tt> ..\check\</tt> <tt> ! Location of the 2D check files and prefixes them with the .tcf filename</tt> 

<li>Add the following output settings commands: 
<tt>! OUTPUT SETTINGS</tt> 
<tt>Map Output Format </tt> <tt>== </tt> <tt> XMDF TIF</tt> <tt> ! Result file types</tt> 
<tt>Map Output Data Types </tt> <tt>== </tt> <tt> h V d dt</tt> <tt> ! Outputs water levels, velocities, depths, minimum timestep</tt> 
<tt>Map Output Interval </tt> <tt>== </tt> <tt> 300</tt> <tt> ! Outputs map data every 300 seconds (5 minutes)</tt> 
<tt>TIF Map Output Interval </tt> <tt>== </tt> <tt> 0</tt> <tt> ! Outputs only maximums for grids</tt> 

<li>Reference the 2d_po layers. When reading in time-series layers, such as 2d_po files, its necessary to use a <tt>Time Series Output Interval </tt> command. This command specifies the output interval in seconds for the time-series based output: 
'''QGIS - SHP''' 
<tt>! TIME SERIES PLOT OUTPUT</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> ..\model\gis\2d_po_M01_001_L.shp</tt> <tt> ! Reads in plot output line</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> ..\model\gis\2d_po_M01_001_P.shp</tt> <tt> ! Reads in plot output point</tt> 
<tt>Time Series Output Interval </tt> <tt>== </tt> <tt> 60</tt> <tt> ! Outputs time series data every 60 seconds</tt> 
'''QGIS - GPKG''' 
<tt>! TIME SERIES PLOT OUTPUT</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> 2d_po_M01_001_L</tt> <tt> ! Reads in plot output line</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> 2d_po_M01_001_P</tt> <tt> ! Reads in plot output point</tt> 
<tt>Time Series Output Interval </tt> <tt>== </tt> <tt> 60</tt> <tt> ! Outputs time series data every 60 seconds</tt> 
<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 explanatory. For this tutorial model they are included to clarify the purpose of each line. 
 

= Running the Simulation =
Set up a simple batch file (.bat) to run TUFLOW. This approach calls the TUFLOW executable file (.exe) and runs the TCF file.
<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\2026.0.0''' folder and the TCF name: 
<tt>"..\..\..\exe\2026.0.0\TUFLOW_iSP_w64.exe" M01_5m_001.tcf</tt> 
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 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 [https://wiki.tuflow.com/TUFLOW_Modelling_Log here]. A template is included in the '''Module_01\Tutorial_Data''' folder. 
If the simulation is successful, the console window should look like the image below.
<ol>
 
[[File:Simulation_Finished_a.png]] 
 
</ol>

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

= Check Files =
TUFLOW writes a series of check files during the model initialisation process when the <tt>Write Check Files </tt> command is specified in the TCF. The files are either in a tabular form (.csv), GIS Vector format (.gpkg, .shp, .mif) or GIS Raster format (.tif, .flt, .asc) and contain information on the input data processed by TUFLOW. 
While the model is running, review the added features are specified correctly: 

:*[[Tutorial_M01_Check_Files_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Check_Files_QGIS_GPKG | QGIS - GPKG]]
 

= Results=
Two map output formats specified for this tutorial:
:*TIF - Grid based output format writing map output data types separately
:*XMDF - Mesh based output format containing all map output data types in a single file
When the model is finished, review the results: 
:*[[Tutorial_M01_Results_QGIS | QGIS]]
 

= Reviewing Model Performance =
There are a number of useful outputs from TUFLOW for reviewing the model performance. 
=== TUFLOW Log File ===
The first place to look is in the TUFLOW Log File (TLF). The <tt>Log Folder </tt> <tt>== </tt> <tt> log</tt> command in the TCF controls where the log file is written. 
Navigate to the '''Module_01\TUFLOW\runs\log''' folder and open the '''M01_5m_001.tlf''' file in a text editor. Scroll down to the bottom to 'Simulation Summary'. This includes information about the computation time, messages, volume calculations and mass error. 
<ol>
 
[[File:Simulation_Summary_02a.PNG]] 
 
</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 [https://wiki.tuflow.com/HPC_Adaptive_Timestepping here]. 
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. 
 
<ol>
[[File:Simulation HPC.PNG]] 
</ol>
 

=== Other Model Performance Indicators ===
For more information on how to review HPC models, see [[HPC_Model_Review | HPC Model Review]]. 
 

= Conclusion =
:*Simple 2D TUFLOW model was created with required GIS and text based inputs.
:*Check files were used to review the model setup.
:*Results were visualised and the performance of the model reviewed. 
:*For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
:*Alternatively, see the [[TUFLOW_Example_Models#Example_Model_Catalogue | TUFLOW Example Models]] to explore the full list of TUFLOW features.
 

= Increasing Model Resolution (Optional) =
This section includes an optional exercise to reduce the cell size from 5m to 2.5m. Consider the impact this has on the model results and the runtime. 
To reduce the cell size in the model: 
<ol>
<li>Save the TUFLOW control file '''M01_5m_001.tcf''' as '''M01_2.5m_001.tcf'''.
<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, update the reference to the new TGC.
<li>Update the batch file with the updated TCF file and run the simulation.
 </ol>
 
{{Tips Navigation
|uplink=[[Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

TUFLOW SWMM Troubleshooting

2026-03-30T02:41:38Z

Emilie Nielsen: /* Simulation Console Window Flashes and Disappears */

= Introduction =
This page contains useful information outlining common modeling mistakes and steps to troubleshoot them. 

=Common Modeling Mistakes=
===Unsaved Control Files===
When changes are made in the control files and the files are not saved, errors occur.
<ol>
<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: 
 
[[File:SWMM_Troubleshooting_CommonErrors_01a.png]] 
 
<li>Use the 'Save All' tool to save all unsaved control files: 
 
[[File:SWMM_Troubleshooting_CommonErrors_02a.png]] 
 
</ol>

===Unsaved GIS Layers===
When changes are made in GIS layers and the layers are not saved, errors occur.
<ol>
<li>Check all GIS input layers are saved. If the 'Save Layer Edits' icon is available ([[File:QGIS UnsavedEdits.png|20px]]), there are unsaved edits in the layer.
<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 after the edits are complete. 
 
{{Video|name=Animation_SWMM_Troubleshooting_CommonErrors_01a.mp4|width=500}} 
</ol>

=== Unsaved SWMM INP file ===
After edits are complete and saved to the SWMM GeoPackage database, a copy of the information needs to be exported to an INP format for reading into TUFLOW. Two mistakes can occur in relation to INP files:
<ol>
<li> No INP file has been exported. If an INP file referenced in the SWMM control file (TSCF) does not exist, the following dialog will appear when attempting to run the model. If this error occurs, check the INP file has been exported from the SWMM GeoPackage and ensure the file reference in the TSCF does not contain any spelling mistakes. 
 
[[File:SWMM_Troubleshooting_CommonErrors_03a.png]] 
 

<li> The save date of the INP must be later than its associated GeoPackage file. If this is not the case, the following dialog will appear when attempting to run the model. The error will also be written to the TUFLOW Log File (.tlf). If this error occurs, export the INP file again to ensure it is newer then its associated GeoPackage file. 
 
[[File:SWMM_Troubleshooting_CommonErrors_04a.png]] 
 
</ol>

===TUFLOW Syntax Rules===
Control files use a double equal sign (<tt>==</tt>). When a single equal sign (<tt>=</tt>) is used, the simulation stops with and error at the end of the .tlf file: 
 
<ol>
[[File:SWMM_Troubleshooting_CommonErrors_05a.png]] 
 
[[File:SWMM_Troubleshooting_CommonErrors_06a.png]] 
 
</ol>

===Spelling Mistakes in Control Files===
Spelling mistakes in control files can result in a 'does not exist' pop up message: 
 
<ol>
[[File:SWMM_Troubleshooting_CommonErrors_07a.png]] 
</ol>
 
To fix the reference:
<ol>
<li>In this example, the file that cannot be found is '''TS01_01.tbc'''. Go to the folder where the file should be ('''TUFLOW\model''' folder).
<li>The file referenced should be '''TS01_001.tbc'''.
<li>Update the reference in the TCF and confirm the file can now be found by right clicking on the file and selecting open. 
{{Video|name=Animation_SWMM_Troubleshooting_CommonErrors_02a.mp4|width=1000}} 
</ol>

===Spelling Mistakes in Input Layers===
Spelling mistakes in input layers can result in an error message in the .tlf: 
 
<ol>
[[File:SWMM_Troubleshooting_CommonErrors_08a.png]] 
</ol>
 
To fix the reference:
<ol>
<li>In this example, the layer that cannot by found is '''2d_bc_SWMM_Culvert_Connections_001_L'''. This layer is within the '''TS01_001.gpkg''' database.
<li>In QGIS, within the Browser Panel, navigate to the folder containing the database (the '''TUFLOW\model\gis''' folder in this case).
<li>Locate the layer with the spelling mistake. In this case '''2d_bc_SWMM_''Culvet''_Connections_001_L'''.
<li>Right click the layer and select 'Manage' > 'Rename Layer' to save the layer under the correct name ('''2d_bc_SWMM_Culvert_Connections_001_L'''). 
 
{{Video|name=Animation_SWMM_Troubleshooting_CommonErrors_03a.mp4|width=1218}} 
</ol>

===TCF does not exist===
Typos or spaces in the TCF name result in a 'does not exist' message in the console 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. 
<li>Example of incorrect TCF name missing an underscore: 
 
[[File:SWMM_Troubleshooting_CommonErrors_09a.png]] 
 
[[File:SWMM_Troubleshooting_CommonErrors_10a.png]] 
 
<li>Example of using space in the TCF name causing TUFLOW to look for a TCF name ending with the first space: 
 
[[File:SWMM_Troubleshooting_CommonErrors_11a.png]] 
 
</ol>

===Ambiguous Command===
TUFLOW control files are command driven text files. The commands must be in the format and location TUFLOW is expecting. The [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] and the [https://docs.tuflow.com/classic-hpc/release/latest/ TUFLOW Release Notes] list all the available commands and specify which TUFLOW control file each command belongs to. 
<ol>
<li>Example of a typo in the ' <tt>BC Control File ==</tt> ' command: 
 
[[File:SWMM_Troubleshooting_CommonErrors_12a.png]] 
 
<li>Example of ' <tt>Map Output Data Types ==</tt> ' command entered into TGC instead of TCF: 
 
[[File:SWMM_Troubleshooting_CommonErrors_13a.png]] 
 
</ol>

=Troubleshooting Steps=
== Model won't run ==
=== Simulation Console Window Flashes and Disappears ===
When batch file is double clicked and the simulation console window flashes and disappears the problem might be in the filepath of the TUFLOW executable or incorrect syntax:
<ol>
<li>Check the TUFLOW executable can be found with the specified filepath (absolute or relative).
<li>Double click the executable, this performs a licence check and console 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>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>If using environment variable 'set exe', confirm there are no spaces surrounding the equals sign (e.g. <tt>set exe="..\..\..\exe\2026.0.0\TUFLOW_iSP_w64.exe"</tt>).
<li>Write '<tt>pause</tt>' at the end of the script, rerun the batch file and the console window should remain open providing more information. In the below example, the file path to the TUFLOW exe is incorrect: 
 
{{Video|name=Animation_SWMM_Troubleshooting_Steps_01a.mp4|width=1218}} 
</ol>

=== _ TUFLOW Simulations (*.log) ===
The log file contains brief overview of the simulation:
<ol>
<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' line.
<li>If there is no log file, see the '''Simulation Console Window Flashes and Disappears''' advice above. 
 
</ol>

=== TUFLOW Log File (*.tlf) ===
The .tlf file contains information on the model run status and any error messages:
<ol>
<li>Navigate to the '''TUFLOW\runs\log''' folder and open the '''.tlf''' file in a text editor.
<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: 
 
{{Video|name=Animation_SWMM_Troubleshooting_Steps_02a.mp4|width=1218}} 

<li>Open the .qgs workspace in QGIS from the '''TUFLOW\runs\log''' folder.
<li>Click 'Apply TUFLOW Styles to Open Layers'.
<li>Zoom in to the location of any error messages, turn on labelling to view the error.
<li>In this example the 2d_bc CN connection isn't snapped to the SX line. 
 
{{Video|name=Animation_SWMM_Troubleshooting_Steps_03a.mp4|width=1218}} 

<li>If no error messages appear in the .tlf and the last line shows 'Sending initialisation data to HPC...' see [[Tutorial_Troubleshooting_QGIS#HPC_TUFLOW_Log_File_.28.2Ahpc.tlf.29 | HPC TUFLOW Log File]] below.
<li>Ensure that the final cumulative mass error is less then 1%. To reduce the mass error and fix model instabilities, see [[TUFLOW_SWMM_Troubleshooting#Model_runs_with_high_mass_error_or_instabilities | Improving Model Stability]] below. 
 
[[File:SWMM_Troubleshooting_Steps_01a.png]] 
 
</ol>

=== SWMM Report File (*rpt)===
The SWMM Report File ('''*.rpt''') contains SWMM related error messages. If the error relates to SWMM, the .tlf will state: 
:<tt>NoXY: ERROR during Preparing and starting SWMM simulation</tt> 
::<tt>For SWMM Model Errors see: <<path to rpt file>></tt> 
To investigate the error(s):
<ol>
<li>Navigate to the '''TUFLOW\results''' folder and open the '''.rpt''' file in a text editor. Review the SWMM initialization error message.
<li>In this case, there is an invalid keyword in the 'OUTFALL' section. This refers to the SWMM INP file.
<li>Navigate to the '''TUFLOW\model\swmm''' folder and open the INP file in a text editor. Find and correct the error. 
 
{{Video|name=Animation_SWMM_Troubleshooting_Steps_04a.mp4|width=1218}} 
</ol>

=== HPC TUFLOW Log File (*.hpc.tlf) ===
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: 
 
[[File:SWMM_Troubleshooting_Steps_02a.png]] 
 
<li>The model is set up to run on GPU and there is no GPU available, or
<li>The GPU needs a driver update, for more information see [https://wiki.tuflow.com/index.php?title=GPU_Setup Update GPU Driver]. 
 
</ol>

== Model runs with high mass error or instabilities ==
=== Identifying Trouble Spots ===
<ol>
<li>TUFLOW GIS messages file ('''_messages.gpkg'''):
*Navigate to the '''TUFLOW\runs\log''' folder and open the '''_messages.gpkg''' file in QGIS.
*Look for instabilities and 2D timestep instability warnings in the file to identify areas of concern. They will often occur near SWMM/2D connections.
<li>SWMM Report file ('''.rpt'''):
*Navigate to the '''TUFLOW\results''' folder and open the '''.rpt''' file in a text editor.
*To determine overall model health, look at the '<tt>Continuity Error (%)</tt>'. This value should be between -0.5% and 0.5%.
*The '<tt>Highest Flow Instability Indexes</tt>' and '<tt>Most Frequent Nonconverging Nodes</tt>' may indicate areas of instability in the model.
<li>Update the Report Step:
*Open the GeoPackage file containing the SWMM options into QGIS. By default, this GeoPackage will be in the '''TUFLOW\model\swmm''' folder.
*Turn on editing for the '''Project--Options''' layer and update the 'REPORT_STEP' attribute to a small time frame (i.e. 5 seconds).
*Ensure the 'ROUTING_STEP' attribute is smaller then the new 'REPORT_STEP' value. Save the edits and export the SWMM INP.
*Rerun the model with the updated Report Step. The time series reports may then include oscillations at unstable areas. 
 
</ol>

=== Improving Model Stability ===
Below are some common causes of instabilities and methods to improve them.
<ol>
<li>The timestep:
*The timestep can cause instabilities. By default, SWMM uses the 2D timestep. Use the TCF command <tt>Timestep Maximum</tt> to force a smaller 2D timestep and improve SWMM stability. This fix is often required when using SWMM hydrology as it puts water into the 1D domain before the 2D, which can lead to large 2D timesteps.
<li>Insufficient storage at 1D nodes:
*Model instabilities often arise from insufficient storage at 1D nodes, especially those associated with HX boundaries. HX cells do not have storage associated with them, so the storage for those cells should be represented in the SWMM domain.
*Storage nodes using the 'PYRAMIDAL' type can be set up to match the 2D model. The size of the shape should correspond to the area of the 2D cells. For example, if two 10m cells are selected, the length (L) and width (W) should be set to 20m and 10m, respectively. Larger dimensions may improve stability, but increasing them too far beyond the cell size may artificially attenuate flood hydrographs.
<li>Not enough connections between the 2D cells and the SWMM 1D network:
*Instabilities may arise from having too few 2D cells connected to the SWMM 1D network. For example, a rectangular culvert 20m wide connected to a single 5m cell may create an instability. In this case, it is recommended that the culvert is connected to four (or more) cells.
<li>2D cells are raised due to a HX connection:
*Instabilities may occur if 2D cells are raised due to an HX connection. HX connections require 2D cell elevations be higher than the node elevation. If an embankment culvert is elevated above the 2D cell elevations (which is common), set the node elevation at or below the lowest 2D cell elevation. Use the 'InOffset' elevation on adjacent conduits to set the culvert to the appropriate elevation, preventing the cell from being raised to the culvert invert.
<li>Incorrectly placed SWMM connections:
*Incorrectly placed SWMM connections may lead to instabilities. For example, if an embankment culvert connects adjacent ditches, but the connections select cells adjacent to rather than containing the ditches, the improper cell selection tends to throttle the flows in 2D even though the 1D has sufficient capacity. This creates a mismatch that leads to oscillations.
<li>If the model is still unstable after trying all the above options:
*If some SWMM to 2D HX connections (embankment culverts) are still unstable, consider converting the HX connections to SX connections with an inlet. This is generally required for embankment culverts where there is overtopping so only a fraction of the flow goes through the culverts (HX culvert connections work well if the culverts convey the majority of the flow). An inlet is required for SX connections. A drop curb inlet can provide a suitable open area for a culvert connection. An SX connection with an inlet may be more stable in these situations because the discharge is based on the WSE (water surface elevation) in the cell rather than the flow going through the cell.
</ol>
 

=Conclusion=
If the above tips do not assist in fixing the error, email [mailto:support@tuflow.com support@tuflow.com]. 

TUFLOW SWMM Tutorial Models:
*[[TUFLOW_SWMM_Tutorial_M01 | TUFLOW SWMM Module 1]] - 1D SWMM Culverts
*[[TUFLOW_SWMM_Tutorial_M02 | TUFLOW SWMM Module 2]] - 1D SWMM Pipe Network / 2D TUFLOW Direct Rainfall Hydrology
*[[TUFLOW_SWMM_Tutorial_M03 | TUFLOW SWMM Module 3]] - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology
*[[TUFLOW_SWMM_Tutorial_M04 | TUFLOW SWMM Module 4]] - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology: Executing multiple different event simulations from a single model control file.
*[[XPSWMM_to_TUFLOW-SWMM | XPSWMM to TUFLOW SWMM]] - How to convert an XPSWMM model to TUFLOW SWMM.

Tutorial M01

2026-03-30T02:40:50Z

Emilie Nielsen: /* Running the Simulation */

= Introduction =
Read the [[Tutorial_Introduction | Tutorial Model Introduction]] before starting this tutorial. It outlines programs requiring installation and provides the tutorial dataset download link. 

In this module, a fully two-dimensional (2D) model is built with a number of TUFLOW control files and Geographic Information System (GIS) layers. 

The TUFLOW control files are: 
:* TUFLOW Simulation Control File (TCF)
:* TUFLOW Geometry Control File (TGC)
:* TUFLOW Boundary Control File (TBC)
:* TUFLOW Boundary Condition Database (bc_dbase)
:* TUFLOW Materials File (materials) 

The GIS layers are: 
:*TGC layers:
<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> *.tif: A DEM dataset defining the ground elevations within the 2D study area.
<li> 2d_mat: A layer defining the land-use (material) types within the 2D study area.</ol></ol>
:*TBC layers:
<ol><ol><li> 2d_bc: A layer defining the locations of external 2D boundaries.
<li> 2d_sa: A layer to define internal 2D flow boundaries.
</ol></ol>
:*TCF layers:
<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 [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual].
 

= 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, refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 
<ol>
[[File:Tute M01 Directory Structure v3.png|left]]
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Sub-Folder
! style="background-color:#005581; font-weight:bold; color:white;" width=10%| Input / Output
! style="background-color:#005581; font-weight:bold; color:white;" width=75%| Description
|-
| bc_dbase|| Input || Boundary condition database(s) and input time-series data.
|-
| check|| Output || GIS and other check files to carry out quality control checks (use Write Check Files).
|-
| model|| Input ||Geometry (TGC), Boundary (TBC) and other model control text files (i.e. no GIS files).
|-
| model\gis|| Input || GIS layers that are inputs to the 2D and 1D model domains are contained within this folder, model\gis is typically used for all QGIS and ArcGIS files.
|-
| 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 specified formats.
|-
| runs|| Input|| TUFLOW Control Files (TCF).
|-
| runs\log|| Output || TUFLOW log files (TLF) and messages layers.
|}
</ol>
The TUFLOW folders can be set up manually, automatically running TUFLOW model with <tt> Write Empty GIS Files </tt> command or automatically through GIS programs:
:*[[Tutorial_M01_Configure_TUFLOW_Project_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Configure_TUFLOW_Project_QGIS_GPKG | QGIS - GPKG]]
:*SMS - the folder structure listed above is automatically created before running the model using the 'Export TUFLOW files' command (see [[Run TUFLOW from within SMS | Run TUFLOW from within SMS]]).
:*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.

The following points on TUFLOW folders and filenames are worth noting:
:*TUFLOW accepts any folder structure, though the above listed format is most commonly used and is recommended. 
:*TUFLOW accepts spaces and special characters (such as ! or #) in filenames and paths, but other software may not. It is recommended that spaces and other special characters are not used in the simulation path and filenames. 
:*Folder paths, filenames, file extensions and TUFLOW commands are not case sensitive in any TUFLOW control files. 
:*Any directories that don't apply can be omitted, for example, if using QGIS or ArcMap the model\mi directory is not required. 
 

= Model Familiarisation=
Become familiar with the model location, using an aerial image and DEM: 
:*[[Tutorial_Site_Familiarisation_QGIS | QGIS]]
 

= TUFLOW Geometry Control File (TGC) =
The TGC file is a series of commands that build the geometry model. At its minimum, the TGC contains:
:*Information on the size and orientation of the grid;
:*Grid cell codes (whether cells are active or inactive);
:*Bed / ground elevations; and
:*Bed material type or flow resistance value.

Commands in the TGC file are applied in sequential order; the order (layering) of these commands is critical. The last occurrence of a command prevails, it is possible to override previous information with new data to modify the model in selected areas. This is useful but is also something to be aware of as to not override commands by mistake.

=== 2D Domain ===
Grid formats currently supported by TUFLOW include the ESRI ASCII grid format (.asc), binary grids (.flt) and geodetic grids (.tif). The Digital Elevation Model (DEM) is provided in .tif format. 

Defining the location and orientation of the TUFLOW 2D domain can be undertaken using four different methods: 
:*Specifying origin coordinates and a second set of coordinates for a point along the X-axis of the domain; 
:*Specifying the origin coordinate and domain orientation angle; 
:*Digitising a line (2d_loc) to represent the bottom edge of the 2D domain (with the line starting at the origin and finishing at a secondary location along the X-axis); or 
:*Digitising location polygon. 

The first method is covered in this tutorial as it is required to use a licence-free version of TUFLOW. The third method is the most commonly used. 
<ol>
<li>Create a new text file called '''M01_001.tgc''' and save it in '''Module_01\TUFLOW\model''' folder. Notice the use of ‘001’ for numbering. This is part of a naming convention, allowing for the iteration of both GIS and TUFLOW control files. This way allows files to be recognised from a specific run and also reverted back to a working iteration in model development. 
<li>Open the created '''M01_001.tgc''' in a text editor and specify the location and dimensions of the TUFLOW domain (rectangular computational area) and the cell size: 

<tt>Origin </tt> <tt>== </tt> <tt>292725, 6177615</tt> <tt> ! Bottom left corner (origin) of the 2D grid</tt> 
<tt>Orientation </tt> <tt>== </tt> <tt>293580, 6177415</tt> <tt> ! Point along the X-axis determining the orientation of the 2D grid </tt> 
<tt>Cell Size </tt> <tt>== </tt> <tt>5</tt> <tt> ! 2D cell size in metres</tt> 
<tt>Grid Size (X,Y) </tt> <tt>== </tt> <tt>850, 1000</tt> <tt> ! 2D grid extent dimensions in metres</tt> 
</ol>

=== Active and Inactive Areas of the 2D Domain ===
By default, every grid cell in a TUFLOW model is set as active and TUFLOW allows water to flow anywhere within the extents of the 2D domain. It is rare for a catchment to be a perfect rectangle. To reduce output file sizes and run times, permanently dry areas can be removed from the model. This can be an iterative process (i.e. run the model initially and refine). For the purpose of the tutorial a polygon is provided to define the active area. 
<ol>
<li>Set all 2D cells within the model domain rectangle to inactive by adding the following command to the TGC file: 
<tt>Set Code </tt> <tt>== </tt> <tt>0</tt> <tt> ! Sets all cells to inactive</tt>
<li>Define active areas: 
:*[[Tutorial_M01_Define_Active_Area_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Define_Active_Area_QGIS_GPKG | QGIS - GPKG]]
<li>Set all cells within the code polygon to active. The command needs to be written after the <tt> Set Code </tt> <tt>== </tt> <tt>0 </tt> command to overwrite the inactive cells within the polygon: 
'''QGIS - SHP''' 
<tt>Read GIS Code </tt> <tt>== </tt> <tt>gis\2d_code_M01_001_R.shp</tt> <tt> ! Sets cell codes according to attributes in the GIS layer</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Code </tt> <tt>== </tt> <tt>2d_code_M01_001_R</tt> <tt> ! Sets cell codes according to attributes in the GIS layer</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 <tt>Read GIS Code </tt> was written before the <tt>Set Code </tt> 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. 

=== 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 [https://wiki.tuflow.com/Zpt_Description Zpt Description]. 

A DEM is used to assign elevations to the Zpts: 
<ol>
<li>Copy the DEM ('''DEM.tif''') from the '''DEM''' folder into a new '''Module_01\TUFLOW\model\grid''' folder. 
<li>Set a global elevation for the Zpts by adding the following line to the TGC file: 
<tt>Set Zpts </tt> <tt>== </tt> <tt> 100</tt> <tt> ! Sets every 2D elevation zpt to 100 metres</tt> 
<li>Assign elevations to the Zpts from the DEM. The command needs to be written after the <tt> Set Zpts </tt> <tt>== </tt> <tt>100 </tt> command to overwrite global Zpts where the DEM data are available: 
<tt>Read GRID Zpts </tt> <tt>== </tt> <tt> grid\DEM.tif</tt> <tt> ! Assigns the elevation of zpts from the grid</tt> 
</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). 

=== Materials ===
Surface roughness or bed resistance values (e.g. Manning’s n) are assigned to material IDs. In order for TUFLOW to associate the Manning’s n to the Material ID, a TUFLOW materials file is required. This can be either a text file format .tmf, or a .csv file. This tutorial model utilises the csv format. 
<ol>
<li>Copy the '''materials.csv''' file from the '''Module_01\Tutorial_Data''' folder into the '''Module_01\TUFLOW\model''' folder. As a minimum this file must contain two columns; the first being the Material ID (as specified in the GIS layer), and the second being the Manning’s n. Additional data such as loss parameters and depth varying Manning's n values (applicable for direct rainfall modelling) are covered in later modules. 
 
[[File:Materials 02.png]] 
 
<li>Set a global material ID for all cells by adding the following line to the TGC file: 
<tt>Set Mat </tt> <tt>== </tt> <tt>1</tt> <tt> ! Sets all cells to a material ID of 1</tt> 
<li>Define spatial material definition:
:*[[Tutorial_M01_Materials_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Materials_QGIS_GPKG | QGIS - GPKG]]
<li>Assign materials from the GIS layer to overwrite the global material at all cells that fall within the material polygons: 
'''QGIS - SHP''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>gis\2d_mat_M01_001_R.shp</tt> <tt> ! Sets material values according to attributes in the GIS layer</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS Mat </tt> <tt>== </tt> <tt>2d_mat_M01_001_R</tt> <tt> ! Sets material values according to attributes in the GIS layer</tt> 
<li>Save the TGC file.

</ol>
Note: As discussed in the previous sections, the order (layering) of these commands is important. 
 

= TUFLOW Boundary Control File (TBC) =
In this step the TBC and Boundary Condition Database (bc_dbase) are introduced. The TBC file contains information regarding the location of boundary conditions and internal links within the model. These include, but are not limited to: 

:*Upstream and downstream flow boundaries 
:*Downstream water level boundaries 
:*Water sources 
:*Direct rainfall
:*Infiltration 
:*1D/2D links 

=== Spatial Definition of Boundary Conditions ===
The following upstream and downstream boundaries are used in this tutorial: 

:*A flow vs time (QT) boundary and a source-area (SA) boundary is used for the inflows. 
:*A stage vs discharge (HQ) boundary is used for the outflow. 

Set up boundary condition layers: 

:*[[Tutorial_M01_Boundary_Conditions_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Boundary_Conditions_QGIS_GPKG | QGIS - GPKG]]

=== TUFLOW Boundary Control File (TBC) ===
The boundary condition layers are read into TUFLOW in a new text file, the TBC. 
<ol>
<li>Create a new text file and save as '''M01_001.tbc''' in the '''Module_01\TUFLOW\model''' folder. 
<li>Open the file in a text editor and add the boundary conditions: 
'''QGIS - SHP''' 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>gis\2d_bc_M01_001_L.shp</tt> <tt> ! Reads in 2D boundaries</tt> 
<tt>Read GIS SA </tt> <tt>== </tt> <tt>gis\2d_sa_M01_001_R.shp</tt> <tt> ! Reads in 2D source area boundaries</tt> 
'''QGIS - GPKG''' 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>2d_bc_M01_001_L</tt> <tt> ! Reads in 2D boundaries</tt> 
<tt>Read GIS SA </tt> <tt>== </tt> <tt>2d_sa_M01_001_R</tt> <tt> ! Reads in 2D source area boundaries</tt> 
<li>Save the TBC.
</ol>
 

= TUFLOW Boundary Condition Database (bc_dbase) =
The bc_dbase is a comma delimited file with .csv extension. It can be opened in any spreadsheet software or a text editor. 
A hydrograph is associated with all of the upstream boundaries: 
<ol>
<li>Open the template bc database '''TUFLOW Tutorial Model BC Database.xlsx''' from the '''Module_01\Tutorial_Data''' folder. 
<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). 
<li>Enter the text '01p2hr.csv' under the 'Source' heading. It is a source file for TUFLOW to extract the timeseries data. 
<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. 
</ol>
<li>Repeat the above process for all of the boundary conditions (i.e. FC02, FC04, FC05, FC06 and FC07). Note, FC02 is used in a later tutorial and Columns E to I are to remain black. The final bc_dbase should show as below: 
 
[[File:M01 bc dbase 003.png]] 
 
<li>Switch to the '01p2hr' sheet, and review the provided hydrographs. Note: the 'Inflow_FC02' hydrograph is not used in this tutorial. 
 
[[File:M01 100y2hr 002.png]] 
 
<li>Save both of the sheets in a csv format that TUFLOW can read. In the '''Module_01\TUFLOW\bc_dbase''' directory, there should be two new files, '''bc_dbase.csv''' and '''01p2hr.csv'''. 
</ol>
 

= 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. 
:*[[Tutorial_M01_Time_Series_Plot_Output_QGIS | QGIS - SHP]] 
:*[[Tutorial_M01_Time_Series_Plot_Output_QGIS_GPKG | QGIS - GPKG]] 
 

= TUFLOW Control File (TCF) =
The TCF file references all the control files, specifies time and output controls. This is the last step before running the simulation. 
<ol>
<li>Create a new text file and save as '''M01_5m_001.tcf''' in the '''Module_01\TUFLOW\runs''' folder. 
<li>Open the file in a text editor and add the following commands: 
'''QGIS - SHP''' 
<tt>! MODEL INITIALISATION</tt> 
<tt>Tutorial Model </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Required command to run this tutorial model licence free </tt> 
<tt>GIS Format </tt> <tt>== </tt> <tt> SHP</tt> <tt> ! Specify SHP as the output format for all GIS files</tt> 
<tt>SHP Projection </tt> <tt>== </tt> <tt> ..\model\gis\projection.prj </tt> <tt> ! Sets the GIS projection for the TUFLOW Model</tt> 
<tt>TIF Projection </tt> <tt>== </tt> <tt> ..\model\grid\DEM.tif </tt> <tt> ! Sets the GIS projection for the output grid files</tt> 
<tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt> 
'''QGIS - GPKG''' 
<tt>! MODEL INITIALISATION</tt> 
<tt>Spatial Database </tt> <tt>== </tt> <tt> ..\model\gis\M01_001.gpkg </tt> <tt> ! Specify the location of the GeoPackage Spatial Database </tt> 
<tt>Tutorial Model </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Required command to run this tutorial model licence free </tt> 
<tt>GIS Format </tt> <tt>== </tt> <tt> GPKG</tt> <tt> ! Specify GPKG as the output format for all GIS files</tt> 
<tt>GPKG Projection </tt> <tt>== </tt> <tt> ..\model\gis\projection.gpkg </tt> <tt> ! Sets the GIS projection for the TUFLOW Model</tt> 
<tt>TIF Projection </tt> <tt>== </tt> <tt> ..\model\grid\DEM.tif </tt> <tt> ! Sets the GIS projection for the output grid files</tt> 
<tt>! Write Empty GIS Files == ..\model\gis\empty ! Creates template GIS layers, commented out as files were already created</tt> 
<li> Define the solution scheme and specify Sub-Grid Sampling (SGS) commands: 
<tt>! SOLUTION SCHEME</tt> 
<tt>Solution Scheme </tt> <tt>== </tt> <tt> HPC</tt> <tt> ! Heavily Parallelised Compute, uses adaptive timestepping</tt> 
<tt>Hardware </tt> <tt>== </tt> <tt> GPU</tt> <tt> ! Comment out if GPU card is not available or replace with "Hardware == CPU" </tt> 
<tt>SGS </tt> <tt>== </tt> <tt> ON</tt> <tt> ! Switches on Sub-Grid Sampling</tt> 
<tt>SGS Sample Target Distance</tt> <tt>== </tt> <tt> 0.5</tt> <tt> ! Sets SGS Sample Target Distance to 0.5m</tt> 
For information on SGS, see Section 3.2 of the latest [https://downloads.tuflow.com/TUFLOW/Releases/2020-10/TUFLOW%20Release%20Notes.2020-10-AD.pdf Release Notes])
 

<li> Update the model inputs section. These commands reference the TGC, TBC, bc_dbase and materials file created in the above steps: 
<tt>! MODEL INPUTS</tt> 
<tt>Geometry Control File </tt> <tt>== </tt> <tt>..\model\M01_001.tgc</tt> <tt> ! Reference the TUFLOW Geometry Control File</tt> 
<tt>BC Control File </tt> <tt>== </tt> <tt> ..\model\M01_001.tbc</tt> <tt> ! Reference the TUFLOW Boundary Conditions Control File</tt> 
<tt>BC Database </tt> <tt>== </tt> <tt> ..\bc_dbase\bc_dbase.csv</tt> <tt> ! Reference the Boundary Conditions Database</tt> 
<tt>Read Materials File </tt> <tt>== </tt> <tt>..\model\materials.csv</tt> <tt> ! Reference the Materials Definition File</tt> 

<li>Add the following time control commands: 
<tt>! TIME CONTROL</tt> 
<tt>Timestep </tt> <tt>== </tt> <tt> 1</tt> <tt> ! Specifies the first 2D computational timestep of 1 second</tt> 
<tt>Start Time </tt> <tt>== </tt> <tt> 0</tt> <tt> ! Specifies a simulation start time of 0 hours</tt> 
<tt>End Time </tt> <tt>== </tt> <tt> 3</tt> <tt> ! Specifies a simulation end time of 3 hours</tt> 

<li>Add the following output folder commands: 
<tt>! OUTPUT FOLDERS</tt> 
<tt>Log Folder </tt> <tt>== </tt> <tt> log</tt> <tt> ! Location of the log output files (e.g. .tlf and _messages files)</tt> 
<tt>Output Folder </tt> <tt>== </tt> <tt> ..\results\</tt> <tt> ! Location of the 2D output files and prefixes them with the .tcf filename</tt> 
<tt>Write Check Files </tt> <tt>== </tt> <tt> ..\check\</tt> <tt> ! Location of the 2D check files and prefixes them with the .tcf filename</tt> 

<li>Add the following output settings commands: 
<tt>! OUTPUT SETTINGS</tt> 
<tt>Map Output Format </tt> <tt>== </tt> <tt> XMDF TIF</tt> <tt> ! Result file types</tt> 
<tt>Map Output Data Types </tt> <tt>== </tt> <tt> h V d dt</tt> <tt> ! Outputs water levels, velocities, depths, minimum timestep</tt> 
<tt>Map Output Interval </tt> <tt>== </tt> <tt> 300</tt> <tt> ! Outputs map data every 300 seconds (5 minutes)</tt> 
<tt>TIF Map Output Interval </tt> <tt>== </tt> <tt> 0</tt> <tt> ! Outputs only maximums for grids</tt> 

<li>Reference the 2d_po layers. When reading in time-series layers, such as 2d_po files, its necessary to use a <tt>Time Series Output Interval </tt> command. This command specifies the output interval in seconds for the time-series based output: 
'''QGIS - SHP''' 
<tt>! TIME SERIES PLOT OUTPUT</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> ..\model\gis\2d_po_M01_001_L.shp</tt> <tt> ! Reads in plot output line</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> ..\model\gis\2d_po_M01_001_P.shp</tt> <tt> ! Reads in plot output point</tt> 
<tt>Time Series Output Interval </tt> <tt>== </tt> <tt> 60</tt> <tt> ! Outputs time series data every 60 seconds</tt> 
'''QGIS - GPKG''' 
<tt>! TIME SERIES PLOT OUTPUT</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> 2d_po_M01_001_L</tt> <tt> ! Reads in plot output line</tt> 
<tt>Read GIS PO </tt> <tt>== </tt> <tt> 2d_po_M01_001_P</tt> <tt> ! Reads in plot output point</tt> 
<tt>Time Series Output Interval </tt> <tt>== </tt> <tt> 60</tt> <tt> ! Outputs time series data every 60 seconds</tt> 
<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 explanatory. For this tutorial model they are included to clarify the purpose of each line. 
 

= Running the Simulation =
Set up a simple batch file (.bat) to run TUFLOW. This approach calls the TUFLOW executable file (.exe) and runs the TCF file.
<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\2025.1.0''' folder and the TCF name: 
<tt>"..\..\..\exe\2026.0.0\TUFLOW_iSP_w64.exe" M01_5m_001.tcf</tt> 
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 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 [https://wiki.tuflow.com/TUFLOW_Modelling_Log here]. A template is included in the '''Module_01\Tutorial_Data''' folder. 
If the simulation is successful, the console window should look like the image below.
<ol>
 
[[File:Simulation_Finished_a.png]] 
 
</ol>

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

= Check Files =
TUFLOW writes a series of check files during the model initialisation process when the <tt>Write Check Files </tt> command is specified in the TCF. The files are either in a tabular form (.csv), GIS Vector format (.gpkg, .shp, .mif) or GIS Raster format (.tif, .flt, .asc) and contain information on the input data processed by TUFLOW. 
While the model is running, review the added features are specified correctly: 

:*[[Tutorial_M01_Check_Files_QGIS | QGIS - SHP]]
:*[[Tutorial_M01_Check_Files_QGIS_GPKG | QGIS - GPKG]]
 

= Results=
Two map output formats specified for this tutorial:
:*TIF - Grid based output format writing map output data types separately
:*XMDF - Mesh based output format containing all map output data types in a single file
When the model is finished, review the results: 
:*[[Tutorial_M01_Results_QGIS | QGIS]]
 

= Reviewing Model Performance =
There are a number of useful outputs from TUFLOW for reviewing the model performance. 
=== TUFLOW Log File ===
The first place to look is in the TUFLOW Log File (TLF). The <tt>Log Folder </tt> <tt>== </tt> <tt> log</tt> command in the TCF controls where the log file is written. 
Navigate to the '''Module_01\TUFLOW\runs\log''' folder and open the '''M01_5m_001.tlf''' file in a text editor. Scroll down to the bottom to 'Simulation Summary'. This includes information about the computation time, messages, volume calculations and mass error. 
<ol>
 
[[File:Simulation_Summary_02a.PNG]] 
 
</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 [https://wiki.tuflow.com/HPC_Adaptive_Timestepping here]. 
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. 
 
<ol>
[[File:Simulation HPC.PNG]] 
</ol>
 

=== Other Model Performance Indicators ===
For more information on how to review HPC models, see [[HPC_Model_Review | HPC Model Review]]. 
 

= Conclusion =
:*Simple 2D TUFLOW model was created with required GIS and text based inputs.
:*Check files were used to review the model setup.
:*Results were visualised and the performance of the model reviewed. 
:*For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
:*Alternatively, see the [[TUFLOW_Example_Models#Example_Model_Catalogue | TUFLOW Example Models]] to explore the full list of TUFLOW features.
 

= Increasing Model Resolution (Optional) =
This section includes an optional exercise to reduce the cell size from 5m to 2.5m. Consider the impact this has on the model results and the runtime. 
To reduce the cell size in the model: 
<ol>
<li>Save the TUFLOW control file '''M01_5m_001.tcf''' as '''M01_2.5m_001.tcf'''.
<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, update the reference to the new TGC.
<li>Update the batch file with the updated TCF file and run the simulation.
 </ol>
 
{{Tips Navigation
|uplink=[[Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

TUFLOW Message 2595

2026-03-30T02:37:34Z

Emilie Nielsen: Created page with "{{TUFLOW_Message |tuflow_message=CHECK 2595 - FLC automatically generated for 2D BG shape. Please check _BG_UVPT check file. |alt_msg=NA |type=CHECK |message_desc= |suggestions= |uplink=2xxx Messages }}"

{{TUFLOW_Message
|tuflow_message=CHECK 2595 - FLC automatically generated for 2D BG shape. Please check _BG_UVPT check file.
|alt_msg=NA
|type=[[CHECK]]
|message_desc=
|suggestions=

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]

}}

TUFLOW Message 2596

2026-03-30T02:37:04Z

Emilie Nielsen: Created page with "{{TUFLOW_Message |tuflow_message=CHECK 2596 - Bridge Soffit is below ground level. Ground Level = <n1>; Bridge Soffit Level = <n2>; Average depth based on wetted width at Bridge Soffit Level = <n3> |alt_msg=NA |type=CHECK |message_desc= |suggestions= |uplink=2xxx Messages }}"

{{TUFLOW_Message
|tuflow_message=CHECK 2596 - Bridge Soffit is below ground level. Ground Level = <n1>; Bridge Soffit Level = <n2>; Average depth based on wetted width at Bridge Soffit Level = <n3>
|alt_msg=NA
|type=[[CHECK]]
|message_desc=
|suggestions=

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]

}}

TUFLOW CATCH Tutorial M04

2026-03-30T02:09:27Z

Emilie Nielsen: /* Running the Simulation */

= Introduction =
In this module, a TUFLOW CATCH integrated model with interventions is developed. 

TUFLOW CATCH Tutorial 04 is built from the models created in [[TUFLOW_CATCH_Tutorial_M02 | TUFLOW CATCH Tutorial 02]] and [[TUFLOW_CATCH_Tutorial_M03 | TUFLOW CATCH Tutorial 03]]. The completed TUFLOW CATCH Tutorial 03 is provided in the '''TUFLOW_CATCH_Module_04\Modelling''' folder of the download dataset as the starting point for this tutorial.
If unfamiliar with TUFLOW CATCH, it is recommended to complete [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]], [[TUFLOW_CATCH_Tutorial_M02 | TUFLOW CATCH Tutorial 02]] and [[TUFLOW_CATCH_Tutorial_M03 | TUFLOW CATCH Tutorial 03]] prior to starting this tutorial.

'''Note:''' An NVIDIA GPU card is required to run this tutorial model. If this is not available, a shortened simulation can be run on CPU by updating the following commands in the Global Settings section of the TUFLOW CATCH Control file (.tcc):

:<tt>Hardware == CPU</tt>
:<tt>End Time == 01/01/2021 12:00:00</tt>

= Meteorological Data =
Meteorological inputs are defined in boundary condition blocks within the receiving model block of the TUFLOW CATCH Control file (.tcc).  For this tutorial, timeseries meteorological data has been supplied.
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOW_CATCH_Module_04\Tutorial_Data''' folder. Copy the '''TC04_met_ts_001.csv''' and paste it in the '''TUFLOW_CATCH_Module_04\Modelling\TUFLOWFV\bc_dbase\met''' folder. This file contains the timeseries meteorological data.
<li>Open the file. As this file is read by TUFLOW FV, the first column (Time) must contain the date is ISODATE format (DD/MM/YYYY hh:mm:ss). The other columns contain the data for the meteorological conditions that will be simulated in this model: 
{|
|
* '''AIR_TEMP''': Air temperature (degrees Celsius)
|
:::* '''REL_HUM''': Relative humidity (%)
|-
|
*'''LW_RAD''': Downward longwave radiation (W m<tt>-2</tt>)
|
:::*'''W10_X''': Zonal wind velocity at 10m (m s-1)
|-
|
*'''SW_RAD''': Downward shortwave radiation (W m-2)
|
:::*'''W10_Y''': Meridional wind velocity at 10m (m s-1)
|}

[[File: TC4_met_ts_data_01a.png]] 
 
</ol>

= Simulation Control Files =
The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its configuration information refer to [[NotepadPlusPlus_Tips | Notepad++ Tips]]. 

==== Generate Template Files ====
This tutorial requires a Water Quality Control file (.fvwq) and a Sediment Transport Control file (.fvsed). Use the TUFLOW CATCH plugin to generate template files:
<ol>
<li>In QGIS, go to Processing > Toolbox from the top drop down menu options to open the Processing Toolbox.
<li>Go to TUFLOW Catch in the processing tool list and select 'Create TUFLOW Catch Project'. This opens the dialog shown below:
*Project Name: '''TC04'''
*Project Folder: Click '...', and navigate to the '''TUFLOW_CATCH_Module_04\Modelling''' folder.
*Project CRS: Click the drop down menu and select 'Project CRS: EPSG:32760 - WGS 84 / UTM zone 60S’.
* TUFLOW HPC Executable: Click '...', and navigate to the '''exe\TUFLOW\2026.0.0 folder'''. Select '''TUFLOW_iSP_w64.exe'''.
* TUFLOW FV Executable: Click '...', and navigate to the '''exe\TUFLOWFV\2026.0.0''' folder. Select '''TUFLOWFV.exe'''.
* Default GIS Format: Click the drop down menu and select 'SHP'.
* Tick on 'Setup Control File Templates'.
* Control File Templates: Expand the 'Advanced Parameters' section. Click '...', and tick on: Water Quality Control file (.fvwq) and Sediment Control file (.fvsed). Ensure all other files are ticked off.
<li> Click 'Run'. Once the tool has finished click 'Close'. 
 
[[File: TC4_Create_CATCH_Project_01a.png]] 
 
</ol>

=== Water Quality Control File (FVWQ) ===
<ol>
<li> Navigate to the '''TUFLOWFV\wqm''' folder and open '''TC04_001.fvwq''' in a text editor.
<li> In the 'Simulation Controls' sections, update the following commands: 
<tt>Simulation Class == DO ! Specify the simulation class to Dissolved Oxygen</tt> 
<tt>WQ dt == 300 ! Interval for updating the water quality module </tt> 
<tt>WQ Units == mgL ! Specify the units to be mgL </tt> 

<li> In the 'Constituent Model Settings', add the following commands to specify the constituent (oxygen and pathogens) parameters. For more information on the model settings for each constituent, refer to the TUFLOW FV Water Quality Manual: [https://docs.tuflow.com/fv/wqm/manual/2025.1/SimulationConstruction-1.html#ConModClssOxy-4 Section 4.6.3.1 (Oxygen)] and [https://docs.tuflow.com/fv/wqm/manual/2025.1/SimulationConstruction-1.html#ConModClssPth-4 Section 4.6.3.2 (Pathogens)]. 
<tt>Oxygen Model == O2 ! Set the oxygen model</tt> 
:<tt>Oxygen Min Max == 0.0, 12.0 ! Specify the allowable minimum and maximum oxygen concentrations</tt> 
:<tt>Oxygen Benthic == 4.7, 1.08 ! Specify the global benthic parameters </tt> 
<tt>End Oxygen Model</tt> 
<tt>Pathogen Model == Free, Ecoli ! Set the pathogen model and name</tt> 
:<tt>Alive Min Max == 0.0, 1e7 ! Specify the allowable minimum and maximum concentrations</tt> 
:<tt>Mortality == 0.08, 2e-12, 6.1, 1.0, 1.11 ! Specify the mortality parameters</tt> 
:<tt>Visible Inactivation == 0.082, 0.0067, 0.5 ! Specify the visible light inactivation parameters</tt> 
:<tt>UVA Inactivation == 0.5, 0.0067, 0.5 ! Specify the UV-A light inactivation parameters</tt> 
:<tt>UVB Inactivation == 1.0, 0.0067, 0.5 ! Specify the UV-B light inactivation parameters</tt> 
:<tt>Settling == -0.03 ! Specify the settling of non-attached pathogens</tt> 
<tt>End Pathogen Model</tt> 

<li> In the 'Material Specifications' section, add the following material blocks to specify oxygen flux for each material ID. 
<tt>Material == Default ! Defines default properties for all materials</tt> 
:<tt>Oxygen Flux == -1400.0 </tt> 
<tt>End Material</tt> 
<tt>Material == 1 ! Defines properties for material ID 1 (overwrites default)</tt> 
:<tt>Oxygen Flux == -1100.0 </tt> 
<tt>End Material</tt> 
<tt>Material == 2 ! Defines properties for material ID 2 (overwrites default)</tt> 
:<tt>Oxygen Flux == -1200.0 </tt> 
<tt>End Material</tt> 
<tt>Material == 3 ! Defines properties for material ID 3 (overwrites default)</tt> 
:<tt>Oxygen Flux == -1300.0 </tt> 
<tt>End Material</tt> 

<li> Save the FVWQ.
</ol>

=== Sediment Transport Control File (FVSED) ===
<ol>
<li> Navigate to the '''TUFLOWFV\stm''' folder and open '''TC04_001.fvsed''' in a text editor.
<li> Update the following command to match the output interval for the rest of the model (300secs or 5mins): 
<tt>Update dt == 300 ! Interval for updating the sediment transport module</tt> 

<li> In the 'Settings' section, update the following commands. For more information on these commands, please refer to the [https://downloads.tuflow.com/TUFLOWFV/Releases/Latest/TUFLOW_FV_ST_and_PT_Modules_User_Manual.pdf TUFLOW FV Sediment Transport Manual]. 
<tt>Erosion Depth Limits == 0.1, 0.5 ! Depth limits within which the erosion rate is scaled down (meters)</tt> 
<tt>Deposition Depth Limits == 0.1, 0.5 ! Depth limits within which the deposition rate is scaled down (meters)</tt> 
<tt>Bed Roughness Model == ks ! Set bed roughness model</tt> 
<tt>Bed Roughness Parameters == 0.02, 0.02 ! Specify the bed roughness for current and waves</tt> 

<li> In the 'Fractions' section, add in the following Fraction block to set the parameters for clay. 
<tt>Fraction == Clay ! Set sediment fraction</tt> 
:<tt>d50 == 0.0002 ! Specify the median grain size of the sediment fraction (meters)</tt> 
:<tt>Particle Density == 2650.0 ! Specify the density of the particle group (kg/m3)</tt> 
:<tt>Settling Model == Constant ! Set the settling model</tt> 
:<tt>Settling Parameters == 1e-05 ! Specify constant settling velocity (m/s)</tt> 
:<tt>Critical Stress Model == Constant ! Set the critical stress model</tt> 
:<tt>Critical Stress Parameters == 0.15 ! Specify constant critical stress (N/m2)</tt> 
:<tt>Erosion Model == Mehta ! Set the erosion model</tt> 
:<tt>Erosion Parameters == 0.01, 0.5, 1.0 ! Specify constant erosion rate (g/m2s), critical shear stress (N/m2) and power coefficient</tt> 
:<tt>Deposition Model == ws0 ! Set the deposition model</tt> 
<tt>End Fraction</tt> 

<li> In the 'Materials' section, add the following material blocks to set the sediment transport for each material ID. 
<tt>Material == 1, 2 ! Defines properties for material IDs 1 and 2</tt> 
:<tt>Nlayer == 1 ! Number of sediment bed layers</tt> 
:<tt>Layer == 1 ! Bed layer number </tt> 
::<tt>Dry Density == 800 ! Dry density of bed layer (kg/m3) </tt> 
::<tt>Initial Mass == 1500 ! Initial mass of each sediment fraction (kg/m2) </tt> 
:<tt>End Layer</tt> 
<tt>End Material</tt> 
<tt>Material == 3 ! Defines properties for material ID 3</tt> 
:<tt>Nlayer == 1 ! Number of sediment bed layers</tt> 
:<tt>Layer == 1 ! Bed layer number </tt> 
::<tt>Dry Density == 800 ! Dry density of bed layer (kg/m3) </tt> 
::<tt>Initial Mass == 3200 ! Initial mass of each sediment fraction (kg/m2) </tt> 
:<tt>End Layer</tt> 
<tt>End Material</tt> 

<li>Save the FVSED.
</ol>

== TUFLOW CATCH Control File (TCC) ==
=== Global Settings ===
For this tutorial, leave all commands as is. This section of the .tcc was populated in [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]].

=== Catchment Hydraulic Model ===
This block contains commands that construct the TUFLOW HPC simulation.
<ol>
<li> Save a copy of '''TC03_001.tcc''' as '''TC04_001.tcc''' in the '''TUFLOW_CATCH_Module_04\Modelling\TUFLOWCATCH\runs''' folder.
<li> Open '''TC04_001.tcc''' in a text editor, and comment out the following command: 
<tt>! Pollutant == Salinity, Temperature, WQ_DISS_OXYGEN_MG_L, WQ_PATH_ECOLI_ALIVE_CFU_100ML, WQ_PATH_ECOLI_DEAD_CFU_100ML, SED_CLAY ! Specify the pollutant names</tt> 
</ol>

=== Pollutant Export Model ===
This block contains commands that control the pollutant export (and other constituent) simulation. As this tutorial model is an integrated simulation with interventions, we must turn the pollutant export model back on:
<ol>
<li> Set the pollutant export model: 
<tt>Catchment Pollutant Export Model == Mass Accumulation Release </tt> 
<li> Uncomment all the commands. The pollutant export model block should look the same as in [[TUFLOW_CATCH_Tutorial_M02#Pollutant_Export_Model | TUFLOW CATCH Tutorial 02]]
</ol>

=== Receiving Model ===
This block contains commands that construct the TUFLOW FV simulation. For this tutorial, the receiving model block must be updated to include water quality and sediment transport.
<ol>
<li> In the 'General Parameters' section, update the following commands to turn on salinity, temperature, sediment and heat. For more information on these commands, refer to [https://downloads.tuflow.com/TUFLOWFV/Releases/Latest/TUFLOW_FV_User_Manual.pdf Appendix B of the TUFLOW FV Manual]  
<tt>Include Salinity == 1,0 </tt> 
<tt>Include Temperature == 1,0 </tt> 
<tt>Include Sediment == 1,0 </tt> 
<tt>Include Heat == 1 </tt> 

<li> In the 'Water Quality' section, update the following commands to set the general WQ parameters and to reference the Water Quality Control file. 
<tt>Water Quality Model == TUFLOW </tt> 
<tt>Water Quality Control File == ..\..\TUFLOWFV\wqm\TC04_001.fvwq ! Reference the Water Quality Control File</tt> 
<tt>Water Quality Model Directory == ..\..\TUFLOWFV\wqm\ ! Location of the Water Quality Directory</tt> 
<tt>Cell Water Quality Depth == 0.05 ! Minimum depth to execute water quality calculations (meters)</tt> 

<li> In the 'Sediment Transport' section, update the following command to reference the Sediment Control file: 
<tt>Sediment Control File == ..\..\TUFLOWFV\stm\TC04_001.fvsed ! Reference the Sediment Control File</tt> 

<li> In the 'Initial Conditions' section, update the following commands to set the initial temperature, salinity, sediment concentration and water quality concentrations. The initial water level was set in [[TUFLOW_CATCH_Tutorial_M03#Receiving_Model | TUFLOW CATCH Tutorial 03]]. 
<tt>Initial Temperature == 17.0 ! Specify initial temperature (degrees Celsius)</tt> 
<tt>Initial Salinity == 0.0 ! Specify initial salinity (psu)</tt> 
<tt>Initial Sediment Concentration == 20 ! Specify initial suspended sediment concentration for clay (mg/L)</tt> 
<tt>Initial WQ Concentration == 8.0, 1e6, 1e6 ! Specify initial water quality concentration for dissolved oxygen, alive and dead E. coli</tt> 

<li>In the 'Meteorology' section, add the following boundary condition blocks to specify meteorological conditions. The variable '<tt>met_ts</tt>' is used to define the location of the meteorological data. 
<tt>Set Variable met_ts == ..\..\TUFLOWFV\bc_dbase\met\TC04_met_ts_001.csv </tt> 
<tt>BC == LW_RAD, <<met_ts>> ! Downward longwave radiation (W m-2)</tt> 
:<tt>BC Header == Time, LW_RAD ! Column headers to read from time series file</tt> 
:<tt>BC Update dt == 300 ! Specify update timestep for BC (seconds)</tt> 
:<tt>BC Time Units == Hours ! Specify time units</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00 ! Specify boundary condition reference time</tt> 
<tt>End BC</tt> 
<tt>BC == SW_RAD, <<met_ts>> ! Downward shortwave radiation (W m-2)</tt> 
:<tt>BC Header == Time, SW_RAD</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 
<tt>BC == W10, <<met_ts>> ! Wind velocity at 10m (m s-1)</tt> 
:<tt>BC Header == Time, W10_X, W10_Y</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 
<tt>BC == AIR_TEMP, <<met_ts>> ! Temperature input (deg C)</tt> 
:<tt>BC Header == Time, AIR_TEMP</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 
<tt>BC == REL_HUM, <<met_ts>> ! Relative humidity (%)</tt> 
:<tt>BC Header == Time, REL_HUM</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 

<li> In the 'Outputs' section, update the existing NetCDF output block to include sediment: 
<tt>Output == NetCDF </tt> 
:<tt>Output Parameters == h, v, d, sed_1 ! Outputs water level, velocity, depth and sediment</tt> 
:<tt>Output Interval == 30 ! Interval to output the data (seconds) </tt> 
:<tt>Suffix == HD ! Specify suffix for the output NetCDF file </tt>
<tt>End Output</tt> 

<li> At the end of the 'Outputs' section, add the following output block to output water quality results. 
<tt>Output == NetCDF </tt> 
:<tt>Output Parameters == wq_all ! Outputs water quality results </tt> 
:<tt>Output Interval == 30 ! Interval to output the data (seconds) </tt> 
:<tt>Suffix == WQ ! Specify suffix for the output NetCDF file </tt>
<tt>End Output</tt> 

<li>Save the TCC.
</ol>

= Running the Simulation =
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOWCATCH\runs''' folder. Save a copy of '''_run_TC03_CATCH.bat''' as '''_run_TC04_CATCH.bat''' and open the file in a text editor.
<li>Update the batch file to reference the '''TC04_001.tcc''': 
<tt>set exe="..\..\..\..\exe\TUFLOWCATCH\2026.0.0\TUFLOWCATCH.exe"</tt> 
<tt>%exe% TC04_001.tcc</tt>
<li>Double click the batch file in file explorer to run the simulation. 
</ol>

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

= Results Output =
Complete the steps outlined in the following links to review simulation results from the TUFLOW CATCH integrated model simulation:
:*[[TUFLOW_CATCH_Tutorial_M04_Results_QGIS | TC04 - Results]] 

= Conclusion =
* A TUFLOW CATCH Integrated model was created.
* Meteorological data, water quality and sediment transport were added to the model.
* A TUFLOW CATCH JSON file was created to review the transfer of results (particularly pollutants) between the TUFLOW HPC and the TUFLOW FV domains.
* For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

TUFLOW CATCH Tutorial M04

2026-03-30T02:09:18Z

Emilie Nielsen: /* Simulation Control Files */

= Introduction =
In this module, a TUFLOW CATCH integrated model with interventions is developed. 

TUFLOW CATCH Tutorial 04 is built from the models created in [[TUFLOW_CATCH_Tutorial_M02 | TUFLOW CATCH Tutorial 02]] and [[TUFLOW_CATCH_Tutorial_M03 | TUFLOW CATCH Tutorial 03]]. The completed TUFLOW CATCH Tutorial 03 is provided in the '''TUFLOW_CATCH_Module_04\Modelling''' folder of the download dataset as the starting point for this tutorial.
If unfamiliar with TUFLOW CATCH, it is recommended to complete [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]], [[TUFLOW_CATCH_Tutorial_M02 | TUFLOW CATCH Tutorial 02]] and [[TUFLOW_CATCH_Tutorial_M03 | TUFLOW CATCH Tutorial 03]] prior to starting this tutorial.

'''Note:''' An NVIDIA GPU card is required to run this tutorial model. If this is not available, a shortened simulation can be run on CPU by updating the following commands in the Global Settings section of the TUFLOW CATCH Control file (.tcc):

:<tt>Hardware == CPU</tt>
:<tt>End Time == 01/01/2021 12:00:00</tt>

= Meteorological Data =
Meteorological inputs are defined in boundary condition blocks within the receiving model block of the TUFLOW CATCH Control file (.tcc).  For this tutorial, timeseries meteorological data has been supplied.
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOW_CATCH_Module_04\Tutorial_Data''' folder. Copy the '''TC04_met_ts_001.csv''' and paste it in the '''TUFLOW_CATCH_Module_04\Modelling\TUFLOWFV\bc_dbase\met''' folder. This file contains the timeseries meteorological data.
<li>Open the file. As this file is read by TUFLOW FV, the first column (Time) must contain the date is ISODATE format (DD/MM/YYYY hh:mm:ss). The other columns contain the data for the meteorological conditions that will be simulated in this model: 
{|
|
* '''AIR_TEMP''': Air temperature (degrees Celsius)
|
:::* '''REL_HUM''': Relative humidity (%)
|-
|
*'''LW_RAD''': Downward longwave radiation (W m<tt>-2</tt>)
|
:::*'''W10_X''': Zonal wind velocity at 10m (m s-1)
|-
|
*'''SW_RAD''': Downward shortwave radiation (W m-2)
|
:::*'''W10_Y''': Meridional wind velocity at 10m (m s-1)
|}

[[File: TC4_met_ts_data_01a.png]] 
 
</ol>

= Simulation Control Files =
The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its configuration information refer to [[NotepadPlusPlus_Tips | Notepad++ Tips]]. 

==== Generate Template Files ====
This tutorial requires a Water Quality Control file (.fvwq) and a Sediment Transport Control file (.fvsed). Use the TUFLOW CATCH plugin to generate template files:
<ol>
<li>In QGIS, go to Processing > Toolbox from the top drop down menu options to open the Processing Toolbox.
<li>Go to TUFLOW Catch in the processing tool list and select 'Create TUFLOW Catch Project'. This opens the dialog shown below:
*Project Name: '''TC04'''
*Project Folder: Click '...', and navigate to the '''TUFLOW_CATCH_Module_04\Modelling''' folder.
*Project CRS: Click the drop down menu and select 'Project CRS: EPSG:32760 - WGS 84 / UTM zone 60S’.
* TUFLOW HPC Executable: Click '...', and navigate to the '''exe\TUFLOW\2026.0.0 folder'''. Select '''TUFLOW_iSP_w64.exe'''.
* TUFLOW FV Executable: Click '...', and navigate to the '''exe\TUFLOWFV\2026.0.0''' folder. Select '''TUFLOWFV.exe'''.
* Default GIS Format: Click the drop down menu and select 'SHP'.
* Tick on 'Setup Control File Templates'.
* Control File Templates: Expand the 'Advanced Parameters' section. Click '...', and tick on: Water Quality Control file (.fvwq) and Sediment Control file (.fvsed). Ensure all other files are ticked off.
<li> Click 'Run'. Once the tool has finished click 'Close'. 
 
[[File: TC4_Create_CATCH_Project_01a.png]] 
 
</ol>

=== Water Quality Control File (FVWQ) ===
<ol>
<li> Navigate to the '''TUFLOWFV\wqm''' folder and open '''TC04_001.fvwq''' in a text editor.
<li> In the 'Simulation Controls' sections, update the following commands: 
<tt>Simulation Class == DO ! Specify the simulation class to Dissolved Oxygen</tt> 
<tt>WQ dt == 300 ! Interval for updating the water quality module </tt> 
<tt>WQ Units == mgL ! Specify the units to be mgL </tt> 

<li> In the 'Constituent Model Settings', add the following commands to specify the constituent (oxygen and pathogens) parameters. For more information on the model settings for each constituent, refer to the TUFLOW FV Water Quality Manual: [https://docs.tuflow.com/fv/wqm/manual/2025.1/SimulationConstruction-1.html#ConModClssOxy-4 Section 4.6.3.1 (Oxygen)] and [https://docs.tuflow.com/fv/wqm/manual/2025.1/SimulationConstruction-1.html#ConModClssPth-4 Section 4.6.3.2 (Pathogens)]. 
<tt>Oxygen Model == O2 ! Set the oxygen model</tt> 
:<tt>Oxygen Min Max == 0.0, 12.0 ! Specify the allowable minimum and maximum oxygen concentrations</tt> 
:<tt>Oxygen Benthic == 4.7, 1.08 ! Specify the global benthic parameters </tt> 
<tt>End Oxygen Model</tt> 
<tt>Pathogen Model == Free, Ecoli ! Set the pathogen model and name</tt> 
:<tt>Alive Min Max == 0.0, 1e7 ! Specify the allowable minimum and maximum concentrations</tt> 
:<tt>Mortality == 0.08, 2e-12, 6.1, 1.0, 1.11 ! Specify the mortality parameters</tt> 
:<tt>Visible Inactivation == 0.082, 0.0067, 0.5 ! Specify the visible light inactivation parameters</tt> 
:<tt>UVA Inactivation == 0.5, 0.0067, 0.5 ! Specify the UV-A light inactivation parameters</tt> 
:<tt>UVB Inactivation == 1.0, 0.0067, 0.5 ! Specify the UV-B light inactivation parameters</tt> 
:<tt>Settling == -0.03 ! Specify the settling of non-attached pathogens</tt> 
<tt>End Pathogen Model</tt> 

<li> In the 'Material Specifications' section, add the following material blocks to specify oxygen flux for each material ID. 
<tt>Material == Default ! Defines default properties for all materials</tt> 
:<tt>Oxygen Flux == -1400.0 </tt> 
<tt>End Material</tt> 
<tt>Material == 1 ! Defines properties for material ID 1 (overwrites default)</tt> 
:<tt>Oxygen Flux == -1100.0 </tt> 
<tt>End Material</tt> 
<tt>Material == 2 ! Defines properties for material ID 2 (overwrites default)</tt> 
:<tt>Oxygen Flux == -1200.0 </tt> 
<tt>End Material</tt> 
<tt>Material == 3 ! Defines properties for material ID 3 (overwrites default)</tt> 
:<tt>Oxygen Flux == -1300.0 </tt> 
<tt>End Material</tt> 

<li> Save the FVWQ.
</ol>

=== Sediment Transport Control File (FVSED) ===
<ol>
<li> Navigate to the '''TUFLOWFV\stm''' folder and open '''TC04_001.fvsed''' in a text editor.
<li> Update the following command to match the output interval for the rest of the model (300secs or 5mins): 
<tt>Update dt == 300 ! Interval for updating the sediment transport module</tt> 

<li> In the 'Settings' section, update the following commands. For more information on these commands, please refer to the [https://downloads.tuflow.com/TUFLOWFV/Releases/Latest/TUFLOW_FV_ST_and_PT_Modules_User_Manual.pdf TUFLOW FV Sediment Transport Manual]. 
<tt>Erosion Depth Limits == 0.1, 0.5 ! Depth limits within which the erosion rate is scaled down (meters)</tt> 
<tt>Deposition Depth Limits == 0.1, 0.5 ! Depth limits within which the deposition rate is scaled down (meters)</tt> 
<tt>Bed Roughness Model == ks ! Set bed roughness model</tt> 
<tt>Bed Roughness Parameters == 0.02, 0.02 ! Specify the bed roughness for current and waves</tt> 

<li> In the 'Fractions' section, add in the following Fraction block to set the parameters for clay. 
<tt>Fraction == Clay ! Set sediment fraction</tt> 
:<tt>d50 == 0.0002 ! Specify the median grain size of the sediment fraction (meters)</tt> 
:<tt>Particle Density == 2650.0 ! Specify the density of the particle group (kg/m3)</tt> 
:<tt>Settling Model == Constant ! Set the settling model</tt> 
:<tt>Settling Parameters == 1e-05 ! Specify constant settling velocity (m/s)</tt> 
:<tt>Critical Stress Model == Constant ! Set the critical stress model</tt> 
:<tt>Critical Stress Parameters == 0.15 ! Specify constant critical stress (N/m2)</tt> 
:<tt>Erosion Model == Mehta ! Set the erosion model</tt> 
:<tt>Erosion Parameters == 0.01, 0.5, 1.0 ! Specify constant erosion rate (g/m2s), critical shear stress (N/m2) and power coefficient</tt> 
:<tt>Deposition Model == ws0 ! Set the deposition model</tt> 
<tt>End Fraction</tt> 

<li> In the 'Materials' section, add the following material blocks to set the sediment transport for each material ID. 
<tt>Material == 1, 2 ! Defines properties for material IDs 1 and 2</tt> 
:<tt>Nlayer == 1 ! Number of sediment bed layers</tt> 
:<tt>Layer == 1 ! Bed layer number </tt> 
::<tt>Dry Density == 800 ! Dry density of bed layer (kg/m3) </tt> 
::<tt>Initial Mass == 1500 ! Initial mass of each sediment fraction (kg/m2) </tt> 
:<tt>End Layer</tt> 
<tt>End Material</tt> 
<tt>Material == 3 ! Defines properties for material ID 3</tt> 
:<tt>Nlayer == 1 ! Number of sediment bed layers</tt> 
:<tt>Layer == 1 ! Bed layer number </tt> 
::<tt>Dry Density == 800 ! Dry density of bed layer (kg/m3) </tt> 
::<tt>Initial Mass == 3200 ! Initial mass of each sediment fraction (kg/m2) </tt> 
:<tt>End Layer</tt> 
<tt>End Material</tt> 

<li>Save the FVSED.
</ol>

== TUFLOW CATCH Control File (TCC) ==
=== Global Settings ===
For this tutorial, leave all commands as is. This section of the .tcc was populated in [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]].

=== Catchment Hydraulic Model ===
This block contains commands that construct the TUFLOW HPC simulation.
<ol>
<li> Save a copy of '''TC03_001.tcc''' as '''TC04_001.tcc''' in the '''TUFLOW_CATCH_Module_04\Modelling\TUFLOWCATCH\runs''' folder.
<li> Open '''TC04_001.tcc''' in a text editor, and comment out the following command: 
<tt>! Pollutant == Salinity, Temperature, WQ_DISS_OXYGEN_MG_L, WQ_PATH_ECOLI_ALIVE_CFU_100ML, WQ_PATH_ECOLI_DEAD_CFU_100ML, SED_CLAY ! Specify the pollutant names</tt> 
</ol>

=== Pollutant Export Model ===
This block contains commands that control the pollutant export (and other constituent) simulation. As this tutorial model is an integrated simulation with interventions, we must turn the pollutant export model back on:
<ol>
<li> Set the pollutant export model: 
<tt>Catchment Pollutant Export Model == Mass Accumulation Release </tt> 
<li> Uncomment all the commands. The pollutant export model block should look the same as in [[TUFLOW_CATCH_Tutorial_M02#Pollutant_Export_Model | TUFLOW CATCH Tutorial 02]]
</ol>

=== Receiving Model ===
This block contains commands that construct the TUFLOW FV simulation. For this tutorial, the receiving model block must be updated to include water quality and sediment transport.
<ol>
<li> In the 'General Parameters' section, update the following commands to turn on salinity, temperature, sediment and heat. For more information on these commands, refer to [https://downloads.tuflow.com/TUFLOWFV/Releases/Latest/TUFLOW_FV_User_Manual.pdf Appendix B of the TUFLOW FV Manual]  
<tt>Include Salinity == 1,0 </tt> 
<tt>Include Temperature == 1,0 </tt> 
<tt>Include Sediment == 1,0 </tt> 
<tt>Include Heat == 1 </tt> 

<li> In the 'Water Quality' section, update the following commands to set the general WQ parameters and to reference the Water Quality Control file. 
<tt>Water Quality Model == TUFLOW </tt> 
<tt>Water Quality Control File == ..\..\TUFLOWFV\wqm\TC04_001.fvwq ! Reference the Water Quality Control File</tt> 
<tt>Water Quality Model Directory == ..\..\TUFLOWFV\wqm\ ! Location of the Water Quality Directory</tt> 
<tt>Cell Water Quality Depth == 0.05 ! Minimum depth to execute water quality calculations (meters)</tt> 

<li> In the 'Sediment Transport' section, update the following command to reference the Sediment Control file: 
<tt>Sediment Control File == ..\..\TUFLOWFV\stm\TC04_001.fvsed ! Reference the Sediment Control File</tt> 

<li> In the 'Initial Conditions' section, update the following commands to set the initial temperature, salinity, sediment concentration and water quality concentrations. The initial water level was set in [[TUFLOW_CATCH_Tutorial_M03#Receiving_Model | TUFLOW CATCH Tutorial 03]]. 
<tt>Initial Temperature == 17.0 ! Specify initial temperature (degrees Celsius)</tt> 
<tt>Initial Salinity == 0.0 ! Specify initial salinity (psu)</tt> 
<tt>Initial Sediment Concentration == 20 ! Specify initial suspended sediment concentration for clay (mg/L)</tt> 
<tt>Initial WQ Concentration == 8.0, 1e6, 1e6 ! Specify initial water quality concentration for dissolved oxygen, alive and dead E. coli</tt> 

<li>In the 'Meteorology' section, add the following boundary condition blocks to specify meteorological conditions. The variable '<tt>met_ts</tt>' is used to define the location of the meteorological data. 
<tt>Set Variable met_ts == ..\..\TUFLOWFV\bc_dbase\met\TC04_met_ts_001.csv </tt> 
<tt>BC == LW_RAD, <<met_ts>> ! Downward longwave radiation (W m-2)</tt> 
:<tt>BC Header == Time, LW_RAD ! Column headers to read from time series file</tt> 
:<tt>BC Update dt == 300 ! Specify update timestep for BC (seconds)</tt> 
:<tt>BC Time Units == Hours ! Specify time units</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00 ! Specify boundary condition reference time</tt> 
<tt>End BC</tt> 
<tt>BC == SW_RAD, <<met_ts>> ! Downward shortwave radiation (W m-2)</tt> 
:<tt>BC Header == Time, SW_RAD</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 
<tt>BC == W10, <<met_ts>> ! Wind velocity at 10m (m s-1)</tt> 
:<tt>BC Header == Time, W10_X, W10_Y</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 
<tt>BC == AIR_TEMP, <<met_ts>> ! Temperature input (deg C)</tt> 
:<tt>BC Header == Time, AIR_TEMP</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 
<tt>BC == REL_HUM, <<met_ts>> ! Relative humidity (%)</tt> 
:<tt>BC Header == Time, REL_HUM</tt> 
:<tt>BC Update dt == 300</tt> 
:<tt>BC Time Units == Hours</tt> 
:<tt>BC Reference Time == 01/01/2021 10:00</tt> 
<tt>End BC</tt> 

<li> In the 'Outputs' section, update the existing NetCDF output block to include sediment: 
<tt>Output == NetCDF </tt> 
:<tt>Output Parameters == h, v, d, sed_1 ! Outputs water level, velocity, depth and sediment</tt> 
:<tt>Output Interval == 30 ! Interval to output the data (seconds) </tt> 
:<tt>Suffix == HD ! Specify suffix for the output NetCDF file </tt>
<tt>End Output</tt> 

<li> At the end of the 'Outputs' section, add the following output block to output water quality results. 
<tt>Output == NetCDF </tt> 
:<tt>Output Parameters == wq_all ! Outputs water quality results </tt> 
:<tt>Output Interval == 30 ! Interval to output the data (seconds) </tt> 
:<tt>Suffix == WQ ! Specify suffix for the output NetCDF file </tt>
<tt>End Output</tt> 

<li>Save the TCC.
</ol>

= Running the Simulation =
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOWCATCH\runs''' folder. Save a copy of '''_run_TC03_CATCH.bat''' as '''_run_TC04_CATCH.bat''' and open the file in a text editor.
<li>Update the batch file to reference the '''TC04_001.tcc''': 
<tt>set exe="..\..\..\..\exe\TUFLOWCATCH\2025.1.0\TUFLOWCATCH.exe"</tt> 
<tt>%exe% TC04_001.tcc</tt>
<li>Double click the batch file in file explorer to run the simulation. 
</ol>

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

= Results Output =
Complete the steps outlined in the following links to review simulation results from the TUFLOW CATCH integrated model simulation:
:*[[TUFLOW_CATCH_Tutorial_M04_Results_QGIS | TC04 - Results]] 

= Conclusion =
* A TUFLOW CATCH Integrated model was created.
* Meteorological data, water quality and sediment transport were added to the model.
* A TUFLOW CATCH JSON file was created to review the transfer of results (particularly pollutants) between the TUFLOW HPC and the TUFLOW FV domains.
* For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

TUFLOW CATCH Tutorial M03

2026-03-30T02:08:50Z

Emilie Nielsen: /* Running the Simulation */

= Introduction =
In this module, a TUFLOW CATCH hydrology model is developed. 

TUFLOW CATCH Tutorial 03 is built from the model created in [[TUFLOW_CATCH_Tutorial_M02 | TUFLOW CATCH Tutorial 02]]. The completed TUFLOW CATCH Tutorial 02 is provided in the '''TUFLOW_CATCH_Module_03\Modelling''' folder of the download dataset as the starting point for this tutorial.
If unfamiliar with TUFLOW CATCH, it is recommended to complete [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]] and [[TUFLOW_CATCH_Tutorial_M02 | TUFLOW CATCH Tutorial 02]] prior to starting this tutorial.

'''Note:''' An NVIDIA GPU card is required to run this tutorial model. If this is not available, a shortened simulation can be run on CPU by updating the following commands in the Global Settings section of the TUFLOW CATCH Control file (.tcc):

:<tt>Hardware == CPU</tt>
:<tt>End Time == 01/01/2021 12:00:00</tt>

= GIS Inputs =
Create, import and view input data:
:*[[TUFLOW_CATCH_Tutorial_M03_TUFLOW_HPC_GIS_Inputs_QGIS | TC03 - TUFLOW HPC GIS Inputs]]
:*[[TUFLOW_CATCH_Tutorial_M03_TUFLOW_FV_GIS_Inputs_QGIS | TC03 - TUFLOW FV GIS Inputs]]

= Simulation Control Files =
The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its configuration information refer to [[NotepadPlusPlus_Tips | Notepad++ Tips]]. 

=== TUFLOW Boundary Control File (TBC) ===
<ol>
<li>Save a copy of '''TC01_001.tbc''' as '''TC03_001.tbc''' in the '''TUFLOW_CATCH_Module_03\Modelling\TUFLOW\model''' folder.
<li> Open the '''TC03_001.tbc''' in a text editor and update the reference to the 1D/2D culvert connections: 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>gis\2d_bc_TC03_001_P.shp</tt> <tt> ! Links the two upstream 1D culverts to the 2D domain</tt> 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>gis\2d_bc_TC03_001_L.shp</tt> <tt> ! Links the two upstream 1D culverts to the 2D domain</tt> 
<li>Save the TBC.
</ol>

=== TUFLOW ESTRY Control File (ECF) ===
<ol>
<li> Save a copy of '''TC01_001.ecf''' as '''TC03_001.ecf''' in the '''TUFLOW_CATCH_Module_03\Modelling\TUFLOW\model''' folder.
<li> Open the '''TC03_001.ecf''' in a text editor and update the following line to reference the new 1d_nwk layer (containing the two upstream culverts): 
<tt>Read GIS Network </tt> <tt>== </tt> <tt>gis\1d_nwk_TC03_001_L.shp</tt> <tt> ! Defines the two upstream culverts</tt>
<li>Save the ECF.
</ol>

== TUFLOW CATCH Control File (TCC) ==
=== Global Settings ===
For this tutorial, leave all commands as is. This section of the .tcc was populated in [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]].

=== Catchment Hydraulic Model ===
This block contains commands that construct the TUFLOW HPC simulation.
<ol>
<li> Save a copy of '''TC02_001.tcc''' as '''TC03_001.tcc''' in the '''TUFLOW_CATCH_Module_03\Modelling\TUFLOWCATCH\runs''' folder.
<li> Open '''TC03_001.tcc''' in a text editor, and update the following commands to reference the new TBC and ECF: 
<tt>BC Control File == ..\..\TUFLOW\model\TC03_001.tbc ! Reference the TUFLOW Boundary Conditions Control File</tt> 
<tt>ESTRY Control File == ..\..\TUFLOW\model\TC03_001.ecf ! Reference the ESTRY (1D) Control File</tt> 

<li> Remove or comment out the following command using a '<tt>!</tt>' symbol. The receiving polygon can only be used in the pollutant export configuration of TUFLOW CATCH. 
<tt>! Receiving Polygon == ..\..\TUFLOW\model\gis\2d_rp_TC01_001_R.shp ! GIS layer defining the receiving polygon</tt> 
</ol>

=== Pollutant Export Model ===
This block contains commands that control the pollutant export (and other constituent) simulation. As this tutorial model is a hydrology simulation, we must set the pollutant export model to 'None', and comment out all commands. The pollutant export model block should look similar to the below: 
:<tt>Catchment Pollutant Export Model == None</tt> 
::<tt>! Constant Salinity == 0.0</tt> 
::<tt>! Constant WQ_DISS_OXYGEN_MG_L == 8.0</tt> 
::<tt>! Time-Series Temperature == temp</tt> 
::<tt>! Material == ALL ! Default parameters for all materials</tt> 
:::<tt> ! SED_CLAY, Method == Shear1, Rate == 0.0, Limit == 100.0, Depth Threshold == 0.02, Deposition Stress == 0.1, Erosion Stress == 0.5, Deposition Velocity == 0.1, Erosion Rate == 0.05</tt> 
:::<tt> ! WQ_PATH_ECOLI_ALIVE_CFU_100ML, Method == Washoff1, Rate == 0.0, Limit == 0.0, Time Constant == 3600.00, Rain Threshold == 1.0, Depth Threshold == 0.20, Deposition Velocity == 0.0</tt> 
:::<tt> ! WQ_PATH_ECOLI_DEAD_CFU_100ML, Method == Washoff1, Rate == 0.0, Limit == 0.0, Time Constant == 3600.00, Rain Threshold == 1.0, Depth Threshold == 0.20, Deposition Velocity == 0.0</tt> 
::<tt>! End Material </tt> 
::<tt>! Other material specifications ...</tt> 
::<tt>! Read GIS Intervention == ..\..\TUFLOW\model\gis\2d_im_TC02_001_L.shp ! GIS layer defining interventions</tt> 
::<tt>! Device == ALL ! Default parameters for all devices</tt> 
:::<tt> ! SED_CLAY, Method == Eqn, Eqn == Constant, Coefficients == 1.0</tt> 
:::<tt> ! WQ_PATH_ECOLI_ALIVE_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 1.0</tt> 
:::<tt> ! WQ_PATH_ECOLI_DEAD_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 1.0</tt> 
::<tt>! End Device</tt> 
::<tt>! Other mass removal specifications ...</tt> 
:<tt>End Catchment Pollutant Export Model </tt> 

=== Receiving Model ===
This block contains commands that construct the TUFLOW FV simulation. These commands are almost entirely those that would be used in setting up a standalone TUFLOW FV control file (.fvc), with a small number of additional commands that relate to TUFLOW CATCH.
<ol>
<li> Set the receiving model: 
<tt>Receiving Model == TUFLOWFV </tt>

<li>Above the 'Hardware' section, add the following command. This command allows the simulation to proceed if minor timestepping mismatches occur in the boundary condition timeseries files (written by TUFLOW CATCH). 
<tt>Global Temporal Extrapolation Check == WARNING </tt> 

<li>In the 'Timestep Commands' section, update the following commands: 
<tt>CFL == 0.95 ! Specify the Courant–Friedrichs–Lewy (CFL) number</tt> 
<tt>Timestep Limits == 0.10,1.0 ! Specify the minimum and maximum timesteps (seconds)</tt> 
<tt>Display dt == 30 ! Interval of displaying timestep information to the log (seconds)</tt> 

<li>In the 'Model Parameters' section, update the following commands. All other commands in this section relate to 3D modelling, so they can be removed or ignored. 
<tt>Stability Limits == 100.0, 10.0 ! Specify maximum water level (meters) and velocity (m/s) which indicate an unstable model</tt> 
<tt>Momentum Mixing Model == Smagorinsky ! Specify the momentum mixing model</tt> 
<tt>Global Horizontal Eddy Viscosity == 0.2 ! Specify the Smagorinsky coefficient</tt> 
<tt>Global Horizontal Eddy Viscosity Limits == 0.05, 99999. ! Specify the minimum and maximum eddy viscosity (m2/s)</tt> 
<tt>Scalar Mixing Model == Smagorinsky ! Specify the scalar mixing model</tt> 
<tt>Global Horizontal Scalar Diffusivity == 0.2 ! Specify the Smagorinsky coefficient</tt> 
<tt>Global Horizontal Scalar Diffusivity Limits == 0.05, 99999. ! Globally sets the minimum and maximum horizontal scalar diffusivity limits</tt> 

<li>At the end of the 'Model Parameters' section, add the following command to set the cell wetting and drying depths: 
<tt>Cell Wet/Dry Depths == 5.0e-03, 5.0e-02 ! Specify the cell wetting and drying depths (meters)</tt> 

<li>In the '2D Geometry' section, update the following commands to reference the TUFLOW FV mesh and the model domain: 
<tt>Geometry 2D == ..\..\TUFLOWFV\model\geo\Stream_Mesh.2dm ! 2D geometry input file (mesh file)</tt> 
<tt>Read Grid Zpts == ..\..\TUFLOWFV\model\geo\DEM.asc ! Assigns the elevation of Zpts from the grid</tt> 

<li>In the 'Materials' section, update/add the following commands. They reference the TUFLOW FV materials GIS layer and specify the surface roughness or bed resistance values (e.g. Manning’s n) assigned to each material ID within the TUFLOW FV model domain. These are distinct materials from those specified in the catchment hydraulic model. 
<tt>Set Mat == 1 ! Sets the default material ID for all cells in the TUFLOW FV model domain</tt> 
<tt>Read GIS Mat == ..\..\TUFLOWFV\model\gis\2d_mat_TC03_FV_001_R.shp ! Sets the TUFLOW FV material values according to attributes in the GIS layer</tt> 
<tt>Material == 1 ! Defines properties for material ID 1</tt>
:<tt>Bottom Roughness == 0.011 ! Specify the Manning's roughness</tt> 
<tt>End Material</tt> 
<tt>Material == 2 ! Defines properties for material ID 2</tt> 
:<tt>Bottom Roughness == 0.015 ! Specify the Manning's roughness</tt> 
<tt>End Material</tt> 
<tt>Material == 3 ! Defines properties for material ID 3</tt> 
:<tt>Bottom Roughness == 0.017 ! Specify the Manning's roughness</tt> 
<tt>End Material</tt> 

<li>In the 'Initial Conditions' section, update the following command to set the initial water level: 
<tt>Initial Water Level == 35.0 ! Specify initial water level (meters)</tt> 

<li>In the 'Non-Catchment Boundaries' section, update the following commands to reference the downstream TUFLOW FV normal (friction slope) boundary and to define its boundary conditions. 
<tt>Read GIS Nodestring == ..\..\TUFLOWFV\model\gis\2d_ns_TC03_DS_boundary_001_L.shp ! GIS nodestring layer defining non-catchment boundary(ies)</tt> 
<tt>BC == QN, DS, 0.001 ! Defines BC type, BC name and friction slope</tt> 
<tt>End BC</tt> 

<li>In the 'Catchment Boundaries' section, update the following command to reference the upstream (inflow) TUFLOW FV boundary. TUFLOW CATCH uses this nodestring to automatically write boundaries that include momentum from catchment hydraulic model predictions. For more information, refer to [https://docs.tuflow.com/catch/manual/2025.1/SimulationConstruction-1.html#SCTCCFV-3 Section 4.5.4 of the TUFLOW CATCH Manual]. 
<tt>Catchment BC Nodestring == ..\..\TUFLOWFV\model\gis\2d_ns_TC03_US_boundary_001_L.shp ! GIS nodestring layer defining catchment boundary(ies) that include momentum</tt> 

<li>Above the 'Outputs' section, add the following commands to reference the downstream TUFLOW FV culvert and its parameters. 
<tt>Read GIS Nodestring == ..\..\TUFLOWFV\model\gis\2d_ns_TC03_culverts_001_L.shp ! GIS nodestring layer defining the downstream culvert</tt> 
<tt>Read GIS Nodestring == ..\..\TUFLOWFV\model\gis\2d_ns_TC03_weir_001_L.shp ! GIS nodestring layer enforcing the road crest at the downstream culvert</tt> 
<tt>Structure == Linked Nodestrings, FC01.2_R_US, FC01.2_R_DS ! Defines the structure type, culvert US nodestring ID, culvert DS nodestring ID</tt> 
:<tt>Flux Function == Culvert ! Culvert flux function </tt> 
:<tt>Culvert File == ..\..\TUFLOWFV\model\csv\TC03_culvert_dbase_001.csv, 1 ! Reference the culvert database and the number of culverts </tt>
<tt>End Structure</tt> 
<tt>Structure == Nodestring, FC01.2_W ! Defines the structure type and the nodestring ID</tt> 
:<tt>Flux Function == Weir_dz ! Weir_dz flux function </tt> 
:<tt>Properties == 0.1, 1.705 ! Defines the weir height above face elevation (meters) and the weir coefficient</tt>
<tt>End Structure</tt> 

<li>In the 'Outputs' section, update/add the following commands. Ensure that the 'Flux' block is removed or commented out. 
<tt>Output == NetCDF </tt> 
:<tt>Output Parameters == h, v, d ! Outputs water level, velocity and depth </tt> 
:<tt>Output Interval == 30 ! Interval to output the data (seconds) </tt> 
:<tt>Suffix == HD ! Specify suffix for the output NetCDF file </tt>
<tt>End Output</tt> 
<tt>Output == Mass </tt> 
:<tt>Output Interval == 30 ! Interval to output the data (seconds) </tt>
<tt>End Output</tt> 

<li>Remove or comment out the following commands: 
<tt>! Write Restart dt == 24</tt> 
<tt>! Restart Overwrite == 1 </tt> 

<li> Save the .tcc.
</ol>

= Running the Simulation =
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOWCATCH\runs''' folder. Save a copy of '''_run_TC02_CATCH.bat''' as '''_run_TC03_CATCH.bat''' and open the file in a text editor.
<li>Update the batch file to reference the '''TC03_001.tcc''': 
<tt>set exe="..\..\..\..\exe\TUFLOWCATCH\2026.0.0\TUFLOWCATCH.exe"</tt> 
<tt>%exe% TC03_001.tcc</tt>
<li>Double click the batch file in file explorer to run the simulation. 
</ol>

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

= Check Files and Results Output =
Complete the steps outlined in the following links to review check files and simulation results from the TUFLOW CATCH hydrology model simulation:
:*[[TUFLOW_CATCH_Tutorial_M03_Check_Files_QGIS | TC03 - Check Files]] 
:*[[TUFLOW_CATCH_Tutorial_M03_Results_QGIS | TC03 - Results]] 

=Reviewing Model Performance=
As discussed in [[TUFLOW_CATCH_Tutorial_M01#Reviewing_Model_Performance | TUFLOW CATCH Tutorial 01]], there are a number of useful outputs from TUFLOW CATCH for reviewing the model performance. 
In this tutorial, the receiving model was specified. As such, the TUFLOW FV Log File (.log) should be reviewed. The <tt>Log Folder == log</tt> command in the .tcc defines where the .log is written. 
Navigate to the '''Modelling\TUFLOWCATCH\runs\log''' folder and open the '''TC03_001_receiving.log''' file in a text editor.
* Scroll down to the bottom to 'Simulation Summary'. This includes information about the computation time and messages. If an error occurred (stopping the simulation), the error message will be output just above the 'Simulation Summary'.
* Review any check, warning or error messages.

'''Note:''' It is recommended to check all simulation log files at the end of each run. For this tutorial, the catchment hydraulic and receiving models were specified, so '''TC03_001.catchlog''', '''TC03_001_catchment_hydraulic.tlf''' and '''TC03_001_receiving.log''' should all be reviewed.

= Conclusion =
* A TUFLOW CATCH Hydrology model was created.
* A TUFLOW FV mesh was added to the stream and the downstream culvert was redefined in TUFLOW FV format.
* A TUFLOW CATCH JSON file was created to review the transfer of results between the TUFLOW HPC and the TUFLOW FV domains.
* For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

TUFLOW CATCH Tutorial M03 TUFLOW HPC GIS Inputs QGIS

2026-03-30T02:08:27Z

Emilie Nielsen: /* TUFLOW CATCH Project Re-Configuration */

==Introduction==
The updated culvert layers are supplied and inspected.

== TUFLOW CATCH Project Re-Configuration ==
Re-configure the TUFLOW CATCH project to use and save empty files to the correct folders:
<ol>
<li>Go to Processing > Toolbox from the top drop down menu options to open the Processing Toolbox.
<li>Go to TUFLOW Catch in the processing tool list and select 'Create TUFLOW Catch Project'. This opens the dialog shown below.
* Project Name: '''TC03'''
* Project Folder: Click '...', and navigate to the '''TUFLOW_CATCH_Module_03\Modelling''' folder.
* Project CRS: Click the drop down menu and select 'Project CRS: EPSG:32760 - WGS 84 / UTM zone 60S’.
* TUFLOW HPC Executable: Click '...', and navigate to the '''exe\TUFLOW\2026.0.0''' folder. Select '''TUFLOW_iSP_w64.exe'''.
* TUFLOW FV Executable: Click '...', and navigate to the '''exe\TUFLOWFV\2026.0.0''' folder. Select '''TUFLOWFV.exe'''.
* Default GIS Format: Click the drop down menu and select 'SHP'.
* Tick on 'Create Empty Files'.
<li> Click 'Run' and a console window will open. This creates the empty GIS files.
<li> Once the tool has finished, click 'Close'. 
 
[[File: TC3_Create_CATCH_Project_01a.png]] 
 
<li> Set up the QGIS workspace by setting the projection to EPSG:32760, loading and styling the DEM and saving the workspace. See [[TUFLOW_CATCH_Tutorial_M01_Project_Initialisation_QGIS | TUFLOW CATCH Module 01 - Project Initialisation]] for details.
</ol>

==Review Supplied TUFLOW Input Files==
Navigate to the '''TUFLOW_CATCH_Module_03\Tutorial_Data''' folder. Copy the below layers into the '''Modelling\TUFLOW\model\gis''' folder:
:* '''1d_nwk_TC03_001_L'''
:* '''2d_bc_TC03_001_L'''
:* '''2d_bc_TC03_001_P'''

For this tutorial, a TUFLOW FV mesh will be included in the channel (outlined in the next section: [[TUFLOW_CATCH_Tutorial_M03_TUFLOW_FV_GIS_Inputs_QGIS | TUFLOW FV GIS Inputs]]). Currently, there is a TUFLOW HPC culvert defined in the channel. This culvert needs to be removed from the TUFLOW HPC, and redefined in TUFLOW FV format.
<ol>
<li>Load the supplied files into QGIS and use the 'Apply TUFLOW Styles to Open Layers'.
<li>Notice that the downstream culvert has been removed. All other culverts are the same. 
 
{{Video|name=animation_TC3_HPC_GIS_inputs_01a.mp4|width=1236}} 
</ol>

 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_M03#GIS_Inputs| Back to TUFLOW CATCH Tutorial 03]]
}}

TUFLOW CATCH Tutorial M02

2026-03-30T02:08:09Z

Emilie Nielsen: /* Running the Simulation */

= Introduction =
In this module, a TUFLOW CATCH pollutant export model with interventions is developed. Interventions are representative of water quality pollutant treatment infrastructure. 

TUFLOW CATCH Tutorial 02 is built from the pollutant export model created in [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]]. The completed TUFLOW CATCH Tutorial 01 is provided in the '''TUFLOW_CATCH_Module_02\Modelling''' folder of the download dataset as the starting point for this tutorial.
If unfamiliar with TUFLOW CATCH, it is recommended to complete [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]] prior to starting this tutorial.

= GIS Inputs =
Create, import and view input data:
:*[[TUFLOW_CATCH_Tutorial_M02_GIS_Inputs_QGIS | TC02 - GIS Inputs]]

= Treatment Tables =
Treatment tables can be used in TUFLOW CATCH models with interventions. Treatment tables are one of the mass removal methods offered by TUFLOW CATCH. A treatment table is a two dimensional array that defines the proportion of pollutant mass removed from the incoming water based on:
* Incoming pollutant concentration: The concentration of a given pollutant entering the treatment device.
:''Note:'' The concentration units depend on the pollutant. Refer to [https://docs.tuflow.com/catch/manual/2025.1/SimulationConstruction-1.html#SCTCCPollExpUnits-5 Section 4.5.3.3.3 of the TUFLOW CATCH Manual] for details on unit conventions.
* Flow rate: The volume of water passing through the treatment device (m³/s).
Treatment tables allow users to vary pollutant removal efficiency. This recognises that some intervention devices perform better when pollutants enter at higher concentrations and lower flow rates, rather than at lower concentrations with higher flow rates. For more information about treatment tables and their properties, please refer to [https://docs.tuflow.com/catch/manual/2025.1/ProcessDescriptions-1.html#ProcessDescriptionsIntervMatrix-4 Section 3.3.1.2 of the TUFLOW CATCH Manual].

For this tutorial, treatment tables for E. coli and clay have been provided:
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOW_CATCH_Module_02\Tutorial_Data''' folder. Copy the '''TC02_ecoli_treatment_001.csv''' and '''TC02_clay_treatment_001.csv''' and paste them in the '''TUFLOW_CATCH_Module_02\Modelling\TUFLOW\bc_dbase''' folder.
<li>Open the '''TC02_ecoli_treatment_001.csv'''. The first row (below the title) defines the incoming concentration (cfu/100mL) and the first column defines the incoming flow rate (m³/s). The other values are the mass removal factors, which define the proportion of pollutant removed for a given concentration and flow rate. For example, for an incoming concentration of 200000 cfu/100mL and an incoming flow rate of 1 m³/s, the removal factor is 0.2. The concentration and flow ranges were determined from the outputs of the previous tutorial model ([[TUFLOW_CATCH_Tutorial_M01 |TUFLOW CATCH Tutorial 01]]). 
 
[[File: TC2_treatment_table_ecoli_01b.png]] 
 
<li>Open the '''TC02_clay_treatment_001.csv'''. This file follows the same structure as the E. coli treatment table, however the incoming concentrations are in mg/L instead of cfu/100mL. 
 
[[File: TC2_treatment_table_clay_01b.png]] 
 
</ol>

= Simulation Control Files =
The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its configuration information refer to [[NotepadPlusPlus_Tips | Notepad++ Tips]]. 

== TUFLOW CATCH Control File (TCC) ==
=== Global Settings ===
For this tutorial, leave all commands as is. This section of the .tcc was populated in [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]].

=== Catchment Hydraulic Model ===
For this tutorial, leave all commands as is. This section of the .tcc was populated in [[TUFLOW_CATCH_Tutorial_M01 | TUFLOW CATCH Tutorial 01]].

=== Pollutant Export Model ===
This block contains commands that control the pollutant export (and other constituent) simulation. For this tutorial, the pollutant export model block must be updated to include interventions.
<ol>
<li> Save a copy of '''TC01_001.tcc''' as '''TC02_001.tcc''' in the '''TUFLOW_CATCH_Module_02\Modelling\TUFLOWCATCH\runs''' folder. Open '''TC02_001.tcc''' in a text editor.
<li> In the 'Interventions' section, update the following command to reference the interventions (2d_im) layer created earlier in this tutorial. 
<tt>Read GIS Intervention == ..\..\TUFLOW\model\gis\2d_im_TC02_001_L.shp ! GIS layer defining interventions</tt> 

<li>In the 'Mass Removal Properties' section, add the following device block. This block defines the default mass removal properties for all pollutants across all devices. Including it is considered best practice, as it ensures that all devices have their mass export properties specified. For more information on the mass removal parameters, please refer to [https://docs.tuflow.com/catch/manual/2025.1/SimulationConstruction-1.html#SCTCCPollExpInter-4 Section 4.5.3.5 of the TUFLOW CATCH Manual]. 
<tt>Device == ALL ! Default parameters for all devices</tt> 
:<tt>SED_CLAY, Method == Eqn, Eqn == Constant, Coefficients == 1.0</tt> 
:<tt>WQ_PATH_ECOLI_ALIVE_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 1.0</tt> 
:<tt>WQ_PATH_ECOLI_DEAD_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 1.0</tt> 
<tt>End Device</tt> 

<li>Set the mass removal properties for intervention devices 'trench1' and 'trench2'. These devices are placed around the edges of paddocks C and D to manage the E. coli runoff. 
<tt>Device == trench1, trench2 ! Defines mass removal properties for trench1 and trench2</tt> 
:<tt>SED_CLAY, Method == Eqn, Eqn == Constant, Coefficients == 0.4</tt> 
:<tt>WQ_PATH_ECOLI_ALIVE_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 0.9</tt> 
:<tt>WQ_PATH_ECOLI_DEAD_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 0.9</tt> 
<tt>End Device</tt> 

<li>Set the mass removal properties for intervention device 'retentionBasin'. This device is place parallel to the road on the eastern side of the model. It has been placed between paddockB and the culvert under the road to minimise clay and E. coli runoff. 
<tt>Device == retentionBasin ! Defines mass removal properties for retentionBasin</tt> 
:<tt>SED_CLAY, Method == Eqn, Eqn == Constant, Coefficients == 0.8</tt> 
:<tt>WQ_PATH_ECOLI_ALIVE_CFU_100ML, Method == Table, Path == ..\..\TUFLOW\bc_dbase\TC02_ecoli_treatment_001.csv</tt> 
:<tt>WQ_PATH_ECOLI_DEAD_CFU_100ML, Method == Table, Path == ..\..\TUFLOW\bc_dbase\TC02_ecoli_treatment_001.csv</tt> 
<tt>End Device</tt> 

<li> Set the mass removal properties for intervention devices 'bufferStrip1' and 'bufferStrip2'. These devices are placed strategically to manage clay sediment runoff. 
<tt>Device == bufferStrip1, bufferStrip2 ! Defines mass removal properties for bufferStrip1 and bufferStrip2</tt> 
:<tt>SED_CLAY, Method == Table, Path == ..\..\TUFLOW\bc_dbase\TC02_clay_treatment_001.csv</tt> 
:<tt>WQ_PATH_ECOLI_ALIVE_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 0.4</tt> 
:<tt>WQ_PATH_ECOLI_DEAD_CFU_100ML, Method == Eqn, Eqn == Constant, Coefficients == 0.7</tt> 
<tt>End Device</tt> 

<li> Save the .tcc.
</ol>

=== Receiving Model ===
For this tutorial, leave all commands as is. This section of the .tcc will be populated in [[TUFLOW_CATCH_Tutorial_M03 | TUFLOW CATCH Tutorial 03]].

= Running the Simulation =
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOWCATCH\runs''' folder. Save a copy of '''_run_TC01_CATCH.bat''' as '''_run_TC02_CATCH.bat''' and open the file in a text editor.
<li>Update the batch file to reference the '''TC02_001.tcc''': 
<tt>set exe="..\..\..\..\exe\TUFLOWCATCH\2026.0.0\TUFLOWCATCH.exe"</tt> 
<tt>%exe% TC02_001.tcc</tt>
<li>Double click the batch file in file explorer to run the simulation. 
</ol>

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

= Check Files and Results Output =
Complete the steps outlined in the following links to review check files and simulation results from the TUFLOW CATCH pollutant export model simulation:

:*[[TUFLOW_CATCH_Tutorial_M02_Check_Files_QGIS | TC02 - Check Files]] 
:*[[TUFLOW_CATCH_Tutorial_M02_Results_QGIS | TC02 - Results]] 

= Conclusion =
* Intervention devices were added to a TUFLOW CATCH Pollutant Export model.
* Check files were used to review the placement of intervention devices.
* TUFLOW CATCH interventions summary and TUFLOW map outputs were assessed to observe the mass removal for each intervention device.
* For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

TUFLOW CATCH Tutorial M02 GIS Inputs QGIS

2026-03-30T02:07:54Z

Emilie Nielsen: /* TUFLOW CATCH Project Re-Configuration */

== Introduction ==
An interventions (2d_im) layer is created to remove pollutants from the run off around the paddocks and within the waterway. 

== TUFLOW CATCH Project Re-Configuration ==
Re-configure the TUFLOW CATCH project to use and save empty files to the correct folders:
<ol>
<li>Go to Processing > Toolbox from the top drop down menu options to open the Processing Toolbox.
<li>Go to TUFLOW Catch in the processing tool list and select 'Create TUFLOW Catch Project'. This opens the dialog shown below.
* Project Name: '''TC02'''
* Project Folder: Click '...', and navigate to the '''TUFLOW_CATCH_Module_02\Modelling''' folder.
* Project CRS: Click the drop down menu and select 'Project CRS: EPSG:32760 - WGS 84 / UTM zone 60S’.
* TUFLOW HPC Executable: Click '...', and navigate to the '''exe\TUFLOW\2026.0.0''' folder. Select '''TUFLOW_iSP_w64.exe'''.
* TUFLOW FV Executable: Click '...', and navigate to the '''exe\TUFLOWFV\2026.0.0''' folder. Select '''TUFLOWFV.exe'''.
* Default GIS Format: Click the drop down menu and select 'SHP'.
* Tick on 'Create Empty Files'.
<li> Click 'Run' and a console window will open. This creates the empty GIS files.
<li> Once the tool has finished, click 'Close'. 
 
[[File: TC2_Create_CATCH_Project_01a.png]] 
 
<li> Set up the QGIS workspace by setting the projection to EPSG:32760, loading and styling the DEM and saving the workspace. See [[TUFLOW_CATCH_Tutorial_M01_Project_Initialisation_QGIS | TUFLOW CATCH Module 01 - Project Initialisation]] for details.
</ol>

== Create Interventions ==
An interventions (2d_im) layer contains one or more lines, called intervention devices. These intervention devices may represent constructed wetlands, bioretention systems, grassed swales, riparian revegetation strips or similar features. In the TUFLOW CATCH Control file, each device is assigned mass removal properties, which can be defined and adjusted on a pollutant by pollutant basis. The location and orientation of each device is specified via lines in the 2d_im layer. 

Create the 2d_im layer using the TUFLOW CATCH plugin:
<ol>
<li> In the Processing Toolbox, go to TUFLOW Catch in the processing tool list and select 'Import Empty'. This opens the dialog shown below.
:* Project Directory: This should automatically be set to the '''TUFLOW_CATCH_Module_02\Modelling''' folder.
:* Empty Type: Click ..., and tick on '2d_im' from the empty type list.
:* Geometry Type: Click ..., and tick on 'Line'.
:* Run ID: '''TC02_001'''
<li> Click 'Run'. Once the tool has finished, click 'Close'. The '''2d_im_TC02_001_L''' will appear in the QGIS Layers panel. 
 
[[File: TC2_import_empty_2d_im_01a.png]] 
 
</ol>

To help determine where the intervention devices should be placed, load in the following files:
*'''2d_mat_TC01_001_R.shp''' from the '''TUFLOW\model\gis''' folder
*'''TC01_001_catchment_hydraulic_d_Max.tif''' from the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOWCATCH\results\grids''' folder

Create interventions: 
<ol>
<li>In the QGIS Layers panel, select (left click) '''2d_im_TC02_001_L''' and toggle on editing.
<li>Select 'Add Line Feature'.
<li>Digitise a line around the corner of the paddock with material ID 9 (paddockD). Use the right mouse button to terminate the line and an attributes dialog will appear. Set the ID to 'trench1' and click 'OK'.
<li>Repeat the same process as above to digitise a line between the road and the paddock with material ID 7 (paddockB). Set the ID to 'retentionBasin'. 
 
{{Video|name=animation_TC2_GIS_inputs_01a.mp4|width=1236}} 
<li>Zoom in to the downstream end of the model. Use the '''TC01_001_catchment_hydraulic_d_Max.tif''' to determine where the water will be flowing. Using the same process as above, digitise a line perpendicular to the water on the western side of the stream. Set the ID to 'bufferStrip1'. 
 
{{Video|name=animation_TC2_GIS_inputs_02a.mp4|width=1236}} 
<li>Create two more intervention devices with ID's 'trench2' and 'bufferStrip2'. Use the image below as a guide. 
'''Note:''' To style the interventions, use the "Apply TUFLOW Styles to Open Layers" [[File: TUFLOW_apply_styles_open_layers_icon.png | 30px]] and the "Apply Label to Current Layer" [[File: TUFLOW_apply_label_icon.png | 40px]] tools from the TUFLOW Plugin toolbar. 
 
[[File: TC2_all_devices_01a.png]] 
 
<li>Once all the intervention devices have been created, turn off editing to save the edits.
</ol>

 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_M02#GIS_Inputs| Back to TUFLOW CATCH Tutorial 02]]
}}

TUFLOW CATCH Tutorial M01

2026-03-30T02:07:38Z

Emilie Nielsen: /* Running the Simulation */

= Introduction =
In this module, a TUFLOW CATCH pollutant export model is developed. 

TUFLOW CATCH Tutorial 01 is built from the model created in [[Tutorial_M06#Part_3_-_Rainfall_Control_File | TUFLOW Tutorial Module 6 - Part 3]]. The completed TUFLOW Module 6 (part 3) is provided in the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOW''' folder of the download dataset as the starting point for this tutorial. If unfamiliar with TUFLOW, it is recommended to complete Modules 1, 2, 3 and 6 of the [[Tutorial_Introduction | TUFLOW Tutorials]] to establish an understanding of 1D and 2D TUFLOW modelling, including direct rainfall models.

= Project Initialisation =
TUFLOW CATCH models are separated into a series of folders which contain the input and output files. The recommended directory structure for TUFLOW CATCH models consists of a top-level folder, '''Modelling''', which contains three subfolders:
* '''TUFLOW''': Contains TUFLOW HPC input files.
* '''TUFLOWCATCH''': Contains the TUFLOW CATCH Control file, as well as all check, results and log files.
* '''TUFLOWFV''': Contains TUFLOW FV input files.
The third level subfolders are outlined below. For a more detailed description, refer to the [https://docs.tuflow.com/catch/latest/ TUFLOW CATCH Manual]. For more information on TUFLOW HPC or TUFLOW FV folder structures, refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] or the [https://downloads.tuflow.com/TUFLOWFV/Releases/Latest/TUFLOW_FV_User_Manual.pdf TUFLOW FV Manual]. 
<ol>
[[File:TC1_folder_structure_01a.png|left]]
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;" | Folder
! style="background-color:#005581; font-weight:bold; color:white;" width=10%| Sub-Folder (s)
! style="background-color:#005581; font-weight:bold; color:white;" width=75%| Description
|-
|rowspan="3" style="text-align: center;"|TUFLOW
| bc_dbase model|| Follows standard TUFLOW structure.
|-
| catch || Not used, but generated for internal use. It holds files that are produced during computation, but deleted when the simulation finishes successfully.
|-
| check results runs || Not used, but generated for internal use. All TUFLOW check and results files are written to the '''TUFLOWCATCH\check''' folder and the '''TUFLOWCATCH\results''' folder respectively. TUFLOW CATCH simulations are run from the .tcc file in the '''TUFLOWCATCH\runs''' folder.
|-
|rowspan="6" style="text-align: center;"|TUFLOWCATCH
| bc_dbase|| Contains the output boundary condition and time-series data.
|-
| check || Contains the GIS and other check files produced by TUFLOW CATCH, TUFLOW and TUFLOW FV to carry out quality control checks
|-
| model || Not used - generated for internal use.
|-
| results|| Contains the result files produced by TUFLOW CATCH, TUFLOW and TUFLOW FV.
|-
| runs|| Contains the .tcc simulation control file.
|-
| runs\log || Contains the log files (e.g. .catchlog, .tlf, .log, etc) and _messages.shp files produced by TUFLOW CATCH, TUFLOW and TUFLOW FV.
|-
|rowspan="2" style="text-align: center;"|TUFLOWFV
| bc_dbase model stm wqm|| Follows standard TUFLOW FV structure.
|-
| check results runs || Not used, but generated for internal use. All TUFLOW FV check and results files are written to the '''TUFLOWCATCH\check''' folder and the '''TUFLOWCATCH\results''' folder respectively. TUFLOW CATCH simulations are run from the .tcc file in the '''TUFLOWCATCH\runs''' folder.
|}
</ol>

The TUFLOW CATCH folders can be set up manually, or automatically through the TUFLOW CATCH QGIS Plugin (recommended).
:*[[TUFLOW_CATCH_Tutorial_M01_Project_Initialisation_QGIS | TUFLOW CATCH Project Initialisation]]

= GIS Inputs =
Create, import and view input data:
:*[[TUFLOW_CATCH_Tutorial_M01_GIS_Inputs_QGIS | TC01 - GIS Inputs]]

= TUFLOW Boundary Condition Database (bc_dbase) =
Update the bc_dbase to remove the 2D boundaries and add a reference to the timeseries temperature data. Note that TUFLOW CATCH does not support 2D boundaries, however, 2d_sa GIS layers can be used to simulate non-hydrologic surface loads. For more information on 2d_sa inputs, refer to [https://docs.tuflow.com/catch/manual/2025.2/ProcessDescriptionsSAs-2.html#ProcessDescriptionsSAs-2 Section 3.4 of the TUFLOW CATCH Manual].
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOW_CATCH_Module_01\Tutorial_Data''' folder. Copy the '''temperature.csv''' and paste it in the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOW\bc_dbase''' folder. This file contains the timeseries temperature data.
<li> Open the file. As this file will be read by TUFLOW CATCH, the first column must contain the date in ISODATE format (DD/MM/YYYY hh:mm:ss). It will also be read by TUFLOW HPC, and therefore must have a column specifying a time in hours from the beginning of the model. In this case, the 'TUFLOW_Time' column contains the time in hours. For example, 01/01/2021 10:00:00 corresponds to 0, 01/01/2021 11:00:00 to 1, and so on. 
 
[[File: TC1_temperature_csv_01a.png]] 
 
<li> In the '''TUFLOW\bc_dbase''' folder, save a copy of the '''bc_dbase_M06_001.csv''' as '''bc_dbase_TC01_001.csv'''.
<li> Open the file and remove the references to the 2D boundaries (FC01, FC02, FC04, FC05, FC06 and FC07).
<li> Add the reference to the timeseries temperature data as shown below: 
 
[[File: TC1_bc_dbase_01b.png]] 
 
<li> Save the bc_dbase.
</ol>

= Materials =
Surface roughness or bed resistance values (e.g. Manning’s n) are assigned to material IDs. To simulate a more complex catchment area, more material IDs have been specified.
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOW_CATCH_Module_01\Tutorial_Data''' folder. Copy the '''materials_TC01_001.csv''' and paste it in the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model''' folder. This file is a modified version of '''materials_M06_002.csv''' from [[Tutorial_M06#Materials_2 | TUFLOW Tutorial Module 6]].
<li>Open the file. Roughness values (Manning's n) have been applied to the five new material IDs: 
 
[[File: TC1_materials_01b.png]] 
 
<li>These new material IDs have been assigned to allow different pollutant export properties to be specified to each material ID. This is discussed in the [[#Pollutant_Export_Model | TUFLOW CATCH Control File]] section.
</ol>

= TUFLOW Soil File (.tsoilf) =
The soils (.tsoilf) file is similar to the materials file. A positive integer ID is assigned to each soil, then an infiltration method followed by the soil parameters. For this tutorial, there is only one soil type (ID 1) which is applied across the whole model.
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOW_CATCH_Module_01\Tutorial_Data''' folder. Copy the '''TC01_soils_001.tsoilf''' and paste it in the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model''' folder. 
<li>Open the file. The Green-Ampt (GA) infiltration method has been used. For more information on infiltration methods, refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 
 
[[File: TC1_soils_file_01a.png]] 
 
</ol>

= Simulation Control Files =
The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its configuration information refer to [[NotepadPlusPlus_Tips | Notepad++ Tips]]. 
=== TUFLOW Geometry Control File (TGC) ===
<ol>
<li> Save a copy of '''M02_001.tgc''' as '''TC01_001.tgc''' in the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model''' folder.
<li> Open the '''TC01_001.tgc''' in a text editor and add the following line after the '<tt>Read GIS Mat</tt>' command to reference the new materials GIS layer. 
<tt>Read GIS Mat == gis\2d_mat_TC01_001_R.shp ! Sets material values according to attributes in the GIS layer</tt> 
<li> Add the following section to globally set the soil ID and the soil thickness: 
<tt>! SOILS</tt> 
<tt>Set Soil == 1 ! Globally sets the soil ID to 1</tt> 
<tt>Set Soil Thickness == 0.2 ! Globally sets the soil thickness to 0.2m</tt> 
<li> Save the TGC.
</ol>

=== TUFLOW Boundary Control File (TBC) ===
<ol>
<li>Save a copy of '''M06_003.tbc''' as '''TC01_001.tbc''' in the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model''' folder.
<li> Open the '''TC01_001.tbc''' in a text editor and remove or comment out the reference to the 2D boundaries using a '<tt>!</tt>' symbol. 
<tt>! Read GIS BC == gis\2d_bc_M01_001_L.shp ! Reads in downstream 2D boundary</tt> 
<li> Add the additional lines to reference the 1D/2D culvert connections: 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>gis\2d_bc_M03_culverts_001_P.shp</tt> <tt> ! Links the 1D culverts to the 2D domain</tt> 
<tt>Read GIS BC </tt> <tt>== </tt> <tt>gis\2d_bc_M03_culverts_001_R.shp | gis\2d_bc_M03_culverts_001_L.shp</tt> <tt> ! Links the 1D culverts to the 2D domain</tt> 
<li>Save the TBC.
</ol>

=== TUFLOW ESTRY Control File (ECF) ===
<ol>
<li> Navigate to the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOW\model''' folder, and open '''TC01_001.ecf''' in a text editor. This file was created using the TUFLOW CATCH plugin.
<li> In the '1D Time Control' section, ensure the following command has been specified to set the 1D computational timestep: 
<tt>Timestep </tt> <tt>== </tt> <tt>0.5</tt> <tt> ! Specifies a 1D computational timestep of 0.5 seconds</tt> 
<li> In the '1D Elements' section, add the following command to define the culverts: 
<tt>Read GIS Network </tt> <tt>== </tt> <tt>gis\1d_nwk_M03_culverts_001_L.shp</tt> <tt> ! Defines culverts</tt>
<li> Add the following command line to define the Advection Dispersion (AD) approach. For more information on Advection Dispersion, please refer to the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]. 
<tt>AD Approach == METHOD A ! Sets the modelling approach for the Advection Dispersion through 1D channels</tt>
<li>Save the ECF.
</ol>

== TUFLOW CATCH Control File (TCC) ==
A TUFLOW CATCH simulation is set up and executed by constructing a TUFLOW CATCH Control file (.tcc). TUFLOW Control file (.tcf) and TUFLOW FV Control file (.fvc) are not used. The .tcc has four command blocks:
<ol>
<li> Global settings
<li> Catchment Hydraulic Model (TUFLOW HPC) commands
<li> Catchment Pollutant Export Model
<li> Receiving Model (TUFLOW FV) commands
</ol>
All blocks must be included in the above order, but the later three can be switched on and off with a single command.

The TUFLOW CATCH plugin has created a .tcc template file in the '''TUFLOWCATCH\runs''' folder, '''TC01_001.tcc'''. This file has been populated with all the commands needed to execute a TUFLOW CATCH simulation. In this section, the template commands will be populated/updated for this tutorial model.

=== Global Settings ===
This section contains information that is applied equally to both TUFLOW HPC and TUFLOW FV.
<ol>
<li> Navigate to the '''TUFLOW_CATCH_Module_01\Modelling\TUFLOWCATCH\runs''' folder and open '''TC01_001.tcc''' into a text editor.
<li> In the 'Simulation Settings' section, update the time commands: 
<tt>Start Time == 01/01/2021 10:00:00 ! Specifies the simulation start time</tt> 
<tt>End Time == 01/01/2021 13:00:00 ! Specifies the simulation end time</tt> 
<li> In the 'Boundary Condition Configuration' section, update the BC and CSV output intervals: 
<tt>Catch BC Output Interval Nodestring == 300 ! Outputs BC nodestring data every 300 seconds</tt> 
<tt>Catch BC Output Interval Lateral == 300 ! Outputs BC lateral data every 300 seconds</tt> 
<tt>CSV Write Frequency Day == 0.01 ! Writes CSV output every 0.01 days</tt> 
</ol>

=== Catchment Hydraulic Model (TUFLOW HPC) ===
This block contains commands that construct the TUFLOW HPC simulation. These commands are almost entirely those that would be used in setting up a standalone TUFLOW HPC control file (.tcf), with a small number of additional commands that relate to TUFLOW CATCH.
<ol>
<li> Set the catchment hydraulic model: 
<tt>Catchment Hydraulic Model == HPC </tt>

<li> Set the zero date. TUFLOW HPC does not support ISODATE format, while TUFLOW FV requires it. This command ensures compatibility by setting the date in TUFLOW FV ISODATE format that corresponds to zero hours in TUFLOW HPC boundary condition files. 
<tt>Zero Date == 01/01/2021 10:00 ! Specifies the simulation start time in TUFLOW FV ISODATE format</tt> 

<li> In the 'GIS' section, remove or comment out the following command using a '<tt>!</tt>' symbol. The SHP projection has already been set in the [[#Global_Settings |Global Settings]] section. 
<tt>! SHP Projection == ..\..\TUFLOW\model\gis\projection.shp</tt> 

<li> In the 'GIS' section, set the projection for the output grid files: 
<tt>TIF Projection == ..\..\TUFLOW\model\grid\DEM.tif ! Sets the GIS projection for the output grid files</tt> 

<li> In the 'Solver' section, set the timestep maximum and time format: 
<tt>Timestep Maximum == 2.5 ! Specifies a maximum timestep (seconds)</tt> 
<tt>Time Format == TUFLOWFV ! Specifies the time format of output results</tt> 

<li> In the 'SGS' section, set the sample target distance: 
<tt>SGS Sample Target Distance == 0.5 ! Sets SGS Sample Target Distance (meters)</tt> 

<li> In the 'Control Files' section, ensure all control files are referenced. 
<tt>Geometry Control File == ..\..\TUFLOW\model\TC01_001.tgc ! Reference the TUFLOW Geometry Control File</tt> 
<tt>BC Control File == ..\..\TUFLOW\model\TC01_001.tbc ! Reference the TUFLOW Boundary Conditions Control File</tt> 
<tt>BC Database == ..\..\TUFLOW\bc_dbase\bc_dbase_TC01_001.csv ! Reference the Boundary Conditions Database</tt> 
<tt>Read Materials File == ..\..\TUFLOW\model\materials_TC01_001.csv ! Reference the Materials Definition File</tt> 
<tt>Rainfall Control File == ..\..\TUFLOW\model\M06_point2grid_003.trfc ! Reference the TUFLOW Rainfall Control File</tt> 
<tt>ESTRY Control File == ..\..\TUFLOW\model\TC01_001.ecf ! Reference the ESTRY (1D) Control File</tt> 

<li> In the 'Soils' section, reference the soils file (.tsoilf), and remove or comment out the 'soil negative rainfall approach' command using a '<tt>!</tt>' symbol. 
<tt>Read Soils File == ..\..\TUFLOW\model\TC01_soils_001.tsoilf ! Reference the Soils File</tt> 
<tt>! Soil Negative Rainfall Approach == FACTOR</tt> 

<li> In the 'Pollutant Configuration' section, reference the receiving polygon and set the pollutants. In this tutorial, salinity, temperature, dissolved oxygen (WQ_DISS_OXYGEN_MG_L), alive and dead ecoli (WQ_PATH_ECOLI_ALIVE/DEAD_CFU_100ML) and clay sediment (SED_CLAY) are simulated. 
<tt>Receiving Polygon == ..\..\TUFLOW\model\gis\2d_rp_TC01_001_R.shp ! GIS layer defining the receiving polygon</tt> 
<tt>Pollutant == Salinity, Temperature, WQ_DISS_OXYGEN_MG_L, WQ_PATH_ECOLI_ALIVE_CFU_100ML, WQ_PATH_ECOLI_DEAD_CFU_100ML, SED_CLAY ! Specify the pollutant names </tt> 

<li> In the 'Output Map Configuration' section, update the following commands to set the map output formats, the map output interval, map cuttoff depth and to define the TIF output parameters. 
<tt>Map Output Format == XMDF TIF ! Result file types</tt> 
<tt>Map Output Data Types == catch h v d ! Output data types</tt> 
<tt>Map Output Interval == 30 ! Interval of output map data (seconds)</tt> 
<tt>Map Cutoff Depth == 0.05 ! Sets map cutoff depth (meters)</tt> 
<tt>TIF Map Output Interval == 0 ! Interval of output TIF map data (seconds)</tt> 
<tt>TIF Map Output Data Types == h d dt ! TIF result file types</tt> 
</ol>

===Pollutant Export Model===
This block contains commands that control the pollutant export (and other constituent) simulation.
<ol>
<li> Set the pollutant export model: 
<tt>Catchment Pollutant Export Model == Mass Accumulation Release </tt>

<li> In the 'Constant Concentrations' section, add the following commands. They set the pollutants 'Salinity' and 'WQ_DISS_OXYGEN_MG_L' (dissolved oxygen) to a constant concentration value that is applied equally to all boundaries and summary files where appropriate. 
<tt>Constant Salinity == 0.0 ! Specify the constant concentration of salinity</tt> 
<tt>Constant WQ_DISS_OXYGEN_MG_L == 8.0 ! Specify the constant concentration of dissolved oxygen</tt> 

<li> In the 'Time Series' section, add the following command. It sets the pollutant 'Temperature' to be a time-series input, and points to the name 'temp' in the bc_dbase. 
<tt>Time-Series Temperature == temp ! Specify temperature as a timeseries and the corresponding BC database name</tt> 

<li>In the 'Pollutant Export Properties' section, add the material block '<tt>ALL</tt>' (<tt>Material == ALL</tt>) from the page linked below. This code block defines the default pollutant export properties for each pollutant. Once uniform conditions are set, progressive specifications of material by material pollutant behaviour can be set. These specifications override previous settings on a spatial basis. Including the default (<tt>ALL</tt>) material block is considered best practice, as it ensures that all pollutants have export properties defined across the entire TUFLOW HPC domain, otherwise an error will occur. For more information on the pollutant export parameters, refer to [https://docs.tuflow.com/catch/manual/2025.0/SimulationConstruction-1.html#SCTCCPollExpPE-4 Section 4.5.3.3 of the TUFLOW CATCH Manual].
:*[[TUFLOW_CATCH_Tutorial_M01_Pollutant_Export#Default_.28ALL.29 | Pollutant Export Properties: ALL]] 

<li>To set the pollutant export properties for the different material IDs, blocks similar to the above (e.g. <tt>Material == 4</tt>) can be used. The material IDs correspond to those defined in the '''2d_mat_TC01_001.shp''' and '''2d_mat_M01_001.shp''' GIS layers. 
 
To estimate E. coli export rates for each paddock, the area of each paddock was calculated. Based on this, appropriate animal populations were assigned. Using these values, the E. coli rates were calculated. For more information on pollutant export calculations, refer to [https://docs.tuflow.com/catch/manual/2025.0/ProcessDescriptions-1.html#ProcessDescriptionsMats-3 Section 3.2.3 of the TUFLOW CATCH Manual]. 
 
[[File: TC1_aerial_with_paddocks_01a.png|left]]
 
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white; padding: 10px" |Material ID
! style="background-color:#005581; font-weight:bold; color:white; padding: 10px" |Paddock Name
! style="background-color:#005581; font-weight:bold; color:white; padding: 10px" |Area (ha)
! style="background-color:#005581; font-weight:bold; color:white; padding: 10px" |Animals
|-
|6||paddockA||1.5|| 23 Sheep, 7 Lambs
|-
|7||paddockB||0.3||2 Cows
|-
|8||paddockC||1.2||20 Sheep
|-
|9||paddockD || 1||4 Cows, 2 Calves
|}
 
 

<li> Set the pollutant export properties for material ID 1. This is the material ID for all areas within the model domain not covered by a material region. These pollutant export properties define the release and deposition of clay sediment. Sediment pollutants generally use the 'Shear1' method. For more information on 'Shear1', refer to [https://docs.tuflow.com/catch/manual/2025.0/SimulationConstruction-1.html#SCTCCPollExpSS-5 Section 4.5.3.3.2 of the TUFLOW CATCH Manual]. 
:*[[TUFLOW_CATCH_Tutorial_M01_Pollutant_Export#Model_Area_.281.29 | Pollutant Export Properties: 1]]

<li>Set the pollutant export properties for material ID 4 (waterholes, eddies, etc). These properties define settling (deposition velocity) of alive and dead E. coli to 2 meters per day (approx 25cm during the simulation). 
:*[[TUFLOW_CATCH_Tutorial_M01_Pollutant_Export#Slow_Moving_Water_.284.29 | Pollutant Export Properties: 4]]

<li>Set the pollutant export properties for material ID's 6 (paddockA), 7 (paddockB), 8 (paddockC) and 9 (paddockD). These properties define the accumulation (rate) and washoff of alive and dead E. coli for the animals on the paddock. 
:*[[TUFLOW_CATCH_Tutorial_M01_Pollutant_Export#Paddocks_.286.2C_7.2C_8_and_9.29 | Pollutant Export Properties: 6, 7, 8, 9]]

<li> For this tutorial, leave all interventions commands as is. This section of the .tcc will be discussed in [[TUFLOW_CATCH_Tutorial_M02 |TUFLOW CATCH Tutorial 02]].
<li> Save the .tcc.
</ol>

===Receiving Model (TUFLOW FV)===
For this tutorial, leave all commands as is. This section of the .tcc will be populated in [[TUFLOW_CATCH_Tutorial_M03 | TUFLOW CATCH Tutorial 03]].

=Running the Simulation=
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOWCATCH\runs''' folder. The TUFLOW CATCH plugin created a batch file (.bat) that references the .tcc called '''Demonstration.bat'''.
<li>Save a copy of '''Demonstration.bat''' as '''_run_TC01_CATCH.bat''' and open the file in a text editor.
<li>Update the batch file to reference the TUFLOW CATCH executable: 
<tt>set exe="..\..\..\..\exe\TUFLOWCATCH\2026.0.0\TUFLOWCATCH.exe"</tt> 
<tt>%exe% TC01_001.tcc</tt>
<li>Double click the batch file in file explorer to run the simulation.
</ol>

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

=Check Files and Results Output=
Complete the steps outlined in the following links to review check files and simulation results from the TUFLOW CATCH pollutant export model simulation:
:*[[TUFLOW_CATCH_Tutorial_M01_Check_Files_QGIS | TC01 - Check Files]] 
:*[[TUFLOW_CATCH_Tutorial_M01_Results_QGIS | TC01 - Results]] 

=Reviewing Model Performance=
There are a number of useful outputs from TUFLOW CATCH for reviewing the model performance.

===TUFLOW CATCH Log File (.catchlog)===
The first file to review is the TUFLOW CATCH Log File (.catchlog). The <tt>Log Folder == log</tt> command in the .tcc controls where the .catchlog is written. 
Navigate to the '''Modelling\TUFLOWCATCH\runs\log''' folder and open the '''TC01_001.catchlog''' file in a text editor. It contains a summary of the TUFLOW CATCH simulation. The following are the key points to review: 
* '''Global Settings:''' The commands from the 'Global Settings' section of the .tcc are echoed here. Review these to confirm that the correct settings have been applied. 
:[[File: TC1_catchlog_01b.png]] 
* '''Simulation Configuration:''' The .catchlog outlines which models have been used and what simulation configuration has been run. In this tutorial, the catchment hydraulic and pollutant export models have been applied, indicating a pollutant export configuration. 
:[[File: TC1_catchlog_02a.png]] 
* '''Run Status:''' At the end of the file, a message will confirm the simulation outcome.
:* If successful, it will state 'Run Successful' 
::[[File: TC1_catchlog_03b.png]] 
:* If an issue occurred, the simulation will stop and an error message will be reported. An example error is shown in the image below.
::'''Note:''' Each TUFLOW CATCH error message has a corresponding wiki page that provides further details about the error, and suggestions for how to fix the issue. Refer to [[5xxx_TUFLOW_Messages | 5xxx Messages]] for a list of all TUFLOW CATCH related error messages. 
::[[File: TC1_catchlog_04c.png]] 

===Other Log Files===
Once the .catchlog has been reviewed, it is recommended to check the TUFLOW Log File (.tlf) if the catchment hydraulic model has been specified and to check the TUFLOW FV Log File (.log) if the receiving model has been specified. These files contain TUFLOW and TUFLOW FV specific check, warning and error messages.

====TUFLOW Log File (.tlf)====
Since the catchment hydraulic model is specified in this tutorial, review the TUFLOW Log File. The <tt>Log Folder == log</tt> command in the .tcc defines where the .tlf is written 
Navigate to the '''Modelling\TUFLOWCATCH\runs\log''' folder and open the '''TC01_001_catchment_hydraulic.tlf''' file in a text editor.
* Scroll down to the bottom to 'Simulation Summary'. This includes information about the computation time, messages, volume calculations and mass error.
* Review any check, warning or error messages.
* For more information on reviewing TUFLOW log outputs, refer to [[HPC_Model_Review | HPC Model Review]].

====TUFLOW FV Log File (.log)====
The receiving model has not been specified in this tutorial, so no TUFLOW FV Log File (.log) has been created. The TUFLOW FV Log File will be reviewed in [[TUFLOW_CATCH_Tutorial_M03#Reviewing_Model_Performance | TUFLOW CATCH Tutorial 03]].

=Conclusion=
* A TUFLOW CATCH Pollutant Export model was created. A downstream receiving polygon was used to track pollutants in the receiving waters.
* Check files were used to review the transfer from the Catchment Hydraulic model (TUFLOW HPC) into the receiving polygon.
* TUFLOW CATCH time series results and TUFLOW map outputs were assessed to observe the pollutant behaviours.
* For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_Introduction| Back to Tutorial Introduction Main Page]]
}}

TUFLOW CATCH Tutorial M01 Project Initialisation QGIS

2026-03-30T02:06:37Z

Emilie Nielsen: /* TUFLOW CATCH Plugin */

== Introduction ==
QGIS is used to configure the TUFLOW CATCH project with the TUFLOW CATCH plugin. For installation, see [[TUFLOW_CATCH_Tutorial_Introduction#Software_Requirements | TUFLOW CATCH Tutorial Introduction]].

There are three steps to set up the TUFLOW CATCH project:
<ol>
<li>Define the QGIS Project Coordinate Reference System (CRS).
<li>Use the TUFLOW CATCH plugin to create the model folder structure and to write empty GIS files for model inputs.
<li>Set up the QGIS workspace to contain the DEM of the site.
</ol>

== Coordinate Reference System (CRS) ==
Define the CRS, also called 'Projection', for the QGIS workspace:
<ol>
<li> Open QGIS.
<li>Go to Project > Properties…
<li>In the CRS tab, type ‘WGS 84 / UTM Zone 60S’.
<li>Select the matching projection in the 'Predefined Coordinate Reference Systems' section.
<li>Click ‘Apply’ and ‘OK’.
<li>Ensure that the projection is set correctly by viewing the bottom right hand corner of the workspace. It should read ‘EPSG:32760’.
 
{{Video|name=animation_TC1_initialisation_01a.mp4|width=1236}} 
</ol>

== TUFLOW CATCH Plugin ==
Create the TUFLOW CATCH project:
<ol>
<li> Go to Processing > Toolbox from the top drop down menu options to open the Processing Toolbox.
<li> Go to TUFLOW Catch in the processing tool list and select 'Create TUFLOW Catch Project'. This opens the dialog shown below.
*Project Name: '''TC01'''
*Project Folder: Click '...', and navigate to the '''TUFLOW_CATCH_Module_01\Modelling''' folder.
*Project CRS: Click the drop down menu and select 'Project CRS: EPSG:32760 - WGS 84 / UTM zone 60S’.
*TUFLOW HPC Executable: Click '...', and navigate to the '''exe\TUFLOW\2026.0.0''' folder. Select '''TUFLOW_iSP_w64.exe'''.
*TUFLOW FV Executable: Click '...', and navigate to the '''exe\TUFLOWFV\2026.0.0''' folder. Select '''TUFLOWFV.exe'''.
*Default GIS Format: Click the drop down menu and select 'SHP'.
*Tick on 'Create Empty Files', 'Create Folder Structure' and 'Setup Control File Templates'
*Control File Templates: Expand the 'Advanced Parameters' section. Click '...', and tick on: TUFLOW CATCH Control file (.tcc), Batch file (.bat) and ESTRY Control file (.ecf). Ensure all other files are ticked off.

<li> Click 'Run' and a console window will open. This creates the TUFLOW CATCH folder structure, the projection files, the empty GIS files and template control files.
<li> Once the tool has finished, click 'Close'.
 
{{Video|name=animation_TC1_initialisation_02b.mp4|width=1236}} 
</ol>

The TUFLOW CATCH folder structure will now be set up in the '''TUFLOW_CATCH_Module_01\Modelling''' folder. The template files '''TC01_001.tcc''', '''Demonstration.bat''' and '''TC01_001.ecf''' will be in their respective folders. Note that the '''Modelling\TUFLOW''' folder still contains all files from [[Tutorial_M06#Part_3_-_Rainfall_Control_File | TUFLOW Tutorial Module 6 (part 3)]].

{{Video|name=animation_TC1_initialisation_03a.mp4|width=1236}} 

== QGIS Workspace ==
Set up the QGIS workspace to contain the model elevation data, and save the workspace:
<ol>
<li>In Windows File Explorer, navigate to the '''TUFLOW\model\grid''' folder. Drag and drop the '''DEM.tif''' file into QGIS.
<li>Change the symbology of the DEM:
* In the QGIS Layers panel, right click the '''DEM''' file and select 'Properties'.
*From the Symbology tab, under 'Band Rendering' select the following options:
:*Render type: Singleband pseudocolor
:*Color ramp: Spectral
:*Color ramp: Invert Color Ramp
:*Mode: Equal Interval
*From the Transparency tab, set the Global Opacity to 75%.
*Click 'Apply' and 'OK'.
 
{{Video|name=animation_TC1_initialisation_04a.mp4|width=1236}} 
<li>Create a hillshade of the DEM:
*Right click on the '''DEM''' file in the QGIS Layers Panel and select 'Duplicate Layer'.
*Right click on the '''DEM_copy''' and select 'Rename Layer'. Rename the layer to '''DEM_Hillshade'''.
*Right click on the '''DEM_Hillshade''' and select 'Properties'.
*From the Symbology tab, under 'Band Rendering' select the following options:
:*Render type: Hillshade
:*Z Factor: 3
*Click 'Apply' and 'OK'.
 
{{Video|name=animation_TC1_initialisation_05a.mp4|width=1236}} 
<li> Save the QGIS workspace:
*Go to Project > Save As.
*Navigate to the '''TUFLOW_CATCH_Module_01''' folder and save the workspace as '''TC01.qgz'''.
</ol>

 
{{Tips Navigation
|uplink=[[TUFLOW_CATCH_Tutorial_M01#Project_Initialisation| Back to TUFLOW CATCH Tutorial 1]]
}}

XPSWMM to TUFLOW-SWMM

2026-03-30T02:05:11Z

Emilie Nielsen: /* TUFLOW Simulation Execution */

= Introduction =
This Wiki page outlines recommended steps for the conversion of an XPSWMM model to TUFLOW. 

XPSWMM is a flood and urban stormwater drainage modeling software developed by Autodesk (previously Innovyze and XP Solutions). The XPSWMM solution uses EPA SWMM for its 1D calculations, dynamically linked to TUFLOW for its 2D calculations. The software functions within a custom build Graphical User Interface (GUI). Unknown to many XPSWMM modelers, during simulation, XPSWMM processes its inputs into TUFLOW files and also calls TUFLOW for the 2D calculations. As XPSWMM uses TUFLOW for its 2D engine, like-for-like results can be achieved using this software. The modeling workflow in TUFLOW differs from XPSWMM, as TUFLOW modeling is integrated with QGIS (Geographical Information System) GIS software instead of embedded within a software specific Graphical User Interface.

If you are building a TUFLOW SWMM model from scratch, not from XPSWMM, please refer to the [[TUFLOW_SWMM_Tutorial_Introduction | TUFLOW SWMM Tutorials]]. Tutorials are provided for the following topics:
* [[TUFLOW SWMM Tutorial M01 | TUFLOW SWMM Module 1]] - 1D SWMM Culverts
* [[TUFLOW SWMM Tutorial M02 | TUFLOW SWMM Module 2]] - 1D SWMM Pipe Network / 2D TUFLOW Direct Rainfall Hydrology
* [[TUFLOW SWMM Tutorial M03 | TUFLOW SWMM Module 3]] - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology
* [[TUFLOW SWMM Tutorial M04 | TUFLOW SWMM Module 4]] - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology: Executing multiple different event simulations from a single model control file.

== Dataset Download ==
The dataset used for this model conversion demonstration is available for download here: [https://downloads.tuflow.com/SWMM/XPSWMM_XPX_to_TUFLOW_Conversion.zip XPSWMM XPX to TUFLOW Conversion Dataset]. 
This dataset contains the XPSWMM model and the resulting TUFLOW model that is created. These can be found in the '''XPSWMM''' and '''Complete_Conversion''' folders respectively. 

'''If you are using this example conversion dataset, please rerun the XPSWMM model in the location where you save the dataset before beginning your own TUFLOW model conversion.''' Rerunning the model is necessary because XPSWMM will write TUFLOW files during its preprocessing, subsequently defining the correct file path information (for the location where you saved your files) in the newly written TUFLOW files. We also recommend creating your own TUFLOW model in a different folder from the provided TUFLOW dataset so you can easily compare your model against it. 

If you do not have access to a XPSWMM license and the XPSWMM Application, please refer to the [[XPSWMM_to_TUFLOW-SWMM_Troubleshooting#Model_Conversion_Without_a_XPSWMM_License |XPSWMM to TUFLOW SWMM Troubleshooting]] page. 

= XPSWMM to TUFLOW Model Conversion =
== Export Data From XPSWMM Model ==
'''Digital Terrain Model (DTM) Data''' 
XPSWMM reads its 2D DTM data in one of two ways:
* The DTM data can be directly specified in the '2D Model Settings', or
* The DTM data can be internally processed by XPSWMM using its terrain tools and DTM builder.
Depending on which method is applied to your XPSWMM model, the steps required to will vary. Review which method is used:
<ol>
<li> Open your existing model in XPSWMM.
<li> In the top dropdown menu options, go to Configuration > Job Control > 2D Model Settings. This will open a dialog.
<li> Under '2D Hydraulics Job Control', select 'Surface & Sampling'.
<li> Review the options in the 'Surface' section:
:* If 'Use DTM' is selected: Continue to the section below ([[XPSWMM_to_TUFLOW-SWMM#Export_DTM_Data_from_XPSWMM |Export DTM Data from XPSWMM]]) and complete the steps.
:* If 'Use Grid File for Topography' is selected and a 'Grid file' is specified, the steps outlined in the 'Export DTM Data From XPSWMM' section can be skipped. Go to the [[XPSWMM_to_TUFLOW-SWMM#Export_XPX_Data_From_XPSWMM|Export XPX Data From XPSWMM]] section.
'''Note:''' If you have a .tif elevation file, you can continue to the [[XPSWMM_to_TUFLOW-SWMM#Export_XPX_Data_From_XPSWMM|Export XPX Data From XPSWMM]] section. The conversion process will be identical however, once converted, you will have to create the '''TUFLOW\model\grid''' folder manually and copy the .tif file into it.
 
{{Video|name=Animation_XPtoTUFLOW_Export_Data_01b.mp4|width=1350}}
 
</ol>

=== Export DTM Data From XPSWMM ===
If 'Use DTM' was selected, XPSWMM preprocesses its Digital Terrain Model (DTM) into a binary XPTIN elevation dataset for inclusion in the TUFLOW model. XPTIN is a binary format that can't readily be used in GIS software. For this reason, the following steps outline how to obtain a DTM dataset in a GIS friendly form.
<ol>
<li> In the XPSWMM Layers panel, under 'Topography', right click on '''DTM''' and select 'Export DTM Data'.
:* Input TIN File: Select the relevant XPSWMM Input TIN file.
:* Output File Format: 'ASCII Grid File Format'.
:* Cell Size Value: Choose a suitable DTM resolution. This resolution should be finer than the hydraulic model resolution. Typically, a DTM resolution is 1/5th to 1/10th of the hydraulic model 2D cell size is common (1 in the example dataset).
''Note: XPSWMM requires an integer cell size value for this export step. For example, Cell Size Values of 1, 2, 3, 4, 5 ... are suitable. The XPSWMM export will not function if you specify a decimal cell size value (eg. 0.5, 2.5, etc.).''
<li> Click 'Export'.
<li> Save the file under an appropriate name (e.g. '''1D2D_Urban_Grid.asc''') to the folder where XPSWMM writes the .tcf during its simulation preprocessing. By default, this is the '''2D\Data''' folder. 
If this folder does not exist, either:
:* The XPSWMM model has not run, so the TUFLOW control files have not been created by XPSWMM. Run the XPSWMM model (go to Analyze > Solve... in top dropdown menu options).
:* Non-default output settings have been specified in XPSWMM. To determine the output location, in the top dropdown menu options, go to Configuration > Job Control > 2D Model Settings > Folder Options. Ensure the following 'Folder Locations' are selected.
::[[File: XPSWMM_to_TUFLOW_2DJobControl_FolderOptions_Dialog_01e.png]] 

<li> In the top dropdown menu options, navigate to Configuration > Job Control > 2D Model Settings. This will open a dialog, under '2D Hydraulics Job Control', select 'Surface & Sampling'.
<li> Tick on 'Use grid file for topography' and select '...' to navigate to the Grid file saved in the '''2D\Data''' folder. This file will be read directly into TUFLOW.
<li> Click 'OK' to save the settings.
<li> Run the XPSWMM model to rewrite the TUFLOW files (including the new linkage to the DTM dataset) to the Data folder (go to Analyze > Solve... in top dropdown menu options).
 
{{Video|name=Animation_XPtoTUFLOW_Export_Data_02b.mp4|width=1350}}
 
</ol>

=== Export XPX Data From XPSWMM ===
A XPX file is a simple command line file that contains the information needed to create link and node objects. To export this data from the XPSWMM model:
<ol>
<li> In XPSWMM, in the top dropdown menu options, navigate to File > Import/Export Data > Export XPX Data. This will open a dialog. Leave all options as default and click 'Export'.
<li> When prompted, save the file under an appropriate name (eg '''1D2D_Urban_001.xpx''') to the folder where the XPSWMM model is located.
 
{{Video|name=Animation_XPtoTUFLOW_Export_Data_03b.mp4|width=1350}}
 
</ol>

== Convert XPSWMM Model to TUFLOW SWMM ==
Ensure you have QGIS and have the QGIS TUFLOW Plugin installed:
*Install QGIS 3.34 or later: [https://www.qgis.org/download/ Latest 64-bit version of QGIS].
*Install the QGIS TUFLOW Plugin by following the instructions, [[TUFLOW_QGIS_Plugin | QGIS TUFLOW Plugin Installation]].

The following steps outline the process of converting a XPSWMM model to TUFLOW SWMM using the '[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]' processing tool.

<ol>
<li> Open QGIS and go to Processing > Toolbox from the top dropdown menu options to open the Processing Toolbox.
<li> Go to TUFLOW >> SWMM in the processing tool list and select '[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]'. This opens the dialog shown below.
:* XPSWMM Exported XPX File: Click '...' and navigate to the exported XPX data (e.g. '''1D2D_Urban_001.xpx'''). This should be located in the same folder as the XPSWMM model.
:* TUFLOW TCF Filename: Click '...' and navigate to the XPSWMM .tcf. This should be located in the '''2D\Data''' folder (e.g. '''2D\Data >> 1D2D_Urban_001.tcf''').
:* SWMM File Prefix: Choose an appropriate prefix for the SWMM files (e.g. '''1D2D_Urban_swmm''').
:* Output Solution Scheme: 'HPC'
:* Output Hardware Specification: 'GPU' (if GPU is not available, select 'CPU')
:* Output Vector Format: 'GPKG'
:* Output Raster Format: 'GTIFF'
:* Output Profile: Any option can be used. 'ALL IN ONE' is used in this example for model design consistency with the [[Tutorial_Introduction | TUFLOW SWMM Tutorials]].
:* Event name if no global storms: Choose an appropriate event name if applicable (100yr in the example dataset).
:* BC width for created 1D/2D connections (HX/SX): This value should be approximately 2 times the width of the hydraulic model 2D cell size (10 in the example dataset).
:* BC offset distance for created 1D/2D connections (HX/SX): Distance from the channel endpoint to the midpoint of the BC line (2 in the example dataset).
:* Output Folder: Click '...' and navigate to an appropriate location to save your TUFLOW model. In this location, create a new folder called '''TUFLOW''' and select it.
:* Output CRS: Select an appropriate Coordinate Reference System (CRS) for the model. For the demonstration model, the CRS is 'EPSG:32760 - WGS 84 / UTM zone 60S'.
<li> Click 'Run'. Once the tool is finished, click 'Close'.
 
{{Video|name=Animation_XPtoTUFLOW_Convert_01c.mp4|width=1350}}
 
</ol>

Inspect the output of the '[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]' processing tool and load the TUFLOW model into QGIS:
<ol>
<li> In Windows File Explorer, inspect the files output by the processing tool. In particular:
* The '''TUFLOW\bc_dbase''' folder contains the BC Database which will contain any curves used in BC conditions, for easy extending to other events.
* The '''TUFLOW\model''' folder contains the TUFLOW SWMM Control File (TSCF) which holds all commands specific to SWMM, including links to the converted SWMM INP file.
* The '''TUFLOW\model\swmm''' folder contains a GeoPackage database ('''*_convert_messages.gpkg'''). This GeoPackage contains locations and descriptions of any errors or warnings that occurred during the conversion process.
: '''Note:''' Conversion messages are addressed in further detail here [[XPSWMM_to_TUFLOW-SWMM_Troubleshooting#Common_Conversion_Issues |XPSWMM to TUFLOW SWMM Troubleshooting]].
* The '''TUFLOW\runs''' folder contains the TCF. If event(s) are specified, the TCF filename with have event placeholder(s), i.e. '_~e1~_~e2~_' (e.g. '''1D2D_Urban_001_~e1~.tcf'''). Again, if event(s) are used, this folder also contains the TUFLOW Event File (TEF) with the event(s) specified. 
{{Video|name=Animation_XPtoTUFLOW_Convert_02b.mp4|width=800}}
 
<li> Open QGIS, and click on the ‘Load TUFLOW Layers from TCF’ symbol from the QGIS TUFLOW Plugin toolbar.
 
[[File: Tuflow_plugin_load_tcf_layers.png]] 
 
<li> Navigate to the location of the TUFLOW model and go to the '''TUFLOW\runs''' folder. Select the TCF.
<li> In the Load Layers window, select:
* Ordering Options: Alphabetical
* Grouping Options: Group by control file
* Raster Load Options: Load Normally
<li> Click ‘Open’ and ‘OK’.
<li> Change the symbology of the DTM dataset:
* In the QGIS Layers panel, right click on the DTM Grid file and select 'Properties'.
* In the Symbology tab, under 'Band Rendering', set the 'Render type' to 'Hillshade' and the 'Z Factor' to 3.
<li> Inspect the output GIS layers.
 
{{Video|name=Animation_XPtoTUFLOW_Convert_03b.mp4|width=1350}}
 
</ol>

== Recommended Additional Conversion Steps ==
While the bulk of the XPSWMM to TUFLOW SWMM model conversion is automated by the '[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]' processing tool, some required or recommended conventions must be implemented/updated manually. Therefore, it is highly recommended to complete the additional conversion steps: [[XPSWMM_to_TUFLOW-SWMM_Recommended_Additional_Conversion_Steps|Recommended Additional Conversion Steps]]. 
These steps can help improve model stability and they may also be helpful to address any messages that occurred when using the conversion tool.
 

== TUFLOW Simulation Execution ==
Set up a simple batch file (.bat) to run TUFLOW. This approach calls the TUFLOW executable file (.exe) and runs the TCF file.
<ol>
<li>Create a new text file in the '''TUFLOW\runs''' folder and save as '''_run_HPC.bat'''.
<li>Open the '''_run_HPC.bat''' in a text editor and include a file path to the TUFLOW executable and the TCF name: 
<tt>set exe="..\..\exe\2026.0.0\TUFLOW_iSP_w64.exe" 
<tt>set run=start "TUFLOW" /wait %exe% -b 
%run% -e1 100yr 1D2D_Urban_001_~e1~.tcf</tt></tt> 
 
'''Note:''' A relative path is used for the executable and the TCF, full file path can also be used.
<li>Save the batch file and double click it in Windows File Explorer to run the simulation. This will open the TUFLOW Console Window and the simulation should be executed.
</ol>

TUFLOW simulations can be executed via numerous ways. A comprehensive summary of the most commonly used approaches is documented in the [[Running_TUFLOW | Running TUFLOW]] Wiki page.

=== Troubleshooting ===
Did your TUFLOW SWMM model fail to run successfully? If so, here is a link to a troubleshooting guide: [[TUFLOW_SWMM_Troubleshooting | TUFLOW SWMM Troubleshooting]]. 

= TUFLOW SWMM Result Viewing =
Are you familiar with loading and viewing TUFLOW results in QGIS? If not, we strongly recommend self-registering and completing our free eLearning:
[https://www.tuflow.com/training/training-course-catalogue/tt001-e-introduction-to-qgis-for-tuflow-elearning/ Introduction to QGIS for TUFLOW]. 

Our [[TUFLOW_SWMM_Tutorial_Introduction | TUFLOW SWMM Tutorials]] also demonstrate working with TUFLOW SWMM results.

= Recommended Further Reading =
For users who wish to get a better understanding of either 2D TUFLOW or 1D EPA SWMM, the following resources may be of use: 
'''TUFLOW''': [https://www.tuflow.com www.tuflow.com]
*[https://www.tuflow.com/downloads/#tuflow TUFLOW User Manual]
*[https://docs.tuflow.com/classic-hpc/release/2023-03-AD/ TUFLOW 2023-03-AD release notes]
*[[Tutorial_Introduction#Tutorial_Modules | TUFLOW Tutorial Models]]

 
'''EPA SWMM''': [https://www.epa.gov/water-research/storm-water-management-model-swmm www.epa.gov]
*[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume1_Hydrology_P100NYRA.pdf SWMM5 Reference Manual - Volume 1 (Hydrology)]
*[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume2_Hydaulics_P100S9AS.pdf SWMM5 Reference Manual - Volume 2 (Hydraulics) ]
*[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume2_Hydraulics_Addendum-20220210mas2wr.pdf SWMM5 Reference Manual - Volume 2 (Hydraulics Addendum) ]
*[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume3_Water_Quality_P100P2NY.pdf SWMM5 Reference Manual - Volume 3 (Water Quality) ]
*[https://downloads.tuflow.com/SWMM/swmm-users-manual-version-5.2.pdf EPA SWMM5 User's Manual]

=Contact=
For comments, requests and feedback contact [mailto:support@tuflow.com support@tuflow.com]. 
For further training opportunities see [https://tuflow.com/training/training-course-catalogue/ TUFLOW Training Catalogue] and/or contact [mailto:training@tuflow.com training@tuflow.com]. 
 

{{Tips Navigation
|uplink=[[Main_Page| Back to Wiki Main Page]]
}}