Tutorial Module08

From Tuflow
Jump to: navigation, search


    In this module we will further develop the model from Module 07. We will be developing a direct rainfall model where a rainfall hyetograph is applied to all active cells within the model boundary. This hyetograph (rainfall versus time) will replace the hydrograph (flow versus time) inflow boundary used in previous modules.

    In this tutorial we will be changing the main river flow to a simple steady state base flow and focusing on the direct rainfall.

    The steps we will be completing in this tutorial are:

    • Apply rainfall over the study area;
    • Apply depth-varying roughness for selected landuses; and
    • Apply initial and continuing rainfall losses

    GIS and Model Inputs

    The steps necessary to modify each of the GIS inputs are demonstrated in MapInfo, ArcGIS and QGIS. At each stage please select your GIS package to view relevant instructions. For this tutorial a hyetograph and polygon representing the rainfall area has been provided.

    Direct Rainfall

    This part of the tutorial will demonstrate how to apply direct rainfall to a model. We will also create a new boundary conditions database to reference the hyetograph. Follow the instructions below for your preferred GIS package.

    Depth Varying Roughness and Rainfall Losses

    This part of the module will demonstrate how depth-varying roughness and rainfall losses can be applied to landuses specified within the model.

  1. Start by opening the materials.csv file found in the TUFLOW\model folder.
  2. We will be applying depth-varying roughness to three of the landuses within our study area. Amend the second column for Material IDs 1 (pasture), 3 (buildings) and 11 (maintained grass) as shown in the figure below.

    M08 Material IDs.png

    Four numbers (y1, n1, y2, n2) are added to each row separated by commas and are applied as follows; below depth y1 (m or ft) a Manning’s n value of n1 is applied; above y2, n2 is applied, and between y1 and y2, the Manning’s n value is interpolated between n1 and n2. The default interpolation method uses a curved fit so that the n values transition gradually.

    For example, for Material ID 1, for depths of water below 0.03m a Manning's n value of 0.10 is applied. For depths of water greater than 0.1m, a Manning's n value of 0.06 is applied. Between 0.03 to 0.1m, a Manning's n value is interpolated between 0.1 and 0.06. For all other Material IDs, the Manning’s n value specified in the second column will be applied at all depths, i.e. a value of 0.022 for Material ID 2.

  3. Next we will amend the Materials.csv file further to include initial and continuing losses. Amend the third column as shown in the figure below:

    M08 Material Continuing Losses.png

    The first number specified in the third column is an initial rainfall loss (in mm or inches). The second number is a continuing rainfall loss (in mm/hr or inches/hr).
    Note that these rainfall losses applied through a materials definition file are different to the losses that are applied through a TUFLOW soils file (.tsoilf). Rainfall losses represent rainfall that does not reach the ground whereas soil infiltration losses infiltrate ponded water into the ground. Rainfall losses are removed prior to application to the model as a boundary on 2D cells.

  4. Save the file as materials_depth_varying.csv. It is now ready to be used in the model.

    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. We will incorporate the direct rainfall changes into the base ('EXG') and developed ('DEV') cases introduced in Module 7.


    There has been one change to the model that impacts the boundary conditions of the model:

    • We have created a new 2d_rf layer to read in direct rainfall over our proposed development.

  5. Begin by opening M07_5m_001.tbc in your text editor. Save the file as M08_5m_001.tbc.
  6. Within the first If Scenario, change 'DEV' to 'DEV|EXG'. In the following Else If Scenario statement, delete 'EXG' from the line. The vertical bar "|" allows you to include additional scenarios into the current IF statement without the need to create a new one.
  7. Comment out the Read GIS SA PITS command within the If Scenario logic block and the Read GIS SA command by placing an exclamation mark "!" at the beginning of the lines. The commands will now be treated as comments and ignored by TUFLOW.
  8. Within the If Scenario logic block and after the commented out line !Read GIS SA PITS == mi\2d_sa_M07_001.MIF add the following:
    MapInfo Users
    Read GIS RF == mi\2d_rf_M08_001.MIF
    QGIS or ArcGIS Users
    Read GIS RF == gis\2d_rf_M08_001_R.SHP
    Tip - indenting commands within your If Scenario statements makes your model more readable
  9. Save the file. The tbc file is now ready to be used.


    We will need to create a new tcf file that references the new tbc, bc_dbase, and materials.csv files.

  10. Open M07_5m_~s1~_001.tcf and save as M08_5m_~s1~_001.tcf.
  11. Update the following commands:
    BC Control File == ..\model\ M08_5m_001.tbc
    BC Database == ..\bc_dbase\bc_dbase_M08_001.csv
    Read Materials File == ..\model\Materials_depth_varying.csv
  12. We will also specify a new output folder for the results of this module:
    Output Folder == ..\results\M08\2d
  13. Lastly, we will write an additional map output so we can view how Manning’s n values change over time. Update the following command:
    Map Output Data Types == h V q d n
  14. Save the file. The tcf file is now ready to be used.

    Run the Simulation

    Using your preferred method for starting TUFLOW, run the newly created M08_5m_~s1~_001.tcf. Please refer to Module 1 for a detailed description of the various methods for running a TUFLOW simulation.
    In this tutorial we are using a batch file to run simulations. The command line in our batch file will be similar to that used in Module 7:

    set TUFLOWEXE=C:\TUFLOW\Releases\2013-12\w64\TUFLOW_iSP_w64.exe
    set RUN=start "TUFLOW" /wait "%TUFLOWEXE%" -b
    %RUN% -s1 EXG M08_5m_~s1~_001.tcf

    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 compiled and the simulation started, we can review the check files to ensure the changes have been correctly applied. The following section of this module outlines how the generated check files can be used to review each of the key changes we have made to the model.
    This is a key stage, you may have noticed in the DOS screen that although the model completed, there was high mass balance error.

    The changes we have made to the model can be reviewed within the tlf (TUFLOW log file) located in the TUFLOW\runs\log folder. The tlf file shows the hyetograph read into the model and its conversion to a hydrograph. This is carried out to smooth the transition from one rainfall period to another.

    M08 Review Check Files tlf.png

    The .tlf file can also be used to check the depth-varying roughness and rainfall losses that we applied to selected landuses. The figure below shows a sample of the information provided.

    M08 Review Check Files tlf information.png

    Review the Results

    Once the simulation has finished, it is good practice to view the Cumulative Mass Error (CME) of the model as it provides a good indication of the stability of the model. The CME may be viewed in a number of different ways. The _ TUFLOW Simulations.log file written to the TUFLOW\runs folder, provides a summary of CME along with other information such as the name of the computer used to run the model and the TUFLOW build used. The figure below shows the output from the log file for our model simulation. The value highlighted is the peak CME throughout the whole simulation. The value of -10.42% is very much outside the recommended range of +/- 3% and tells us the CME needs to be looked into in more detail.

    M08 Simulation summary.png
    Three csv files providing further information on CME have also been written to the TUFLOW\results\1D and TUFLOW\results\M08\2D. These are:

    • M08_5m_001_MB1D.csv: Mass balance reporting for all 1D domains
    • M08_5m_001_MB2D.csv: Mass balance reporting for all 2D domains
    • M08_5m_001_MB.csv: Mass balance reporting for the overall model (1D and 2D domains)

    Opening the M07_5m_001_MB.csv file and plotting the Cum ME (%) column produces the figure below. The high CME values are seen to occur in the first half hour of our simulation

    M08 EXG CME.png

    The high CME values in our model are due to some fundamental changes to the run parameters that may need to be incorporated into the majority of direct rainfall models. These are:

    • Adjustment of the Cell Wet/Dry depth parameter. You may have spotted in the figure of the tlf file above that a message was outputted:

    “WARNING 2317 - For direct rainfall models set "Cell Wet/Dry Depth == 0.0002" if CME exceeds 1%.”

    As with all checks, warnings and errors, further information can be found on the TUFLOW Message Database. More information on this message specifically can be found here. The Cell Wet/Dry Depth command specifies the depth at the cell in which TUFLOW transitions from wet to dry and vice versa. The depth should be selected according to the magnitude of flooding depths. As direct rainfall models typically have a high proportion of shallow sheet flow, a wet/dry depth of less than 1mm (eg. 0.0002m) may be required.
    To make this change, open the file M08_5m_~s1~_001.tcf found within the TUFLOW\Runs folder and save as M08_5m_~s1~_002.tcf. Add the following commands anywhere within the .tcf:

    Cell Wet/Dry Depth == 0.0002

    • Double Precision

    So far we have been simulating the model for the Single Precision version of TUFLOW. This can be confirmed in the screenshot above of the _ TUFLOW Simulations.log file. For direct rainfall models, it is recommended that the Double Precision version of TUFLOW is used.
    The difference between double and single precision is the number of decimal points used by the Tuflow solver. For most applications, the number of decimal points used in single precision is suitable, however with direct rainfall models we typically have very shallow depths. At these shallow depths more decimal points are needed or the rounding error can be significant. For more information on single vs double precision, refer to this forum post.

    Add the following command anywhere within M08_5m_~s1~_002.tcf.

    Model Precision == Double

    Inclusion of the Model Precision command will ensure the model is always simulated with the correct version. If the model is simulated with a version other than that intended, the simulation will be stopped and an error outputted.

    The final changes we need to make are to the batch file. Update the file with the changes highlighted in red:

    set TUFLOWEXE=C:\TUFLOW\Releases\2013-12\w64\ TUFLOW_iDP_w64.exe
    set RUN=start "TUFLOW" /wait "%TUFLOWEXE%" -b

    %RUN% -s1 EXG M08_5m_~s1~_002.tcf

    Save the .tcf and batch files and re-run the model. Once the model has finished simulating, open the M08_5m_002_MB.csv file and plot the Cum ME (%) column. The results should show a reduction in CME to within the recommended range of +/-3%.

    M08 001 002 MB.png

    Viewing the Results

    Open the 2D results in your results viewer or import to your GIS package.
    For more information on how to do this, refer to Tutorial Module 1

    This module has applied the rainfall boundary to every active 2D cell. To aid visualisation of the results, an appropriate cut-off depth is typically used to only display the results above the specified depth. The depth chosen differentiates between shallow, sheet flow and depths classed as 'flooded'. The cut-off can be specified directly in the tcf using the command Map Cutoff Depth or through post-processing of the results.
    The below image shows the maximum predicted flood depth, with a cut-off depth of 0.1m applied.

    M08 D max.PNG
    To post process the gridded results with a cut-off depth, the asc_to_asc utility may be used.

    Visualising the velocity vectors in direct rainfall models provides a means to investigate flow paths and their behaviour. Note in the below image that a cut-off depth has been applied to the depth grid, but not the velocity vectors, thus the velocity and direction of shallow sheet flow can still be seen.
    M08 D Vector.PNG

    This model has allowed for the Manning's n roughness values for select landuses to vary with flood depth. This variation over time may be visualised by viewing the 'n' map output type. This additional dataset is located with the simulation results (n.dat or within the xmdf file) and can be visualised using the same methods as for all other map output types. The below image is a snapshot of the manning's 'n' value at 1.6hrs into the simulation.
    M08 N.PNG


    In this module, we have applied direct rainfall over the model. We have specified depth-varying roughness and rainfall losses to selected landuses. This module also highlights the need to lower the Cell Wet/Dry Depth and use the Double Precision version of TUFLOW for the majority of direct rainfall models, particularly those experiencing high mass errors.

    Extension Exercises

    For an extra challenge, run the developed case and review the model results.
    How do the results change with the development?
    Think back to the pit and pipe system developed in Module 7. For this module, inflows were applied directly into the pits. How does using direct rainfall change the predicted flooding mechanism through the drainage network?

    The below dot points provides some guidance in undertaking these extension exercises.

    • Change the scenario in the batch file from the existing 'EXG' to the developed case 'DEV'.
    • Using the instructions in Module 5, look at the impact the development and the pit and pipe network has on the surface water flow. Are the results as you expect? How do they compare to the impacts assessed in Module 5?


    • Check the flow through the pit and pipe network in the developed case. How does it perform? What would happen to the development if you took the drainage network out?

    M08 pipes.png
    For added information on the application of rainfall boundaries within a model, you can include the Cumulative Rainfall (RFC) and Rainfall Rate (RFR) in the Map Output Data Type command. These outputs will track the rainfall in mm/hr (RFR) and the total rainfall depth applied to the model over time (RFC). Note that these output formats are only available for the 2016-03 release of TUFLOW or later.
    Tutorial08 RFR.PNG


    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). 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 cannot 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 _messages.mif or _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 support@tuflow.com or add and describe the problem on the discussion page.