XPSWMM to TUFLOW-SWMM

From Tuflow
Jump to navigation Jump to search

Page Under Construction - Expected Finalization date: 23 February 2024

Introduction

This Wiki page outlines recommended steps for 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). 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.


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:


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 an XPSWMM / TUFLOW discount in recognition of past royalties Autodesk paid TUFLOW when you purchased an XPSWMM perpetual license.

XPSWMM to TUFLOW Model Conversion

If using the example conversion dataset, rerun the XPSWMM model before beginning the conversion process. This will establish the correct filepaths and avoid errors while following the conversion process.


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.

The following sections explain how 2D data can be exported from XPSWMM and/or reconfigured into a format that is more standard of a TUFLOW model. The conversion has been summarized into three steps:

  1. Obtain Digital Terrain Model (DTM) dataset for TUFLOW model.
  2. Use TUFLOW's Processing Tool to configure the XPSWMM written TUFLOW files into a standard TUFLOW folder structure and GIS database format.
  3. Manual optional changes to the TUFLOW control files.


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 which method is applied to your XPSWMM model, the steps required to convert the model to TUFLOW will vary.

Let's review what method is used:

  1. Open your existing model in XPSWMM.
  2. In the top dropdown menu options, navigate 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:


XPSWMM DTM Preprocessing

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

Note: If 'Use DTM' was selected, follow the steps below. Otherwise, do not complete these steps; continue to the Convert XPSWMM Model to Recommended TUFLOW Structure section.


XPSWMM provides two options for preprocessing the DTM to be used in the TUFLOW model, both options are outlined below. As 'Option 1' is straightforward and 'Option 2' is more involved, 'Option 2' is demonstrated in the video below.

Option 1 (recommended) - Use Original Source Elevation Data Imported to XPSWMM:
  1. Locate the original 'Grid' file (.asc or .flt/.hdr format). Save it 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 01c.png
  2. 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'.
  3. 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.
  4. Click 'OK' to save the settings.
  5. If these steps worked as expected, skip 'Option 2' and continue to the next section. Otherwise, proceed to 'Option 2'.


Option 2 - Export DTM Data from XPSWMM:
  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/10th (or smaller) of the hydraulic model 2D cell size.
  2. Click 'Export'.
  3. Save the file 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 'Folder Locations' shown in the image above are selected.
  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. In the top dropdown menu options, go to Analyze > Solve. This will rerun the XPSWMM model and ensure that the Grid file is recorded.


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:

Folder Folder Folder Purpose
TUFLOW Folder Structure.JPG
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
model\grid
model\mi
model\swmm		 GIS layers defining the input spatial datasets are saved here.
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.


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 Convert TUFLOW Model GIS Format.

  1. Open QGIS. If you do not have QGIS installed:
  2. In QGIS, go to Processing > Toolbox from the top dropdown menu options to open the Processing Toolbox.
  3. Go to 'TUFLOW' in the processing tool list and select 'Convert TUFLOW Model GIS Format'. 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 TUFLOW SWMM Tutorials.
    • 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'.
  4. Click 'Run'.


Note: Update text further here after Ellis updates Plugin

  • TUFLOW Folder
  • SWMM Folder


Clean TUFLOW Control File

In the process of converting a model, the Convert TUFLOW Model GIS Format tool adds commands to control files. While these control files will allow the converted model to run, they have not been structured neatly. To maintain an easy to read and effective model, it is recommended to 'clean up' the TUFLOW control files. This can be done by:

  • Removing unnecessary commands.
  • Including a title at the beginning of each control file. For example, ! TUFLOW CONTROL FILE (.TCF) defines the model simulation parameters and directs input from other data sources.
  • Adding headings to sections of the control file. For example, ! MODEL INITIALIZATION could be used as a header for the commands required to initialize the TUFLOW SWMM model.
  • Using comments to explain the purpose of commands. For example, Spatial Database == ..\model\gis\1D2D_Urban_001.gpkg  ! Specify the location of the GeoPackage Spatial Database.
  • Using relative file paths to specify the location of various files and layers in the model.

