Difference between revisions of "XPSWMM to TUFLOW-SWMM"

From Tuflow
Jump to navigation Jump to search
 
(84 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.
 
 
 
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.
 
  
 +
XPSWMM is a flood and urban stormwater drainage modeling software developed by Autodesk (previously Innovyze and XP Solutions). The XPSWMM solution uses EPA SWMM for its 1D calculations, dynamically linked to TUFLOW for its 2D calculations. The software functions within a custom build Graphical User Interface (GUI). Unknown to many XPSWMM modelers, during simulation, XPSWMM processes its inputs into TUFLOW files and also calls TUFLOW for the 2D calculations. As XPSWMM uses TUFLOW for its 2D engine, like-for-like results can be achieved using this software. The modeling workflow in TUFLOW differs from XPSWMM, as TUFLOW modeling is integrated with QGIS (Geographical Information System) GIS software instead of embedded within a software specific Graphical User Interface.
  
 
If you are building a TUFLOW SWMM model from scratch, not from XPSWMM, please refer to the <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 9:
 
* <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 ==
 
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>
 
<br>
 
  
 
== Dataset Download ==
 
== Dataset Download ==
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>
+
The dataset used for this model conversion demonstration is available for download here: <u>[https://downloads.tuflow.com/SWMM/XPSWMM_XPX_to_TUFLOW_Conversion.zip XPSWMM XPX to TUFLOW Conversion Dataset]</u>. <br>
 +
This dataset contains the XPSWMM model and the resulting TUFLOW model that is created. These can be found in the '''XPSWMM''' and '''Complete_Conversion''' folders respectively. <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.
+
'''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>
<br>
 
<br>
 
  
= XPSWMM to TUFLOW Model Conversion=
+
If you do not have access to a XPSWMM license and the XPSWMM Application, please refer to the <u>[[XPSWMM_to_TUFLOW-SWMM_Troubleshooting#Model_Conversion_Without_a_XPSWMM_License |XPSWMM to TUFLOW SWMM Troubleshooting]]</u> page. <br>
== 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 to TUFLOW Model Conversion =
 +
== Export Data From XPSWMM Model ==
 +
'''Digital Terrain Model (DTM) Data'''<br>
 +
XPSWMM reads its 2D DTM data in one of two ways:
 +
* The DTM data can be directly specified in the '2D Model Settings', or
 +
* The DTM data can be internally processed by XPSWMM using its terrain tools and DTM builder.
 +
Depending on which method is applied to your XPSWMM model, the steps required to will vary. Review which method is used:
 
<ol>
 
<ol>
<li> <u>[[XPSWMM_Conversion_DTM | Digital Terrain Model (DTM) Data Processing]]</u>
+
<li> Open your existing model in XPSWMM.
<li> <u>[[XPSWMM_Conversion_TUFLOW_Structure | Convert XPSWMM Model to Recommended TUFLOW Structure]]</u>
+
<li> In the top dropdown menu options, go to Configuration > Job Control > 2D Model Settings. This will open a dialog.
<li> <u>[[XPSWMM_Conversion_Load_TUFLOW_Model | Load Model in QGIS]]</u>
+
<li> Under '2D Hydraulics Job Control', select 'Surface & Sampling'.
 +
<li> Review the options in the 'Surface' section:
 +
:* If 'Use DTM' is selected: Continue to the section below (<u>[[XPSWMM_to_TUFLOW-SWMM#Export_DTM_Data_from_XPSWMM |Export DTM Data from XPSWMM]]</u>) and complete the steps.
 +
:* If 'Use Grid File for Topography' is selected and a 'Grid file' is specified, the steps outlined in the 'Export DTM Data From XPSWMM' section can be skipped. Go to the <u>[[XPSWMM_to_TUFLOW-SWMM#Export_XPX_Data_From_XPSWMM|Export XPX Data From XPSWMM]]</u> section.
 +
'''Note:''' If you have a .tif elevation file, you can continue to the <u>[[XPSWMM_to_TUFLOW-SWMM#Export_XPX_Data_From_XPSWMM|Export XPX Data From XPSWMM]]</u> section. The conversion process will be identical however, once converted, you will have to create the '''TUFLOW\model\grid''' folder manually and copy the .tif file into it.
 +
<br><br>
 +
{{Video|name=Animation_XPtoTUFLOW_Export_Data_01b.mp4|width=1350}}
 +
<br>
 
</ol>
 
</ol>
  
== One Dimensional (1D) SWMM Model Elements ==
+
=== Export DTM Data From XPSWMM ===
The 1D culvert, pipe network and sub-catchment hydrology EPA SWMM items in the XPSWMM model need to be exported from the software and reconfigured for use by TUFLOW. Please follow the suggested workflow and instructions outlined below:
+
If 'Use DTM' was selected, XPSWMM preprocesses its Digital Terrain Model (DTM) into a binary XPTIN elevation dataset for inclusion in the TUFLOW model. XPTIN is a binary format that can't readily be used in GIS software. For this reason, the following steps outline how to obtain a DTM dataset in a GIS friendly form.
 
 
 
<ol>
 
<ol>
<li> <u>[[XPSWMM_Conversion_Export_SWMM_Pipe_Network_Data | Export 1D EPA SWMM Pipe Network Data from XPSWMM]]</u>
+
<li> In the XPSWMM Layers panel, under 'Topography', right click on '''DTM''' and select 'Export DTM Data'.
<li> <u>[[XPSWMM_Conversion_Reconfigure_SWMM_Pipe_Network_Data | Configure 1D EPA SWMM Pipe Network Data for TUFLOW]]</u>
+
:* Input TIN File: Select the relevant XPSWMM Input TIN file.
<li> <u>[[XPSWMM_Conversion_Export_SWMM_Hydrology | Export SWMM Hydrology]]</u>
+
:* Output File Format: 'ASCII Grid File Format'.
<li> <u>[[XPSWMM_Conversion_Reconfigure_SWMM_Junctions | Update SWMM Junction Data]]</u>
+
:* Cell Size Value: Choose a suitable DTM resolution. This resolution should be finer than the hydraulic model resolution. Typically, a DTM resolution is 1/5th to 1/10th of the hydraulic model 2D cell size is common (1 in the example dataset).
<li> <u>[[XPSWMM_Conversion_Export_SWMM_INP | Export Update SWMM INP Files]]</u>
+
''Note: XPSWMM requires an integer cell size value for this export step. For example, Cell Size Values of 1, 2, 3, 4, 5 ... are suitable. The XPSWMM export will not function if you specify a decimal cell size value (eg. 0.5, 2.5, etc.).'' 
</ol>
+
<li> Click 'Export'.
 +
<li> Save the file under an appropriate name (e.g. '''1D2D_Urban_Grid.asc''') to the folder where XPSWMM writes the .tcf during its simulation preprocessing. By default, this is the '''2D\Data''' folder. <br>
 +
If this folder does not exist, either:
 +
:* The XPSWMM model has not run, so the TUFLOW control files have not been created by XPSWMM. Run the XPSWMM model (go to Analyze > Solve... in top dropdown menu options).
 +
:* Non-default output settings have been specified in XPSWMM. To determine the output location, in the top dropdown menu options, go to Configuration > Job Control > 2D Model Settings > Folder Options. Ensure the following 'Folder Locations' are selected.
 +
::[[File: XPSWMM_to_TUFLOW_2DJobControl_FolderOptions_Dialog_01e.png]]<br><br>
  
 
+
<li> In the top dropdown menu options, navigate to  Configuration > Job Control > 2D Model Settings. This will open a dialog, under '2D Hydraulics Job Control', select 'Surface & Sampling'.
 
+
<li> Tick on 'Use grid file for topography' and select '...' to navigate to the Grid file saved in the '''2D\Data''' folder. This file will be read directly into TUFLOW.  
 
+
<li> Click 'OK' to save the settings.
 
+
<li> Run the XPSWMM model to rewrite the TUFLOW files (including the new linkage to the DTM dataset) to the Data folder (go to Analyze > Solve... in top dropdown menu options).
 
+
<br><br>
 
+
{{Video|name=Animation_XPtoTUFLOW_Export_Data_02b.mp4|width=1350}}
=== 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]]
+
</ol>
<br><br>
 
  
Convert 1D XPSWMM hydraulics features into a EPA SWMM 5 INP file format for TUFLOW:
+
=== Export XPX Data From XPSWMM ===
 +
A XPX file is a simple command line file that contains the information needed to create link and node objects. To export this data from the XPSWMM model:
 
<ol>
 
<ol>
<li> In XPSWMM, select 'Runoff Mode' from the toolbar.
+
<li> In XPSWMM, in the top dropdown menu options, navigate to File > Import/Export Data > Export XPX Data. This will open a dialog. Leave all options as default and click 'Export'.
<br><br>
+
<li> When prompted, save the file under an appropriate name (eg '''1D2D_Urban_001.xpx''') to the folder where the XPSWMM model is located.
[[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>
 
<br><br>
{{Video|name=Animation_XPtoTUFLOW_1D_model_08a.mp4|width=1350}}
+
{{Video|name=Animation_XPtoTUFLOW_Export_Data_03b.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>
 
<br>
 
</ol>
 
</ol>
  
===Update SWMM Nodes--Junction Attributes===
+
== Convert XPSWMM Model to TUFLOW SWMM ==
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.  
+
Ensure you have QGIS and have the QGIS TUFLOW Plugin 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>.
 +
 
 +
The following steps outline the process of converting a XPSWMM model to TUFLOW SWMM using the '<u>[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]</u>' processing tool.
  
 
<ol>
 
<ol>
<li> In the QGIS Layers panel, select (left click) '''Nodes--Junctions''' and toggle on editing.
+
<li> Open QGIS and go to Processing > Toolbox from the top dropdown menu options to open the Processing Toolbox.
<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 '<u>[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]</u>'. This opens the dialog shown below.
<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.
+
:* XPSWMM Exported XPX File: Click '...' and navigate to the exported XPX data (e.g. '''1D2D_Urban_001.xpx'''). This should be located in the same folder as the XPSWMM model.  
:* Input Subcatchment layers: If available, select '''Hydrology--Subcatchments'''.
+
:* TUFLOW TCF Filename: Click '...' and navigate to the XPSWMM .tcf. This should be located in the '''2D\Data''' folder (e.g. '''2D\Data >> 1D2D_Urban_001.tcf''').
:* Input Inlet Usage Layers: If available, select the inlet usage layer (i.e. '''swmm_iu_XP_001''')
+
:* SWMM File Prefix: Choose an appropriate prefix for the SWMM files (e.g. '''1D2D_Urban_swmm''').
:* Input BC Connection Layers: If available, select the 2d_bc connection layer (i.e. '''1D2D_Urban_001_2d_bc_L''').
+
:* Output Solution Scheme: 'HPC'
:* General Options:  
+
:* Output Hardware Specification: 'GPU' (if GPU is not available, select 'CPU')
:::* Maximum Depth Option (Ymax): 'Set to 0.0'.
+
:* Output Vector Format: 'GPKG'
:::* Nodes receiving subcatchment flows option (if connected to 2D): 'Set Apond = 0.0; Ksur = 0.0 (overwrites options below)'.
+
:* Output Raster Format: 'GTIFF'
:* Nodes connected to 2D without Inlets:
+
:* 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>.
:::* Ysur: 0
+
:* Event name if no global storms: Choose an appropriate event name if applicable (100yr in the example dataset).
:::* Area of ponding: This value should match the 2D cell area associated with 1D/2D culvert connections.
+
:* BC width for created 1D/2D connections (HX/SX): This value should be approximately 2 times the width of the hydraulic model 2D cell size (10 in the example dataset).
:* Nodes connected to 2D with Inlets:
+
:* BC offset distance for created 1D/2D connections (HX/SX): Distance from the channel endpoint to the midpoint of the BC line (2 in the example dataset).
:::* Maximum depth (Ymax) option: 'Use global option'
+
:* 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.
:::* Ysur: 0
+
:* Output CRS: Select an appropriate Coordinate Reference System (CRS) for the model. For the demonstration model, the CRS is 'EPSG:32760 - WGS 84 / UTM zone 60S'.
:::* Area of ponding: This value should match the 2D cell area associated with the Inlet Usage connections.
+
<li> Click 'Run'. Once the tool is finished, click 'Close'.
:* 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>
 
<br><br>
{{Video|name=Animation_XPtoTUFLOW_1D_model_10a.mp4|width=1350}}
+
{{Video|name=Animation_XPtoTUFLOW_Convert_01c.mp4|width=1350}}
 
<br>
 
<br>
 
</ol>
 
</ol>
  
===Export INP Files===
+
Inspect the output of the '<u>[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]</u>' processing tool and load the TUFLOW model into QGIS:
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>
 
<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 Windows File Explorer, inspect the files output by the processing tool. In particular:
<li> In the tool window, select 'Run as Batch Process...' (located at the bottom left). This feature allows us to convert multiple GeoPackages to SWMM inp files in one go.
+
* The '''TUFLOW\bc_dbase''' folder contains the BC Database which will contain any curves used in BC conditions, for easy extending to other events.
<li> Under 'GeoPackage Input File', click '...' and navigate to the '''TUFLOW\model\swmm''' folder. Select the HDR GeoPackage file.
+
* The '''TUFLOW\model''' folder contains the TUFLOW SWMM Control File (TSCF) which holds all commands specific to SWMM, including links to the converted SWMM INP file.
<li> Click the plus icon
+
* The '''TUFLOW\model\swmm''' folder contains a GeoPackage database ('''*_convert_messages.gpkg'''). This GeoPackage contains locations and descriptions of any errors or warnings that occurred during the conversion process.
<li> Click 'Run'.  
+
: '''Note:''' Conversion messages are addressed in further detail here <u>[[XPSWMM_to_TUFLOW-SWMM_Troubleshooting#Common_Conversion_Issues |XPSWMM to TUFLOW SWMM Troubleshooting]]</u>.
<li> Once the tool has finished, click the 'Parameters' tab.
+
* The '''TUFLOW\runs''' folder contains the TCF. If event(s) are specified, the TCF filename with have event placeholder(s), i.e. '_~e1~_~e2~_' (e.g. '''1D2D_Urban_001_~e1~.tcf'''). Again, if event(s) are used, this folder also contains the TUFLOW Event File (TEF) with the event(s) specified. <br>
<li> Repeat steps 2 and 3 for the RNF and inlet curves GeoPackages.
+
{{Video|name=Animation_XPtoTUFLOW_Convert_02b.mp4|width=800}}
<li> Once the tool has finished, click 'Close'.
+
<br>
<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'''.
+
<li> Open QGIS, and click on the ‘Load TUFLOW Layers from TCF’ symbol from the QGIS TUFLOW Plugin toolbar.
 +
<br>
 +
[[File: Tuflow_plugin_load_tcf_layers.png]]<br>
 +
<br>
 +
<li> Navigate to the location of the TUFLOW model and go to the '''TUFLOW\runs''' folder. Select the TCF.
 +
<li> In the Load Layers window, select:
 +
* Ordering Options: Alphabetical
 +
* Grouping Options: Group by control file
 +
* Raster Load Options: Load Normally
 +
<li> Click ‘Open’ and ‘OK’.
 +
<li> Change the symbology of the DTM dataset:
 +
* In the QGIS Layers panel, right click on the DTM Grid file and select 'Properties'.
 +
* In the Symbology tab, under 'Band Rendering', set the 'Render type' to 'Hillshade' and the 'Z Factor' to 3.
 +
<li> Inspect the output GIS layers.
 
<br><br>
 
<br><br>
{{Video|name=Animation_XPtoTUFLOW_1D_model_11a.mp4|width=1350}}
+
{{Video|name=Animation_XPtoTUFLOW_Convert_03b.mp4|width=1350}}
 
<br>
 
<br>
 
</ol>
 
</ol>
  
= Link 1D SWMM and 2D TUFLOW Model =
+
== Recommended Additional Conversion Steps ==  
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.
+
While the bulk of the XPSWMM to TUFLOW SWMM model conversion is automated by the '<u>[[QGIS_SWMM_Convert_XPSWMM_Model_From_XPX|Convert - XPSWMM model from XPX]]</u>' processing tool, some required or recommended conventions must be implemented/updated manually. Therefore, it is highly recommended to complete the additional conversion steps: <u>[[XPSWMM_to_TUFLOW-SWMM_Recommended_Additional_Conversion_Steps|Recommended Additional Conversion Steps]]</u>. <br>  
 
+
These steps can help improve model stability and they may also be helpful to address any messages that occurred when using the conversion tool.  
== 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>
 
<br>
  
=== TUFLOW SWMM Control File (TSCF) ===
+
== TUFLOW Simulation Execution ==
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>
+
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 Windows File Explorer, navigate to the '''TUFLOW\model''' folder and create a new blank text file with the extension .tscf.
+
<li>Create a new text file in the '''TUFLOW\runs''' folder and save as '''_run_HPC.bat'''.  
<li> Open the TSCF into a Text Editor (Notepad++ is recommended) and add the following commands.<br>
+
<li>Open the '''_run_HPC.bat''' in a text editor and include a file path to the TUFLOW executable and the TCF name: <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>set </font>exe<font color="red">=</font>"..\..\exe\2023-03-AD\TUFLOW_iSP_w64.exe"<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>set </font>run<font color="red">=</font>start "TUFLOW" /wait <font color="orange">%exe%</font> -b<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="orange">%run%</font> -e1 100yr 1D2D_Urban_001_~e1~.tcf</tt></font></tt> <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>
 
<br>
 +
'''Note:''' A relative path is used for the executable and the TCF, full file path can also be used.
 +
<li>Save the batch file and double click it in Windows File Explorer to run the simulation. This will open the TUFLOW DOS Console Window and the simulation should be executed.
 
</ol>
 
</ol>
  
=== TUFLOW Boundary Control File (TBC) ===
+
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.
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) ===
+
=== Troubleshooting ===
The TUFLOW Geometry Control File (TGC) contains a series of commands that build the geometry model. At its minimum, the TGC contains:
+
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>
:* 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) ===
+
= TUFLOW SWMM Result Viewing =
The TCF file references all the control files, specifies time and output controls.<br>
+
Are you familiar with loading and viewing TUFLOW results in QGIS? If not, we strongly recommend self-registering and completing our free eLearning:
 +
