Tuflow

Tutorial Module01 Archive: Difference between revisions

Browse history interactively
Content deleted Content added
VisualWikitext
Created page with "<ol> == Introduction == Please read the <u> Tutorial Model Introduction</u> before starting this tutorial. It outlines the programs requiring installation..."
 
No edit summary
 
(23 intermediate revisions by 5 users not shown)
Line 1:
<ol>
== Introduction ==
Please read the <u>[[Tutorial_ModelTutorial_Model_Archive | Tutorial Model Introduction]]</u> before starting this tutorial. It outlines the programs requiring installation and where the source data can be downloaded (e.g. aerial photos, DEM...).<br>
 
In this first module, a fully two-dimensional (2D) model is built. The steps required to build, run and review a basic 2D TUFLOW model are listed in the table of contents above and shown in the workflow diagram below.<br>
Line 31:
 
<ol>
<li>Set up the model directory and sub-directories as recommended in the list below (for a more detailed description , please seerefer the Folders and Filepath Section ofto the <u>[httphttps://wwwdocs.tuflow.com/Tuflow%20Documentation.aspx|classic-hpc/manual/latest/ TUFLOW User Manual])</u>). Alternatively, you can copy the TUFLOW folder and all sub-folders from the TUFLOW Folders Template folder in the supplied files to a local drive on your computer.<br>
''* If using SMS, the folder structure listed above is automatically created before running the model using the "Export TUFLOW files" command (see <u>[[Run TUFLOW from within SMS|Run TUFLOW from within SMS]]</u>).
<br>
Line 77:
''* If using SMS, you will need to open the DEM_M01.SMS.tin
<li> Create a projection file and write the template GIS files (to be used to build the model) for the project. For a description on how to do this please select your GIS package below.<br>
* <u>[[Tute_Arc_M01_Create_ProjectionTute_Arc_M01_Create_Projection_Archive|ArcGIS - Create Projection (not using the ArcTUFLOW Toolbox)]]</u>
* <u>[[Tute_MI_M01_Create_ProjectionTute_MI_M01_Create_Projection_Archive|Mapinfo - Create Projection]]</u>
* <u>[[Tute_QGIS_M01_Create_ProjectionTute_QGIS_M01_Create_Projection_Archive|QGIS - Create Projection (not using the QGIS TUFLOW Plugin)]]</u>
* <u>[[Tute_SMS_M01_Create_ProjectionTute_SMS_M01_Create_Projection_Archive|SMS - Create Projection and GIS Empty Files]]</u>
''ArcMap users can automate this step using the <u>[[TUFLOW_ArcGIS_Toolbox|ArcTUFLOw Toolbox]]</u>. Similarly, QGIS users can also automate the process using the <u>[[TUFLOW_QGIS_Plugin | QGIS TUFLOW Plugin]]</u>.''
<br>
Line 108:
 
=== Run TUFLOW to Create Empty (Template) GIS Files===
We now need to run TUFLOW using the TUFLOW Control File (TCF). There are a number of ways TUFLOW can be setup to run. In each case the TUFLOW executable is started with the TCF as the input. For more information on running TUFLOW please refer to the ''Managing and Starting Simulations'' section of the <u>[httphttps://wwwdocs.tuflow.com/Tuflow%20Documentation.aspx|classic-hpc/manual/latest/ TUFLOW User Manual]</u>. The most common ways are outlined below. We will be using a batch file for this tutorial, however any of the methods below will work.
 
<ol>
Line 120:
<br>
<li> Start TUFLOW from a batch file using the TCF file we have created ('''M01_5m_001.tcf'''). Follow the steps outlined in, <u>[[Run TUFLOW From a Batch-file | Running TUFLOW from a Batch-file]]</u> to create the batch file.
<li> Double click the created batch file (.bat) from Windows Explorer to execute the simulation. A console (DOS) window should appear as shown below:<br>
[[File:Tute M01 DOS Empties.png|frame|none]]
<br>
Line 163:
<u>'''SMS Users:''' </u>
<ol>
<li> For instructions on how to complete these steps using SMS, see <u>[[Tute SMS M01 Define 2D DomainDomain_Archive | Define the 2D Domain using SMS]]</u>.
</ol>
<br>
Line 169:
=== Define Elevations ===
In the previous section, the extent and dimensions of the 2D domain were defined. We now need to assign elevations at each 2D cell centre, mid-side and corner. These points are known as Zpts.<br>
Knowledge of 2D domain geometry is fundamental to understanding how TUFLOW works. A brief description on the computational function of each of the Zpts in a TUFLOW cell is given in the <u>[[Zpt_Description | Zpt Description]]</u> page. It is also highly recommended to read the ''2D Model domain Schematisation'' Section of the <u>[http://www.tuflow.com/Tuflow%20Documentation.aspx|TUFLOW User Manual]</u>.<br>
<br>
There are two methods to assign the elevations to the Zpts. The first is to directly input the elevation model into TUFLOW as either a TIN or gridded DEM dataset. TUFLOW will assign the elevations from the elevation dataset to Zpts within the DEM / TIN. This offers the following benefits:<br>
Line 175:
* Flexibility, if the cell size, dimension or rotation of the TUFLOW model is changed, TUFLOW will update the elevations automatically.
 
The second approach is to manually assign the elevation at each of the points using a GIS package. This approach involves TUFLOW writing out the Zpt layer in GIS format and the user defining the elevation at each point in a GIS package. For earlier versions of TUFLOW this method was the only option, it has largely been superseded, but is <u>[[Tute_M01_GIS_Based_Zpt_InspectionTute_M01_GIS_Based_Zpt_Inspection_Archive | still supported]]</u>. For the reasons listed above direct input of the elevation model as either a TIN or DEM is the preferred approach.
 
<u>'''ArcGIS, Mapinfo, and QGIS Users'''</u><br>
The process of using a direct TIN or DEM read into TUFLOW is outlined below. It is recommended that you have the DEM open in your GIS package, if you do not have it open it can be found in the '''Module_Data\DEMs\''' folder under your GIS package name. Please select <u>one</u> of the following approaches, for users without 12D or SMS the DEM method is recommended.
* <u>[[Tute_M01_Inspect_Zpts_ASCTute_M01_Inspect_Zpts_ASC_Archive|Direct input of DEM (recommended)]]</u>
* <u>[[Tute_M01_Inspect_Zpts_TINTute_M01_Inspect_Zpts_TIN_Archive|Direct input of 12D or SMS TIN]]</u>
 
<u>'''SMS Users'''</u>
The model elevations were previously defined during the <u>[[Tute SMS M01 Define 2D DomainDomain_Archive|Define 2D Domain Using SMS]]</u>) step. No furtyher actions are required. Please progress to the next step.<br>
<br>
 
Line 193:
<li>To set the active areas please select you GIS package below:</li>
 
* <u>[[Tute_M01_Active_Areas_MITute_M01_Active_Areas_MI_Archive|Define active area in Mapinfo]]</u>
* <u>[[Tute_M01_Active_Areas_ArcTUFLOWTute_M01_Active_Areas_ArcTUFLOW_Archive|Define active area in ArcGIS (arcTUFLOW)]]</u>
* <u>[[Tute_M01_Active_Areas_QGISTute_M01_Active_Areas_QGIS_Archive|Define active area in QGIS]]</u>
* <u>[[Tute_M01_Active_Areas_SMSTute_M01_Active_Areas_SMS_Archive|Define active area in SMS]]</u>
 
For ArcMap users not using the ArcTUFLOW toolbox, instructions can be found here: <u>[[Tute_M01_Active_Areas_ArcTute_M01_Active_Areas_Arc_Archive|Define active area in ArcGIS (no toolbox)]]</u>.
</ol>
<br>
Line 219:
Surface roughness or bed resistance values (eg. Manning’s n) are assigned to Materials values. The '''Module_Data\Module_01\''' folder already contains the materials table that we’ll use. We will review these in a GIS package, please select one of:
 
* <u>[[Tute_M01_Materials_MITute_M01_Materials_MI_Archive|Mapinfo]]</u>
* <u>[[Tute_M01_Materials_ArcTute_M01_Materials_Arc_Archive|ArcGIS]]</u>
* <u>[[Tute_M01_Materials_QGISTute_M01_Materials_QGIS_Archive|QGIS]]</u>
* <u>[[Tute_M01_Materials_SMSTute_M01_Materials_SMS_Archive|SMS]]</u>
 
In order for TUFLOW to associate the Manning’s n to the Material ID, a TUFLOW Materials File is required. This is can be either a text file (.tmf) or an .csv file which can be edited in Excel. In this tutorial model we will utilise the second (.csv) option.
Line 265:
 
For details on setting up the GIS layers required, please select your GIS package.<br>
* <u>[[Tute_M01_Boundaries_MITute_M01_Boundaries_MI_Archive|Mapinfo]]</u>
* <u>[[Tute_M01_Boundaries_ArcTute_M01_Boundaries_Arc_Archive|ArcGIS]]</u>
* <u>[[Tute_M01_Boundaries_QGISTute_M01_Boundaries_QGIS_Archive|QGIS]]</u>
* <u>[[Tute_M01_Boundaries_SMSTute_M01_Boundaries_SMS_Archive|SMS]]</u>
<br>
 
Line 361:
If your simulation has been successful, the console window should look like the image below.<br><br>
 
For instructions on how to complete these steps using SMS, see <u>[[Tute M01 Model Controls SMSSMS_Archive|Set Model Controls and Run the Simulation using SMS]]</u>. <br><br>
 
[[File:Tute M01 Simulation Finished.png|800px]]
Line 388:
Open and view the TUFLOW results in your viewing package, for instructions on this please select your results package below.<br>
*<u>[[View_Results_in_SMS_10.11_Archive|SMS 10.1]]</u>
*<u>[[View_Results_in_SMS_11.11_Archive|SMS 11.1]]</u>
*<u>[[View_Results_in_MapInfoView_Results_in_MapInfo_Archive|MapInfo]]</u>
*<u>[[View_Results_in_ArcGISView_Results_in_ArcGIS_Archive|ArcGIS]]</u>
*<u>[[View_Results_in_QGIS_with_the_TUFLOW_ViewerView_Results_in_QGIS_with_the_TUFLOW_Viewer_Archive|QGIS using TUFLOW plugin]]</u>
*<u>[[View_Results_in_QGISView_Results_in_QGIS_Archive|QGIS using raster and shapefiles]]</u>
 
== Reviewing Model Performance ==
Line 401:
With the <font color="blue"><tt>Write Check Files </tt></font> command specified in the TCF, TUFLOW will write a series of check files prior to the simulation starting. The check files are useful for reviewing the inputs have been correctly specified. This is particularly the case of long simulations, for example if you have a large model that runs for 12 hours and you are running a model with additional breakline (see Module 3), it is good to check that these features are correctly represented. This can be done using the check files whilst the 12 hour simulation is running, rather than waiting until the simulation finishes! We will introduce the check files as we progress with the tutorial modules.
In the first module we will use the _zpt_check file, which contains all the final Zpt elevations, for the active model area. Please select your GIS package.
* <u>[[Tute_M01_Zpt_Check_MITute_M01_Zpt_Check_MI_Archive|Mapinfo]]</u>
* <u>[[Tute_M01_Zpt_Check_ArcTute_M01_Zpt_Check_Arc_Archive|ArcGIS]]</u>
* <u>[[Tute_M01_Zpt_Check_QGISTute_M01_Zpt_Check_QGIS_Archive|QGIS]]</u>
* <u>[[Tute_M01_Zpt_Check_SMSTute_M01_Zpt_Check_SMS_Archive|SMS]]</u>
 
For information on other TUFLOW check files please refer to the <u>[[TUFLOW_Check_Files|Check Files]]</u> page of the TUFLOW Wiki.
 
=== TUFLOW Log file ===
The first place to look is at the final output in the DOSconsole window. If you missed this, for example if the model was run in batch mode this information is contained in the TUFLOW Log File (.tlf). Earlier on we add the following command to the TCF:<br>
<font color="blue"><tt>Log Folder </tt></font> <font color="red"><tt>==</tt></font> <tt>Log</tt><br>
 
Line 431:
Simulation FINISHED
</pre>
The next part of the ''Simulation Summary'' contains information on the messages issued by TUFLOW. Of note is the 2D Negative Depths (1). This indicates that the numerical solution has "overshot" and calculated a negative depth. Repeated negative depths are an indication that the model is not performing well. We will look at where these occur in the next [[Tutorial_Module01Tutorial_Module01_Archive#TUFLOW_Messages_Layers | section]].
<pre>
Total 1D Negative Depths: 0
Line 463:
 
=== TUFLOW Messages Layers ===
TUFLOW writes a number of messages, in increasing order of severity these are: Check --> Warning --> Error. Each of the messages generated by TUFLOW has a four digit ID code. A description of each of these messages is given in the message database section of this wiki: <u>[[TUFLOW_Message_How_ToTUFLOW_Messages | (TUFLOW Messages Database)]]</u>.
When a numerical model such as TUFLOW struggles to converge to a solution, spurious results such as negative depths can be generated. When this occurs TUFLOW creates a warning and writes this to the _messages.csv file and also to a GIS file. This can be opened in excel, or your GIS package.
<ol>
Line 489:
:The '''_ TUFLOW Simulations.log''' also contains a variety of other information, such as date, computer name, TUFLOW build version, the CPU hours and a other useful data.
*Time-series mass balance output. This is written to the same location as the 2D model results (in this case '''TUFLOW\results\M01\2d\'''). This file has the same name as the runfile (TCF) with the suffix, '''_MB.csv'''. As such the mass balance spreadsheet for this simulation is called '''M01_5m_002_MB.csv'''. Open the file in Excel. It contains a summary of the mass entering and leaving the model. Plot the first (time) and last (cumulative mass error %) columns within the spreadsheet to review the time varying mass error values.
*MB1 and MB2 map output. These 2D map outputs can be viewed using the methods described above in <u>[[Tutorial_Module01Tutorial_Module01_Archive#Viewing_Results_2| Viewing Results]]</u>.
The MB1 output tracks the convergence of the solution at each cell since the previous output time. The MB2 is the cumulative sum of the MB1 output. In the image below the MB2 output is shown at the final timestep (3 hours). It highlights areas in which the 2D solution has not performed well during the simulation.<br>
It can be seen that these are the areas along the main channel. The creek is approximately 5-10m wide and the flowpath is being represented by 1-2 grid cells. This is likely to be causing the issues.<br>
Line 496:
 
== Conclusion ==
To conclude, in this module we have created a 2D TUFLOW model. We have setup the required GIS and text based inputs and ran the simulation. We have visualised the results and reviewed the performance of the model.<br>
 
The model results, depths and velocity outputs look sensible. However, the model has a slight issue with mass balance, which appears in the main channel areas. This is most likely caused by the inadequate representation of the creek with the cell size adopted in the tutorial model. This cell size has been chosen to allow the model to be simulated quickly on most computers.<br>
 
In Module 3 we will model the creek area as an embedded 1D open channel, this should minimise the mass area noted in this tutorial. Reducing the cell size also allows for a better representation of the channel in the 2D model.<br>
 
See the <u>[[Tutorial_Module01Tutorial_Module01_Archive#Advanced_-_Model_Resolution_.28Optional.29 |Optional Section]]</u> below, in which we look at halving the cell size and the effect this has on the model results and simulation time.
 
Whilst reviewing the results, you may have noticed that the water was being held behind these road embankments (which were essentially acting as dams in the model. We will embed 1D culverts through the road embankments in <u>[[Tutorial_Module02Tutorial_Module02_Archive |Module 2]]</u>. This will introduce the 1D control files and linking of the 1D model to the 2D.
 
==Troubleshooting==
This section contains links to some common issues that may occur when progressing through the first module of the TUFLOW tutorial model. If you experience an issue that is not detailed on here please either send an email to [mailto:support@tuflow.com support@tuflow.com].<br>
 
*<u>[[Save_Date_ErrorSave_Date_Error_Archive|Save date of .tab file is later than .mif or .mid]]</u><br>
*<u>[[Tutorial_Troubleshoot_2014|ERROR 2014 - No active cells within SA inflow polygon]]</u>
*<u>[[Only_TUFLOW_DOS_WindowOnly_TUFLOW_Console_Window_Archive | Why does the TUFLOW DOSconsole Windowwindow open, though the TCF isn’t read and the simulation doesn’t execute?]]</u>
 
== Advanced - Model Resolution (Optional) ==
Line 528:
<u>'''SMS Users:''' </u>
<ol>
<li> For instructions on how to complete these steps using SMS, see <u>[[Tute_SMS_M01_2.5m5m_Archive | Change Cell Size Using SMS]]</u>.
</ol>
''TIP: If you forget any of the steps, the complete inputs files are provided as part of the download package (zip file).''
<br>
===Results===
Using the methods described above <u>[[Tutorial_Module01Tutorial_Module01_Archive#Viewing_the_ResultsViewing_Results | hereabove]]</u>, view the results in your preferred package. Do the results appear different? Is the increase in simulation time justified?
 
[[File:Tute M01 2p5m results SMS.png|450px]]
Line 554:
The model performs better with a smaller cell size, as the 5m resolution is a bit too coarse for representing the narrow in-bank flowpath in a 2D manner. In Module 3 we will overcome this issue by modelling the creek using a 1D model, which will be dynamically linked with the 2D model.<br>
<br>
It is worth noting the increase in runtime, by halving the cell size by a factor of 2, we have four times as many cells (each 5m x 5m cell is now four 2.5m x 2.5m cells), we also needed to reduce the timestep, as the Courant number is directly related to cell size (refer to the <u>[https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW manualManual]</u>) this would normally be reduced by a factor 2 as well. This translates to an approximate increase in runtime of 8 (four times the number of cells and half the timestep). Choosing an appropriate cell size that allows representation of the hydraulics whilst resulting in realistic run times is an important part of the modelling process. With some planning you should be able to avoid a model that requires excessive run times!<br>
<br>
The following postWiki on the TUFLOW forumpage gives some guidance on <u>[http://www.tuflow.com/forum//index.php?showtopic=937[Estimating_Runtimes | estimating model runtimes]]</u> based on the model area and cell size.
 
== Advanced - HPC Solver (Optional) ==
This section will introduce how to run the model TUFLOW’s HPC (Heavily Parallelised Compute) solver, and how to fix some common issues that may occur when trying to run a simulation using Graphics Processing Unit (GPU) hardware. Please see [[HPC_Features_Archive | HPC Features Archive]] for more information on TUFLOW HPC features supported in the 2017 release.
 
TUFLOW HPC can run between 10 and 100 times faster than TUFLOW Classic using NVidia Graphics Processing Units (GPU)(depending on the model configuration and hardware performance). <br><br>
Line 576:
<u>'''SMS Users:''' </u>
<ol>
<li> For instructions on how to complete these steps using SMS, see <u>[[Tute_SMS_M01_HPCTute_SMS_M01_HPC_Archive | TUFLOW HPC Using SMS]]</u>.
</ol>
''TIP: If you forget any of the steps, the complete input files are provided as part of the download package (zip file).''
<br>
===Results===
Using the methods described above in the <u>[[Tutorial_Module01Tutorial_Module01_Archive#Viewing_Results | Viewing Results]]</u> section.
* Check the simulation logs in the DOSconsole window, .tlf and .hpc.tlf log files.
* View the results in your preferred package.
Do the logs and results appear different? Did the simulation run faster using the GPU hardware? For more information about computer hardware and simulation speed, please refer to the <u>[[Hardware_Benchmarking | Hardware Benchmarking Page]]</u>.
Line 601:
</ol>
<br>
If you experience an issue that is not detailed above please send an email to [mailto:support@tuflow.com support@tuflow.com]<br>
Retrieved from "https://wiki.tuflow.com/Tutorial_Module01_Archive"