The example below demonstrates how to clean up a TCF.

Will create this video and edit text next week.

Load TUFLOW Model in QGIS

Load and style the TUFLOW model in QGIS:

  1. Click on the ‘Load TUFLOW Layers from TCF’ symbol from the TUFLOW Plugin toolbar.
    Tuflow plugin load tcf layers.png

  2. Go to the location of the TUFLOW model and navigate to the TUFLOW\runs folder. Select the TCF.
  3. In the Load Layers window, select:
    • Ordering Options: Alphabetical
    • Grouping Options: Group by control file
    • Raster Load Options: Load Normally
  4. Click ‘Open’ and ‘OK’.


Style the layers however you desire. Common steps to do this are:

  1. Click on the ‘Apply TUFLOW Styles to Open Layers’ symbol from the TUFLOW Plugin toolbar.
    Tuflow plugin styles open layers.png

  2. Change the symbology of the DEM:
    • In the QGIS Layers panel, move the Grid file to the bottom of the list. This ensures that all the other layers are visible in the QGIS workspace.
    • In the QGIS Layers panel, right click the Grid file and select 'Properties'.
    • From the Symbology tab, under 'Band Rendering' select the following options:
    • Render type: Singleband pseudocolor
    • Color ramp: Spectral
    • Color ramp: Invert Color Ramp
    • Mode: Equal Interval
    • From the Transparency tab, set the Global Opacity to 75%.
    • Click 'Apply' and 'OK'.


  3. Create a hillshade of the DEM:
    • In the QGIS Layers panel, right click on the Grid file and select 'Duplicate Layer'.
    • Right click on the copy 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'.
    • From the Symbology tab, under 'Band Rendering' select the following options:
    • Render type: Hillshade
    • Z Factor: 3
    • Click 'Apply' and 'OK'.


One Dimensional (1D) SWMM Model Elements

Export 1D EPA SWMM Pipe Network Data from XPSWMM

Convert 1D XPSWMM hydraulics features into a EPA SWMM 5 INP file format for TUFLOW:

  1. In XPSWMM, select 'Hydraulics Mode' from the toolbar.

    XPSWMM to TUFLOW toolbar hydraulics mode 01a.png
  2. 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.
  3. When prompted to save changes, select 'Yes'.
  4. 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.
  5. 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 'GeoPackage - Create from SWMM inp ' 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.
  6. Click 'Run'. Once the tool is finished, click 'Close'.
  7. 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.
  8. 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.
  9. Inspect the attributes associated with the various objects in the GeoPackage to familiarize yourself with the data.


Correct SWMM Nodes--Junction/Outfall Model Design

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.

  1. In the QGIS Layers panel, select (left click) Nodes--Junctions to make it the active dataset.
  2. Go to Processing > Toolbox from the top dropdown menu options to open the Processing Toolbox.
  3. Go to TUFLOW >> SWMM in the processing tool list and select 'Junctions - Downstream junctions to outfalls'. This opens the dialog shown below.
    • Input Junctions: Nodes--Junctions (this is prepopulated as Nodes--Junctions is the active dataset).
    • Input Conduits: Click '...' and tick on Links--Conduits
    • 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:
    1. Click '...', select 'Save to GeoPackage...'.
    2. Navigate to the TUFLOW\model\swmm folder and select the HDR GeoPackage file created in the Convert XPSWMM Model to Recommended TUFLOW Structure section. Click 'Save'.
    3. 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.
    4. Click 'OK'.
  4. Click 'Run'. Once the tool is finished, click 'Close'.
  5. The temporary junctions layer, Modified junctions layer, and the new outfalls layer, Nodes--Outfalls, will appear in the QGIS Layers panel.
  6. In the QGIS Layers panel, right click Modified junctions layer, and select 'Remove Layer..'.
  7. In the QGIS Layers panel, select (left click) Nodes--Outfalls and toggle off editing.


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.

  1. In the QGIS Layers panel, select (left click) Nodes--Junctions and toggle on editing.
  2. Use the 'Select Features' tool to select all nodes included in the Nodes--Junctions layer. This will change their color to bright yellow.
  3. In the Processing Toolbox, go to 'Vector Selection' and select 'Select within distance'. This opens the dialog shown below.
    • Select features from: Nodes--Junctions (this is prepopulated as Nodes--Junctions is the active dataset).
    • By comparing to the features from: Click the drop down menu and select Nodes--Outfalls.
    • Where the features are within: '0.1 meters'
    • Modify current selection by: 'selecting within current selection'
  4. Click 'Run'. Once the tool is finished, click 'Close'.
  5. In the QGIS Layers panel, right click Nodes--Junctions and select 'Open Attribute Table'.
  6. 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.
  7. Toggle the editing off to save the edits.