<u>[https://www.tuflow.com/training/training-catalogue/tt001e-introduction-to-qgis-for-tuflow-elearning/ Introduction to QGIS for TUFLOW]</u>. <br>
 +
Our <u>[[TUFLOW_SWMM_Tutorial_Introduction | TUFLOW SWMM Tutorials]]</u> also demonstrate working with TUFLOW SWMM results.
  
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>
+
= 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:<br>
 +
'''TUFLOW''': <u>[https://www.tuflow.com www.tuflow.com]</u>
 +
*<u>[https://www.tuflow.com/downloads/#tuflow TUFLOW User Manual]</u>
 +
*<u>[https://docs.tuflow.com/classic-hpc/release/2023-03-AD/ TUFLOW 2023-03-AD release notes]</u>  
 +
*<u>[[Tutorial_Introduction#Tutorial_Modules | TUFLOW Tutorial Models]]</u>
  
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>
 
<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>
  
=== Optional: Format TUFLOW Control Files ===
+
=Feedback / Suggestions=
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:
+
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>.
:* 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>
 
<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]]
 
}}
 
}}

Latest revision as of 10:16, 6 September 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. The modeling workflow in TUFLOW differs from XPSWMM, as TUFLOW modeling is integrated with QGIS (Geographical Information System) GIS software instead of embedded within a software specific Graphical User Interface.

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

