Difference between revisions of "XPSWMM to TUFLOW-SWMM"

From Tuflow
Jump to navigation Jump to search
(90 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<font size = 18>Page Under Construction - Expected Finalization date: 23 February 2024 </font>
 
 
= Introduction =
 
= Introduction =
This Wiki page outlines recommended steps for conversion of an XPSWMM model to TUFLOW. <br>
+
This Wiki page outlines recommended steps for the conversion of an XPSWMM model to TUFLOW. <br>
  
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). During simulation, XPSWMM calls a TUFLOW dynamic library for the 2D calculations. As XPSWMM uses TUFLOW for its 2D engine, XPSWMM and TUFLOW use the same 2D solution and will achieve identical results if configured in a like-for-like way.
+
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. TUFLOW is the natural replacement for XPSWMM for people who are looking for an alternative solution following Autodesk's recent XPSWMM pricing, licensing, and support changes.
 
 
Common user feedback suggests the XPSWMM GUI is useful for simple modeling projects; however, it can become cumbersome and inefficient in workflow when dealing with larger datasets and/or a large volume of different scenario and event simulations. In response to requests from USA XPSWMM users who want to convert XPSWMM models into a native TUFLOW format, TUFLOW linkage with 1D EPA Storm Water Management Model (SWMM) was added as a supported feature in TUFLOW 2023-03-AD release. The modeling workflow in TUFLOW differs from XPSWMM, as TUFLOW modeling is integrated with QGIS (Geographical Information System) GIS software. This GIS integration is well-suited for working with larger datasets. Additionally, the structural design associated with TUFLOW modeling makes its general workflow extremely efficient, particularly for the automated management of multiple scenarios and events.  
 
  
 +
Common user feedback suggests the XPSWMM GUI is useful for simple modeling projects; however, it can become cumbersome and workflow inefficient when dealing with larger datasets and/or a large volume of different scenario and event simulations. In response to requests from USA XPSWMM users who want to convert XPSWMM models into a native TUFLOW format, TUFLOW linkage with 1D EPA Storm Water Management Model (SWMM) was added as a supported feature in TUFLOW 2023-03-AD release. The modeling workflow in TUFLOW differs from XPSWMM, as TUFLOW modeling is integrated with QGIS (Geographical Information System) GIS software. This is, however, a net positive. GIS integration is well-suited for working with larger datasets. Additionally, the structural design associated with TUFLOW modeling makes its general workflow extremely efficient, particularly for the automated management of multiple scenarios and events.
  
 
If you are building a TUFLOW SWMM model from scratch, not from XPSWMM, please refer to the <u>[[TUFLOW_SWMM_Tutorial_Introduction | TUFLOW SWMM Tutorials]]</u>. Tutorials are provided for the following topics:
 
If you are building a TUFLOW SWMM model from scratch, not from XPSWMM, please refer to the <u>[[TUFLOW_SWMM_Tutorial_Introduction | TUFLOW SWMM Tutorials]]</u>. Tutorials are provided for the following topics:
Line 13: Line 11:
 
* <u>[[TUFLOW SWMM Tutorial M03 | TUFLOW SWMM Module 3]]</u> - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology
 
* <u>[[TUFLOW SWMM Tutorial M03 | TUFLOW SWMM Module 3]]</u> - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology
 
* <u>[[TUFLOW SWMM Tutorial M04 | TUFLOW SWMM Module 4]]</u> - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology: Executing multiple different event simulations from a single model control file.
 