1D/2D Pipe Network Pit (Inlet Usage) Connections

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

XPSWMM Kerb Inlet.JPG

Transfer of inlet usage connection information from XPSWMM to TUFLOW involves a three step process:

  1. Export data from XPSWMM.
  2. Convert the exported data into a TUFLOW SWMM compatible format.
  3. Make minor edits to correct for snapping deficiencies in the XPSWMM export tools.


Export Data from XPSWMM

  1. In XPSWMM, select 'Hydraulics Mode' from the toolbar.

    XPSWMM to TUFLOW toolbar hydraulics mode 01a.png
  2. In the XPSWMM Layers panel, right click Nodes and select 'Export To GIS File...'. This will open a dialog.
  3. 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
  4. 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
  5. In the right-hand table, the items above, along with 'Node Name', 'Node X' and 'Node Y', should be selected.
  6. 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'.
  7. Click 'Export'. A message will appear reporting how many nodes were exported.


Convert Exported Data into TUFLOW SWMM Format

  1. In Windows File Explorer, navigate to the TUFLOW\model\swmm folder. Drag and drop the node export .shp file into QGIS.
  2. In the QGIS Layers panel, select (left click) the node export layer.
  3. In the Processing Toolbox, go to TUFLOW >> SWMM and select 'Convert - XPSWMM GIS inlet layers to SWMM'. This opens the dialog shown below.
    • GIS layer with inlet information: This is prepopulated as the node export layer is the active dataset).
    • 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):
    1. Click '...', and select 'Save to File...'.
    2. 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.
    3. Click 'Save'.
    • GeoPackage file for inlet usage:
    1. Click '...', and select 'Save to File...'.
    2. Navigate to the TUFLOW\model\swmm folder. Choose an appropriate .gpkg file name. For example, swmm_iu_XP_001.gpkg.
    3. Click 'Save'.
  4. Click 'Run'. Once the tool is finished, click 'Close'.
  5. Remove the node export layer from the QGIS workspace.
  6. 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.


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.

  1. In the QGIS Layers panel, select (left click) the inlet usage layer (i.e. swmm_iu_XP_001) and toggle on editing.
  2. In the Processing Toolbox, select the 'Edit Features In-Place' tool Edit features in place icon.png. This allows the editing of an existing layer, instead of the creation of a new layer.
  3. 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'
  4. Click 'Modify All Features'. Once the tool is finished, click 'Close'.
  5. Toggle off the editing for the inlet usage layer (i.e.swmm_iu_XP_001) to save the edits.


Create 1D/2D Culvert Connections

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.

