XPSWMM to TUFLOW-SWMM

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

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.

Dataset Download

The XPSWMM model used for this model conversion demonstration is available for download here: XPSWMM to TUFLOW Model Conversion Dataset. A copy of the completed converted model can be downloaded at the end of the page.

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.

XPSWMM to TUFLOW Model Conversion

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.

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

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 Update SWMM INP Files

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.

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

1. In XPSWMM, select 'Runoff Mode' from the toolbar.
   
   
   
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'.
   
   

   
   

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

    
    

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

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

   
   

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, 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.
3. Under 'GeoPackage Input File', click '...' and navigate to the TUFLOW\model\swmm folder. Select the HDR GeoPackage file.
4. Click the plus icon
5. Click 'Run'.
6. Once the tool has finished, click the 'Parameters' tab.
7. Repeat steps 2 and 3 for the RNF and inlet curves GeoPackages.
8. Once the tool has finished, click 'Close'.
9. 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.
   
   

   
   

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 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.
   Read SWMM == ..\swmm\1D2D_Urban_HDR_001.inp  ! 1D SWMM Pipe Network input file
   Read SWMM == ..\swmm\1D2D_Urban_RNF_001.inp  ! 1D SWMM Hydrology input file
   Read SWMM == ..\swmm\swmm_inlet_curves_XP_001.inp  ! 1D SWMM Inlet Curves input file
   Read GIS SWMM Inlet Usage == ..\swmm\swmm_iu_XP_001.gpkg >> inlet_usage  ! 1D SWMM Pipe Network Inlet Usage layer
   
   <<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 the reference to the 2d_bc points layer. This layer was removed from the model GeoPackage in the Export 1D EPA SWMM Pipe Network Data from XPSWMM section.
3. 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.
   Read GIS BC == 1D2D_Urban_001_2d_bc_L  ! Reads in 2D boundaries and links 1D SWMM culverts to the 2D TUFLOW domain
   
   Video

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.

The TGC requires no updates; however, it is recommended to review the TGC before running the simulation to ensure all commands are correct.

TUFLOW Control File (TCF)

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

In the Convert XPSWMM Model to Recommended TUFLOW Structure section, the Convert TUFLOW Model GIS Format 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.

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.

1. Remove or comment out the commands listed below.

   Check MI Save Date ==	Mass Balance Output Interval (s) ==
   MI Projection ==	CSV Time ==
   MI Projection Check ==	Viscosity Formulation ==
   Timestep (s) ==	Viscosity Coefficient ==
   Cell Wet/Dry Depth ==	SX ZC Check ==
   Read GIS XP Nodes ==	SX Storage Approach ==
   Simulations Log Folder ==	HX ZC Check ==
   Store Maximums and Minimums ==	Mass Balance Corrector ==
   Mass Balance Output ==

2. Make the following updates:

   Original Command	Updated Command
   GPKG Projection == 1D2D_Urban_001_proj	GPKG Projection == ??
   Write Check Files == OFF	Write Check Files == ..\check\
   Output Folder == ..\results\Output	Output Folder == ..\results\
   Log Folder == log\Log	Output Folder == log
   Map Output Data Types == qVdhZ0	Map Output Data Types == q V d h Z0
   Map Output Format == XMDF	Map Output Format == XMDF TIF

3. Add the following commands:
   Tutorial Model == ON  ! Required command to run this tutorial model licence free
   GIS Format == GPKG  ! Specify GPKG as the output format for all GIS files
   Solution Scheme == HPC  ! Heavily Parallelised Compute, uses adaptive timestepping
   Hardware == CPU  ! Replace with "Hardware == GPU" if GPU available
   Start Time == 0  ! Specifies the simulation start time (0 hours)
   End Time == 3  ! Specifies the simulation end time (3 hours)
   TIF Map Output Interval == 0  ! Outputs only maximums for grids
   
4. Add the following command to reference the TUFLOW SWMM Control File (TSCF):
   SWMM Control File == ..\model\1D2D_Urban_001.tscf
5. Save the TCF.
   
   Video
   

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, ! 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.
• Utilizing 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.
  

If using the provided model conversion dataset, the final Control files should look like this:
insert images when dataset finalised

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.

Feedback / Suggestions

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

Up
Back to Main Page