Dataset Download

The dataset used for this model conversion demonstration is available for download here: XPSWMM XPX to TUFLOW Conversion Dataset.
This dataset contains the XPSWMM model and the resulting TUFLOW model that is created. These can be found in the XPSWMM and Complete_Conversion folders respectively.

If you are using this example conversion dataset, please rerun the XPSWMM model in the location where you save the dataset before beginning your own TUFLOW model conversion. Rerunning the model is necessary because XPSWMM will write TUFLOW files during its preprocessing, subsequently defining the correct file path information (for the location where you saved your files) in the newly written TUFLOW files. We also recommend creating your own TUFLOW model in a different folder from the provided TUFLOW dataset so you can easily compare your model against it.

If you do not have access to a XPSWMM license and the XPSWMM Application, please refer to the XPSWMM to TUFLOW SWMM Troubleshooting page.

XPSWMM to TUFLOW Model Conversion

Export Data From XPSWMM Model

Digital Terrain Model (DTM) Data
XPSWMM reads its 2D DTM data in one of two ways:

  • The DTM data can be directly specified in the '2D Model Settings', or
  • The DTM data can be internally processed by XPSWMM using its terrain tools and DTM builder.

Depending on which method is applied to your XPSWMM model, the steps required to will vary. Review which method is used:

  1. Open your existing model in XPSWMM.
  2. In the top dropdown menu options, go to Configuration > Job Control > 2D Model Settings. This will open a dialog.
  3. Under '2D Hydraulics Job Control', select 'Surface & Sampling'.
  4. Review the options in the 'Surface' section:
    • If 'Use DTM' is selected: Continue to the section below (Export DTM Data from XPSWMM) and complete the steps.
    • If 'Use Grid File for Topography' is selected and a 'Grid file' is specified, the steps outlined in the 'Export DTM Data From XPSWMM' section can be skipped. Go to the Export XPX Data From XPSWMM section.
    Note: If you have a .tif elevation file, you can continue to the Export XPX Data From XPSWMM section. The conversion process will be identical however, once converted, you will have to create the TUFLOW\model\grid folder manually and copy the .tif file into it.


