View source for TUFLOW SWMM Tutorial M01

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

The GIS layers are:<br>
:*TSCF (TUFLOW SWMM Control File) layers:
<ol><ol><li>SWMM.inp: A text file containing a record of the SWMM culvert inputs and also SWMM simulation parameters. </ol></ol>
<ol><ol><li>1d_SWMM_Inlet: A layer used to define culvert inlet nodes. </ol></ol>
:*TBC layers:
<ol><ol><li> 2d_bc: A layer defining the locations of 1D/2D links.<br>

</ol></ol>
'''TUFLOW SWMM Module 1 builds from the model created in <u>[[Tutorial_M02 | TUFLOW 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''' <br>
<br>

= SWMM Inputs and 1D/2D Linking=
==Create SWMM GeoPackage Spatial Database== 
<ol> 
<li>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.<li>Open QGIS and select Processing >> Toolbox from the top drop menu options to open the Processing Toolbox panel.
<li>From the '''TUFLOW >> SWMM''' processing tool list, select '''GeoPackage-Create'''. <br>
[[File: SWMM_Tute_001_Geopackage_Create_Tool.png||900px]]<br>
<li>Within the GeoPackage-Create options, set the following:
*'''CRS for GeoPackage''' = Project CRS: EPSG:32760 - WGS 84/UTM zone 60S
*'''Initial SWMM Sections''', click on the '''...''' button, then select: '''''Title,''' '''Options,''' '''Nodes-Junctions,''' '''Nodes-Outfalls,''' '''Links-Conduits,''' '''Streets,''' '''Inlets,''' '''Report'''''
*'''GPKG file name to create''', click on the '''...''' button, select '''Save to File...'''. Navigate to the newly created swmm folder and set the SWMM GeoPackage Spatial Database name to '''TS01_001.gpkg'''
* Select '''Run'''. After the processing task is complete, select '''Close'''.  

<li>Open the new SWMM GeoPackage Spatial Database in QGIS by dragging and dropping '''swmm\TS01_001.gpkg''' from Windows Explorer into QGIS. When prompted by QGIS select "Add Layers" to open all vectors within the GeoPackage database. By default, all items in the available list should have been selected.<br>
</li></ol> 
<font color="red">'''<< Add video of above steps - when you create the vid ask me about the select CRS option. I want a specific workflow used so it captures something I didn't find intuitive>>'''</font>

== GIS Data Entry ==
Navigate to the '''TUFLOW_SWMM_Module_01\Tutorial_Data''' folder in Windows Explorer. Drag and drop '''SWMM_Culverts.gpkg''' into QGIS to open the file. SWMM_Culverts.gpkg includes three Layers, Links-Conduits, Nodes-Junctions and Nodes-Outfall. Links-Conduits defines the culvert location, type and geometry. Nodes-Junction define the upstream culverts inverts. Nodes-Outfall define the downstream culvert inverts.

Complete the following steps: 

# Copy the objects from '''Links--Conduits <font color="blue">SWMM_Culverts.gpkg</font>''' into '''Links--Conduits <font color="blue">TS01_001.gpkg</font>'''. Steps to Copy/Paste are as follows:
#* Left click '''Links--Conduits <font color="blue">SWMM_Culverts.gpkg</font>''' in the QGIS Layers Panel. Right cick the Layer and select ''Zoom to Layer'' if the three objects within the layer are currently not displayed in the main Map Window.
#* Use the select the Feature by Area tool to select all items included in '''Links--Conduits <font color="blue">SWMM_Culverts.gpkg</font>'''
#* Select Edit >> Copy Features
#* Left click '''Links--Conduits <font color="blue">TS01_001.gpkg</font>''' in the QGIS Layers Panel.
#* Select Toggle Editing to enable changes to be made to the Layer.
#* Select Edit >> Paste Features

<font color="red">'''<< Add video for Copy Paste>'''</font>