* <u>[[TUFLOW SWMM Tutorial M04 | TUFLOW SWMM Module 4]]</u> - 1D SWMM Pipe Network / 1D SWMM Urban Hydrology: Executing multiple different event simulations from a single model control file.
<br>
 
  
== TUFLOW Licensing / XPSWMM Discount ==
+
== Dataset Download ==
If you are an existing / or past XPSWMM perpetual license owner who would like to purchase a TUFLOW license, please contact <u>[mailto::sales@tuflow.com sales@tuflow.com]</u>. You may be eligible for an XPSWMM / TUFLOW discount in recognition of past royalties Autodesk paid TUFLOW when you purchased an XPSWMM perpetual license. <br>
+
The XPSWMM model used for this model conversion demonstration, and the resulting TUFLOW model that is created, are available for download here: <u>[https://downloads.tuflow.com/SWMM/XPSWMM_to_TUFLOW_Model_Conversion.zip XPSWMM to TUFLOW Model Conversion Dataset]</u>. The models are found in the XPSWMM and TUFLOW folders respectively. <br>
<br>
 
  
== Dataset Download ==
+
'''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.<br>
The XPSWMM model used for this model conversion demonstration is available for download here: <u>[https://downloads.tuflow.com/SWMM/XPSWMM_to_TUFLOW_Model_Conversion.zip XPSWMM to TUFLOW Model Conversion Dataset]</u>. A copy of the completed converted model can be downloaded at the end of the page. <br>
 
  
'''If you are using this example conversion dataset, please rerun the XPSWMM model before beginning the conversion process.''' This will generate the XPSWMM TUFLOW files and establish the correct file paths within them, aligning with the location where you have saved the dataset on your computer.
+
== TUFLOW Licensing / XPSWMM Discount ==
<br>
+
If you are an existing or past XPSWMM perpetual license owner who would like to purchase a TUFLOW license, please contact <u>[mailto::sales@tuflow.com sales@tuflow.com]</u>. You may be eligible for a XPSWMM / TUFLOW discount in recognition of past royalties Autodesk paid TUFLOW if you previously purchased an XPSWMM perpetual license.
<br>
 
  
 
= XPSWMM to TUFLOW Model Conversion=
 
= XPSWMM to TUFLOW Model Conversion=
 
== Two Dimensional (2D) Model Elements ==
 
== Two Dimensional (2D) Model Elements ==
XPSWMM writes TUFLOW model files when it pre-processes the model inputs defined in its GUI (prior to the hydraulic calculations). Using default settings, XPSWMM typically writes the TUFLOW files to the '''2D\Data''' folder. follow these steps to extract and format the XPSWMM / TUFLOW 2D model features.<br>
+
XPSWMM writes TUFLOW model files during its preprocessing of the model inputs defined in its GUI (prior to the hydraulic calculations). By default, XPSWMM usually writes the TUFLOW files to the '''2D\Data''' folder. For use by TUFLOW, some 2D model elements within the XPSWMM model must be exported and formatted. To accomplish this, please follow the links provided below:
  
 
<ol>
 
<ol>
 
<li> <u>[[XPSWMM_Conversion_DTM | Digital Terrain Model (DTM) Data Processing]]</u>
 
<li> <u>[[XPSWMM_Conversion_DTM | Digital Terrain Model (DTM) Data Processing]]</u>
 
<li> <u>[[XPSWMM_Conversion_TUFLOW_Structure | Convert XPSWMM Model to Recommended TUFLOW Structure]]</u>
 
<li> <u>[[XPSWMM_Conversion_TUFLOW_Structure | Convert XPSWMM Model to Recommended TUFLOW Structure]]</u>
<li>* <u>[[XPSWMM_Conversion_Load_TUFLOW_Model | Load Model in QGIS]]</u>
+
<li> <u>[[XPSWMM_Conversion_Load_TUFLOW_Model | Load Model in QGIS]]</u>
</ol>
 
 
 
 
 
 
 
 
 
=== Convert XPSWMM Model to Recommended TUFLOW Structure ===
 
When XPSWMM writes its TUFLOW files, it consolidates all the information into a single folder (typically the '''2D\Data''' folder). This is not a standard TUFLOW structure. The standard structure used by the majority of TUFLOW modelers globally includes the following subfolders:
 
 
 
{| class="wikitable" width="80%" style="text-align:center"
 
!style="background-color:#005581; font-weight:bold; color:white;"| Folder
 
!style="background-color:#005581; font-weight:bold; color:white;"| Folder
 
!style="background-color:#005581; font-weight:bold; color:white;"| Folder Purpose
 
 
 
|-
 
|rowspan="10"|[[File:TUFLOW_Folder_Structure.JPG | 150px]]
 
|-
 
|colspan="2"|'''Folders typically saved to the network within a folder titled TUFLOW'''
 
|-
 
| runs || TUFLOW Control File(s) (.tcf), the primary file(s) used to run TUFLOW simulations, are saved here.
 
|-
 
| runs\log || TUFLOW simulation log and error/warning message files are written here during a model simulation.
 
|-
 
| bc_dbase || Input boundary condition database(s) and time-series data for 1D and 2D domains are saved here.
 
|-
 
| model || TUFLOW's second level control files (.tgc, .tbc, .tscf, .ecf) are saved here.
 
|-
 
| model\gis <br> model\grid <br> model\mi <br> model\swmm || GIS layers defining the input spatial datasets are saved here.
 
|-
 
|colspan="2"|'''Folders typically saved to a computers local drive in a Project folder'''
 
|-
 
| results || TUFLOW simulation results are written here during a model simulation.
 
|-
 
| check || TUFLOW simulation check files are written here during a model simulation.
 
|}
 
 
 
<br>
 
To simplify the process of converting the XPSWMM model to the recommended TUFLOW SWMM folder structure, we have created a processing tool. This tool converts the GIS format of the XPSWMM model, creates the recommended TUFLOW folder structure and saves the converted model files to their correct locations. For more information on the processing tool, see <u>[[Convert_TUFLOW_Model_GIS_Format | Convert TUFLOW Model GIS Format]]</u>.
 
 
 
<ol>
 
<li> Open QGIS. If you do not have QGIS installed:
 
:*Install QGIS 3.34 or later: <u>[https://www.qgis.org/en/site/forusers/download.html Latest 64-bit version of QGIS]</u>.
 
:*Install the QGIS TUFLOW Plugin by following the instructions, <u>[[TUFLOW_QGIS_Plugin | QGIS TUFLOW Plugin Installation]]</u>.
 
<li> In QGIS, go to Processing > Toolbox from the top dropdown menu options to open the Processing Toolbox.
 
<li> Go to 'TUFLOW' in the processing tool list and select '<u>[[Convert_TUFLOW_Model_GIS_Format |Convert TUFLOW Model GIS Format]]</u>'. This opens the dialog shown below.
 
:* TCF: Click '...' and navigate to the XPSWMM .tcf. This should be located in the '''2D\Data''' folder.
 
:* 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 <u>[[Tutorial_Introduction | TUFLOW SWMM Tutorials]]</u>.
 
:* 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.
 
:* Advanced Parameters:
 
::* Tick on 'Write empty files'.
 
::* Output CRS: Select an appropriate Coordinate Reference System (CRS) for the model.
 
::* Tick on 'Force TUFLOW Directory Structure'.
 
::* TUFLOW Directory Structure Settings: Click '...'. Under 'Folder Structure', click the plus button to add a folder. Set 'Key' to '''swmm''', and 'Path' to '''./model/swmm'''.
 
<li> Click 'Run'.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_2D_model_03a.mp4|width=1350}}
 
<br>
 
<li> Inspect the tool output to familiarize yourself with the TUFLOW model structure.
 
<br><br>
 
{{Video|name=|width=1350}}
 
<br>
 
</ol>
 
<br>
 
 
 
=== Load and Style the TUFLOW Model in QGIS ===
 
Load the TUFLOW model in QGIS:
 
<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> Go to the location of the TUFLOW model and navigate 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’.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_2D_model_04a.mp4|width=1350}}
 
<br>
 
</ol>
 
 
 
Style the 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>Create a hillshade of the DEM:
 
* In the QGIS Layers panel, right click on the Grid file and select 'Rename Layer'. Rename the layer to include 'Hillshade' in the filename. For example, '''1D2D_Urban_Grid_copy''' > '''1D2D_Urban_Grid_Hillshade'''.
 
* Right click on the Hillshade and select 'Properties'.
 
* In the Symbology tab, under 'Band Rendering' select the following options:
 
:* Render type: Hillshade
 
:* Z Factor: 3
 
* In the Transparency tab, set the 'Global Opacity' to 75%.
 
* Click 'Apply' and 'OK'.
 
<br>
 
{{Video|name=Animation_XPtoTUFLOW_2D_model_06a.mp4|width=1350}}
 
<br>
 
</ol>
 
 
 
Save the QGIS Workspace:
 
<ol>
 
<li>From the top dropdown menu options, go to Project > Save As.
 
<li>Navigate to the file location containing the '''TUFLOW''' folder and save the workspace with the extension, .qgz.
 
 
</ol>
 
</ol>
<br>
 
  
 
== One Dimensional (1D) SWMM Model Elements ==
 
== One Dimensional (1D) SWMM Model Elements ==
 +
The 1D culvert, pipe network, and sub-catchment hydrology EPA SWMM items from XPSWMM require exporting and reconfiguring for compatibility with TUFLOW. Please follow the suggested workflow and instructions provided in the links below:
  
=== Export 1D EPA SWMM Pipe Network Data from XPSWMM ===
 
Convert 1D XPSWMM hydraulics features into a EPA SWMM 5 INP file format for TUFLOW:
 
 
<ol>
 
<ol>
<li> In XPSWMM, select 'Hydraulics Mode' from the toolbar.
+
<li> <u>[[XPSWMM_Conversion_Export_SWMM_Pipe_Network_Data | Export 1D EPA SWMM Pipe Network Data from XPSWMM]]</u>
<br><br>
+
<li> <u>[[XPSWMM_Conversion_Reconfigure_SWMM_Pipe_Network_Data | Configure 1D EPA SWMM Pipe Network Data for TUFLOW]]</u>
[[File: XPSWMM_to_TUFLOW_toolbar_hydraulics_mode_01a.png|700px]]
+
<li> <u>[[XPSWMM_Conversion_Export_SWMM_Hydrology | Export SWMM Hydrology]]</u>
<br>
+
<li> <u>[[XPSWMM_Conversion_Reconfigure_SWMM_Junctions | Update SWMM Junction Data]]</u>
<li> From the XPSWMM top dropmenu, select File > Import/Export Data > Export to EPASWMM5. The exported INP file will be saved under the same name and in the same folder location as the .xp project file.
+
<li> <u>[[XPSWMM_Conversion_Export_SWMM_INP | Export Updated SWMM INP Files]]</u>
<li> When prompted to save changes, select 'Yes'.
 
<li> In Windows File Explorer, navigate to the folder containing the .xp project file and rename the exported INP file by adding 'HDR' to the file name. For example, '''1D2D_Urban_001.inp''' > '''1D2D_Urban_HDR_001.inp'''.
 
<li> Copy the renamed INP file into the '''TUFLOW\model\swmm''' folder. From this folder, drag and drop the .inp file into QGIS. This will open the '<u>[[QGIS_SWMM_GeoPackage_Create_from_SWMM_inp |GeoPackage - Create from SWMM inp ]]</u>' tool from the QGIS Processing Toolbox.
 
:* SWMM Input File (inp): Pre-populated
 
:* CRS for GeoPackage: Select and appropriate Coordinate Reference System (CRS) for the model.
 
:* GeoPackage output filename: Prepopulated to save the output GeoPackage file under the same name and in the same folder location as the SWMM input file.
 
<li> Click 'Run'. Once the tool is finished, click 'Close'.
 
<li> A dialog will appear. Select 'Add Layers' to open all vectors within the newly created SWMM GeoPackage file. By default, all items in the available list should have been selected.
 
<li> In the QGIS Layers panel, move the SWMM GeoPackage file to the top of the list. This will ensure the data within this database file is displayed above all other layers in the project.
 
<li> Inspect the attributes associated with the various objects in the GeoPackage to familiarize yourself with the data.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_01a.mp4|width=1350}}
 
<br>
 
 
</ol>
 
</ol>
  
The process above has created a '''Nodes--Junctions''' layer, containing all the model nodes. In the <u>[[#Convert_XPSWMM_Model_to_Recommended_TUFLOW_Structure | Convert XPSWMM Model to Recommended TUFLOW Structure]]</u> section, an improperly formatted layer of the same nodes was generated from XPSWMM. To prevent future errors, this layer should be removed from the QGIS workspace and deleted from its GeoPackage.  
+
= TUFLOW Control Files Updates =
<ol>
+
The linking between 2D TUFLOW and 1D SWMM is established within the TUFLOW control files. The following sections (linked below) outline the basic commands needed to complete the linking process and execute the model. These tasks require the use of a text editor. The tutorial demonstration uses Notepad++. For configuration information, refer to <u>[[NotepadPlusPlus_Tips | Notepad++ Tips]]</u>. For a clean and organized model, it is recommended to name all the TUFLOW control files similarly. For example, '''1D2D_Urban_001.tscf''', '''1D2D_Urban_001.tbc''', '''1D2D_Urban_001.tgc''', and '''1D2D_Urban_5m_001.tcf'''. <br>
<li> In the QGIS Layers panel, open the tbc group (i.e. '''1D2D_Urban_001.tbc'''). Right click the 2d_bc points layer and select 'Remove Layer...'.
 
<li> From the top dropdown menu options, select View > Panels. Tick on 'Browser Panel'.
 
<li> In the QGIS Browser panel, navigate to the '''TUFLOW\model\gis''' folder and open the GeoPackage layer tree.<br>
 
:'''Note:''' Within the QGIS Browser panel, there is a dropdown directory, 'Project Home'. This directory is a shortcut to the location where the QGIS workspace is saved.
 
<li> Right click 2d_bc points layer (i.e.'''1D2D_Urban_001_2d_bc_P''') and select Manage > Delete Layer.
 
<br><br>
 
{{Video|name=|width=1350}}
 
<br>
 
</ol>
 
  
===Correct SWMM Nodes--Junction/Outfall Model Design===
+
''Note: For this demonstration, all commands will reference the datasets in the provided conversion model. Please update these references with the filenames used in your model if you are using these steps as a guide to convert your own XPSWMM model to TUFLOW.<br>''
XPSWMM used a modified version of the EPA SWMM engine. Unlike traditional EPA SWMM networks that require '''Nodes--Junctions''' at the upstream end of culverts and '''Nodes--Outfalls''' at the outlets, XPSWMM uses '''Nodes--Junctions''' in all locations. TUFLOW's implementation of SWMM has retained the traditional EPA SWMM structure. Due to this fundamental difference in approach, some manipulation of the XPSWMM '''Nodes--Junctions''' information is necessary.
 
  
 
<ol>
 
<ol>
<li> In the QGIS Layers panel, select (left click) '''Nodes--Junctions''' to make it the active dataset.
+
<li><u> [[XPSWMM_Conversion_TUFLOW_SWMM_Control_File_(TSCF) | TUFLOW SWMM Control File (TSCF)]]</u>
<li> Go to Processing > Toolbox from the top dropdown menu options to open the Processing Toolbox.
+
<li><u> [[XPSWMM_Conversion_TUFLOW_Boundary_Control_File_(TBC) | TUFLOW Boundary Control File (TBC)]]</u>
<li> Go to TUFLOW >> SWMM in the processing tool list and select '<u>[[QGIS_SWMM_Junctions_Downstream_Junctions_to_Outfalls |Junctions - Downstream junctions to outfalls]]</u>'. This opens the dialog shown below.
+
<li><u> [[XPSWMM_Conversion_TUFLOW_Geometry_Control_File_(TGC) | TUFLOW Geometry Control File (TGC)]]</u>
:* Input Junctions: '''Nodes--Junctions''' (this is prepopulated as '''Nodes--Junctions''' is the active dataset).
+
<li><u> [[XPSWMM_Conversion_TUFLOW_Control_File_(TCF) | TUFLOW Control File (TCF)]]</u>
:* Input Conduits: Click '...' and tick on '''Links--Conduits'''
+
<li><u> [[XPSWMM_Conversion_TUFLOW_Control_File_Formatting | Optional: Format TUFLOW Control Files]]</u>
:* Modified Junctions Layer: Leave this field blank so the tool writes the data to a temporary file. It will not be used.
 
:* Modified Outfalls Layer:
 
<ol>
 
::<li> Click '...', select 'Save to GeoPackage...'.
 
::<li> Navigate to the '''TUFLOW\model\swmm''' folder and select the HDR GeoPackage file created in the <u>[[#Convert_XPSWMM_Model_to_Recommended_TUFLOW_Structure | Convert XPSWMM Model to Recommended TUFLOW Structure]]</u> section. Click 'Save'.
 
::<li> A dialog will open. In the 'Layer Name' field, write '''Nodes--Outfalls'''. It is important that this layer is named correctly so it is recognized by the other TUFLOW SWMM processing tools.
 
::<li> Click 'OK'.
 
</ol>
 
<li> Click 'Run'. Once the tool is finished, click 'Close'.
 
<li> The temporary junctions layer, '''Modified junctions layer''', and the new outfalls layer, '''Nodes--Outfalls''', will appear in the QGIS Layers panel.
 
<li> In the QGIS Layers panel, right click '''Modified junctions layer''', and select 'Remove Layer..'.
 
<li> In the QGIS Layers panel, select (left click) '''Nodes--Outfalls''' and toggle off editing.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_02a.mp4|width=1350}}
 
<br>
 
 
</ol>
 
</ol>
  
To complete the update process, it is necessary to remove the junction nodes from '''Nodes--Junctions''' that coincide with the nodes created in '''Nodes-Outfalls'''. While this can be done manually, the steps below illustrate an automated process using a processing 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>
 
<ol>
<li> In the QGIS Layers panel, select (left click) '''Nodes--Junctions''' and toggle on editing.
+
<li>Create a new text file in the '''TUFLOW\runs''' folder and save as '''_run_HPC.bat'''.  
<li> Use the 'Select Features' tool to select all nodes included in the '''Nodes--Junctions''' layer. This will change their color to bright yellow.
+
<li>Open the '''_run_HPC.bat''' in a text editor and include a file path to the TUFLOW executable and the TCF name: <br>
<li> In the Processing Toolbox, go to 'Vector Selection' and select 'Select within distance'. This opens the dialog shown below.
+
<font color="black"><tt>"..\..\exe\2023-03-AD\TUFLOW_iSP_w64.exe" 1D2D_Urban_001.tcf</tt></font> <br>
:* Select features from: '''Nodes--Junctions''' (this is prepopulated as '''Nodes--Junctions''' is the active dataset).
+
'''Note:''' A relative path is used for the executable and the TCF, full file path can also be used.
:* By comparing to the features from: Click the drop down menu and select '''Nodes--Outfalls'''.
+
<li>Save the batch file and double click it in Windows File Explorer to run the simulation. This will open the TUFLOW DOS Console Window and the simulation should be executed.  
:* Where the features are within: '0.1 meters'
 
:* Modify current selection by: 'selecting within current selection'
 
<li> Click 'Run'. Once the tool is finished, click 'Close'.
 
<li> In the QGIS Layers panel, right click '''Nodes--Junctions''' and select 'Open Attribute Table'.
 
<li> In the attributes table, only some of the junction nodes will be selected. Select 'Delete selected features' to delete these nodes. Close the attribute table.
 
<li> Toggle the editing off to save the edits.  
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_03a.mp4|width=1350}}
 
<br>
 
 
</ol>
 
</ol>
  
=== 1D/2D Pipe Network Pit (Inlet Usage) Connections ===
+
TUFLOW simulations can be executed via numerous ways. A comprehensive summary of the most commonly used approaches is documented in the <u>[[Running_TUFLOW | Running TUFLOW]]</u> Wiki page.
⁠Inlet usage connections establish the 1D/2D linkages between the ground surface, defined in 2D, and the 1D SWMM pipe network. Physically, these features come in various forms and dimensions; however they are commonly referred to as kerb inlets, with or without associated grates. An example is shown in the image below. <br>
 
<br>
 
[[File: XPSWMM_Kerb_Inlet.JPG | 300px ]] <br>
 
<br>
 
Transfer of inlet usage connection information from XPSWMM to TUFLOW involves a three step process:
 
<ol>
 
<li> Export data from XPSWMM.
 
<li> Convert the exported data into a TUFLOW SWMM compatible format.
 
<li> Make minor edits to correct for snapping deficiencies in the XPSWMM export tools.
 
</ol>
 
  
 +
=== Troubleshooting ===
 +
Did your TUFLOW SWMM model fail to run successfully? If so, here is a link to a troubleshooting guide: <u>[[TUFLOW_SWMM_Troubleshooting | TUFLOW SWMM Troubleshooting]]</u>.<br>
  
==== Export Data from XPSWMM====
+
= TUFLOW SWMM Result Viewing =
<ol>
+
Are you familiar with loading and viewing TUFLOW results in QGIS? If not, we strongly recommend self-registering and completing our free eLearning:
<li> In XPSWMM, select 'Hydraulics Mode' from the toolbar.
+
<u>[https://www.tuflow.com/training/training-catalogue/tt001e-introduction-to-qgis-for-tuflow-elearning/ Introduction to QGIS for TUFLOW]</u>. <br>
<br><br>
+
Our <u>[[TUFLOW_SWMM_Tutorial_Introduction | TUFLOW SWMM Tutorials]]</u> also demonstrate working with TUFLOW SWMM results.
[[File: XPSWMM_to_TUFLOW_toolbar_hydraulics_mode_01a.png|700px]]
 
<br>
 
<li> In the XPSWMM Layers panel, right click '''Nodes''' and select 'Export To GIS File...'. This will open a dialog.
 
<li> Select the GIS File: Click the '...' and navigate to the '''TUFLOW\model\swmm''' folder. Enter an appropriate filename and set the file type to ESRI (*.shp). For example, '''1D2D_Urban_Node_Export_001.shp'''
 
<li> Click 'Node Data and Results' to expand the folder tree. Go to Node Data and Results > Hydraulics Node > HDR Node Data. Double click to select the following items:
 
:* Node 2D Inflow Capture Flag
 
:* Ground Elevation (Spill Crest)
 
:* 2D Inflow Capture Coefficient
 
:* 2D Inflow Capture Exponent
 
<li> In the right-hand table, the items above, along with 'Node Name', 'Node X' and 'Node Y', should be selected.
 
<li> In the 'Custom Name' column, select each entry and shorten the text to less than 10 characters. For example, 'Node 2D Inflow Capture Flag' > 'NodeIn' and 'Ground Elevation (Spill Crest)' > 'Ground'.
 
<li> Click 'Export'. A message will appear reporting how many nodes were exported.  
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_04b.mp4|width=1350}}
 
<br>
 
</ol>
 
  
==== Convert Exported Data into TUFLOW SWMM Format ====
+
=Recommended Further Reading=
<ol>
+
For users who wish to get a better understanding of either 2D TUFLOW or 1D EPA SWMM, the following resources may be of use:<br>
<li> In Windows File Explorer, navigate to the '''TUFLOW\model\swmm''' folder. Drag and drop the node export .shp file into QGIS.
+
'''TUFLOW''': <u>[https://www.tuflow.com www.tuflow.com]</u>  
<li> In the QGIS Layers panel, select (left click) the node export layer.
+
*<u>[https://www.tuflow.com/downloads/#tuflow TUFLOW User Manual]</u>  
<li> In the Processing Toolbox, go to TUFLOW >> SWMM and select '<u>[[QGIS_SWMM_Convert_XPSWMM_GIS_Inlet_Layers_to_SWMM |Convert - XPSWMM GIS inlet layers to SWMM]]</u>'. This opens the dialog shown below.
+
*<u>[https://docs.tuflow.com/classic-hpc/release/2023-03-AD TUFLOW 2023-03-AD release notes]</u>  
:* GIS layer with inlet information: This is prepopulated as the node export layer is the active dataset.
+
*<u>[[Tutorial_Introduction#Tutorial_Modules | TUFLOW Tutorial Models]]</u>
:* Inlet name field: 'Node Name'
 
:* Inlet elevation field: 'Ground'
 
:* Inlet 2d capture flag field: 'NodeIn'
 
:* Inlet discharge equation coefficient field: 'Coeff'
 
:* Inlet discharge exponent field: 'Exponent'
 
:* Inlet connection width: This defines the number of 2D cells associated with the 1D/2D connections. Typically, this should match the 2D cell size of the model.
 
:* CRS: Select the models' Coordinate Reference System (CRS).
 
:* SWMM inp file (for inlet definition and curves):
 
<ol>
 
::<li> Click '...', and select 'Save to File...'.
 
::<li> Navigate to the '''TUFLOW\model\swmm''' folder. Choose an appropriate .inp file name. For example, '''swmm_inlet_curves_XP_001.inp'''. This tool will also create a .gpkg file with the same data and name; saved in the same file location, i.e. '''swmm_inlet_curves_XP_001.gpkg'''.
 
::<li> Click 'Save'.
 
</ol>
 
:* GeoPackage file for inlet usage:
 
<ol>
 
::<li> Click '...', and select 'Save to File...'.
 
::<li> Navigate to the '''TUFLOW\model\swmm''' folder. Choose an appropriate .gpkg file name. For example, '''swmm_iu_XP_001.gpkg'''.
 
::<li> Click 'Save'.
 
</ol>
 
<li> Click 'Run'. Once the tool is finished, click 'Close'.
 
<li> Remove the node export layer from the QGIS workspace.
 
<li> In Windows File Explorer, navigate to the '''TUFLOW\model\swmm''' folder. Drag and drop the two new GeoPackage databases (i.e. '''swmm_iu_XP_001.gpkg''' and '''swmm_inlet_curves_XP_001.gpkg''') into QGIS (hold Ctrl to select multiple). Inspect the attributes associated with the objects in both GeoPackages.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_05b.mp4|width=1350}}
 
<br>
 
</ol>
 
  
====Edit TUFLOW SWMM Data====
 
Unfortunately, the snapping tolerance set by XPSWMM for its Node GIS Data Export function is larger than the underlying model information it is associated with. This can cause a slight offset in the data. To rectify this issue, we will use a processing tool designed to assist in this task.
 
<ol>
 
<li> In the QGIS Layers panel, select (left click) the inlet usage layer (i.e. '''swmm_iu_XP_001''') 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 'Vector geometry' in the processing tool list and select 'Snap geometries to layer'. This opens the dialog shown below.
 
:* Reference Layer: '''Nodes--Junctions'''. This is the layer we want the inlet usage layer to snap to.
 
:* Tolerance: '0.1 meters'
 
:* Behavior: 'Prefer aligning nodes, insert extra vertices where required'
 
<li> Click 'Modify All Features'. Once the tool is finished, click 'Close'.
 
<li> Toggle off the editing for the inlet usage layer (i.e.'''swmm_iu_XP_001''') to save the edits.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_06b.mp4|width=1350}}
 
 
<br>
 
<br>
</ol>
+
'''EPA SWMM''': <u>[https://www.epa.gov/water-research/storm-water-management-model-swmm www.epa.gov]</u>
 +
*<u>[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume1_Hydrology_P100NYRA.pdf SWMM5 Reference Manual - Volume 1 (Hydrology)]</u>
 +
*<u>[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume2_Hydaulics_P100S9AS.pdf SWMM5 Reference Manual - Volume 2 (Hydraulics) ]</u>
 +
*<u>[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume2_Hydraulics_Addendum-20220210mas2wr.pdf  SWMM5 Reference Manual - Volume 2 (Hydraulics Addendum) ]</u>
 +
*<u>[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume3_Water_Quality_P100P2NY.pdf  SWMM5 Reference Manual - Volume 3 (Water Quality) ]</u>
 +
*<u>[https://downloads.tuflow.com/SWMM/SWMM5_User%27s_Manual.pdf EPA SWMM5 User's Manual]</u>
  
===Edit 1D/2D Culvert Connections===
+
=Feedback / Suggestions=
In addition to the pipe network inlet usage 1D/2D connections, we also need to connect the 1D culvert inlet/outlets to the 2D. These features are typically associated with culverts located under raised roads or rail embankments, outlets from pipe networks into creeks, streams, or rivers, or open pipe network inlets and outlets linked to major stormwater drainage infrastructure, which often involves the modification of historically above-ground streamflows to an underground stormwater network. An example is shown in the image below.<br>
+
We hope you have found this model conversion page helpful. If you have any feedback or suggestions, please email <u>[mailto::support@tuflow.com support@tuflow.com]</u>.
<br>
 
[[File: XPSWMM_Culvert_Inlet.JPG | 500px]]<br>
 
<br>
 
In order to connect a 1D SWMM culvert to TUFLOW 2D, TUFLOW SWMM necessitates 1D/2D HX connection lines at the upstream (inlet) end of the culvert and 1D/2D SX connection lines at the downstream (outlet) end. This model schematization differs from that of the TUFLOW ESTRY and XPSWMM, which require 1D/2D SX connections both upstream and downstream, but aligns with the traditional requirements of EPA SWMM.
 
<br>
 
[[File: 1D2D_Connections_Diagram.png | 300px]]
 
<br>
 
 
 
In the <u>[[#Convert_XPSWMM_Model_to_Recommended_TUFLOW_Structure | Convert XPSWMM Model to Recommended TUFLOW Structure]]</u> section, the XPSWMM 1D/2D connections were converted into TUFLOW format. However, since we have included and edited the SWMM data (HDR, inlet curves, and inlet usage GeoPackages), this connections layer needs to be updated. We need to change the upstream SX connections to HX connections, create new upstream CN lines, and ensure that the connections are snapped to the pipe network.
 
<ol>
 
<li> In the QGIS Layers panel, within the TBC group, select (left click) the 2d_bc lines layer (i.e. '''1D2D_Urban_001_2d_bc_L''') and toggle on editing. This layer contains the converted XPSWMM 1D/2D connections.
 
<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 'Vector geometry' in the processing tool list and select 'Snap geometries to layer'. This opens the dialog shown below.
 
:* Reference Layer: '''Links--Conduits'''. This is the layer we want the 2d_bc connections layer to snap to.
 
:* Tolerance: '0.1 meters'
 
:* Behavior: 'Snap end points to end points only'
 
<li> Click 'Modify All Features'. Once the tool is finished, click 'Close'.
 
<li> This tool has ensured that the 2d_bc connections layer is snapped to the pipe network.
 
<br><br>
 
{{Video|name=|width=1350}}
 
<br>
 
<li> In the top dropdown menu options, select View > Toolbars. Tick on 'Snapping Toolbar'.
 
<li> Select the 'Enable Snapping' [[File: snapping_icon.png]] and 'All Layers > Advanced Configuration', an eye icon appears.
 
<br><br>
 
[[File: snapping_toolbar_dropdown_menu.png | 500px]]
 
<br><br>
 
<li> Select the 'Edit Advanced Configuration' [[File: Advanced_config_icon.png | 30px]] and tick on the 2d_bc connections layer and the '''Links--Conduits''' layer.
 
<li> From the 'Digitizing Toolbar', use the 'Add Line Feature' tool to create a CN line to each upstream connection.
 
<li> Use the 'Identify Features' [[File: identify_features_icon.png | 30px]] tool to select an upstream 'SX' connection. A dialog will open.
 
<li> Change the 'Type' field to 'HX'.
 
<li> Repeat this for each upstream 'SX' connection.
 
<li> Toggle off editing for the 2d_bc connections layer to save the edits.
 
<br><br>
 
{{Video|name=|width=1350}}
 
<br>
 
</ol>
 
 
 
=== SWMM Hydrology ===
 
If the XPSWMM model includes EPA SWMM hydrology, the hydrology components can be brought across into TUFLOW SWMM.
 
 
 
First, to confirm the SWMM Hydrology runoff method has been used in the XPSWMM model, review the model settings. In XPSWMM, from the top dropdown menu options, go to Configuration > Mode Properties. Under 'Solve Mode', select 'Methods' Confirm 'SWMM Methods (64 bit)' is selected. <br>
 
 
<br>
 
<br>
[[File:XPSWMM_to_TUFLOW_swmm_hydrology_runoff_method_01b.png]]
 
<br><br>
 
  
Convert 1D XPSWMM hydraulics features into a EPA SWMM 5 INP file format for TUFLOW:
 
<ol>
 
<li> In XPSWMM, select 'Runoff Mode' from the toolbar.
 
<br><br>
 
[[File: XPSWMM_to_TUFLOW_toolbar_runoff_mode_01a.png|700px]]
 
<br>
 
<li> From the XPSWMM top dropdown menu options, select File > Import/Export Data > Export to EPASWMM 5. The exported INP file will be saved under the same name and in the same folder location as the .xp project file.
 
<li> When prompted to save changes, select 'Yes'.
 
<li> In QGIS, go to TUFLOW >> SWMM in the processing tool list and select '<u>[[QGIS_SWMM_GeoPackage_Create_from_SWMM_inp |GeoPackage - Create from SWMM inp ]]</u>'. This open the dialog shown below.
 
:* SWMM Input File (inp): Navigate to the folder location of the .xp project file and select the recently exported INP file.
 
:* CRS for GeoPackage: Select an appropriate Coordinate Reference System (CRS) for the model.
 
:* GeoPackage output filename: Navigate to the '''TUFLOW\model\swmm''' folder. Save the file with the same name as the SWMM input file, but append 'RNF' to the filename. For example '''1D2D_Urban_001.inp''' > '''1D2D_Urban_RNF_001.gpkg'''.
 
<li> Click 'Run'. Once the tool is finished, click 'Close'.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_08a.mp4|width=1350}}
 
<br>
 
<li> This tool has generated a '''Nodes--Junctions''' layer which is a duplicate of the '''Nodes--Junctions''' layer in the HDR GeoPackage. Thus, we will remove the RNF '''Nodes--Junctions''' layer.
 
<li> In QGIS, from the top dropdown menu options, select View > Panels. Tick on 'Browser Panel'.
 
<li> In the QGIS Browser Panel, navigate to the '''TUFLOW\model\swmm''' folder and open the RNF GeoPackage layer tree.
 
:'''Note:''' Within the QGIS Browser Panel, there is a dropdown directory, 'Project Home'. This directory is a shortcut to the location where the QGIS workspace is saved.
 
<li> Right click '''Nodes--Junctions''' and select Manage > Delete Layer.
 
<li> In Windows File Explorer, navigate to the '''TUFLOW\model\swmm''' folder. Drag and drop the RNF GeoPackage into QGIS.
 
<li> In the QGIS Layers panel, move the RNF GeoPackage below the other GeoPackages in the list. This will ensure the data within this database file does not cover the other layers in the project. <br>
 
'''Note:''' For hydrology, TUFLOW has more advanced, workflow efficient 'Event Scenario Management' options than XPSMM. If your project requires the simulation of multiple hydrology events, please complete <u>[[TUFLOW_SWMM_Tutorial_M04 | TUFLOW SWMM Module 4]]</u> and use the model design concepts in it to upgrade the configuration of your TUFLOW model to accommodate for the simulation of multiple events from a single model.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_09a.mp4|width=1350}}
 
<br>
 
</ol>
 
 
===Update SWMM Nodes--Junction Attributes===
 
The following GIS feature update to the '''Nodes--Junctions''' attributes will finalize the SWMM portion of the TUFLOW model. This is typically the final step in the model building process, as the recommended attributes for junction node vary depending on whether the node is associated with inlet usage connections, 1D/2D culvert connections and SWMM hydrology sub-catchments.
 
 
<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 the '<u>[[QGIS_SWMM_Junctions_Set_Attributes |Junctions - Set attributes ]]</u>' processing tool. This opens the dialog shown below.
 
:* Input Subcatchment layers: If available, select '''Hydrology--Subcatchments'''.
 
:* Input Inlet Usage Layers: If available, select the inlet usage layer (i.e. '''swmm_iu_XP_001''')
 
:* Input BC Connection Layers: If available, select the 2d_bc connection layer (i.e. '''1D2D_Urban_001_2d_bc_L''').
 
:* General Options:
 
:::* Maximum Depth Option (Ymax): 'Set to 0.0'.
 
:::* Nodes receiving subcatchment flows option (if connected to 2D): 'Set Apond = 0.0; Ksur = 0.0 (overwrites options below)'.
 
:* Nodes connected to 2D without Inlets:
 
:::* Ysur: 0
 
:::* Area of ponding: This value should match the 2D cell area associated with 1D/2D culvert connections.
 
:* Nodes connected to 2D with Inlets:
 
:::* Maximum depth (Ymax) option: 'Use global option'
 
:::* Ysur: 0
 
:::* Area of ponding: This value should match the 2D cell area associated with the Inlet Usage connections.
 
:* Nodes without 2D Connection:
 
:::* Surcharge Depth: This value should be a value higher than any expected water level in the model.
 
:::* Area of ponding: 1
 
<li>Select 'Modify All Features'. Once the tool has finished, click 'Close'.
 
<li>Turn off editing to save the edits.
 
<li>View the attributes within '''Nodes--Junctions''' to verify the data processing has been completed correctly. <br>
 
For a summary of the attributes associated with the '''Nodes--Junctions''' layer, refer to <u>[https://docs.tuflow.com/classic-hpc/release/2023-03-AD/SWMM-Input-Detailed-1.html#tab:tab-SWMM-Input-Junctions TUFLOW 2023-03-AD Release Notes (Table A.30)]</u> and the <u>[https://downloads.tuflow.com/SWMM/SWMM5_Reference_Manual_Volume2_Hydaulics_P100S9AS.pdf SWMM Reference Manual - Volume 2 (Hydraulics)]</u>.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_10a.mp4|width=1350}}
 
<br>
 
</ol>
 
 
===Export INP Files===
 
SWMM cannot directly read GeoPackage databases. Therefore, we need to convert all three GeoPackage files (HDR, RNF and inlet curves) into the SWMM INP file format. Both the HDR and RNF GeoPackages contain a '''Project--Options''' section, which are identical as they were extracted from the same XPSWMM model. These options are necessary for executing the SWMM simulation. Since '''Project--Options''' is already included in the HDR and RNF, it is not needed in the inlet curves INP file. <br>
 
'''Note:''' The inlet usage GeoPackage does not need to be converted to a SWMM inp file. Since it contains only one layer, it can be directly read into TUFLOW SWMM.
 
 
<ol>
 
<li> In QGIS, go to TUFLOW >> SWMM in the processing tool list and select '<u>[[QGIS_SWMM_GeoPackage_Write_to_SWMM_inp |GeoPackage - Write to SWMM inp]]</u>'.
 
<li> In the tool window, click the '...' and navigate to the '''TUFLOW\model\swmm''' folder. Select the HDR GeoPackage file.
 
<li> Click 'Run'.
 
<li> Once the tool has finished, click the 'Parameters' tab.
 
<li> Repeat steps 2 and 3 for the RNF and inlet curves GeoPackages.
 
<li> Once the tool has finished, click 'Close'.
 
<li> The three SWMM INP files will be located in the '''TUFLOW\model\swmm''' folder, with each file sharing the same filename as their respective GeoPackages. For example, '''1D2D_Urban_HDR_001.gpkg''' > '''1D2D_Urban_HDR_001.inp'''.
 
<br><br>
 
{{Video|name=Animation_XPtoTUFLOW_1D_model_11a.mp4|width=1350}}
 
<br>
 
</ol>
 
 
= Link 1D SWMM and 2D TUFLOW Model =
 
The linking between the 1D SWMM and the 2D TUFLOW model is established within the TUFLOW control files, which are essential for running TUFLOW-SWMM simulations. The following steps outline the basic commands needed to complete the linking process and execute the model. These commands may need to be modified depending on the modeling task.
 
 
== Model Projection ==
 
 
 
 
== Simulation Control Files ==
 
The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its configuration information refer to <u>[[NotepadPlusPlus_Tips | Notepad++ Tips]]</u>. For a clean and organized model, it is recommended to name all the TUFLOW control files similarly. For example, '''1D2D_Urban_001.tscf''', '''1D2D_Urban_001.tbc''', '''1D2D_Urban_001.tgc''' and '''1D2D_Urban_5m_001.tcf'''. <br>
 
 
'''Note:''' For this demonstration, all commands will reference the datasets in the provided conversion model. Please update these references with the filenames sued in your model.<br>
 
<br>
 
 
=== TUFLOW SWMM Control File (TSCF) ===
 
The TUFLOW SWMM Control File (TSCF) is used to control the SWMM input data flow. All 1D SWMM files and commands are referenced in the TUFLOW SWMM Control File.<br>
 
<ol>
 
<li> In Windows File Explorer, navigate to the '''TUFLOW\model''' folder and create a new blank text file with the extension .tscf.
 
<li> Open the TSCF into a Text Editor (Notepad++ is recommended) and add the following commands.<br>
 
<font color="blue"><tt>Read SWMM </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\swmm\1D2D_Urban_HDR_001.inp </tt></font> <font color="green"><tt> ! 1D SWMM Pipe Network input file</tt></font><br>
 
<font color="blue"><tt>Read SWMM </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\swmm\1D2D_Urban_RNF_001.inp </tt></font> <font color="green"><tt> ! 1D SWMM Hydrology input file</tt></font><br>
 
<font color="blue"><tt>Read SWMM </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\swmm\swmm_inlet_curves_XP_001.inp </tt></font> <font color="green"><tt> ! 1D SWMM Inlet Curves input file</tt></font><br>
 
<font color="blue"><tt>Read GIS SWMM Inlet Usage</tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\swmm\swmm_iu_XP_001.gpkg >> inlet_usage </tt></font> <font color="green"><tt> ! 1D SWMM Pipe Network Inlet Usage layer</tt></font>
 
<br><br>
 
'''<<Video>>'''
 
<br>
 
</ol>
 
 
=== TUFLOW Boundary Control File (TBC) ===
 
The TUFLOW Boundary Control File (TBC) contains information regarding the location of boundary conditions and internal links within the model.
 
<ol>
 
<li> In Windows File Explorer, navigate to the '''TUFLOW\model''' folder and open the TBC into a text editor (Notepad++ is recommended).
 
<li> Remove the reference to the 2d_bc points layer. This layer was removed from the model GeoPackage in the <u>[[#Export_1D_EPA_SWMM_Pipe_Network_Data_from_XPSWMM |Export 1D EPA SWMM Pipe Network Data from XPSWMM]]</u> section.
 
<li> The TBC should reference the 2D boundary condition layer and the 1D/2D connection layer. In this case, they are both included in the 2d_bc connections layer. <br>
 
<font color="blue"><tt>Read GIS BC </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>1D2D_Urban_001_2d_bc_L </tt></font> <font color="green"><tt> ! Reads in 2D boundaries and links 1D SWMM culverts to the 2D TUFLOW domain</tt></font><br>
 
<br>
 
'''<font color="red">Video</font>'''
 
</ol>
 
 
=== TUFLOW Geometry Control File (TGC) ===
 
The TUFLOW Geometry Control File (TGC) contains 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.
 
<br>
 
The TGC requires no updates; however, it is recommended to review the TGC before running the simulation to ensure all commands are correct.
 
<br><br>
 
 
=== TUFLOW Control File (TCF) ===
 
The TCF file references all the control files, specifies time and output controls.<br>
 
 
In the <u>[[#Convert_XPSWMM_Model_to_Recommended_TUFLOW_Structure | Convert XPSWMM Model to Recommended TUFLOW Structure]]</u> section, the <u>[[Convert_TUFLOW_Model_GIS_Format |Convert TUFLOW Model GIS Format]]</u> processing tool utilizes the TUFLOW control files generated by XPSWMM to construct the TUFLOW SWMM model control files. During this process, the tool updates the commands within the TUFLOW control files to align with the requirements of a TUFLOW SWMM model. However, since the original control files were intended for use with XPSWMM, they lack the commands required to execute a TUFLOW simulation. Additionally, these files often contain unnecessary and/or outdated commands.<br>
 
 
In the section above, the TBC was edited to reflect the model updates implemented during the conversion process, while no updates were necessary for the TGC. However, the TCF requires updating to ensure the TUFLOW SWMM model runs smoothly.
 
<ol>
 
<li> Remove or comment out the commands listed below.
 
{|
 
|style="width: 50%"| <font color="blue"><tt>Check MI Save Date </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>Mass Balance Output Interval (s) </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>MI Projection </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>CSV Time </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>MI Projection Check </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>Viscosity Formulation </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>Timestep (s) </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>Viscosity Coefficient </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>Cell Wet/Dry Depth </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>SX ZC Check </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>Read GIS XP Nodes </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>SX Storage Approach </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>Simulations Log Folder </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>HX ZC Check </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>Store Maximums and Minimums </tt></font> <font color="red"><tt>== </tt></font>
 
|<font color="blue"><tt>Mass Balance Corrector </tt></font> <font color="red"><tt>== </tt></font>
 
|-
 
|<font color="blue"><tt>Mass Balance Output </tt></font> <font color="red"><tt>== </tt></font>
 
|}
 
<li> Make the following updates:
 
{|class="wikitable"
 
! Original Command
 
! Updated Command
 
|-
 
|<font color="blue"><tt>GPKG Projection </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>1D2D_Urban_001_proj</tt></font>
 
|<font color="blue"><tt>GPKG Projection </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>??</tt></font>
 
|-
 
|<font color="blue"><tt>Write Check Files </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>OFF</tt></font>
 
|<font color="blue"><tt>Write Check Files </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\check\</tt></font>
 
|-
 
|<font color="blue"><tt>Output Folder </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\results\Output </tt></font>
 
|<font color="blue"><tt>Output Folder </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\results\</tt></font>
 
|-
 
|<font color="blue"><tt>Log Folder </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>log\Log </tt></font>
 
|<font color="blue"><tt>Output Folder </tt></font> <font color="red"><tt>== </tt></font> <font color="blue"><tt>log</tt></font>
 
|-
 
|<font color="blue"><tt>Map Output Data Types </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>qVdhZ0 </tt></font>
 
|<font color="blue"><tt>Map Output Data Types </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>q V d h Z0</tt></font>
 
|-
 
|<font color="blue"><tt>Map Output Format </tt></font> <font color="red"><tt>== </tt></font> <font color="blue"><tt>XMDF </tt></font>
 
|<font color="blue"><tt>Map Output Format </tt></font> <font color="red"><tt>== </tt></font> <font color="blue"><tt>XMDF TIF</tt></font>
 
|}
 
<li> Add the following commands:<br>
 
<font color="blue"><tt>Tutorial Model </tt></font> <font color="red"><tt>== </tt></font> <font color="blue"><tt>ON </tt></font> <font color="green"><tt> ! Required command to run this tutorial model licence free</tt></font><br>
 
<font color="blue"><tt>GIS Format </tt></font> <font color="red"><tt>== </tt></font> <font color="blue"><tt>GPKG </tt></font> <font color="green"><tt> ! Specify GPKG as the output format for all GIS files</tt></font><br>
 
<font color="blue"><tt>Solution Scheme </tt></font> <font color="red"><tt>== </tt></font> <font color="blue"><tt>HPC </tt></font> <font color="green"><tt> ! Heavily Parallelised Compute, uses adaptive timestepping</tt></font><br>
 
<font color="blue"><tt>Hardware </tt></font> <font color="red"><tt>== </tt></font> <font color="blue"><tt>CPU </tt></font> <font color="green"><tt> ! Replace with "Hardware == GPU" if GPU available </tt></font><br>
 
<font color="blue"><tt>Start Time </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>0 </tt></font> <font color="green"><tt> ! Specifies the simulation start time (0 hours) </tt></font><br>
 
<font color="blue"><tt>End Time </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>3 </tt></font> <font color="green"><tt> ! Specifies the simulation end time (3 hours)</tt></font><br>
 
<font color="blue"><tt>TIF Map Output Interval </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>0 </tt></font> <font color="green"><tt> ! Outputs only maximums for grids</tt></font><br>
 
<li> Add the following command to reference the TUFLOW SWMM Control File (TSCF):<br>
 
<font color="blue"><tt>SWMM Control File </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt>..\model\1D2D_Urban_001.tscf</tt></font>
 
<li> Save the TCF.
 
<br><br>
 
'''<font color="red> Video </font>'''
 
<br>
 
</ol>
 
 
=== Optional: Format TUFLOW Control Files ===
 
In the sections above, we removed unnecessary commands from the TUFLOW control files and introduced additional commands to ensure the TUFLOW SWMM model runs smoothly. In this section, we will format and organize the TUFLOW control files to enhance readability, thereby improving the overall functionality of the model. This can be done by:
 
:* Using relative file paths to specify the location of various files and layers in the model.
 
:* Including a title at the beginning of each control file. For example, <font color="green"><tt>! TUFLOW CONTROL FILE (.TCF) defines the model simulation parameters and directs input from other data sources</tt></font>.
 
:* Adding headings to sections of the control file. For example, <font color="green"><tt>! MODEL INITIALIZATION</tt></font> could be used as a header for the commands required to initialize the TUFLOW SWMM model.
 
:* Utilizing comments to explain the purpose of commands. For example, <font color="blue"><tt>Spatial Database </tt></font> <font color="red"><tt>== </tt></font> <font color="black"><tt> ..\model\gis\1D2D_Urban_001.gpkg </tt></font> <font color="green"><tt> ! Specify the location of the GeoPackage Spatial Database</tt></font>.<br>
 
<br>
 
If using the provided model conversion dataset, the final Control files should look like this:<br>
 
'''<font color="red"> insert images when dataset finalised </font>'''
 
<br>
 
 
=Converted Dataset=
 
After completing the model conversion steps outlined above, you can download the converted TUFLOW SWMM model dataset using the following link: '''<<link>>'''
 
This dataset includes both the original XPSWMM model and the converted TUFLOW model. We recommend checking your converted TUFLOW model against the provided one to ensure all conversion steps were completed correctly.
 
<br>
 
<br>
 
 
=Feedback / Suggestions=
 
If you have any suggestions to be included in these pages, please email <u>[mailto::support@tuflow.com support@tuflow.com]</u>.
 
  
  
 
{{Tips Navigation
 
{{Tips Navigation
|uplink=[[Main_Page| Back to Main Page]]
+
|uplink=[[Main_Page| Back to Wiki Main Page]]
 
}}
 
}}

Revision as of 16:03, 27 February 2024

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. TUFLOW is the natural replacement for XPSWMM for people who are looking for an alternative solution following Autodesk's recent XPSWMM pricing, licensing, and support changes.

Common user feedback suggests the XPSWMM GUI is useful for simple modeling projects; however, it can become cumbersome and workflow inefficient when dealing with larger datasets and/or a large volume of different scenario and event simulations. In response to requests from USA XPSWMM users who want to convert XPSWMM models into a native TUFLOW format, TUFLOW linkage with 1D EPA Storm Water Management Model (SWMM) was added as a supported feature in TUFLOW 2023-03-AD release. The modeling workflow in TUFLOW differs from XPSWMM, as TUFLOW modeling is integrated with QGIS (Geographical Information System) GIS software. This is, however, a net positive. GIS integration is well-suited for working with larger datasets. Additionally, the structural design associated with TUFLOW modeling makes its general workflow extremely efficient, particularly for the automated management of multiple scenarios and events.

If you are building a TUFLOW SWMM model from scratch, not from XPSWMM, please refer to the TUFLOW SWMM Tutorials. Tutorials are provided for the following topics:

Dataset Download

The XPSWMM model used for this model conversion demonstration, and the resulting TUFLOW model that is created, are available for download here: XPSWMM to TUFLOW Model Conversion Dataset. The models are found in the XPSWMM and TUFLOW 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.

TUFLOW Licensing / XPSWMM Discount

If you are an existing or past XPSWMM perpetual license owner who would like to purchase a TUFLOW license, please contact sales@tuflow.com. You may be eligible for a XPSWMM / TUFLOW discount in recognition of past royalties Autodesk paid TUFLOW if you previously purchased an XPSWMM perpetual license.

XPSWMM to TUFLOW Model Conversion

Two Dimensional (2D) Model Elements

XPSWMM writes TUFLOW model files during its preprocessing of the model inputs defined in its GUI (prior to the hydraulic calculations). By default, XPSWMM usually writes the TUFLOW files to the 2D\Data folder. For use by TUFLOW, some 2D model elements within the XPSWMM model must be exported and formatted. To accomplish this, please follow the links provided below:

  1. Digital Terrain Model (DTM) Data Processing
  2. Convert XPSWMM Model to Recommended TUFLOW Structure
  3. Load Model in QGIS

One Dimensional (1D) SWMM Model Elements

The 1D culvert, pipe network, and sub-catchment hydrology EPA SWMM items from XPSWMM require exporting and reconfiguring for compatibility with TUFLOW. Please follow the suggested workflow and instructions provided in the links below:

  1. Export 1D EPA SWMM Pipe Network Data from XPSWMM
  2. Configure 1D EPA SWMM Pipe Network Data for TUFLOW
  3. Export SWMM Hydrology
  4. Update SWMM Junction Data
  5. Export Updated SWMM INP Files

TUFLOW Control Files Updates

The linking between 2D TUFLOW and 1D SWMM is established within the TUFLOW control files. The following sections (linked below) outline the basic commands needed to complete the linking process and execute the model. These tasks require the use of a text editor. The tutorial demonstration uses Notepad++. For configuration information, refer to Notepad++ Tips. For a clean and organized model, it is recommended to name all the TUFLOW control files similarly. For example, 1D2D_Urban_001.tscf, 1D2D_Urban_001.tbc, 1D2D_Urban_001.tgc, and 1D2D_Urban_5m_001.tcf.

Note: For this demonstration, all commands will reference the datasets in the provided conversion model. Please update these references with the filenames used in your model if you are using these steps as a guide to convert your own XPSWMM model to TUFLOW.

  1. TUFLOW SWMM Control File (TSCF)
  2. TUFLOW Boundary Control File (TBC)
  3. TUFLOW Geometry Control File (TGC)
  4. TUFLOW Control File (TCF)
  5. Optional: Format TUFLOW Control Files

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.

  1. Create a new text file in the TUFLOW\runs folder and save as _run_HPC.bat.
  2. Open the _run_HPC.bat in a text editor and include a file path to the TUFLOW executable and the TCF name:
    "..\..\exe\2023-03-AD\TUFLOW_iSP_w64.exe" 1D2D_Urban_001.tcf
    Note: A relative path is used for the executable and the TCF, full file path can also be used.
  3. Save the batch file and double click it in Windows File Explorer to run the simulation. This will open the TUFLOW DOS Console Window and the simulation should be executed.

TUFLOW simulations can be executed via numerous ways. A comprehensive summary of the most commonly used approaches is documented in the 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 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: Introduction to QGIS for TUFLOW.
Our 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: www.tuflow.com


EPA SWMM: www.epa.gov

Feedback / Suggestions

We hope you have found this model conversion page helpful. If you have any feedback or suggestions, please email support@tuflow.com.


Up
Go-up.png Back to Wiki Main Page