Export DTM Data From XPSWMM

If 'Use DTM' was selected, XPSWMM preprocesses its Digital Terrain Model (DTM) into a binary XPTIN elevation dataset for inclusion in the TUFLOW model. XPTIN is a binary format that can't readily be used in GIS software. For this reason, the following steps outline how to obtain a DTM dataset in a GIS friendly form.

  1. In the XPSWMM Layers panel, under 'Topography', right click on DTM and select 'Export DTM Data'.
    • Input TIN File: Select the relevant XPSWMM Input TIN file.
    • Output File Format: 'ASCII Grid File Format'.
    • Cell Size Value: Choose a suitable DTM resolution. This resolution should be finer than the hydraulic model resolution. Typically, a DTM resolution is 1/5th to 1/10th of the hydraulic model 2D cell size is common (1 in the example dataset).
    Note: XPSWMM requires an integer cell size value for this export step. For example, Cell Size Values of 1, 2, 3, 4, 5 ... are suitable. The XPSWMM export will not function if you specify a decimal cell size value (eg. 0.5, 2.5, etc.).
  2. Click 'Export'.
  3. Save the file under an appropriate name (e.g. 1D2D_Urban_Grid.asc) to the folder where XPSWMM writes the .tcf during its simulation preprocessing. By default, this is the 2D\Data folder.
    If this folder does not exist, either:
    • The XPSWMM model has not run, so the TUFLOW control files have not been created by XPSWMM. Run the XPSWMM model (go to Analyze > Solve... in top dropdown menu options).
    • Non-default output settings have been specified in XPSWMM. To determine the output location, in the top dropdown menu options, go to Configuration > Job Control > 2D Model Settings > Folder Options. Ensure the following 'Folder Locations' are selected.
    XPSWMM to TUFLOW 2DJobControl FolderOptions Dialog 01e.png

  4. In the top dropdown menu options, navigate to Configuration > Job Control > 2D Model Settings. This will open a dialog, under '2D Hydraulics Job Control', select 'Surface & Sampling'.
  5. Tick on 'Use grid file for topography' and select '...' to navigate to the Grid file saved in the 2D\Data folder. This file will be read directly into TUFLOW.
  6. Click 'OK' to save the settings.
  7. Run the XPSWMM model to rewrite the TUFLOW files (including the new linkage to the DTM dataset) to the Data folder (go to Analyze > Solve... in top dropdown menu options).


