View source for TUFLOW SWMM Tutorial M01

= Introduction =
In this module, three culverts are added to represent flow through three separate road embankments. EPA SWMM is used as the solution scheme for the 1D culvert flow calculations, dynamically linked with the TUFLOW HPC 2D solution scheme. <br>

TUFLOW SWMM Tutorial Module 2 builds from the model created in <u>[[Tutorial_M02 |TUFLOW Tutorial Module 2]]</u> (in the TUFLOW Only tutorial dataset). The completed Module 2 model is provided in the '''''TUFLOW_SWMM_Module_01\TUFLOW''''' folder of the download dataset as the starting point for this tutorial. If you are not already familiar with TUFLOW, we recommend first completing Module 1 and 2 of the <u>[[Tutorial_Introduction | "TUFLOW Only" Tutorials]]</u> to establish an understanding of 2D modelling, before progressing to learning how to link 1D EPA SWMM to 2D TUFLOW. <br>

= QGIS Project Initialization =
QGIS Version 3.34 or newer, and QGIS TUFLOW Plugin 3.9.0.49 or newer are required to access the SWMM Processing Tools described in the following sections. For installation, see <u>[https://wiki.tuflow.com/index.php?title=TUFLOW_QGIS_Plugin#Installation_of_Plugin Installation of TUFLOW Plugin]</u>.<br>
Define the Coordinate Reference System (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’.
</ol>
<br>
{{Video|name=Animation_TS1_Initialization_01a.mp4|width=1235}}<br>

Load in the project GIS layers:
<ol>
<li>Click on the ‘Load TUFLOW Layers from TCF’ symbol from the TUFLOW Plugin toolbar.
<br>
[[File: Tuflow_plugin_load_tcf_layers.png]]<br>
<br>
<li>In File Explorer, navigate to the '''TUFLOW_SWMM_Module_01\TUFLOW\runs''' folder and select '''M02_5m_001.tcf'''.
<li>Click ‘Open’ and ‘OK’.
</ol>
<br>

Style the TUFLOW layers however you desire. Common steps to do this are:
<ol>
<li>Click on the ‘Apply TUFLOW Styles to Open Layers’ symbol from the TUFLOW Plugin toolbar.
<br>
[[File:tuflow_plugin_styles_open_layers.png]]<br>
<br>
<li>Change the symbology of the DEM:
*Right click on the '''DEM''' file in the Layers panel 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'.
<br>
{{Video|name=Animation_TS1_Initialization_02b.mp4|width=1235}}<br>
<li>Create a hillshade of the DEM:
*Right click on the '''DEM''' file in the 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''' file and select 'Properties'.
*From the Symbology tab, under 'Band Rendering' select the following options:
:*Render type: Hillshade
:*Z Factor: 3
*Click 'Apply' and 'OK'.
<br>
{{Video|name=Animation_TS1_Initialization_03b.mp4|width=1235}}<br>
</ol>

= SWMM Inputs and 1D/2D Linking=
==Create SWMM GeoPackage Spatial Database== 
Create a new folder in the '''TUFLOW_SWMM_Module_01\TUFLOW\model''' folder called '''swmm'''. This is the location where all SWMM inputs will be saved.<br>
<br>
In QGIS, create the SWMM GeoPackage Database:
<ol> 
<li>Go to '''Processing > Toolbox''' from the top drop menu options to open the Processing Toolbox panel.
<li>Go to '''TUFLOW > SWMM''' in the processing tool list and select 'GeoPackage - Create'. This opens the dialog shown below.
:*To set the ‘CRS for GeoPackage’: Click the drop down menu and select ‘Project CRS: EPSG:32760 - WGS 84 / UTM zone 60S’.
:*To set the ‘Initial SWMM Sections’: Click the …, and tick on: 
:**'''Project--Title''', '''Project--Options''', '''Project --Report.'''
:**'''Nodes--Junctions''', '''Nodes--Outfalls.''' 
:**'''Links--Conduits, Links--Streets''', '''Links--Inlets'''.
:*To define the ‘GPKG filename to create’: Click the …, select ‘Save to File’. Navigate to the '''TUFLOW\model\swmm''' folder and save the GeoPackage Database as '''sw01_001.gpkg'''.

<li>Click ‘Run’. 
<li>Once to tool has finished, click ‘Close’.
<li>In File Explorer, navigate to the '''TUFLOW\model\swmm''' folder and drag and drop '''sw01_001.gpkg''' into QGIS. 
<li>When prompted by QGIS, select 'Add Layers' to open all vectors within '''sw01_001.gpkg'''. By default, all items in the available list should have been selected. 
<li>In the QGIS Layers Panel, move '''sw01_001.gpkg''' to the top of the list. This will ensure the data within this database file is displayed above all other layers in the project. 
</ol>
<br>
{{Video|name=Animation_TS1_SWMM_Inputs_01d.mp4|width=1235}}
<br>
<br>

== GIS Data Entry ==

A GeoPackage called '''SWMM_Culverts.gpkg''' is provided in the '''TUFLOW_SWMM_Module_01\Tutorial_Data''' folder. It contains three layers: 
:*'''Conduits:''' defines the culvert location, type and geometry.
:*'''Junctions:''' defines the upstream culverts inverts.
:*'''Outfalls:''' defines the downstream culvert inverts.
<br>
To populate the GeoPackage created in the previous section:
<ol>
<li>In Windows Explorer, navigate to the '''TUFLOW_SWMM_Module_01\Tutorial_Data''' folder. Drag and drop the '''SWMM_Culverts.gpkg''' into QGIS. By default, all items in the GeoPackage will be selected. Click 'Add Layers'.
<li>In the QGIS Layers Panel, right click on the '''SWMM_Culverts >>''' '''Conduits''' layer and select 'Zoom to Layer'.
<li>Use the 'Select Features' tool to highlight all items included in '''Conduits'''.
<li>Select 'Edit' from the top QGIS tab and 'Copy Features' from the drop down manu. 
<li>Select the '''sw01_001.gpkg >>''' '''Links--Conduits''' layer in the Layers Panel by left clicking on it once. 
<li>Make the '''Links--Conduits''' layer editable by clicking the 'Toggle Editing' symbol [[File:toggle_editing_icon.png|27x27px]].
<li>Select 'Edit' from the top QGIS tab and click 'Paste Features' from the drop down menu.
<li>Toggle the editing off to save the edits.<br>
<br>
{{Video|name=Animation_TS1_SWMM_Inputs_02c.mp4|width=1235}}
<br>
<li>Similarly, copy the objects from '''Junctions''' into '''Nodes--Junctions'''. Junctions are considered inlets, and should be defined at the upstream end of culverts.
<li>Also copy the objects from '''Outfalls''' into '''Nodes--Outfalls'''. Outfalls are treated as outlets, and are required at the downstream end of culverts.
<li> Toggle off editing and save the edits.
<li>Close '''SWMM_Culverts.gpkg''' 
<br><br>
{{Video|name=Animation_TS1_SWMM_Inputs_03c.mp4|width=1235}}
<br>
<li>Inspect the attribute information within the respective layers to familiarize yourself with the data.
<br><br>
{{Video|name=Animation_TS1_SWMM_Inputs_04c.mp4|width=1235}}
</ol>
<br>

== GIS Data Updates ==
The provided GIS data requires numerous updates, prior to our model simulation. We have built these updates into this tutorial to demonstrate some of the available TUFLOW SWMM model built processing tools. The following updates are being made to Objects and Layers within '''sw01_001.gpkg''' 
===Update Conduit Details===
Step 1 involves updating the ''From Node'' and ''To Node'' attribute information in '''Links--Conduits'''. This information is necessary to "build" the 1D SWMM network. It defines the Link/Node connections. The information we will be adding to '''Links--Conduits''' is extracted from '''Nodes--Junctions''' and '''Nodes--Outfalls''' automatically using the 'Conduits - Assign Node Fields' tool from the Processing Toolbox.
<ol>
<li>In the QGIS Layers Panel, select (left click) '''Links--Conduits''' and toggle on editing.
<li>In the Processing Toolbox, select the 'Edit Features In-Place' tool [[File:edit_features_in_place_icon.png]]. This allows the editing of an existing layer, instead of the creation of a new layer.
<li>Go to TUFLOW > SWMM in the processing tool list and select 'Conduits - Assign Node Fields'. This opens the dialog shown below.
<li>Tick on the SWMM Node Layers: '''Nodes--Junctions''' and '''Nodes--Outfalls'''.
<li>Select 'Modify All Features'.
<li>Once the tool has finished, click 'Close'.
<li>View the attributes associated within '''Links--Conduits''' to verify the data processing has been completed correctly. The ''From Node'' and ''To Node'' attribute information is now configured correctly.<br>
'''Tip:''' If you wish to only update select objects during a future modelling project, instead of the entire '''Link--Conduits''' dataset, select the target objects first using the Feature by Area tool. The ''Conduits - Assign Node Fields'' tool will provide an option to ''Modify Selected Features'', instead of ''Modify All Features.''
<br><br>
{{Video|name=Animation_TS1_SWMM_Inputs_05c.mp4|width=1235}}
<br>
</ol>

===Update Losses===

Step 2, update the loss attributes in the '''Links--Conduits''' Layer. These values will be entered manually in this example using default values. Variation to the default values can be used in project models to reflect site specific information if desired. 
<ol>
<li>In the QGIS Layers Panel, select (left click) '''Links--Conduits''' and toggle on editing.
<li>Right click '''Links--Conduits''' and select 'Open Attribute Table'.
<li>Update the following fields:
:*losses_Kentry: 0.5
:*losses_Kexit: 1.0
:*losses_Kavg: 0.0
The video below demonstrates how to do this one entry at a time, or via the bulk attribute update options in QGIS.
<li>Turn off editing to save the edits.
<br><br>
{{Video|name=Animation_TS1_SWMM_Inputs_06c.mp4|width=1235}}
</ol>
<br>
An urban pipe network is added to the model in TUFLOW SWMM Module 2. In that situation, different loss attributes are required for the road culverts and underground stormwater pipe network links. To simplify the loss attribute update step in that situation, we will be using the 'Conduits - Assign Node Fields' processing tool. It is however, not necessary for this Module 1 tutorial because all the 1D SWMM inputs are embankment culverts with the same loss parameters applied to all objects.
<br>
<br>

=== Create 1D/2D Connections===
The following instructions introduce a new tool that automates the creation of 1D/2D connections. For 1D SWMM, HX lines are required from the upstream end of the culvert, and SX connections are used at the downstream end of the culvert.
<ol>
<li>In the QGIS Layers Panel, select (left click) '''Links--Conduits'''.
<li>In the Processing Toolbox, go to TUFLOW > SWMM and select 'BC - Create channel endpoint 1D/2D connections'. This opens the dialog shown below.  
:*Input Conduits Layer: '''Links--Conduits'''
:*Offset Distance: 2
:*Length of BC lines: 10
:*Tick on 'Set 2D cell elevation to 1D culevrt invert at 1D/2D connection cells if needed'.
:*Output Layer:
<ol>
::<li>Click the ... and select 'Save to GeoPackage'.
::<li>Navigate to the '''TUFLOW\model\swmm''' folder and select '''sw01_001.gpkg'''. Click Save. 
::<li>A dialog will open. In the Layer Name box, write '''2d_bc_SWMM_Culvert_Connections_001_L'''.
::<li>Click 'OK'.
</ol>
<li>Click 'Run'.
<li>Once the tool is finished, click 'Close'.
<li>The '''2d_bc_SWMM_Culvert_Connections_001_L''' appears in the Layers Panel.
</ol>
<br>
{{Video|name=Animation_TS1_SWMM_Inputs_07c.mp4|width=1235}}
<br>

===Update Junction Details===

<ol>
<li>In the QGIS Layers Panel, select (left click) '''Nodes--Junctions''' and toggle on editing.
<li>In the Processing Toolbox, select the 'Edit Features In-Place' tool. This allows the editing of an existing layer, instead of the creation of a new layer.
<li>Go to TUFLOW > SWMM in the processing tool list and select '''Junctions - Set attributes''' processing tool. This opens the dialog shown below.
:*Input BC Connection Layer: '''2d_bc_SWMM_Culvert_Connections_001_L'''
:*Nodes connected to 2D without Inlets (Ysur): 0
:*Nodes connected to 2D without Inlets (Apond): 50

<li>Select 'Modify All Features'.
<li>Once the tool has finished, click 'Close'.
<li>Turn off editing to save the edits.
<li>View the attributes associated within '''Nodes--Junctions''' to verify the data processing has been completed correctly.
<br><br>
{{Video|name=Animation_TS1_SWMM_Inputs_08c.mp4|width=1235}}
<br>
</ol>

==SWMM Options==
<ol>
<li>In the QGIS Layers Panel, select (left click) '''Project--Options''' and toggle on editing. 
<li>Right click '''Project--Options''' and select 'Open Attribute Table'.
<li>Update the following options: 
*'''Start Date''': 2020-01-01 (Date Format: YYYY-MM-DD)
*'''Report step''': 00:05:00
<li>Turn off editing to save the edits.  
</ol>

{{Video|name=Animation_TS1_SWMM_Inputs_09c.mp4|width=1235}}
<br><br>

== Export SWMM INP File ==
SWMM does not read '''sw01_001.gpkg''' directly as an input GIS file. We will need to convert the gpkg file to a SWMM INP file format.

<ol>
<li>In the Processing Toolbox, go to TUFLOW > SWMM and select 'GeoPackage - Write to SWMM inp'. This opens the dialog shown below.
:*GeoPackage Input File: Navigate to the '''TUFLOW\model\swmm''' folder and select '''sw01_001.gpkg'''.<br>
<li>By default, the tool will save the SWMM inp file in the same folder location using the same name as the GeoPackage input File. 
<li>Click 'Run'.
<li>Once the tool is finished, click 'Close'.
<li>The '''sw01_001.inp''' will now be located in the '''TUFLOW\model\swmm''' folder.
<br><br>
{{Video|name=Animation_TS1_SWMM_Inputs_10b.mp4|width=1235}}
</ol><br>

= Simulation Control Files =
The following steps will require us of a text editor. The tutorial demonstration uses Notepad++. For Notepad++ configuration infromation refer to <u>[[NotepadPlusPlus_Tips | Notepad++ Tips]]</u>. <br>

To differentiate the TUFLOW SWMM tutorials from the TUFLOW/ESTRY tutorials, TS will be used as the new file prefix in this series of tutorials. To avoid the potential risk of overwriting existing control files accidentally, we will start by saving new control files where we will be making subsequent syntax updates during the following steps. <br>

Set up the simulation control files:
<ol>
<li>Open '''M02_5m_001.tcf''' in Notepad++. Save the file as '''TS01_5m_001.tcf''' in the '''TUFLOW_SWMM_Module_01\TUFLOW\runs''' folder.
<li>Open '''M01_001.tbc''' using the "Open File" function in Notepad++. Save the file as '''TS01_001.tbc''' in the '''TUFLOW_SWMM_Module_01\TUFLOW\model''' folder.
<li>Create a new blank text file called '''TS01_001.tscf''' and save it in the '''TUFLOW_SWMM_Module_01\TUFLOW\model''' folder.
<br><br>
{{Video|name=Animation_TS1_Sim_Control_00a.mp4|width=1235}}<br>
</ol>

=== TUFLOW Control File (TCF) ===
<ol>
<li>Open the '''TS01_5m_001.tcf'''<li>Make the following reference update:  <br>
<font color="blue"><tt>BC Control File </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\model\TS01_001.tbc</tt></font> <font color="green"><tt>  ! Reference the TUFLOW Boundary Conditions Control File</tt></font> <li>Add the following line in the '<font color="green"><tt>Model Inputs</tt></font>' section:  <br>
<font color="blue"><tt>SWMM Control File </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\TS01_001.tscf </tt></font> <font color="green"><tt>  ! Reference the SWMM (1D) Control File</tt></font> 
<li>Add the following line in the '<font color="green"><tt>Output Settings</tt></font>' section: <br>
<font color="blue"><tt>NetCDF Output Start Date </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2020-01-01 00:00 </tt></font> <font color="green"><tt>! Sets the output units for the NetCDF time variable</tt></font> 
<li>Save the TCF.
<br><br>
{{Video|name=Animation_TS1_Sim_Control_01b.mp4|width=1235}}<br>
</ol>

=== TUFLOW Boundary Control File (TBC) ===
<ol>
<li>From '''TS01_001.tcf''', right click '''TS01_001.tbc''' and select 'Open File'. This opens '''TS01_001.tbc''' into a new tab in Notepad ++.
<li>Add the following command lines after '<font color="blue"><tt>Read GIS SA </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2d_sa_M01_001_R</tt></font>':  <br>
<font color="blue"><tt>Read GIS BC </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>swmm\sw01_001.gpkg >></tt></font> <font color="black"><tt>2d_bc_SWMM_Culvert_Connections_001_L</tt></font> <font color="green"><tt>      ! Links 1D SWMM culverts to the 2D TUFLOW domain</tt></font> 
<li>Save the TBC.
<br><br>
{{Video|name=Animation_TS1_Sim_Control_02b.mp4|width=1235}}<br>
</ol>

=== TUFLOW SWMM Control File (TSCF) ===
A new control file, the TUFLOW SWMM Control File (TSCF), is introduced. SWMM is a 1D hydraulic solver. All 1D SWMM files and commands are referenced in the TUFLOW SWMM Control File.<br>
<ol>
<li>From '''TS01_001.tcf''', right click '''TS01_001.tscf''' and select 'Open File'. This opens '''TS01_001.tscf''' into a new tab in Notepad ++.
<li>Add the following command: <br>
<font color="blue"><tt>Read SWMM </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>swmm\sw01_001.inp</tt></font> <font color="green"><tt>  ! 1D SWMM culvert input file</tt></font> <br>
<li>Save the TSCF.
<br><br>
{{Video|name=Animation_TS1_Sim_Control_03b.mp4|width=1235}}<br>
</ol>
<br>

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

<li>Double click the batch file in File Explorer to run the simulation. 
<br>
If the model simulation doesn't run, here is a link to some common <u>[[Tutorial_Troubleshooting_QGIS | Trouble Shooting]]</u> advice.
<br><br>
{{Video|name=Animation_TS1_Run_Sim_01b.mp4|width=1235}}<br>
</ol>
<br>

= Check Files and Results Output=
Complete the steps outlines in the following link to review check files and simulation results from the TUFLOW SWMM model simulation:

<u>[[TUFLOW_SWMM_Tutorial_M01_Check_QGIS | TUFLOW SWMM Tutorial 01 Check Files]]</u> <br>
<u>[[TUFLOW_SWMM_Tutorial_M01_Results_QGIS | TUFLOW SWMM Tutorial 01 Results]]</u><br>

= Conclusion =
:*EPA SWMM Culverts were added to convey water through the structures under the three roads in the tutorial model.
:*Check files were used to review the application of the boundary links.
:*Results through the 1D network structures were assessed.
<br>
{{Tips Navigation
|uplink=[[TUFLOW_SWMM_Tutorial_Introduction| Back to TUFLOW SWMM Tutorial Introduction Main Page]]
}}