- 1 Introduction
- 2 Modify GIS Inputs
- 3 Modify Simulation Control Files
- 4 Run the Simulation
- 5 Review Check Files
- 6 Review the Results
- 7 Conclusion
- 8 Troubleshooting
As discussed in Module 1 (discussion here), the main creek channel is not very well represented using the 5m 2D cell size. In parts, the creek is only 5-10m wide and the 5m cell size could be considered too coarse to accurately represent the creek topography. Refer to the below figure.
Using a cell size that is coarse relative to the width of the creek channel may reduce the accuracy of the computed conveyance in the channel and introduce a source of mass error to the model. There are two options for improving the representation of the creek channel:
- decrease the width of the 2D cells; and/or
- model the channel as a 1D network, dynamically linked to the 2D domain (the floodplain).
In the optional section of module 1 (located here), we looked at reducing the cell size to get a better representation of the channel. In this module we will adopt the second approach of modelling the creek as 1D elements.
Setting up a 1D/2D model where the 1D channel cuts through the 2D domain is probably the most time-consuming type of a TUFLOW model to setup. However, the reduction in simulation time can be beneficial and make this a good approach. For this module, most of the time consuming data entry tasks have been undertaken, so you can progress through the module in a relatively short period of time. However, throughout the tutorial we will provide guidance on making this process as efficient as possible should you have to start from scratch.
There are a number of steps involved in the process.
Within our GIS platform we need to make the following changes:
- Define 1D Cross-Sections (1d_xs)
- Define 1D Channels (1d_nwk)
- Define 1D/2D Links (2d_bc)
- Deactivate 2D Cells (2d_bc)
- Define Boundary Conditions
We also need to modify the TUFLOW run files to reflect these new and changed GIS layers.
As well as replacing the in-bank area with 1D elements, we we also extend the model further downstream. As this extends beyond the area of the DEM provided, we will transition from a 1D/2D model within the study area to a 1D only model. This allows us to extend the downstream boundary (stage-discharge boundary) further from our area of interest. We have cross-sectional details downstream of the DEM, but insufficient topography data to model this in 2D. This approach can also be used to reduce the 2D model area, thereby reducing model runtimes, or allowing a finer 2D cell size to be used.
Modify GIS Inputs
As with Modules 2 and 3 of the TUFLOW wiki, the GIS inputs are demonstrated in MapInfo, ArcGIS and QuantumGIS (QGIS). At each stage please select your GIS package for instructions.
A 1D model requires cross-sections for processing of the channel geometry. There are a number of different formats for cross-sections to be input to TUFLOW. In this module we will be using an offset-elevation approach (XZ). This is a typical format for inputting cross-sections however, other options include height-width (HW) and MIKE11 format inputs. These are not covered in this tutorial, however the general process is very similar.
To save time, the locations and XZ profiles for the 1D cross sections are provided. The XZ profiles were automatically extracted from the DEM triangulation using the 12D software (www.12d.com) with the aid of the TUFLOW utility 12da_to_from_mif.exe using the -xs option (see 12da_to_from_mif wiki page). The SMS TUFLOW interface has a similar and easier process, noting that a licence for the SMS TUFLOW interface is required to save the cross-sections.
It is more common for this information to come from surveyed cross-sections. If the survey has been provided as x-y-z points, or a a GIS layer of points, the xs_Generator utility can be used to create the cross-sections in a TUFLOW format. The xs_Generator utility is described in the XsGenerator wiki page.
For each cross-section there is an individual comma separated variable (.csv) file. The 1d_xs layer contains a link to the source .csv file at every cross-section location. SMS users can skip these steps and click on the link below for further steps.
Tip: The XY scatter plot can be setup as the default chart type in excel, this makes it simple to plot the cross-sections, simply open the .csv in Excel using the GIS hotlink functionality, select the data and the hit the F11 key to create a chart. Instructions for setting an x-y scatter as the default chart type can be found in this Excel tip.
For MapInfo users with the miTools utility, the cross-sections can be viewed directly within MapInfo, instructions for doing so are in the viewing cross-sections in MapInfo with the miTools page.
Users with the SMS-TUFLOW interface can also directly view the cross-sections in the viewing cross-sections in SMS page.
Now that we have looked at the cross section data, we must add 1D channels for the 1D network. In TUFLOW, cross sections can either be located at the ends of each channel reach, or at some point along the reach. The way that TUFLOW uses the cross-section depends upon the location, for example a "centre" cross-section has a higher priority than "end" sections if both "End" and "Centre" sections are defined. For more information on the 1D topography, you are encouraged to read Section 4.6 of the 2010 TUFLOW manual.
For this tutorial, we will locate most of the cross-sections at the ends of channels. There are a number of locations where a "centre" section will be used. The final channel will be a weir type channel; this represents a weir with a known stage-discharge curve. In later modules we will also use "centre" cross sections for the modelling of structures.
For the open channel type we will use three different types of channels. The three types channel types are: standard open channel (S), weir (W) and channel connector (X). The GIS "Channel_type" attribute is in brackets. The connector channel is used where there is a branch in the channel, the connector type indicates a side channel entering. This is not mandatory, but if using channel interpolation, this allows TUFLOW to determine the main channel.
As the cross sections have been provided, the digitisation of the channel is simply a matter of joining the dots. We are going to create a series of lines between the cross sections. It is important that the end of each channel snaps to a vertex along the cross-section line, so we will be using the snapping tools in the GIS. We have provided a 1d_nwk_M04_creek_001 GIS layer. This layer has the first few channels digitised for you. A revised culvert layer 1d_nwk_M04_creek_001 is also provided, this has the culverts connected to the new channels layer. The creation of the 1d network layers is described for the GIS packages below:
In this section we define lines where there is flow exchange between the 1D and 2D components of the model. At first it may seem slightly complicated, but it is actually very logical and the method allows the user to change the 2D cell size and orientation at a later stage without having to change the 1D/2D linking. Before we begin creating the link we will spend a bit of time describing how the link works. More details on the 1D/2D link can be found in Section 4.10.5 of the 2010 TUFLOW manual.
Description of linking concept
We are going to apply a water level boundary to the 2D cells along the 1D/2D interface. In the 2D boundary condition (2d_bc) GIS layer, we define the location at which this link occurs. The 2D water level applied at the 2D boundary cells is calculated in the 1D model. The terminology used in TUFLOW is a "HX" type boundary on the 2D cells, with the H indicating that a Head (water level) boundary is used and the X indicating the value is coming from an eXternal model (in this case the 1D).
Using a similar naming convention, a HT boundary is a Head versus Time boundary, a QT indicates a flow-time (hydrograph) boundary and a HQ boundary used in the model is a Head versus Flow (or stage-discharge) boundary.
Depending on the water level in the surrounding 2D cells, flow can either enter or leave the "HX" cells. The volume of water entering or leaving the 2D boundary is added or subtracted from the 1D model to preserve volume. As was done in Module 2 for the SX lines, we must connect the HX lines to the 1D network. This is done using CN type lines in the 2d_bc layer, where a CN line is connected to the HX line, the water level from the 1D nodes is transferred to the HX line. In between 1D nodes a linear interpolation of water level is applied. This is shown in the image below.
As the water level in the 2D is calculated at the cell centres, once the water level in the 1D exceeds the elevation in the boundary cell water can enter or leave the model. If there is a levee, it is important that we use breaklines in the model to ensure that the elevations of the 2D cells are consistent with the levee crest. This will be described in the next section of the tutorial. The next four images show a section view of the 1D/2D link and how this may progress during a flood event.
Often HX lines are located along the top of a levee (natural or artificial) or flood defence running along the river bank. When carving a 1D channel through a 2D domain, the HX line must be either on the top of the levee or on the inside of the levee (closest to the channel). If the HX line is located on the other side of the levee away from the channel, the effect of the levee on water flow is not modelled. In the sections above, it can be seen that the boundary cell is along the levee and the interaction between the channel and the floodplain (1D and 2D) occurs at the correct elevation.
Now that we have a background in the linking approach it is time to define the 1D/2D link. This process is described for the various GIS packages in the links below:
As mentioned above, the water level from the 1D is transferred out to the 2D HX cells. Therefore, it is important that the 2D cell elevation reflects the level when water can spill out into the 2D. The water level computation point for the 2D cells is the cell centre, therefore it is important to use a "thick" breakline. The types of breaklines was discussed further when reviewing the check files for the previous module here.
In the image below, the lightly shaded cells are the 1D/2D boundary cells. The black labels are the elevations with no breakline (elevation as read from the DEM). At the circled cell, the cell centre elevation is 44.35, this controls when water can spill from the 1D to the 2D. The red line indicates the true top of bank; the labels are elevations along this line. If this is included as a breakline, the elevations are as labelled in yellow. In this case, the level at the circled cell is actually 44.57. Including breaklines for the top of bank is important, particularly if there is an embankment or levee.
To include breaklines for the top of bank, follow the instructions outlined in your GIS package below.
SMS Users: SMS automatically extracts elevations for the HX lines when we export the TUFLOW files. Please proceed to the next section.
Deactivate 2D Cells
Now that we have defined the 1D model and the 1D/2D linking location, we need to deactivate the 2D cells where the 1D model is replacing the 2D solution. It is important that the area deactivated from the 2D is the same as the area modelled in the 1D solution. If the 1D cross sections are 20m wide, but a 40m width is removed from the 2D model, the model will be underestimating the conveyance. The opposite would be true if the 1D cross sections were 80m wide but only a 40m width had been deactivated, i.e. the model would be overestimating the conveyance.
As the HX line was created along the top of bank and was as wide as the cross-sections, we can snap the code polygon (which deactivates the 2D cells) to the HX line. To do this please select your GIS package from the list below:
Define Boundary Conditions
You may have noticed that in addition to extending downstream of the 2D active domain to the north, the 1D network extends slightly upstream from the 2D active domain at the south western edge of the model. Therefore, we need to adjust the inflow and outflow boundary locations. We are going to replace the upstream inflow boundary (QT type) which is in the 2D_bc layer, with boundaries applied at the upstream and downstream extents of the 1D network. To do this we need to:
- Create a new 1d_bc layer and add the boundary to this; and
- Change the boundary file read into the TUFLOW boundary control file (.tbc).
We will be using the same boundary hydrograph and therefore will not need to update the boundary database (bc_dbase).
For the GIS changes please select your GIS package from the list below.
Modify Simulation Control Files
Now that we have made all of the necessary changes to the GIS layers, we need to update our control files to utilise the new GIS layers. Now that the 1D component of the model is becoming more complex we are going to use a separate control file for the 1D inputs. The new 1D control file will have the extension .ecf, this stands for ESTRY Control File. ESTRY was a 1D hydraulic modelling package before TUFLOW was created. The functionality of ESTRY has been incorporated in TUFLOW but for historic reasons the 1D control file is still referred to as the ESTRY Control File and has the .ecf file extension.
SMS users do not need to modify the control files manually because SMS writes out the control cards and files automatically while exporting the TUFLOW project. Please proceed to Simulation Setup.
Start 1D Domain
- Output Folder == ..\results\M03\1d\
- Write Check Files == ..\check\1d\
- Output Interval (s) == 180 ! Output every 3 minutes. Note the (s) is required to output indicate value is in seconds
- Timestep == 0.75 ! Set 1D timestep to be half the 2D timestep
- Read GIS Network == ..\model\gis\1d_nwk_M02_culverts_001_L.shp
- Read GIS Network == ..\model\gis\1d_nwk_M02_culverts_001_P.shp
As we have changed the geometry M03_5m_001.tgc and boundaries M02_5m_001.tbc we will need to update these files, and the links in the .tcf.
Geometry Control File == ..\model\M04_5m_001.tgc
BC Control File == ..\model\M04_5m_001.tbc
BC Database == ..\bc_dbase\bc_dbase_M04.csv
ESTRY Control File == ..\model\M04_1d_001.ecf
Screen/Log Display Interval == 40
TUFLOW will write the output every 40 timesteps. For the 1.5 second timestep this means we will get output every 60 seconds of simulation time.
This concludes the changes that we need to make to the .tcf, but before we run the model we need to update the .ecf, .tgc, .tbc and bc_dbase files.
Output Folder == ..\results\1D\
Note: We have removed the module number from the output folder ..\results\1D\ instead of ..\results\M04\1D\ from now on all 1D output will be written to the same folder. It is a matter of preference, TUFLOW will output the results where you want them!
In MapInfo the culverts (line objects) and 2D connections (point objects) are in the same GIS layer and we updated this from version 1d_nwk_M02_culverts_001 to 1d_nwk_M04_culverts_001. Update this reference in the .ecf.
Read GIS Network == mi\1d_nwk_M04_culverts_001.mif
For Other GIS users, we need to updated to the new culvert line layer, and the remove the link to the points layer which contains the obsolete 1D/2D boundaries. To remove the culvert connections, add an exclamation mark at the start of the line, or delete the reference to 1d_nwk_M02_culverts_001_P.shp:
Read GIS Network == gis\1d_nwk_M04_culverts_001_L.shp
Read GIS Network == gis\1d_nwk_M02_culverts_001_P.shp
For MapInfo users:
Read GIS Network == mi\1d_nwk_M04_channels_001.mif
Read GIS Table Links == xs\1d_xs_M04_creek_001.mif
Read GIS BC == mi\1d_bc_M04_001.MIF
For Other GIS users:
Read GIS Network == gis\1d_nwk_M04_channels_001_L.shp
Read GIS Table Links == xs\1d_xs_M04_creek_001_L.shp
Read GIS BC == gis\1d_bc_M04_001_P.shp
SMS users do not need to modify the control files manually because the control cards/files are automatically generated by SMS while exporting TUFLOW files. Follow these steps to Setup the Simulation.
There have been three changes to the geometry:
- We have updated the active model area;
- We have created a polygon in the 2d_bc format to deactivate the creek from the 2D model; and
- We have added a breakline to ensure the elevations of the 2D cells along the 1D/2D interface are correct.
Read GIS Code == mi\2d_code_M04_001.MIF
Read GIS Code == gis\2d_code_M04_001_R.shp
Read GIS Code BC == mi\2d_bc_M04_HX_001.mif
Read GIS Code == gis\2d_code_M04_null_creek_001_R.shp
Read GIS Z HX Line MAX == mi\2d_bc_M04_HX_001.mif | mi\2d_bc_M04_HX_001_P.mif
Read GIS Z HX Line MAX == gis\2d_bc_M04_HX_001_L.shp | gis\2d_bc_M04_HX_001_P.shp
! Read GIS BC == gis\2d_bc_M01_002_L.SHP
For MapInfo users:
Read GIS BC == mi\2d_bc_M04_culverts_001.MIF
Read GIS BC == mi\2d_bc_M04_HX_001.mif
For Other GIS users:
Comment out (or delete) the following line:
!Read GIS BC == gis\2d_bc_M02_culv_001_L.shp
The GIS layer 2d_bc_M02_culv_001_L.shp contains only the 1d/2d connection for the northern culvert. This culvert is now connected directly to the 1D open channel and this culvert connection is no longer required.
Add the following line.
Read GIS BC == gis\2d_bc_M04_HX_001_L.shp
Boundary Database (bc_dbase)
The revised boundary data has been provided for this tutorial. This includes the stage-discharge boundary for the weir at the downstream end of the model.
Run the Simulation
Using your preferred method for starting TUFLOW, run the recently created M04_5m_001.tcf. Please refer to module 1 for a detailed description of the various methods for running a TUFLOW simulation.
If the model fails to start correctly please refer to the troubleshooting section at the end of this page.
Review Check Files
Once the model has started we can review the check files to ensure the changes have been correctly applied. From the TUFLOW\check\2d\ folder import (into MapInfo) or open (ArcMap and QGIS) the following check files:
From the TUFLOW\check\1d\ folder import (into MapInfo) or open (ArcMap and QGIS) the following check files:
In the creek channel we should see that there are channels in the 1D network and that the 2D grid has been deactivated. Along the HX line we should see that there are connections in the 1d_to_2d check file and that the breaklines have modified the elevations at these cells. This is shown in the image below. If these changes are not visible in your model, ensure that the correct .tcf has been run and refer to the troubleshooting section.
Review the Results
Open the 2D results in your results viewer or import to your GIS package. You should see that where we have replaced the 2D with the 1D model there are no results displayed.
If you look at the 1D results (by importing the time series (_TS.mif or _TS_P.shp from the 1D results folder, or opening the M04_5m_001_1d_Q.csv) the 1D channels are conveying flow. In order to get map output for the 1D we need to use Water Level Line (WLL) inputs. The underlying water level from the 1D model is displayed across this line and as such it should be digitised perpendicular to flow.
The water level line process is detailed in Section 4.11 of the 2010 TUFLOW manual. For the purpose of this tutorial the 1D_WLL GIS inputs have been provided for you.
For MapInfo users:
Copy the 1d_WLL_M04_001.mif and 1d_WLLp_M04_001.mif to your TUFLOW\model\mi\ folder. Add the following to the 1D (ESTRY) control file M04_1d_001.ecf.
Read GIS WLL == mi\1d_WLL_M04_001.mif
Read GIS WLL Points == mi\1d_WLLp_M04_001.mif
For ArcMap / QGIS users:
Copy the 1d_WLL_M04_001_L.shp and 1d_WLLp_M04_001_P.shp to your TUFLOW\model\gis\ folder. In the Estry Control File (.ecf) add the following lines:
Read GIS WLL == gis\1d_WLL_M04_001_L.shp
Read GIS WLL Points == gis\1d_WLLp_M04_001_P.shp
We have made major changes to our TUFLOW tutorial model. The open channel in now modelled in 1D, with 1D/2D connections along the top of bank. The model has also been extended further downstream (in 1D) and a user defined stage-discharge relationship has been adopted.
Congratulations on finishing Module 4!
If the TUFLOW simulation fails to start TUFLOW will output the error in a number of locations. Firstly, check the Console Window or the TUFLOW Log File (.tlf) (located in the TUFLOW\runs\log\ folder with the name M04_5m_001.tlf). This file can be opened in a text editor and the error is generally located at the end of the file. You can however search for "Error" if you can not see the error. In most cases there is also a spatial location for the error message (if the error reported in the log file is prefixed by XY:). To check the location of the geographic errors, open the M04_5m_001_messages.mif or M04_5m_001_messages_P.shp file in your GIS package.
This section contains links to some possible problems that may occur when progressing through the fourth tutorial module. If you experience an issue that is not detailed, please email firstname.lastname@example.org or add and describe the problem on the discussion page.