XPSWMM Culvert Inlet.JPG

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.

  1. In the QGIS Layers panel, select (left click) Links--Conduits.
  2. Use the 'Select Features' tool to select the culvert and pipe objects that will have a clear opening in Links--Conduits (hold Shift to select multiple). Typically, these culvert and pipe objects are located under an embankment or connect to/from a waterway, such as a creek. In XPSWMM, this type of feature is typically represented by Links snapped to Nodes with 'Link invert to 2D' selected.
  3. In the Processing Toolbox, go to TUFLOW >> SWMM and select 'BC - Create channel endpoint 1D/2D connections'. This opens the dialog shown below.
    • Input Conduits Layer: Links--Conduits (this is prepopulated as Links--Conduits is the active dataset).
    • Tick on 'Selected features only'.
    • Create connections at: 'Both ends'.
    • Offset Distance: This value is the distance from the channel endpoint to the midpoint of the BC line. The recommended value is 2.
    • Length of BC lines: This value should be similar the width of the channel.
    • Tick on 'Set 2D cell elevation to 1D culvert invert at 1D/2D connection cells if needed'.
    • Output Layer:
    1. Click the ... and select 'Save to GeoPackage'.
    2. Navigate to the TUFLOW\model\gis folder and select the GPKG created from the XPSWMM model in the Convert XPSWMM Model to Recommended TUFLOW Structure section. This GPKG will have the same name as the original XPSWMM model.
    3. Click 'Save'. A dialog will open. In the 'Layer Name' field, write an appropriate layer name. It is recommended to name the output layer with the prefix '2d_bc' so TUFLOW styles can be automatically applied. For example, 2d_bc_Culvert_Connections_001_L.
    4. Click 'OK'.
  4. Click 'Run'. Once the tool is finished, click 'Close'.
  5. The 2d_bc layer will appear in the QGIS Layers panel. Select (left click) the 2d_bc layer and click 'Apply TUFLOW Styles to Current Layer'. Toggle on editing.
  6. Review the 2d_bc_SWMM_Culvert_Connections_001_L data. Make corrections by deleting objects located where a 1D/2D connection was required only at one end of the conduit, rather than at both ends.
  7. Toggle editing off for 2d_bc_SWMM_Culvert_Connections_001_L to save the edits.


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.

XPSWMM to TUFLOW swmm hydrology runoff method 01b.png

Convert 1D XPSWMM hydraulics features into a EPA SWMM 5 INP file format for TUFLOW:

  1. In XPSWMM, select 'Runoff Mode' from the toolbar.

    XPSWMM to TUFLOW toolbar runoff mode 01a.png
  2. 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.
  3. When prompted to save changes, select 'Yes'.
  4. In QGIS, go to TUFLOW >> SWMM in the processing tool list and select 'GeoPackage - Create from SWMM inp '. 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.
  5. Click 'Run'. Once the tool is finished, click 'Close'.

    Video - waiting on subcatchments

  6. 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.
  7. In QGIS, from the top dropdown menu options, select View > Panels. Tick on 'Browser Panel'.
  8. 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.
  9. Right click Nodes--Junctions and select Manage > Delete Layer.
  10. In Windows File Explorer, navigate to the TUFLOW\model\swmm folder. Drag and drop the RNF GeoPackage into QGIS and review the attribute data.

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 TUFLOW SWMM Module 4 (1D SWMM Pipe Network / 1D SWMM Urban Hydrology: Executing multiple different event simulations from a single model control file). 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.



Video - waiting on subcatchments

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.

  1. In the QGIS Layers panel, select (left click) Nodes--Junctions and toggle on editing.
  2. 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.
  3. Go to TUFLOW >> SWMM in the processing tool list and select the 'Junctions - Set attributes ' 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.
    • Input BC Connection Layers: If available, select the 2d_bc connection layer.
    • 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
  4. Select 'Modify All Features'. Once the tool has finished, click 'Close'.
  5. Turn off editing to save the edits.
  6. View the attributes within Nodes--Junctions to verify the data processing has been completed correctly.
    For a summary of the attributes associated with the Nodes--Junctions layer, refer to TUFLOW 2023-03-AD Release Notes (Table A.30) and the SWMM Reference Manual - Volume 2 (Hydraulics).