# Copy the objects from '''Nodes--Junction <font color="blue">SWMM_Culverts.gpkg</font>''' into '''Nodes--Junction <font color="blue">TS01_001.gpkg</font>'''. Junctions are considered inlets, and should be defined at the upstream end of culverts.
# Copy the objects from '''Nodes--Outfall <font color="blue">SWMM_Culverts.gpkg</font>''' into '''Nodes--Outfall <font color="blue">TS01_001.gpkg</font>'''. Outfalls are treated as outlets, and are required at the downstream end of culverts.
# Close '''SWMM_Culverts.gpkg''' 
# Inspect the attribute information within the respective layers to familiarize yourself with the data.

<font color="red">'''<< Add video for viewing attribute data>>'''</font>

== 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 '''TS01_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--Junction''' and '''Nodes--Outfall''' automatically using the '''Conduits - Assign Node Fields''' tool from the Processing Toolbox.

# Select (Left mouse click) '''Links--Conduits''' in the QGIS Layers panel and Toggle Editing on.
# From the Processing Toolbox, select "''Editing in place"''. This allows the editing of an existing Layer, instead of the creation of a new Layer.
# Select the '''Conduits - Assign Node Fields''' processing tool.
# Select '''Nodes--Junction''' and '''Nodes--Outfall''' in the SWMM Node Layers field.
# Select Modify All Features.
# Close the ''Conduits - Assign Node Fields'' processing tool.
# View the attributes associated with Links-Conduits to verify the data processing has been completed correctly. The ''From Node'' and ''To Node'' attribute information is now configured correctly.
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.''

<font color="red">'''<< Add video >>'''</font>

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

# Select (Left mouse click) '''Links--Conduits''' in the QGIS Layers panel and Toggle Editing on.
# Right mouse click '''Links--Conduits''' in the QGIS Layers panel and select Open Attribute Table.
# Set:
#* ''losses_Kentry'' = 0.5 
#* ''losses_kexit'' = 1.0 
# Save '''Links--Conduits'''

<font color="red">'''<< Add video >>'''</font>

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 attibute update step in that situation, we will be introducing 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.

===Update Junction Details===

Step 3,requires updating the storage attributes in the '''Node--Junctions''' Layer. These values will be entered manually in this example, using generic values. Variation to the default values can be used in project models to reflect site specific information if desired.
# Select (Left mouse click) '''Nodes--Junctions''' in the QGIS Layers panel and Toggle Editing on.
# Right mouse click '''Nodes--Junctions''' in the QGIS Layers panel and select Open Attribute Table.
# Set the ''Apond'' attribute to 100 for all (3) objects.
# Save '''Nodes--Junction'''.

<font color="red">'''<< Add video >>'''</font>

In TUFLOW SWMM Module 2, when we add underground pipe network infromation, we will require different Apond and Ysur attributes for the road culverts and underground pipe network junctions. To simplify the parameter update step in that situation, we will be introducing the '''''Junctions - Set attributes''''' processing tool. It is however, not necessary for this Module 1 tutorial because all the 1D SWMM inputs are embankment culverts.

=== 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>Select (Left mouse click) '''Links-Conduits''' in the QGIS Layers panel.
<li>Use the select the Feature by Area tool to select all culvert objects in '''Links-Conduits'''.

<li>In the search box of the Processing Toolbox panel, type SWMM.

<li>From the SWMM list, choose the '''BC - Create channel endpoint 1D/2D connections'''. 

<li>Select the following options:
*'''Input Conduits Layer''' = Links Conduits
*'''Offset distance''' = 2
*'''Length of BC lines''' = 10
*'''Output Layer'''= Select: '''Save to GeoPackage'''. Choose '''TS01_001.gpkg''' in the '''model\swmm''' folder and click Save. A Layer Name Window will open. Provide the following name: '''2d_bc_SWMM_Connections_001_L'''.<br><br></ol>
<font color="red">'''<< Add video >>'''</font>

==SWMM Options==
<ol>
<li> Select the '''Options''' Layer in '''TS01_001.gpkg''' file. 
<li> Select Toggle Editing to enable changes to be made to the Layer.