Export XPX Data From XPSWMM

A XPX file is a simple command line file that contains the information needed to create link and node objects. To export this data from the XPSWMM model:

  1. In XPSWMM, in the top dropdown menu options, navigate to File > Import/Export Data > Export XPX Data. This will open a dialog. Leave all options as default and click 'Export'.
  2. When prompted, save the file under an appropriate name (eg 1D2D_Urban_001.xpx) to the folder where the XPSWMM model is located.


Convert XPSWMM Model to TUFLOW SWMM

Ensure you have QGIS and have the QGIS TUFLOW Plugin installed:

The following steps outline the process of converting a XPSWMM model to TUFLOW SWMM using the 'Convert - XPSWMM model from XPX' processing tool.

  1. Open QGIS and go to Processing > Toolbox from the top dropdown menu options to open the Processing Toolbox.
  2. Go to TUFLOW >> SWMM in the processing tool list and select 'Convert - XPSWMM model from XPX'. This opens the dialog shown below.
    • XPSWMM Exported XPX File: Click '...' and navigate to the exported XPX data (e.g. 1D2D_Urban_001.xpx). This should be located in the same folder as the XPSWMM model.
    • TUFLOW TCF Filename: Click '...' and navigate to the XPSWMM .tcf. This should be located in the 2D\Data folder (e.g. 2D\Data >> 1D2D_Urban_001.tcf).
    • SWMM File Prefix: Choose an appropriate prefix for the SWMM files (e.g. 1D2D_Urban_swmm).
    • Output Solution Scheme: 'HPC'
    • Output Hardware Specification: 'GPU' (if GPU is not available, select 'CPU')
    • Output Vector Format: 'GPKG'
    • Output Raster Format: 'GTIFF'
    • Output Profile: Any option can be used. 'ALL IN ONE' is used in this example for model design consistency with the TUFLOW SWMM Tutorials.
    • Event name if no global storms: Choose an appropriate event name if applicable (100yr in the example dataset).
    • BC width for created 1D/2D connections (HX/SX): This value should be approximately 2 times the width of the hydraulic model 2D cell size (10 in the example dataset).
    • BC offset distance for created 1D/2D connections (HX/SX): Distance from the channel endpoint to the midpoint of the BC line (2 in the example dataset).
    • Output Folder: Click '...' and navigate to an appropriate location to save your TUFLOW model. In this location, create a new folder called TUFLOW and select it.
    • Output CRS: Select an appropriate Coordinate Reference System (CRS) for the model. For the demonstration model, the CRS is 'EPSG:32760 - WGS 84 / UTM zone 60S'.
  3. Click 'Run'. Once the tool is finished, click 'Close'.