Video - waiting on subcatchments

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

  1. In QGIS, go to TUFLOW >> SWMM in the processing tool list and select 'GeoPackage - Write to SWMM inp'.
  2. In the tool window, click the '...' and navigate to the TUFLOW\model\swmm folder. Select the HDR GeoPackage file.
  3. Click 'Run'.
  4. Once the tool has finished, click the 'Parameters' tab.
  5. Repeat steps 2 and 3 for the RNF and inlet curves GeoPackages.
  6. Once the tool has finished, click 'Close'.
  7. 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.

    Video - waiting on Subcatchments

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.


Simulation Control Files

The following steps will require use of a text editor. The tutorial demonstration uses Notepad++. For its 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 sued in your model.

TUFLOW Control File (TCF)

The TCF file references all the control files, specifies time and output controls.

  1. In Windows File Explorer, navigate to the TUFLOW\runs folder and open the TCF into a Text Editor (Notepad++ is recommended).
  2. Make the following reference updates:
    Model Initialization updates:
    Spatial Database == ..\model\gis\1D2D_Urban_001.gpkg
    GIS Format == GPKG
    Solution Scheme updates:
    Solution Scheme == HPC
    Hardware == GPU
    Model Inputs updates:
    SWMM Control File == ..\model\1D2D_Urban_001.tscf
    Time Control updates:
    Start Time == <<start time>>
    End Time == <<end time>>
  3. Replace the 'Output Directory' commands with the following:
    Log Folder == log
    Output Folder == ..\results\
    Write Check Files == ..\check\

    Video



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.

  1. In Windows File Explorer, navigate to the TUFLOW\model folder and create a new blank text file with the extension .tscf.
  2. Open the TSCF into a Text Editor (Notepad++ is recommended) and add the following commands. These filenames are examples, reference your model SWMM INP files.
    Read SWMM == ..\swmm\1D2D_Urban_HDR_001.inp
    Read SWMM == ..\swmm\1D2D_Urban_RNF_001.inp
    Read SWMM == ..\swmm\swmm_inlet_curves_XP_001.inp
    Read SWMM Inlet Usage == ..\swmm\swmm_iu_XP_001.gpkg

    <<Video>>


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.

  1. In Windows File Explorer, navigate to the TUFLOW\model folder and open the TBC into a text editor (Notepad++ is recommended).
  2. Remove all commands from the TBC file.
  3. Add the following command to reference the external model boundary:
    Read GIS BC == 1D2D_Urban_001_2d_bc_L
  4. Add the following command to reference the link between the 1D SWMM culverts and the 2D TUFLOW domain.
    Read GIS BC == 2d_bc_Culvert_Connections_001_L

    Video


TUFLOW Geometry Control File (TGC)

The TGC file is a series of commands that build the geometry model. At its minimum, the TGC contains:

  • Information on the size and orientation of the grid;
  • Grid cell codes (whether cells are active or inactive);
  • Bed / ground elevations; and
  • Bed material type or flow resistance value.
  1. In Windows File Explorer, navigate to the TUFLOW\model folder and open the TGC into a text editor (Notepad++ is recommended).
  2. Replace all '#' with '!'.
    Video


Below is from Pavlina's edits - keeping as a reference for now

  1. Update main TUFLOW control file (TCF):
    • Add below commands if applicable:
      Solution Scheme == HPC
      Hardware == GPU
      GIS Format == GPKG
    • Add TSCF command to read the 1D SWMM features:
      SWMM Control File == ..\swmm\SWMM.tscf
    • Add time control comands:
      Start Time == <<start_time>>
      End Time == <<end_time>>
    • Rarely used options to consider removing from the TCF:
      SX ZC Check == OFF
      HX ZC Check == OFF
      Mass Balance Corrector == OFF
    • Remove XPSWMM references:
      Read GIS XP Nodes ==
      Read GIS XP WLL ==
      Read GIS XP NETWORK ==
    • Add scenarios/events if applicable

    <<Video>>


Feedback / Suggestions

If you have any suggestions to be included in these pages, please email support@tuflow.com.


Up
Go-up.png Back to Main Page
Retrieved from "https://wiki.tuflow.com/w/index.php?title=XPSWMM_to_TUFLOW-SWMM&oldid=38055"