<li>Right click the Layer in the Layers Panel and select 'Open Attribute Table'.</li><li> Update the following option: 
*'''Start Date''': 01/01/2020 (USA Date Format: MM/DD/YYY)
*'''Report step''': 00:05:00
<li>Save and Toggle Editing off.  
</ol>


<font color="red">'''<< Add video >>'''</font>

== Export SWMM INP File ==
SWMM does not read '''TS01_001.gpkg'''  directly as an input GIS file. SWMM requires a INP file

<ol>
<li>Right click '''Links--Conduits''' in the QGIS Layers panel, and select '''TUFLOW >> SWMM - Export inp file'''.
<li>Select '''TS01_001.gpkg''' as the GeoPackage Input File.
<li>Set the SWMM output filename to '''TS01_001.inp''' in the '''TUFLOW/model/swmm''' folder.
<li>Select "Run", then "Close" after the processing is complete.
</ol>
<font color="red">'''<< Add video >>'''</font>

= Simulation Control Files = 
=== TUFLOW Boundary Control File (TBC) ===
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. 
<ol>
<li>Rename '''M01_001.tbc''' as '''TS01_001.tbc''' in the '''TUFLOW_SWMM_Module_01\TUFLOW\model''' folder.
<li>Open '''TS01_001.tbc''' in a text editor and add the additional lines: <br>
<font color="blue"><tt>Read GIS BC </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>2d_bc_SWMM_Connections_001_L</tt></font> <font color="green"><tt>  ! Links the 1D culverts to the 2D domain</tt></font> <br>
<li>Save the TBC.
</ol>
<font color="red">'''<< Add video >>'''</font>

=== 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>Create a new text file called '''TS01_001.tscf''', saved in the '''TUFLOW_SWMM_Module_01\TUFLOW\model''' folder.
<li>Add the following command lines: <br>
<font color="blue"><tt>Read SWMM </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>swmm\TS01_001.inp</tt></font> <font color="green"><tt>  ! 1D SWMM input file</tt></font> <br>
<li>Save the TSCF. <br>
</ol>
<font color="red">'''<< Add video >>'''</font>

=== TUFLOW Control File (TCF) ===
<ol>
<li>Save a copy of the '''M02_5m_001.tcf''' as '''M03_5m_001.tcf''' in the '''Module_03\TUFLOW\runs''' folder. 
<li>Open the '''M03_5m_001.tcf''' in a text editor:<br>
Add the following line in the 'Model Inputs' 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> <br>
Add the following line in the 'Output Settings' 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> <br>
<li>Make the following reference updates:  <br>
<font color="blue"><tt>Spatial Database </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\gis\TS01_001.gpkg </tt></font> <font color="green"><tt>! Specify the location of the GeoPackage Spatial Database</tt></font> <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> <br>
<li>Save the TCF.
</ol>
<font color="red">'''<< Add video >>'''</font>

= 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 Windows file explorer to run the simulation. 
</ol>
<font color="red">'''<< Add video >>'''</font>
<br>
If your model simulation did not run. Here is a link to some comon <u>[[Tutorial_Troubleshooting_QGIS | Tutorial Trouble Shooting]]</u> advice.

= Check Files =
= Results =
Plot time series results through the pipe network:
<ol>
<li>Open the TUFLOW Viewer in the QGIS TUFLOW Plugin.
<li>Select File > Load Results - Time Series. Navigate to the '''TS01_5m_001_swmm_ts.gpkg''' in the  '''TUFLOW_SWMM_Module_01\TUFLOW\results''' folder and open it.
<li>Two additional files appear in the Layers panel:
*'''TS01_5m_001_PLOT_L'''
*'''TS01_5m_001_PLOT_P'''
<li>Select the '''TS01_5m_001_PLOT_L''' file in the Layers panel and using the 'Select Features' tool highlight one of the pipe 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. <br>
<br>
[Video]<br>
<br>
</ol>
Plot longitudinal profiles from the Time Series datasets:<br>
<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.<br>
<br>
[Video]<br>
</ol>
<br>

= Conclusion =
:*EPA SWMM Culverts were added to convey water through the three structures under the 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]]
}}