Inspect the output of the 'Convert - XPSWMM model from XPX' processing tool and load the TUFLOW model into QGIS:

  1. In Windows File Explorer, inspect the files output by the processing tool. In particular:
    • The TUFLOW\bc_dbase folder contains the BC Database which will contain any curves used in BC conditions, for easy extending to other events.
    • The TUFLOW\model folder contains the TUFLOW SWMM Control File (TSCF) which holds all commands specific to SWMM, including links to the converted SWMM INP file.
    • The TUFLOW\model\swmm folder contains a GeoPackage database (*_convert_messages.gpkg). This GeoPackage contains locations and descriptions of any errors or warnings that occurred during the conversion process.
    Note: Conversion messages are addressed in further detail here XPSWMM to TUFLOW SWMM Troubleshooting.
    • The TUFLOW\runs folder contains the TCF. If event(s) are specified, the TCF filename with have event placeholder(s), i.e. '_~e1~_~e2~_' (e.g. 1D2D_Urban_001_~e1~.tcf). Again, if event(s) are used, this folder also contains the TUFLOW Event File (TEF) with the event(s) specified.


  2. Open QGIS, and click on the ‘Load TUFLOW Layers from TCF’ symbol from the QGIS TUFLOW Plugin toolbar.
    Tuflow plugin load tcf layers.png

  3. Navigate to the location of the TUFLOW model and go to the TUFLOW\runs folder. Select the TCF.
  4. In the Load Layers window, select:
    • Ordering Options: Alphabetical
    • Grouping Options: Group by control file
    • Raster Load Options: Load Normally
  5. Click ‘Open’ and ‘OK’.
  6. Change the symbology of the DTM dataset:
    • In the QGIS Layers panel, right click on the DTM Grid file and select 'Properties'.
    • In the Symbology tab, under 'Band Rendering', set the 'Render type' to 'Hillshade' and the 'Z Factor' to 3.
  7. Inspect the output GIS layers.


Recommended Additional Conversion Steps

While the bulk of the XPSWMM to TUFLOW SWMM model conversion is automated by the 'Convert - XPSWMM model from XPX' processing tool, some required or recommended conventions must be implemented/updated manually. Therefore, it is highly recommended to complete the additional conversion steps: Recommended Additional Conversion Steps.
These steps can help improve model stability and they may also be helpful to address any messages that occurred when using the conversion tool.

TUFLOW Simulation Execution

Set up a simple batch file (.bat) to run TUFLOW. This approach calls the TUFLOW executable file (.exe) and runs the TCF file.

  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:
    set exe="..\..\exe\2023-03-AD\TUFLOW_iSP_w64.exe"
    set run=start "TUFLOW" /wait %exe% -b
    %run% -e1 100yr 1D2D_Urban_001_~e1~.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