Tuflow - User contributions [en]

TUFLOW Message 3002

2026-04-22T00:45:37Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 3002 - Non-CUDA_SUCCESS code returned ERROR 3002: Check that you have the correct NVIDIA driver installed 
|alt_msg= ERROR 3002 - HPC has reported an error - see .hpc.tlf 
|type=[[ERROR]]
|message_desc=The GPU driver appears to be installed, but one of the following has occurred:
* The GPU driver failed to initialise.
* A compute context could not be created on the selected device.
* The ptx code could not be compiled for the selected device. (TUFLOW 2025 and earlier)

|suggestions=
* Check that the .ptx files (TUFLOW 2025 and earlier) or .fatbin files (TUFLOW 2026 onwards) are in the same directory as the TUFLOW executable (there should be four of them). If needed, download the release again from the website.
* Upgrade to the latest NVidia drivers for your system from the NVIDIA website.

|uplink=[[3xxx_TUFLOW_Messages|3xxx Messages]]
}}

TUFLOW Message 3704

2026-03-25T05:29:55Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 3704 - CATCH models require at least one groundwater layer. |alt_msg=NA |type=ERROR |message_desc=TUFLOW CATCH models require one or more groundwater layers. |suggestions=Include at least one vertical groundwater layer in the the HPC Catchment Hydraulic Model. |uplink=3xxx Messages }}"

{{TUFLOW_Message
|tuflow_message=ERROR 3704 - CATCH models require at least one groundwater layer.
|alt_msg=NA
|type=[[ERROR]]
|message_desc=TUFLOW CATCH models require one or more groundwater layers.
|suggestions=Include at least one vertical groundwater layer in the the HPC Catchment Hydraulic Model.
|uplink=[[3xxx_TUFLOW_Messages|3xxx Messages]]
}}

TUFLOW Message 0055

2026-03-25T03:55:20Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=WARNING 0055 - ulimit is low and this could SIGSEGV issues to occur. |alt_msg=NA |type=WARNING |message_desc=This message only occurs for TUFLOW on Linux. When running on Linux, TUFLOW checks the stack size limits. If the soft limit is less than 100MB TUFLOW will issue WARNING 0055. On Windows a stack size for the executable is set at 100MB. |suggestions=If the soft stack limit is too small, this can TUFLOW to crash with SI..."

{{TUFLOW_Message
|tuflow_message=WARNING 0055 - ulimit is low and this could SIGSEGV issues to occur.
|alt_msg=NA
|type=[[WARNING]] 
|message_desc=This message only occurs for TUFLOW on Linux. 
When running on Linux, TUFLOW checks the stack size limits. If the soft limit is less than 100MB TUFLOW will issue WARNING 0055. On Windows a stack size for the executable is set at 100MB.
|suggestions=If the soft stack limit is too small, this can TUFLOW to crash with SIGSEGV (segmentation fault) to occur. If this occurs, raise the stack limit by increasing the ulimit.

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 2629

2026-03-25T03:17:27Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 2629 - Counted no rainfall hyetographs. |alt_msg=NA |type=ERROR |message_desc=This error message only occurs if using a TUFLOW Rainfall Control File (.trfc). When reading rainfall hyetographs from <tt>Read GIS RF Polygons</tt> and <tt>Read GIS RF Points</tt> no hyetographs were found. |suggestions=Ensure the rainfall hyetographs have been specified with either 2d_rf point or po..."

{{TUFLOW_Message
|tuflow_message=ERROR 2629 - Counted no rainfall hyetographs.
|alt_msg=NA
|type=[[ERROR]]
|message_desc=This error message only occurs if using a TUFLOW Rainfall Control File (.trfc). When reading rainfall hyetographs from <tt>Read GIS RF Polygons</tt> and <tt>Read GIS RF Points</tt> no hyetographs were found.
|suggestions=Ensure the rainfall hyetographs have been specified with either 2d_rf point or polygon objects.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2628

2026-03-25T03:13:20Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 2628 - Rainfall polygons contain a mix of named and non named.
|alt_msg=NA
|type=[[ERROR]]
|message_desc=This error message only occurs if using a TUFLOW Rainfall Control File (.trfc) with <tt>RF Interpolation Method</tt> <tt>== </tt><tt>Poly</tt>. If all rainfall polygons contain names, then rainfall points are not used. If all rainfall polygons are have blank names then rainfall points are used. However, mixing named and non named rainfall polygons is not possible - this causes ERROR 2628 to be issued.
|suggestions=Either apply names to all polygons and use polygon attributes, or set all polygons to blank names and use rainfall points.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2627

2026-03-25T03:09:05Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 2627 - Using Rainfall Polygons attributes and ignoring points.
|alt_msg=NA
|type=[[WARNING]]
|message_desc=This warning message only occurs if using a TUFLOW Rainfall Control File (.trfc) with <tt>RF Interpolation Method</tt> <tt>== </tt><tt>Poly</tt>. If all rainfall polygons contain names, then rainfall points are not used and WARNING 2627 is issued.
|suggestions=Rainfall points are not required or used when rainfall polygons with attributes are specified and these can be removed from the .trfc file.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2627

2026-03-25T03:06:07Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 2627 - Using Rainfall Polygons attributes and ignoring points.
|alt_msg=NA
|type=[[CHECK]]
|message_desc=This warning message only occurs if using a TUFLOW Rainfall Control File (.trfc) with <tt>RF Interpolation Method</tt> <tt>== </tt><tt>Poly</tt>. If all rainfall polygons contain names, then rainfall points are not used and WARNING 2627 is issued.
|suggestions=Rainfall points are not required or used when rainfall polygons with attributes are specified and these can be removed from the .trfc file.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2626

2026-03-25T03:02:57Z

Par:

{{TUFLOW_Message
|tuflow_message=CHECK 2626 - Rainfall polygon names are blank, will use point attributes for names and rf factors.
|alt_msg=NA
|type=[[CHECK]]
|message_desc=This check message only occurs if using a TUFLOW Rainfall Control File (.trfc) with <tt>RF Interpolation Method</tt> <tt>== </tt><tt>Poly</tt>. If all rainfall polygons contain blank names, then rainfall points attributes (Name, F1 and F2) are used and any polygon attributes (e.g. F1 and F2) are ignored and CHECK 2626 is issued.
|suggestions=Review that using rainfall point data is intended.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2625

2026-03-25T02:02:55Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 2625 - No polygons read for "RF Interpolation Method == Poly" |alt_msg=ERROR 2625 - No triangles read for "RF Interpolation Method == TIN" |type=ERROR |message_desc=These ERROR messages are issued when insufficient data is specified in the TUFLOW rainfall control file (.trfc). If using <tt>RF Interpolation Method</tt> <tt>== </tt><tt>Poly</tt>" then v..."

{{TUFLOW_Message
|tuflow_message=ERROR 2625 - No polygons read for "RF Interpolation Method == Poly"
|alt_msg=ERROR 2625 - No triangles read for "RF Interpolation Method == TIN"
|type=[[ERROR]]
|message_desc=These ERROR messages are issued when insufficient data is specified in the TUFLOW rainfall control file (.trfc). If using <tt>RF Interpolation Method</tt> <tt>== </tt><tt>Poly</tt>" then valid rainfall polygons must be read in with the command "<tt>Read GIS RF Polygons</tt> <tt>== </tt><tt><gis layer></tt>".
 
Likewise, if using <tt>RF Interpolation Method</tt> <tt>== </tt><tt>TIN</tt>" then valid triangles must be read with the command "<tt>Read GIS RF Triangles</tt> <tt>== </tt><tt><gis layer></tt>".

|suggestions=Review the inputs and ensure that valid polygons or triangles are specified for the RF Interpolation Method.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2624

2026-03-25T01:54:02Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=CHECK 2624 - "Maximum RF Location" command is no longer used. |alt_msg=CHECK 2624 - "Maximum Hyetograph Point" command is no longer used. |type=CHECK |message_desc=Prior to the 2026 release of TUFLOW the rainfall control file (.trfc) commands <tt>Maximum RF Location</tt> and <tt>Maximum Hyetograph Point</tt> could be used to control the memory allocated for reading and processing of..."

{{TUFLOW_Message
|tuflow_message=CHECK 2624 - "Maximum RF Location" command is no longer used.
|alt_msg=CHECK 2624 - "Maximum Hyetograph Point" command is no longer used.
|type=[[CHECK ]]
|message_desc=Prior to the 2026 release of TUFLOW the rainfall control file (.trfc) commands <tt>Maximum RF Location</tt> and <tt>Maximum Hyetograph Point</tt> could be used to control the memory allocated for reading and processing of rainfalls. From the 2026 release onwards this is no longer required as the these are dynamically allocated based on the input files. 
These commands are ignored from the 2026 release onwards.
|suggestions=These commands can be removed from the .trfc if the model will not be simulated with versions of TUFLOW prior to 2026.0.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2623

2026-03-25T01:44:37Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 2623 - Overlapping rainfall areas - overwriting.
|alt_msg=NA
|type=[[WARNING]]
|message_desc=This message is only produced for a rainfall control file (.trfc) with "RF Interpolation Method == Poly". When processing rainfalls from a .trfc, rainfall grids are produced. Each raster pixel in the output rainfall is assigned a rainfall based on the polygon that it falls within. If overlapping polygons occur then WARNING 2623 is produced and the subsequent polygon with overwrite the previous polygons for that location. 
|suggestions=Ensure that rainfall polygons do not contain overlapping areas.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 0934

2026-03-24T05:13:55Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 0934 - Unable to load CodeMeter Runtime Library, please ensure it is installed.
|alt_msg=NA
|type=[[ERROR]] 
|message_desc=When using CodeMeter WIBU dongles, the CodeMeter Runtime needs to be installed. ERROR 0934 indictaes that TUFLOW has not been able to successfully load the CodeMeter Runtime.

|suggestions=Check that the CodeMeter Runtime is installed, see [[Wibu_Dongles#Installation_of_CodeMeter_RunTime_Kit|Installation of CodeMeter Runtime Kit for further instructions.]]

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0934

2026-03-24T05:13:45Z

Par:

TUFLOW Message 0054

2026-03-24T05:13:29Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=CHECK 0054 - ulimit not set to maximum. |alt_msg=NA |type=CHECK |message_desc=This message only occurs for TUFLOW on Linux. When running on Linux TUFLOW checks the soft and hard stack size limits. If the soft limit is less than hard limit then CHECK 0054 is issued. By default TUFLOW will attempt to raise the soft limit to the hard limit, unless the command line argument <tt>-nua</tt> is specified. |suggestions=If the soft s..."

{{TUFLOW_Message
|tuflow_message=CHECK 0054 - ulimit not set to maximum.
|alt_msg=NA
|type=[[CHECK]] 
|message_desc=This message only occurs for TUFLOW on Linux. 
When running on Linux TUFLOW checks the soft and hard stack size limits. If the soft limit is less than hard limit then CHECK 0054 is issued. By default TUFLOW will attempt to raise the soft limit to the hard limit, unless the command line argument <tt>-nua</tt> is specified.
|suggestions=If the soft stack limit is too small, this can TUFLOW to crash with SIGSEGV (segmentation fault) to occur. If this occurs, raise the ulimit.

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0934

2026-03-24T04:51:01Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 0934 - Unable to load CodeMeter Runtime Library, please ensure it is installed. |alt_msg=NA |type=ERROR |message_desc=When using CodeMeter WIBU dongles, the CodeMeter Runtime needs to be installed. ERROR 0934 indictaes that TUFLOW has not been able to successfully load the CodeMeter Runtime. |suggestions=Check that the CodeMeter Runtime is installed, see Wibu_Dongles#Installation_of_CodeMeter_RunTime_Kit|Installation o..."

TUFLOW Message 3056

2026-03-24T03:51:10Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 3056 - Unable to load CUDA libraries. Check that you have NVidia GPU driver installed |alt_msg=NA |type=ERROR |message_desc=When using GPU hardware to run simulations, the GPU driver is only loaded when required (lazy loaded). ERROR 3056 indictaes that TUFLOW has not been able to successfully load the NVidia driver. |suggestions=Check that running on Nvidia GPU hardware is desired, i.e. the computer has an NVidia GPU. <b..."

{{TUFLOW_Message
|tuflow_message=ERROR 3056 - Unable to load CUDA libraries. Check that you have NVidia GPU driver installed
|alt_msg=NA
|type=[[ERROR]] 
|message_desc=When using GPU hardware to run simulations, the GPU driver is only loaded when required (lazy loaded). ERROR 3056 indictaes that TUFLOW has not been able to successfully load the NVidia driver.

|suggestions=Check that running on Nvidia GPU hardware is desired, i.e. the computer has an NVidia GPU.
 
Check that NVidia drivers are installed, an easy check for this is to type "nvidia-smi" into the Command Prompt or Powershell on Windows or a Terminal shell on Linux 
This should produce an output like the below: 
[[File:Example nvidia-smi output.png|600px]]

If an nvidia GPU is present but nvidia-smi is unable to be found then the drivers may need to be installed. 
Check the the CUDA version is at least 12.9. 
If running Linux on WSL then the WSL lib location may need to be added to the $LD_LIBRARY_PATH environment variable. For example: 
<tt>export LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH</tt>

|uplink=[[3xxx_TUFLOW_Messages|3xxx Messages]]
}}

File:Example nvidia-smi output.png

2026-03-24T03:42:11Z

Par:

Output from nvidia-smi on linux

TUFLOW Message 2801

2025-06-02T04:56:40Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 2801 - Unable to allocate memory for Quadtree cell centres.
|alt_msg=Numerous with the form "ERROR 2801 - Unable to allocate memory for Quadtree ..." 

|type=[[ERROR]]
|message_desc=TUFLOW was unable to allocate memory required for storing Quadtree data.
|suggestions=Review the console or log file output, prior to the ERROR should be an indicating of the amount of memory required. For example: 
<tt>Allocating memory for Quadtree mesh data, memory required <value>kB. 
ERROR 2801 - Unable to allocate memory for Quadtree cell centres 
</tt>
Use Windows Task Manager to see how much memory is free.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2582

2025-06-02T04:45:51Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 2582 - Calibration points not supported for this build - please notify [mailto:support@tuflow.com support@tuflow.com].
|alt_msg=NA 

|type=[[WARNING]]
|message_desc=Feedback on the calibration point feature indicated that this was not being used, when the GIS formats were extended to include SHP and GPKG this feature was not implemented.
|suggestions=If you are attempting to use this functionality, please contact [mailto:support@tuflow.com support@tuflow.com] so that we look to implement this.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2582

2025-05-29T02:27:53Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 2582 - Calibration points not supported for this build - please notify [mailto:support@tuflow.com support@tuflow.com].
|alt_msg=NA 

|type=[[WARNING]]
|message_desc=Feedback on the calibration point feature indicated that this was not being used, when the GIS formats were extended to include SHP and GPKG this feature was not implemented.
|suggestions=If you are attempting to use this functionality, please contact [mailto:support@tuflow.com support@tuflow.com].

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 1430

2025-05-28T10:34:09Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 1430 - XF file is not a CSV XF file. Re-reading csv file.
|alt_msg=ERROR 1430 - Could not find 1D Node for NA Table. Please check if all QT bc lines have selected active 2D cells. 

|type=[[WARNING]] [[ERROR]]
|message_desc=These are two separate and unrelated errors. This will be fixed in a future version. 
 
WARNING 1430 - XF file is not a CSV XF file. Re-reading csv file. Indicates that an .xf file that is being read from a input .csv is not in the correct format and the original input file is being read. 
 
ERROR 1430 - Could not find 1D Node for NA Table. Please check if all QT bc lines have selected active 2D cells. Can occur when a 2D QT boundary does not select any 2D cells.

|suggestions= 
WARNING 1430 - XF file is not a CSV XF file. Re-reading csv file. After issuing this message TUFLOW should re-create the .xf file so future simulations do not have the same issue. However, if this message is repeated over numerous simulations, please contact [mailto:support@tuflow.com support@tuflow.com]. 
 
ERROR 1430 - Could not find 1D Node for NA Table. Please check the location of QT boundaries to ensure that have active 2D cells.

|uplink=[[1xxx_TUFLOW_Messages|1xxx Messages]]
}}

TUFLOW Message 0253

2025-05-28T06:07:43Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 0253 - Failed to read coordinates for an object in a GIS layer.
|alt_msg=NA
|type=[[ERROR]]
|message_desc=When reading in an objects coordinates from a GIS layer TUFLOW has been unable to read these. This could be null or corrupt geometries stored in the file. If using the Geopackage file format, the message will also include "GPKG row no: <row number>" to allow the object to be easily found.

|suggestions=Find and remove null geometry objects from the layer, by deleting the reported row number, or select in GIS e.g. using the 'remove null geometry tool' in QGIS. Another option is to select all objects within the model area using a selection tool like 'Select Features by Area' and saving the selection as a new layer. The selection tool should only select objects with valid geometry.
 
If the issue persists, please contact [mailto:support@tuflow.com support@tuflow.com], with the log file (.tlf) and the GIS layer.
|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0621

2025-05-27T23:46:24Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 0621 - Unable to get location of program data. Return status:<>.
|alt_msg=WARNING 0621 - Unable to get program data location, from environment variable. 
WARNING 0621 - Unable to get username, supressing default simulation log folder.
|type=[[WARNING]]
|message_desc=TUFLOW uses the Windows Environment variables "USERNAME" and "PROGRAMDATA". These are used for the determining the "TUFLOW Licence Settings file" search paths and also for setting the output location of the "Simulations Log Folder". This message indicates that TUFLOW has received an ERROR from Windows when trying to get this information.
|suggestions=As TUFLOW has been unable to get this information, the licence settings and simulations log folder may not be working as expected. 
Refer to Section "Running Simulations" [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for information on the TUFLOW Licence Settings (.lcf). 
Refer to TCF Appendix of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for information on the "Simulations Log Folder". 
Please contact [mailto:support@tuflow.com support@tuflow.com] TUFLOW log file and information on Windows version.

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0620

2025-05-27T23:22:57Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 0620 - Issue setting console title. Please contact support@tuflow.com.
|alt_msg=WARNING 0620 - Issue freeing console. Please contact support@tuflow.com. 
WARNING 0622 - Issue setting console title. Please contact support@tuflow.com.
|type=[[WARNING]]
|message_desc=When running TUFLOW sets the console window title to include the TUFLOW Version, the simulation name and the hardware. This message indicates that there was an error returned from Windows when TUFLOW tried to set the title.
|suggestions=This is very rare message! This should not affect the TUFLOW simulation or results. However, please contact [mailto:support@tuflow.com support@tuflow.com] with information on the Windows version and TUFLOW log file so that we can investigate.

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0622

2025-05-27T23:22:17Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 0622 - Issue setting console title. Please contact [mailto:support@tuflow.com support@tuflow.com].
|alt_msg=NA 

|type=[[WARNING]]
|message_desc=This is a duplicate message, please see [[TUFLOW_Message_0620| WARNING 0620]]
|suggestions=This is a duplicate message, please see [[TUFLOW_Message_0620| WARNING 0620]]

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0620

2025-05-27T23:20:38Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 0620 - Issue setting console title. Please contact support@tuflow.com.
|alt_msg=WARNING 0620 - Issue freeing console. Please contact support@tuflow.com. 

|type=[[WARNING]]
|message_desc=When running TUFLOW sets the console window title to include the TUFLOW Version, the simulation name and the hardware. This message indicates that there was an error returned from Windows when TUFLOW tried to set the title.
|suggestions=This is very rare message! This should not affect the TUFLOW simulation or results. However, please contact [mailto:support@tuflow.com support@tuflow.com] with information on the Windows version and TUFLOW log file so that we can investigate.

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0627

2025-05-27T23:13:55Z

Par:

{{TUFLOW_Message
|tuflow_message=WARNING 0627 - CSV file appears to contain multiple data blocks... skipping xf file generation.
|alt_msg=NA 
|type=[[WARNING]]
|message_desc=CSV files in TUFLOW can support multiple data blocks, one after the other in the file. This was done as prior to 2007 Excel (.xls) had a column limit of 256 in a single worksheet. To get around this, large datasets could be written with data split into vertical blocks in a file, like the schematic below:
 
[[File:Msg_0627_csv_xf_unsupported.JPG|200px]] 
 
After Excel increased the limit on the number of columns (in the .xlsx format) this style of .csv is rarely used. Whilst it is still supported in TUFLOW, it is not supported with the xf file format.
|suggestions=There are a number of ways to overcome this:
* Turning off XF files for the model (with the .tcf command "XF Files == OFF". Refer to TCF Appendix of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]
* Turning off XF files for the boundary data (with the .tcf command "XF Files Boundaries == OFF". Refer to TCF Appendix of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]
* Changing the format of the .csv file so that all data appears in the same data block, as per the schematic below. The last option is the preferred option, as this will allow the model to use XF files speeding up the initialisation.
 
[[File:Msg_0627_csv_xf_supported.JPG|400px]] 
 

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

File:Msg 0627 csv xf supported.JPG

2025-05-27T22:58:34Z

Par:

File:Msg 0627 csv xf unsupported.JPG

2025-05-27T22:56:41Z

Par:

TUFLOW Message 0623

2025-05-27T05:07:16Z

Par:

{{TUFLOW_Message
|tuflow_message=CHECK 0623 - No write permission for: <filepath and filename>. Skipping.
|alt_msg=NA 

|type=[[CHECK]]
|message_desc=TUFLOW has been not been able to open a file with write permission. This can only occur for some output files, with the most common file being the "_ All TUFLOW Simulations.log". 
There could be a number of reasons that TUFLOW is unable access the file in write mode including: 
* User does not have write permissions for that location or file. 
* Another TUFLOW simulation (or another process) currently has the file open. 
This check message can not occur for files such as the .tlf which are unique for each simulation and must be written, for example the .tlf file. As TUFLOW has been unable to open the file, no entry will be written for the simulation, but the simulation will still run.
|suggestions=
Check the user has write permissions in the location. 
If the user has the correct permissions, the most likely reason is that numerous simulations are started at the exact same time causing conflicts. To prevent this, avoid batch files that start multiple simulations at the same time (in a batch file the command timeout <number of seconds>, e.g. to create a 10 second delay use "timeout 10"). 
If the simulations log file is not required this can be turned off with the .tcf command "SIMULATIONS LOG FOLDER == Do not use". Refer to TCF Appendix of the [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]
|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 2937

2025-05-26T06:13:17Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=WARNING 2937 - "BED RESISTANCE DEPTH INTERPOLATION" only used for HQ curves in HPC solver. |alt_msg=NA |type=WARNING |message_desc..."

{{TUFLOW_Message
|tuflow_message=WARNING 2937 - "BED RESISTANCE DEPTH INTERPOLATION" only used for HQ curves in HPC solver. 
|alt_msg=NA
|type=[[WARNING]] 
|message_desc=Bed Resistance Depth Interpolation is not used in TUFLOW HPC (including Quadtree). When depth varying Manning's n values are used in HPC, interpolation between depths is linear. When using HQ curves that are calculated based on specified slope, the Bed Resistance Depth Interpolation setting is used.
|suggestions= Review whether command should be used in the model.
|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2320

2025-05-26T06:03:49Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 2320 - FC commands not yet supported in HPC or GPU solver.
|alt_msg=ERROR 2320 - Read TGF command not yet supported in HPC or GPU solver. 
ERROR 2320 - Read TGA command not yet supported in HPC or GPU solver. 
ERROR 2320 - TUFLOW 2016-03 GPU Solver does not support 1D links. 
ERROR 2320 - GLO commands not yet supported in HPC or GPU solver. 
ERROR 2320 - "Bed Resistance Values == CHEZY" not supported in HPC solver. 
ERROR 2320 - "Bed Resistance Values == MANNING M" not supported in HPC solver. 
WARNING 2320 - HPC or GPU Solver ignoring Read GIS Objects/Receptors commands. 
|type=[[WARNING]] 
[[ERROR]] 
|message_desc= Some TUFLOW Classic functionalities are not supported by the TUFLOW HPC solver.

|suggestions=

* If using a 2d_fc layer, change to a 2d_lfcsh layer which is supported by TUFLOW HPC.
* The 2016-03 TUFLOW GPU solver is a legacy feature, TUFLOW HPC (on GPU hardware) should be used instead.
* GLO commands are supported in TUFLOW HPC from the 2023-03-AD build and onwards.
* Read GIS Objects/Receptors commands are supported in TUFLOW HPC from the 2023-03-AA build and onwards.

|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 0250

2025-05-08T04:37:44Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 0250 - Too many CPU threads for model size, thread limit: <>.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=When running HPC models (not including quadtree) over a number of processing devices (CPU threads or GPU cards) the model is split and each device gets an equal portion of the model to solve (split along the model x-dimension) . Running very small models can mean that more compute devices than model columns are used.
For example in the .tgc the following commands: 
<tt>
<tt>Grid Size (X,Y) </tt> <tt>==</tt><tt> 2, 4</tt> 
<tt>Cell Size </tt> <tt>==</tt><tt> 1</tt>
</tt>
Creates a model with 2 columns (in the x-direction) and 4 rows (in the y-direction). Running the above model with CPU Threads == 4 would give ERROR 0250. The minimum number of model columns for a device is 4, so a model with 10 columns could run on 2 CPU, but any more would result in ERROR 0250. Note: there is little benefit in running small models on large numbers of threads, and this may actually cause a slow down in the simulation speed due to computational overhead. 
For Quadtree the number of threads must be less than the number of cells.

|suggestions=Review model size definition in the TGC file. 
If model is intended to be small, the number of CPU threads may need to be reduced. E.g. set <tt>Hardware </tt> <tt>==</tt><tt> CPU</tt> and <tt>CPU Threads </tt> <tt>==</tt><tt> 1</tt> in the TCF file.

|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 3517

2025-05-01T05:00:10Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 3517 - Z Shape Route not supported yet in SGS. Please contact support@tuflow.com.
 
|alt_msg=ERROR 3517 - HX 2D BC not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - Interpolate ZUVH not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - ZC == MIN(ZU,ZV) not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - FC not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - "Read RowCol Zpt" or "Read MID Zpt" not supported with Quadtree. 
ERROR 3517 - "Read RowCol Zpt" or "Read MID Zpt" not supported in SGS. 
etc
|type=[[ERROR]]
|message_desc=These commands/functions are not supported in either SGS or Quadtree (depending on the message received) with the used TUFLOW version. 
If the message received is "ERROR 3517 - "Read RowCol Zpt" not supported with Quadtree" this is because the GIS layer is cell size dependent and cannot be used in a Quadtree model, as they have multiple cell sizes. 
If the error is ERROR 3517 - "Read RowCol Zpt" or "Read MID Zpt" not supported in SGS", this error occurs as reading data in this format only reads the cell centre (zc), cell face (zu and zv) and cell corner (zh) elevations. Data read in RowCol are read based on the model row and column reference and does not account for sub grid sampling within a cell. This command was made redundant with the addition of direct reading of raster grids and TIN files in the 2011 version of TUFLOW. 
Note: "Read RowCol Zpt" and "Read MID Zpt" are treated identically in TUFLOW with "Read MID Zpt" being the syntax for versions prior to 2010 when GIS formats were extended to include Shapefile.
|suggestions=
Use the latest version of TUFLOW available from the TUFLOW website. Alternatively, remove these features to run in SGS (or Quadtree depending on the message).

If the message received is "ERROR 3517 - "FC" not supported yet in SGS" this is because a GIS 2d_fcsh layer is used. Change this to a 2d_lfcsh layer which is supported when using SGS.

If the message received is "ERROR 3517 - "Read RowCol Zpt" not supported with Quadtree" or "ERROR 3517 - "Read RowCol Zpt" not supported in SGS" use the source elevation layer that the file was originally generated from. This can be replaced with "Read Grid Zpt" if using a raster grid, or "Read TIN Zpt" if using a TIN surface.

Alternatively, if you have both .mid/.mif it is possible (although not recommended) to generate a raster within QGIS which can be read into TUFLOW instead. If there is no .mif file, this can be generated in TUFLOW using the following in the TGC (anywhere the zpt layer is not 99 will be the original sample points and elevations). Note that SGS must be switched off for this model run to get the .mif file created: 
<tt>Set Zpts<tt>== </tt> <tt>99</tt> 
<tt>Read MID Zpts<tt>== </tt> <tt>input_file.mid</tt> 
<tt>Write GIS Zpts<tt>== </tt> <tt>output_file.mif !or .shp, .gpkg</tt> 
<tt>Stop</tt> 

|uplink=[[3xxx_TUFLOW_Messages|3xxx Messages]]
}}

TUFLOW Message 3517

2025-05-01T04:52:53Z

Par:

{{TUFLOW_Message
|tuflow_message=ERROR 3517 - Z Shape Route not supported yet in SGS. Please contact support@tuflow.com.
 
|alt_msg=ERROR 3517 - HX 2D BC not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - Interpolate ZUVH not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - ZC == MIN(ZU,ZV) not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - FC not supported yet in SGS. Please contact support@tuflow.com. 
ERROR 3517 - "Read RowCol Zpt" or "Read MID Zpt" not supported with Quadtree. 
ERROR 3517 - "Read RowCol Zpt" or "Read MID Zpt" not supported in SGS. 
etc
|type=[[ERROR]]
|message_desc=These commands/functions are not supported in either SGS or Quadtree (depending on the message received) with the used TUFLOW version. 
If the message received is "ERROR 3517 - "Read RowCol Zpt" not supported with Quadtree" this is because the GIS layer is cell size dependent and cannot be used in a Quadtree model, as they have multiple cell sizes. 
If the error is ERROR 3517 - "Read RowCol Zpt" or "Read MID Zpt" not supported in SGS", this error occurs as reading data in this format only reads the cell centre (zc), cell face (zu and zv) and cell corner (zh) elevations. Data read in RowCol are read based on the model row and column reference and does not account for sub grid sampling within a cell. This command was made redundant with the addition of direct reading of raster grids and TIN files in the 2011 version of TUFLOW. 
Note: "Read RowCol Zpt" and "Read MID Zpt" are treated identically in TUFLOW with "Read MID Zpt" being the syntax for versions prior to 2010 when GIS formats were extended to include Shapefile.
|suggestions=
Use the latest version of TUFLOW available from the TUFLOW website. Alternatively, remove these features to run in SGS (or Quadtree depending on the message).

If the message received is "ERROR 3517 - "FC" not supported yet in SGS" this is because a GIS 2d_fcsh layer is used. Change this to a 2d_lfcsh layer which is supported when using SGS.

If the message received is "ERROR 3517 - "Read RowCol Zpt" not supported with Quadtree" or "ERROR 3517 - "Read RowCol Zpt" not supported in SGS" use the source elevation layer that the file was originally generated from. Alternatively, if you have both .mid/.mif it is possible to generate a raster within QGIS which can be read into TUFLOW instead. If there is no .mif file, this can be generated in TUFLOW using the following in the TGC (anywhere the zpt layer is not 99 will be the original sample points and elevations). Note that SGS must be switched off for this model run to get the .mif file created: 
<tt>Set Zpts<tt>== </tt> <tt>99</tt> 
<tt>Read MID Zpts<tt>== </tt> <tt>input_file.mid</tt> 
<tt>Write GIS Zpts<tt>== </tt> <tt>output_file.mif !or .shp, .gpkg</tt> 
<tt>Stop</tt> 

|uplink=[[3xxx_TUFLOW_Messages|3xxx Messages]]
}}

1D Syphons

2024-07-17T05:41:09Z

Par: minor addition

Page Under Construction
 
 
 
== Introduction ==
A syphon (or siphon) is a hydraulic structure used to transfer water from one location to another, typically over an elevation difference, without the need for pumping. A syphon operates based on the principle of atmospheric pressure and gravity.

The components of a syphon are:
*Inlet: Located at the higher water level, where water enters the siphon.
*Outlet: Positioned at the lower water level, where water exits.
*Riser: The vertical section that rises from the inlet to the crest of the U-shape.
*Downleg: The section that descends from the crest to the outlet.

== 1D Configuration ==
Whilst TUFLOW does have a specific syphon channel, there are two approaches to model a syphon system in TUFLOW.
=== Matrix Flows ===
The most appropriate approach to model a syphon is to use a M channel, described in Section 5.8.1 ''M Channels (User Defined Flow Matrix)'' in the [https://downloads.tuflow.com/TUFLOW/Releases/Latest/TUFLOW%20Manual.pdf| TUFLOW user manual]. An M channel can be used to define a matrix of flows between two invert levels based on their respective depths. If this matrix of flows through the syphon can be calculated, or if they are given as part of the operational instructions, then they can be input in .csv form as below, where negative values indicate flows going from downstream to upstream.

[[File:M channel matrix.jpg]]

=== Storage Nodes & Additional Losses ===
Alternatively, 1d_nwk nodes can be used to account for the storage of the vertical portion of the syphon as the images shown below. This configuration essentially estimates the flows conveyed though the syphon based on the upstream and downstream water level and the hydraulic property of the bottom pipe. It is strongly recommended to calibrate the model result against measurement data to check the accuracy or if measurement data are not available, conduct sensitivity testing.

[[File:Syphon storagenodes.jpg]]

==== Syphon Losses ====
For this method, the main losses for a syphon should be considered:
* entry and exit losses
* friction at pipe and wall
* bend losses

Bend losses (or any extra loss) through the syphon can be accounted for using the Form_Loss attribute of the pipe. 
The equation used for the loss of head due to pipe bend is provided below:

[[File:Bend loss eqn.jpg]]

Where: 
'''kb''' = co-efficient of bend 
'''v''' = velocity of fluid (m/s) 
'''g''' = acceleration of gravity (9.8 m/s2)

The following figure provides bend coefficient values for common bend types:

[[File:Bend losses 1.jpg |thumb|none|upright=5|Table 8-4, Fluid Mechanics: Fundamentals and Applications 4th ed.(2018)]] 

If you have any further questions about syphons or any other aspect of TUFLOW functionality, please email TUFLOW support: [mailto:support@tuflow.com?Subject=TUFLOW%201D%20weirs%20help support@tuflow.com]

{{Tips Navigation
|uplink=[[ TUFLOW 1D Channels and Hydraulic Structures | Back to 1D Channels and Hydraulic Structures]]
}}

12da to from GIS

2023-10-30T04:53:42Z

Par: Added some extra information on UTF16 conversion.

=Introduction=
'''12da_to_from_GIS.exe''' converts .12da files from the 12D software [http://www.12d.com (www.12d.com)] to and from .mif and .shp files, the .12da file needs to be in ANSI encoding, not UTF. If importing/exporting to/from 12D and a GIS simply specify the file that you wish to have translated. If the file has a .12da (or a .4da) extension, the program converts it to a .mif/.mid file format. If the file has a .mif extension, the program converts it to a .12da file. 
Note, when converting from a .12da file to a .mif file without any options, 12da_to_from_mif automatically creates a .mif/.mid file suitable for use by Read GIS Z Line. This is useful for importing 3D breaklines (eg. of a road design) directly into TUFLOW. 
There are some very useful options as discussed in the table below. 
Of particular note is the -xs option to generate a TUFLOW 1D cross-section database from a 12D DTM. This approach is far more preferable to extracting cross-sections manually and is much better than extracting cross-sections from a grid based DTM (eg. Vertical Mapper or Spatial Analyst) as it only extracts points where the DTM triangle sides intersect the cross-section line, thereby keeping the number of points in the cross-section profile to a minimum, and also improving the accuracy of the profile. 
The zln option can also be very useful when the DTM river bathymetry is poor because the aerial survey is inaccurate where there is water or dense vegetation, and you need to carve a section through the DTM along the river based on a cross-section survey. 
 
=Options (switches)=
'''TABLE 1: 12da_to_from_GIS Options (Switches)'''
{| align="center" class="wikitable"

! Switch
! width=85% | Description
|-
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;"| When converting from a .mif file to a .12da file
|-
|"-zln"|| When converting a .mif file to .12da file, if zln is specified polylines are interpreted in the same manner as a TUFLOW 3D breakline (see Read GIS Z Line) such that any points snapped to the polyline are used to set the elevations of any vertices along the polyline that do not have points snapped to them. The first attribute in the .mif file must be the Elevation. (Note, when converting in reverse from a .12da file to a .mif file without any options, 12da_to_from_mif automatically creates a .mif/.mid file suitable for use by Read GIS Z Line.) 
This is useful for creating 3D polylines for 12D where an elevation does not exist at a vertice. It is particularly useful where a river’s bathymetry in a DTM is being created from cross-section surveys, and the DTM operator wishes to use the elevations at the cross-section survey points, but needs to put more shape into the breaklines being digitised between the cross-sections so as to carve out the river’s bathymetry into the DTM. Using 12da_to_from_mid with the zln option will interpolate elevations at every string vertice, something that 12D does not offer (as far as we know!).
|-
!colspan="2" style="background-color:#005581; font-weight:bold; color:white;"| When converting from a .12da file to a .mif file
|-
|"-hip"|| When converting a .12da file to a .mif file will include any 12D hipdata polylines.
|-
|"-xs"|| When converting a .12da file to a .mif file creates a TUFLOW cross-section database (ie. one .csv file per 3D polyline) and a 1d_xs layer (1d_tab or 1d_xs format – see Read GIS Table Links and Section 4.6.3). This is used to extract 1D cross-sections from a DTM for use in TUFLOW. Cross-sections generated this way can also be viewed and edited in the SMS TUFLOW Interface. 
The process to create the cross-sections from a 12D DTM is as follows: 
*Digitise the location of cross-section lines either in a GIS or in 12D. If in a GIS, export the layer out as a .mif file and then run 12da_to_from_gis to convert the .mif file into a .12da file. For example use: 
:<tt>12da_to_from_gis.exe xs.mif</tt> 
:to generate a file called xs.12da. Import the .12da file into 12D. 
*In 12D drape the cross-section polylines over the DTM (your 12D operator should know how to do this!) to create 3D polylines with vertices where the cross-section line intersects a DTM triangle edge.
*Export the 3D draped polylines from 12D as a .12da file.
*Run 12da_to_from_gis using the -xs option. For example: 
:<tt>12da_to_from_gis.exe -xs -shp xs_draped.12da</tt> 
:This will produce a 1d_xs layer in shapefile format ready for use by TUFLOW and a .csv file for each cross-section line. Keep the 1d_xs layer and the .csv files in the same folder in the event that you move them elsewhere. 
Using the xsGenerator.exe utility, you can also assign material values to each of the cross-section points (see [[xsGenerator | this page]]).
|}

=Examples=
<tt>12da_to_from_gis.exe -mif road_breaklines.12da</tt> 
creates .mif/.mid files of the 2D and 3D breaklines in the file road_breaklines.12da. The .mif/.mid files can be directly used by Read GIS Z Line. 
 
<tt>12da_to_from_gis.exe 2d_hx_lines.mif</tt> 
creates a file 2d_hx_lines.mif.12da. Import this file into 12D then drape these lines over the DTM and export the file, say as 2d_hx_lines_draped.12da, then execute the following: 
<tt>12da_to_from_gis.exe 2d_hx_lines_draped.12da</tt> 
This creates 3D breakline .mif/.mid files of the TUFLOW HX lines that can be used to ensure the 2D HX cells are set to the exact elevations along the HX lines by using the below command in the .tgc file.: 
<tt>Read GIS Z Line THICK == mi\2d_hx_lines_draped.12da.mif </tt> 

=Frequently Asked Questions (FAQ)=
==Why are the SHP or MIF files created by the 12da_to_from_GIS utility empty?==
The reason for empty output files may be that 12D (v10 or later) produces output files in UTF-16 encoding by default. This encoding is not compatible with the utility and can lead to empty SHP or MIF outputs. The .12da can be exported from 12D into ANSI format, or readily converted in text editor from UTF16 to ANSI making it compatible with TUFLOW and TUFLOW utilities. Instructions for both methods are below. 
In 12D, when exporting the TIN as a .12da file, make sure to select the "[Ansi format]" 
[[File:12da_TIN_export_screenshot.JPG|500px]] 
This change will be highlighted at the bottom of the Write 12da pop up box. See figure below. 
[[File:12da_TIN_export_screenshot_ANSI_Format_set.JPG|500px]] 

Alternatively, an existing .12da file can easily be converted to ANSI encoding in Notepad++, under the Encoding menu: 
[[File:Convert ANSI.jpg|500px]]

{{Tips Navigation
|uplink=[[TUFLOW_Utilities | Back to TUFLOW Utilities]]
}}

Run TUFLOW From a Batch-file

2023-06-23T05:38:53Z

Par: /* Looping in a batch file up to a certain number of runs */ remove link to forum

TUFLOW simulations can also be started from a batch file. Batch files are text files which contain a series of commands. Batch files allow a large degree of flexibility in starting TUFLOW simulations, advanced batch files can be used to:

* Run multiple simulations
* Set CPU priority for TUFLOW simulations
* Create a wait (e.g. start a simulation in 1 hour)
* Test simulation input
* Copy a TUFLOW model
* Package a TUFLOW model
* Post process results after simulation has finished.
Batch files are executed by double clicking the created .bat file from Windows Explorer.
<ol>
==Simple batch file==
To use a batch file, create a new text file in the TUFLOW\runs directory. The name is arbitrary but the file must have the extension ".bat". For example the file name could be '''_run_TUFLOW.bat'''.

Open this file in a text editor and add the following line.

<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" "M01_5m_001.tcf"</pre>
This is the simplest command line for starting TUFLOW, the line above contains only two arguments, the first is the path to the TUFLOW executable and the second argument "M01_5m_001.tcf" is the simulation file name. Depending on the location of the executable the above command line will need to be modified. The quotations around the TUFLOW executable and the .tcf file name are only required if there are spaces in the file names. However, it is recommended to include these to avoid problems.

==Batch File Switches==
These switches are available in all batch files, they are not specific to TUFLOW.

===Pause===
A second line with the text "pause" can be added, this will prompt the user to press a key at the end of the batch file. This is useful if the DOS window disappears from the screen, before you can read the output. The pause command will keep the window open.
<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" "M01_5m_001.tcf"
pause</pre>

===Starting process in new window===
In order to run multiple simulations at the same time, each simulation needs be started in a new console window. To do this begin the batch file line with the "Start" command, a for the window is then added. For example, to start the simulation above in a new window titled "TUFLOW" the following would be used.

<pre>Start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" "M01_5m_001.tcf"</pre>
===Wait===
If multiple simulations are to be run, it is often desirable to run these in series, i.e. the second simulation starts after the first has finished. a /wait switch can be added which makes the batch file wait until the process is finished before moving onto the next command. 
An example of this is: 
<pre>Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_5m_001.tcf
Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_2.5m_001.tcf</pre>
Without the wait command, both simulations would start at the same time. 
'''Note:''' Unless there is a third simulation in the batch file the /wait command in the second line is not required, this prevents the batchfile from moving onto the third line.
===Setting a priority===
The priority of a process (such a TUFLOW simulation) can be specified within a batch file. This can be useful for a number of reasons:
*Lowering the priority of a simulation to allow you to continue working;
*Setting a high priority for critical runs; or
*Making sure you runs are high priority on a shared computing resource!

The following are valid priority switches (in increasing order of priority):
*/LOW
*/BELOWNORMAL
*/NORMAL
*/ABOVENORMAL
*/HIGH
*/REALTIME

An example of a low priority simulation is: 
<pre>start "TUFLOW" /low "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" "M01_5m_001.tcf"</pre>
'''TIP:''' The priority of a TUFLOW simulation can be changed at a later stage by using the '''Windows Task Manager''', navigate to the '''Processes''' tab and right click on the TUFLOW process (e.g. TUFLOW_iSP_w64.exe) and select the set priority option.

===Minimising the console window===
Using the /min switch will keep the console window for TUFLOW models minimised, so it doesn't pop up to the front every time when the next model starts.
<pre>Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_5m_001.tcf
Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_2.5m_001.tcf</pre>
==no console simulation==

==No Console Option==
Using the -nc switch will run a simulation without opening a DOS console window. This option is desirable for people running simulation on the cloud. Note, if an invalid .tcf file is specified, the simulation stops and returns an error level of 1 to the operating system.

<pre>Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_5m_001.tcf
Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_2.5m_001.tcf</pre>

== TUFLOW switches in a batch file==
These switches are specific to TUFLOW simulations.
===Testing a simulation===
The -t (test) switch is very useful for testing the data input without running the simulation. It is good practice to use this switch before carrying out the simulations, as this will tell you whether there are any data input problems. The -t switch runs TUFLOW to just before it starts the hydrodynamic computations.
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -t "M01_5m_001.tcf"</pre>
===Batch mode in TUFLOW===
The use of the –b (batch) switch which suppresses the need to press the return key at the end of a simulation. This ensures that one simulation proceeds on to the next without any need for user input. This is required for running multiple simulations in series (one after the other).
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b "M01_5m_001.tcf"</pre>
===Automatically Create Folders in a TUFLOW model===
The use of the -acf (automatically create folders) switch prevents the dialog prompt from appearing when encountering non-existent folders (ie. results folders), and creates these folders automatically. If for any reason the folder can't be created, a dialog will appear. This feature was first introduced for Build 2012-05-AE and is not available for TUFLOW builds prior to this. For models simulated with Build 2013-12-AA or later, non-existent folders are now automatically created. If you would prefer to have the create folder query dialog to appear, you can specify the –qcf run time option (stands for query create folders). 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -acf "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Suppress Queries in a TUFLOW model===
The use of the -nq (no queries) switch prevents the termination query dialog from displaying when Ctrl+C is pressed to terminate a simulation cleanly. If –nq is specified and Ctrl-C is pressed, the simulation terminates cleanly without a query dialog to check you are certain, so be careful! This feature was first introduced for Build 2012-05-AE and is not available for TUFLOW builds prior to this. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nq "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Copy a TUFLOW model===
TUFLOW can be run in copy mode, which can be useful for transferring a model to another site or for making an archive of the input data. 

To copy a TUFLOW model, the '''-c''' switch must be included on the TUFLOW command line, as a minimum. The '''-c''' switch copies only the files read by TUFLOW. As such, for MapInfo users, the .mif and .mid files read by TUFLOW will be copied. The remaining MapInfo format files (.tab, .id, .dat and .map) are not read by TUFLOW and will not be copied. By default, the '''-c''' switch copies all TUFLOW inputs for the simulation into a subdirectory where the .tcf is located (generally TUFLOW\runs\). 

Additional optional flags can be added to the base '''-c''' switch, in any combination, including: 
;* “a” (all); 
: The addition of the “a” flag (e.g. -ca) copies all files of the same name for all input files (ie. same name, but different extensions). This option is particularly useful if the .tab and other associated files of a GIS layer need to be archived or delivered. 
;* “p” (path); and 
: The addition of the “p” flag (e.g. -cp) allows the user to specify an alternate path in which to copy the model. Without this flag, the location defaults to the .tcf’s location. For example, specifying the following, will place a copy of the model into a folder C:\put_model_here: 
REM <tt>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -cp "C:\put_model_here" "C:\TUFLOW\runs\M01_5m_001.tcf"</tt> 
;* “ncf” (no check files) 
: The addition of the “ncf” flag (e.g. -cncf) copies the essential input files and excludes all check files. 

Note that these optional flags can be added in any combination to the base '''-c''' switch (e.g.
-c, -ca, -cp, -cncf, -cap, -cancf, -cpncf, -capncf). 

Specifying '''-c''' on the TUFLOW command line creates a folder “<.tcf filename>_copy” (or “<.tcf filename>_copy_all” if the “a” flag is added) in the same location as the .tcf file. Under the folder, input files are copied (including the full folder structure), and any check files and output folders created. For example, specifying: 
: <tt>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -c “C:\tuflow_models\my model.tcf”</tt> will make a copy of the TUFLOW model based on the file <tt>“my model.tcf”</tt> in a folder <tt>"my model.tcf_copy"</tt>, or <tt>"my model.tcf_copy_all"</tt> if using the “a” flag. 

'''Note:'''
<ol>
<li> Use the full path to the .tcf file (this is the default if running from UltraEdit or using the right click approach).
<li>Make sure there is sufficient disk space (no checks for sufficient disk space are made).
<li>Output folders and some output files are created but these will be empty.
<li>Any check folder(s) are created and check files written (these can be deleted if wishing to minimise the size of the folder).
<li>The full path of the input files is reproduced to provide traceability and also handle inputs from other drives and URLs. Drive letters are replaced, for example, “C:” becomes a folder “C Drive”. URLs (denoted by “\\” or “//” at the beginning of the path) are replaced by a folder called “URL\”.
<li>To run the copied .tcf file, it will be necessary to change any non-relative pathnames according to the point above. Alternatively you can share and then map, for example, the “D Drive” folder as “D:”.
<li>The Check MI Save Date will need to be set to WARNING or OFF in the .tcf file if the –ca option has not been used as the .tab and other files will not have been copied.
<li>There is a limit of 1,000 characters (including spaces) on pathnames. As very long pathnames can result due to the above approach, if the number of characters exceeds 1,000, problems may occur.
<li>The -c switch automatically invokes the -t (ie. the simulation does not commence, only the input data is tested/checked).
<li>The -b option still applies if several models wish to be copied using a batch (.bat) file.
</ol> 

An example that copies all files (-ca switch) is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -ca "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>
An example that copies all files to an alternate path (-cap) is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -cap "C:\Copy_of_model" "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>
An example that copies all files to an alternate path, excluding any check files, (-capncf) is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -capncf "C:\Copy_of_model" "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Package a TUFLOW model===
Package model function attempts to copy all input files for all events and scenarios defined in the model, if only single set of events and scenarios is required, -c is preferable. Unlike the -c option, -pm does not read and process the data during the file copy, as such it is substantially faster than -c. The package model function does not require access to a TUFLOW licence.

Additional optional flags can be added to the base '''-pm''' switch, in any combination, including: 
;* “All”; 
: The addition of the “All” flag (e.g. -pmAll) copies all file extensions (e.g. 1d_nwk_culv_L.mif, will become 1d_nwk_culv_L.*). 
;* “L” (list); and 
: The addition of the “L” flag (e.g. -pmL) list the files to be copied into an output file, but don’t copy. 
;* “ini” (file.ini) 
: The addition of the “ini” flag (e.g. -pmini) provides a .ini file with user defined options. A .ini file can be used to overwrite the default base and destination folders, and specify events/scenarios for models with events/scenarios in filenames. Valid options should be separated by a vertical bar. 

Combinations of the above are also valid, with the order of the optional switches not being important (-pmAllL would be treated the same as -pmLAll). 
When using package model the default destination folder is created in the same directory as the .tcf file, with the prefix “pm_”. For example, C:\Projects\Modelling\TUFLOW\runs\Run_001.tcf will create a package in the folder “C:\Projects\Modelling\TUFLOW\runs\pm_Run_001\. 

Three options are also available for handling of the binary processed files created by TUFLOW to speed up the simulation start. These options are: 
;* “-xf0”; 
: Do not copy .xf files, only the original inputs are copied. 
;* “-xf1”; and 
: Copy both raw input files and .xf files. 
;* “-xf2” 
: Copy only .xf files, if xf files exist for an input only the xf will be copied. 
 
An example of package model that copies all files is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pmAll "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>
An example of package model that copies all files except .xf files, (-pmAll -xf0) is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pmAll -xf0 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>
An example of package model that copies all files with specified .ini file (-pmAllini) is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pmAllini package.ini "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>
An example of .ini file to overwrite the default base and destination folders, and specify events/scenarios for models with events/scenarios in filenames: 
<pre>
Base Folder == <folder>
Copy Destination == <folder>
Model Scenario ~s<number>~ == <scenario A> | <scenario B> | …
Model Event ~e<number>~ == <event A> | <event B> | …
</pre>

===GPU Module Control===
The -pu switch can be used to select which GPU card or cards to direct the simulation towards. –pu must be specified once for each device. For example, to direct the simulation to GPU devices 0 and 2, specify -pu0 -pu2. (Note: the GPU device numbering starts a 0, not 1). For example:
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -pu0 -pu2 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Event and Scenario Management===
The -e and -s switches can be used to manage multiple events and scenarios from a single tuflow control file. The -e and -s wildcard is replaced by the following entry specified in the batch file. For example, the following batch file commands will run two simulations in series:
* M01_Q050_24hr_2m_Dev_001.tcf; and
* M01_Q100_24hr_2m_Dev_001.tcf;

<pre>Start "TUFLOW" /wait "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 Q050 -e2 24hr -s1 2m -s2 Dev "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_~e1~_~e2~_~s1~_s2~_001.tcf"
Start "TUFLOW" /wait "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 Q100 -e2 24hr -s1 2m -s2 Dev "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_~e1~_~e2~_~s1~_s2~_001.tcf"</pre>

Please be aware that the % symbol is a special character in a batch file. If the % symbol is used within a wildcard, it will not be read when searching for that wildcard in TUFLOW. 
For example if the following event wildcard is used; 
*-e 10% 
TUFLOW will search for '10' instead of '10%' as the event wildcard. 
 
It is recommended that modellers avoid the use of a % symbol in any wildcard values. The string 'pct' is a great alternative for the % symbol. 
For example, using: 
*-e 10pct 
Alternatively, using the % symbol twice in a row as shown below should result in a desired wildcard value. 
*-e 10%% (TUFLOW will search for 10%)

==Advanced Batch Files==
The below section shows example batch files for maximizing run efficiency,
===Creating a delay===
====Windows 7 and newer====
For a Windows 7 and newer operating system a delay of a set duration can be created with the Timeout <seconds> command. For example: 
<pre>Timeout 10</pre>
Will create a 10 second delay, a countdown timer is given. Press any key to continue.

====Other Systems====
It is possible to create a delay of specified length in a batch file. The best way do this is actually to create a second batch file! To do this create a text file and call it '''wait.bat'''. Within that file enter the following text:
<pre>@ping 127.0.0.1 -n 2 -w 1000 > nul
@ping 127.0.0.1 -n %1% -w 1000> nul</pre>
To create the pause we ping an address for a set time and disregard the output. Once the wait.bat has been created, it can be called from another batchfile using the following syntax:
<pre>call wait <time in seconds.</pre>
In the example below, the first simulation is started and then 60 seconds later (using the wait.bat file) the second simulation is started. Note there is no /wait flag specified, if there was the batchfile would wait for 60 seconds after the first simulation had finished before starting the second simulation.
<pre>Start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_5m_001.tcf
call wait 60
Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" M01_2.5m_001.tcf</pre>
For this to work the wait.bat file needs to be in the same folder as the batchfile calling it. You can put the file in a specific location and add this path as an environment variable. If this is done "call wait <time in seconds> can be added to any batch file. 
To set the environment variable, you will need to have administrator access to the machine, and add a colon (;) and then the batchfile location (e.g. "C:\batch_files\" , without the quotes) in the '''path''' system variables. The separator character is a colon (;) this is added to specify a new path. For more details on modifying the environment please see here: [http://support.microsoft.com/kb/310519 http://support.microsoft.com/kb/310519].

===Variables===
Batch files can be easily setup so that they are more generic and easily customised when moving from one project to another. For example, in the below a variable, TUFLOWEXE, is used to define the path to the TUFLOW exe to be used, and a variable RUN is used to incorporate options such as the /wait so that the simulations run in series (one after the other).

<pre>set TUFLOWEXE=C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe
set RUN=start "TUFLOW" /wait "%TUFLOWEXE%" -b
%RUN% MR_H99_C25_Q100.tcf
%RUN% MR_H99_C25_Q050.tcf
%RUN% MR_H99_C25_Q020.tcf</pre>
The advantage of using variables is if the path to the TUFLOW exe changes, or to run a different version of TUFLOW, it is just a simple change in the .bat file. In the above, note the use of quotes around %TUFLOWEXE% in the definition for the RUN variable – quotes are needed around file pathnames whenever they contain a space.
===Looping in a batch file===
If you have a large number of events to run using the event files a for loop can be used in a batch file. In this example we have 5 event magnitudes (-e1 input) and 5 event durations (-e2 input). The following batch file can be used to run all 25 simulations one after the other:
<pre>
@echo off

REM This sets the variables as local, so you can use another batch file with A and B variables
SetLocal

REM set up variables
set A=Q010 Q020 Q050 Q100 Q200
set B=10min 30min 60min 120min 270min

REM Loop Through
FOR %%a in (%A%) do (
FOR %%b in (%B%) DO (
start "TUFLOW" /wait C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe -b -e1 %%a -e2 %%b filename.tcf
)
)
pause
</pre>
In order to test the syntax, you can test the batch file by replacing the following line: 
<tt>start "TUFLOW" /wait C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe -b -e1 %%a -e2 %%b filename.tcf</tt> 
With the following line: 
<tt>echo start "TUFLOW" /wait C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe -b -e1 %%a -e2 %%b filename.tcf</tt> 
By using the echo in the command line, rather than starting the simulations the command line will be displayed in the DOS output. In the example above the DOS output is shown in the image below.
[[File:DOS nested batch output.png|frame|none]]

Alternatively this can be achieved using the following syntax, which is essentially the same but has the for loops compressed to a single line:
<pre>
@echo off
setlocal
set A=Q010 Q020 Q050 Q100 Q200
set B=10min 30min 60min 120min 270min

FOR %%a in (%A%) do FOR %%b in (%B%) do start "TUFLOW" TUFLOW_iSP_w64.exe -b -e1 %%a -e2 %%b filename_~e1~_~e2~.tcf
pause
</pre>
This can be extended to more variables for example:
<pre>
@echo off
setlocal
set A=Q010 Q020 Q050 Q100 Q200
set B=10min 30min 60min 120min 270min
set C=Exg Dev Mit

FOR %%a in (%A%) do (
FOR %%b in (%B%) do (
FOR %%c in (%C%) do (
start "TUFLOW" /wait TUFLOW_iSP_w64.exe -b -e1 %%a -e2 %%b -s1 %%c filename_~e1~_~e2~_~s1~.tcf
)
)
)
pause
</pre>

===Looping in a batch file up to a certain number of runs===
The below example shows a method for controlling the number of concurrent simulations. 

As a brief description of the below, the "do_while_loop_start" counts the number of processes in the task manager which have "TUFLOW" in the name. If this is greater than or equal to the variable "CPU_Cores" then the batch file waits for 60 seconds.

<pre>
@ echo off

Set A=Q001 Q002 Q005 Q010 Q020 Q050 Q100
Set B=Exg Dev
set /a CPU_Cores=3

FOR %%a in (%A%) DO (
FOR %%b in (%B%) DO (
call :do_while_loop_start
Start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -s1 %%b M01_5m_~e1~_~s1~_001.tcf
)
)

Pause

:do_while_loop_start
set /a count=0
for /f %%x in ('tasklist ^| find /c "TUFLOW"') do set count=%%x
if %count% geq %CPU_Cores% (
PING 1.1.1.1 -n 1 -w 60000 >NUL
goto do_while_loop_start
)
</pre>

Another way to achieve the same result using IF logic is shown below. This batch file will loop through the series of 14 simulations in groups of three. The batch file will pause until the last of the three active model simulations are complete. When complete, the next series of three simulations will be started in parallel.

<pre>
@ echo off
setlocal enabledelayedexpansion

SET A=Q001 Q002 Q005 Q010 Q020 Q050 Q100
SET B=Exg Dev
SET P=3

SET /A Counter=0
FOR %%a in (%A%) DO (
FOR %%b in (%B%) DO (
SET /A Counter+=1
IF /i !Counter!==!P! (
Start "TUFLOW" /wait "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -s1 %%b M01_5m_~e1~_~s1~_001.tcf
SET /A Counter=0
) ELSE (
Start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -e1 %%a -s1 %%b M01_5m_~e1~_~s1~_001.tcf
)
)
)
</pre>

===Looping in a batch file using scenario logic===
Sometimes when using different scenarios, it is useful to run a specific set of events for one scenario but other events for a different scenario. 
This can be automated within looped batch files using a bit of logic. 
In the the example below there is model with defended and undefended scenarios. The defended scenario needs to be run for the 20, 100 and 200 year events but the undefended scenario is only run for the 100 year event. All models are run for the hr and 3hr critical durations. 
The below batch file also uses the looping up to a certain number of runs, as seen in the point above. 
To customize this script, alter the location of the TUFLOW executable, the name of tcf and the scenarios that you would like to run (Refer to 'Set A==', 'Set C==' and 'Set B=='). 
<pre>
@ echo off
setlocal enabledelayedexpansion

REM ______________SET RUN VARIABLES_____________
set TUFLOWEXE=C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe
set RUN=start "TUFLOW" /low "%TUFLOWEXE%" -b
set /a CPU_Cores=5

set tcf=M01_5m_~s1~_~e1~_~e2~_001.tcf

Set A=UDEF DEF
REM set B in loop beow
Set C==01hr 03hr

REM ______________SET LOOPS____________________
FOR %%a in (%A%) do (

REM _____DEFINE RUN LOGIC______
IF "%%a"=="UDEF" (
set B=100yr
)
IF "%%a"=="DEF" (
set B=020yr 100yr 200yr
)

REM ______________RUN LOOPS____________________
FOR %%b in (!B!) do (
FOR %%c in (%C%) do (
call :do_while_loop_start
%RUN% -s1 %%a -e1 %%b -e2 %%c %tcf%
timeout 60

)
)
)

REM ___________COUNT RUN INSTANCES______________
:do_while_loop_start
set /a count=0
for /f %%x in ('tasklist ^| find /c "TUFLOW"') do set count=%%x
if %count% geq %CPU_Cores% (
PING 1.1.1.1 -n 1 -w 60000 >NUL
goto do_while_loop_start
)

endlocal
</pre>
===Coordinating Asynchronous Simulations===
This batch file will set off asynchronous runs on separate threads, and then wait for all runs to finish before moving to the next process. This example kicks off 8 tuflow.exe processes and then waits before collating (in fortran) and processing the results (in python). Both “combine_therad_outputs.exe” and “Post_process.py” are dummy programs only (with dummy arguments), and are included just to demonstrate how any sort of post processing might be called after the synchronisation of all TUFLOW simulations.

<pre>
@echo off

:: Set local
setlocal
:: User defined variables – will need to be changed
set "for_infile=inputs_fortran.inp"
set "run_exe=tuflow.exe"
set "file_prefix=C:\temp\test"
set "sum_exe=combine_thread_outputs.exe"
set "n_threads=8"
set "pyt_code=Post_process.py"
set "pyt_infile=inputs_python.inp"

:: Random lock file
set "lock=%temp%\wait%random%.lock"

:: Launch processes asynchronously, with stream 9 redirected to a lock file.
:: The lock file will remain locked until the individual exe instance ends.
:: %%a is sent to %run_exe% as an argument to set the thread to use
for /L %%a in (0,1,7) do (
start "" 9>"%lock%%%a" %run_exe% %for_infile% %%a
)

:: Wait for the processes to finish
:Waitrun
1>nul 2>nul ping /n %n_threads% ::1
for /L %%N in (0,1,7) do (
(call ) 9>"%lock%%%N" || goto :Waitrun
) 2>nul

:: Delete the lock files
del "%lock%*"

:: Collate thread outputs
%sum_exe% %file_prefix% %n_threads%

:: Make image
python %pyt_code% %pyt_infile%

:: Finish up
echo Done.
</pre>

===Shutdown on Completion===
Often we may have a number of TUFLOW simulations going when we leave work on a Friday afternoon, if these are not going to take all weekend to run, using some of the batch file logic above you can create a batch file that will shutdown the computer when no TUFLOW simulations are running. An example batch file for this purpose is below: 
<pre>
echo off

:do_while_loop_start
set /a count=0
for /f %%x in ('tasklist ^| find /c "TUFLOW"') do set count=%%x
IF %count%==0 (
shutdown.exe /s /t 30
) ELSE (
timeout 60
goto do_while_loop_start
)
pause
</pre>
This batch file counts the number of processes with "TUFLOW" in the process name and if this is greater than 0, a delay of 60 seconds is created and the loop started again. If no "TUFLOW" simulations are running a shutdown command is issued. 
To test the batch file it is recommended that you add an "echo" in front of the <tt>shutdown.exe /s /t 30</tt> command to ensure it is working correctly (I use this on a Windows 7 machine, but have not tested it on either XP or Windows 8). 
In order to restart the machine rather than power it off the /s can be replaced with /r. This can be useful when a heavily utilised modelling computer needs a restart!
</ol>

User:Par

2023-06-01T02:39:17Z

Par: tidied up my role

Phillip Ryan is involved in numerical modelling projects in the flooding and coastal areas. These include flood studies, floodplain management studies, flood impact assessments, storm tide studies, Monte Carlo analysis, wave modelling, coastal hydrodynamic and advection-dispersion modelling. Phillip is involved in TUFLOW software development, support and training.

TUFLOW Message 2720

2023-06-01T02:37:11Z

Par: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 2720 - With NetCDF call <NetCDF Library call>. NetCDF: <Error reported by NetCDF library> |alt_msg=NA |type=ERROR |message_desc=The..."

{{TUFLOW_Message
|tuflow_message=ERROR 2720 - With NetCDF call <NetCDF Library call>. NetCDF: <Error reported by NetCDF library>
|alt_msg=NA
|type=[[ERROR]]
|message_desc=There has been an error reported in the underlying NetCDF library used by TUFLOW. The last part of the message should contain the error message return from the NetCDF, this may give an indication as to what the issue is. For example '''NetCDF: cannot delete file''' could occur if overwriting a file which is locked by another application.
|suggestions=Read the NetCDF error message to see if this explains why the error maybe occurring. If this does not make sense, please send the .tlf file to support@tuflow.com
|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

Main Page

2020-09-22T22:23:25Z

Par: Changed a couple of links from http:// to https://

__NOTOC__
[[File:TUFLOWNewLogo.jpg|250px|link=https://tuflow.com/|left|top|target="_blank"]][[File:BMT logo (PowerPoint) Logo Only.png|200px|link=https://www.bmtwbm.com.au/|right]]
<center style=font-size:290%;color:#005581;background: white>TUFLOW Wiki Homepage</center> 
This Wiki contains information relating to the flood and coastal simulation software TUFLOW Classic and TUFLOW HPC (Heavily Parallelised Compute). It is designed to be used in conjunction with the TUFLOW [https://www.tuflow.com/Download/TUFLOW/Releases/2018-03/TUFLOW%20Manual.2018-03.pdf Manual], [https://www.tuflow.com/forum/index.php?act=idx Forum] and [https://www.tuflow.com/Default.aspx Website] 

{|style="width:100%; border-spacing:8px; margin:0px 0px;"


|style="width:20%; border:1px solid #005581; vertical-align:top; color:#000; background:#B5CBDF;"|
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#B5CBDF;"
! <h2 style="margin:0; background:#005581; font-size:120%; font-weight:bold; border:1px solid #005581; text-align:left; color:white; padding:0.2em 0.4em;">TUFLOW Set-up and use</h2>
|-
||
[[File:Wiki Homepage Start Here v2.PNG||150px|right]]
'''TUFLOW'''
* [[New_User_Installation_Guide| How to install TUFLOW]]
* [[TUFLOW_Licensing | How to configure a licence]]
* [[Tutorial_Model| How to build a TUFLOW model (tutorials)]]
* [[Running_TUFLOW | How to run a TUFLOW model]]
* [[TUFLOW_Utilities | Free pre/post-processing utilities]]

'''TUFLOW Benchmarks''' 
* [[TUFLOW_Benchmarking | TUFLOW Solution Accuracy Benchmarks]]
* [[Hardware_Benchmarking | Computer Hardware Speed Benchmarks]]
* [[Hardware_Benchmarking_(2018-03-AA) | Computer Hardware Speed Benchmarks - New 2018 Release Version]]

'''Best Practice Guidance''' 
* [[TUFLOW_Modelling_Webinars | Webinar Recordings]]
* [[TUFLOW_Modelling_Guidance | Other Useful Modelling Guidance]]
|}


|style="width:20%; border:1px solid #005581; vertical-align:top; color:#000; background:#B5CBDF;"|
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#B5CBDF;"
! <h2 style="margin:0; background:#005581; font-size:120%; font-weight:bold; border:1px solid #005581; text-align:left; color:white; padding:0.2em 0.4em;">Tutorial Models (TUFLOW Classic and HPC)</h2>
|-
||
[[File:Wiki_Homepage_Blackboard_v2.PNG||200px|right]]
* [[Tutorial_Model|Tutorial Model Introduction]]
* [[Tutorial Module01|Module 1]] (2D only)
* [[Tutorial Module02|Module 2]] (1D Culverts)
* [[Tutorial Module03|Module 3]] (2D Topography Updates)
* [[Tutorial Module04|Module 4]] (1D Channel / 2D Floodplain)
* [[Tutorial Module05|Module 5]] (Scenario / Logic Control)
* [[Tutorial Module06|Module 6]] (Modelling Bridges)
* [[Tutorial Module07|Module 7]] (Urban Pipe Modelling)
* [[Tutorial Module08|Module 8]] (Direct Rainfall Modelling)
* [[Tutorial_Module09|Module 9]] (Multiple Domain 2D-2D Model)
* [[Tutorial_Module10|Module 10]] (Managing Multiple Events)
* [[Tutorial_Module11|Module 11]] (Dam Break Modelling)
* [[Tutorial Module14|Module 14]] (Pump Modelling in 2D)
 
* [[Flood_Modeller_Tutorial_Model|Flood Modeller Introduction]]
* [[Flood_Modeller_Tutorial_Module01|FM Module 1]] (Linking Flood Modeller to TUFLOW)
* [[Flood_Modeller_Tutorial_Module02|FM Module 2]] (Linking Flood Modeller to ESTRY)

|-
|}


|style="width:20%; border:1px solid #005581; vertical-align:top; background:#B5CBDF;"|
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#B5CBDF;"
! <h2 style="margin:0; background:#005581; font-size:120%; font-weight:bold; border:1px solid #005581; text-align:left; color:white; padding:0.2em 0.4em;">TUFLOW Troubleshooting</h2>
|-
||
[[File:Wiki Homepage Health.PNG|150px|right]]
'''Error/Warning Message Database'''
* [[TUFLOW_Message_How_To|About This Database]]
* [[0xxx TUFLOW Messages]]
* [[1xxx TUFLOW Messages]]
* [[2xxx TUFLOW Messages]]
* [[3xxx TUFLOW Messages]]
* [[9xxx TUFLOW Messages]]
 
* [[TUFLOW_Check_Files|TUFLOW Check Files]]
* [https://www.tuflow.com/forum/index.php?act=idx| TUFLOW Forum]
* [mailto:support@tuflow.com support@tuflow.com]
|-
|}


|}

{|style="width:100%; border-spacing:8px; margin:0px 0px;" 

|style="width:30%; border:1px solid #005581; vertical-align:top; color:#000; background:#B5CBDF;"|
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#B5CBDF;"
! <h2 style="margin:0; background:#005581; font-size:120%; font-weight:bold; border:1px solid #005581; text-align:center; color:white; padding:0.2em 0.4em;">Downloads</h2>
|-
||
<gallery mode="packed-overlay" widths=100px heights=100px color:red>
Image:Mainpage_TUFLOW_Installer_Logo_001.PNG|[https://www.tuflow.com/Downloads.aspx DOWNLOAD TUFLOW CLICK HERE]
Image:Mainpage_TUFLOW_Release_Notes_001.PNG|[https://www.tuflow.com/Downloads.aspx RELEASE NOTES]
Image:Mainpage_TUFLOW_Manual_003.PNG|[https://www.tuflow.com/Downloads.aspx USER MANUAL]
Image:Wiki Homepage Free v2.PNG|[[New_User_Guide_Free_Demo_Version| TRY TUFLOW FOR FREE]]
</gallery>
|-
|}


|style="width:30%; border:1px solid #005581; vertical-align:top; color:#000; background:#B5CBDF;"|
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#B5CBDF;"
! <h2 style="margin:0; background:#005581; font-size:120%; font-weight:bold; border:1px solid #005581; text-align:center; color:white; padding:0.2em 0.4em;"> Recent Wiki Updates / New Content (click image to view)</h2>
|-
||
{|
|style="width:50%; vertical-align:top; color:#000; background:#B5CBDF; padding:0.2em 0.4em; font-size:92%"|
<gallery mode="packed-overlay" widths=110px heights=110px>
Image:Quadtree_Implementation_Guide_005.jpg|[[TUFLOW_Modelling_Webinars#TUFLOW_Modelling_Webinars | Webinar: Quadtree Implementation]]
Image:Remap Advice LinkedIn.jpg | [[TUFLOW_Remapping | TUFLOW Remapping Tool]]
Image:Hardware_Configuration_001.jpg|[[Hardware_Selection_Guidance | Hardware Selection Advice]]
Image:TUFLOW_Output_Advice.jpg|[[TUFLOW_Modelling_Webinars | Webinar: Output Management Advice]]
Image:QGIS_Instalation_Guide_Youtube_Picture.jpg|[[TUFLOW_Modelling_Webinars | Webinar: QGIS Configuration and Use Advice]]
Image:Notepad_Webinar_Cover.PNG|[[TUFLOW_Modelling_Webinars | Webinar: Notepad++ Configuration Advice]]
Image:Webinar_Calibration.PNG|[[TUFLOW_Modelling_Webinars | Webinar: Model Calibration]]
</gallery>
|}
|}


|}


{|style="width:100%; border-spacing:8px; margin:0px 0px;" 

|style="width:50%; border:1px solid #005581; vertical-align:top; color:#000; background:#B5CBDF;"|
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#B5CBDF;"
! <h2 style="margin:0; background:#005581; font-size:120%; font-weight:bold; border:1px solid #005581; text-align:left; color:white; padding:0.2em 0.4em;"> Tips and Tricks</h2>
|-
||
{|
|style="width:50%; vertical-align:top; color:#000; background:#B5CBDF; padding:0.2em 0.4em;"|
'''Text Editor/Spreadsheet Software''' 
* [[Excel_Tips | Excel]]
* [[NotepadPlusPlus_Tips | Notepad ++]]
* [[TextPad_Tips | TextPad]]
* [[UltraEdit_Tips | UltraEdit]]
'''GIS Software''' 
* [[12D_Model | 12D Model]]
* [[ArcGis_Tips | ArcGIS]]
* [[Ensight_Tips | Ensight]]
* [[GeoRiver_Tips|GeoRiver]]
* [[Google_Earth_Tips | Google Earth]]
* [[MapInfo_Tips | MapInfo / Vertical Mapper / Encom Discover]]
* [[QGIS_Tips | QGIS (Previously Quantum GIS)]]
* [[SMS_Tips | SMS]]
* [[SAGA_Tips | SAGA]]
|style="width:50%; vertical-align:top; color:#000; background:#B5CBDF; padding:0.2em 0.4em;"|
'''Model Conversions''' 
* EPA SWMM to TUFLOW (coming soon)
* [[FLO2D_to_TUFLOW | FLO2D to TUFLOW]]
* [[HEC-RAS_to_TUFLOW | HEC-RAS to TUFLOW]]
* [[MIKE_Flood_to_TUFLOW|MIKE Flood to TUFLOW]]
'''Other''' 
* [[DOS_Window_Tips | DOS Window]]
* [[Windows_Tips|Windows]]
* [[TUFLOW_Utilities | TUFLOW Utilities]]
* [[Hardware_Selection_Advice | Hardware Selection Advice]]
* [[Flood Modeller-TUFLOW Linking| Flood Modeller-TUFLOW Linking]]
* Python (Coming Soon)
|-
|}

|}

|style="width:50%; border:1px solid #005581; vertical-align:top; color:white; background:#B5CBDF;"| 
{|width="100%" cellpadding="2" cellspacing="5" style="vertical-align:top; background:#B5CBDF;"
! <h2 style="margin:0; background:#005581; font-size:120%; font-weight:bold; border:1px solid #005581; text-align:left; color:white; padding:0.2em 0.4em;">Demo/Example Models</h2>
|-
||
{|
|style="width:50% vertical-align:top; color:#000; background:#B5CBDF; padding:0em 1em;"|
'''Example Models''' 
The example models are a set of 80 standalone models that demonstrate some of the most widely used features of TUFLOW. They are separated into the following categories: 
* [[Example_Models_Home_page| Basic 2D model]]
* [[Example_Models_Home_page|Output options]]
* [[Example_Models_Home_page|Boundary Condition Options]]
* [[Example_Models_Home_page|Topography Updates]]
* [[Example_Models_Home_page|Loss Options]]
* [[Example_Models_Home_page|Scenario/Event Management]]
* [[Example_Models_Home_page|Bridges]]
* [[Example_Models_Home_page|1D/2D modelling]]
* [[Example_Models_Home_page|1D Operating Structures]]
* [[Example_Models_Home_page|2D/2D Modeling]]
* [[Example_Models_Home_page|TUFLOW HPC (Including GPU Hardware)]]
|style="width:50%; vertical-align:top; horizontal-align:right color:#000; background:#B5CBDF; padding:0em 1em;"|

'''Floodplain Management Association Challenge Models''' 
The following models were created as part of the Floodplain Management Association 2012 Annual Conference 2-D Modelling Challenge:
* [[FMA_Challenge_Models_Introduction | FMA Challenge Models Introduction]]
* [[FMA Challenge 1 (1D-2D linked)|FMA Challenge 1]] (FMA Challenge 1D-2D linked)
* [[FMA Challenge 2|FMA Challenge 2]] (2D only, TUFLOW and TUFLOW-GPU)
* [[FMA Challenge 3|FMA Challenge 3]] (1D-2D, including infiltration)
|}
|}

|}
{{NUMBEROFARTICLES}} pages have been created

ASC to ASC

2018-05-14T10:49:23Z

Par: /* Maximum */

<ol>
=Introduction=
asc_to_asc.exe is a utility that can be used to perform a range of operations on gridded files. The input grids can be either ESRI ASCII grid (.asc) or binary float grids (.flt), both of which can be input and output from TUFLOW. 
This utility is useful for comparing and processing TUFLOW outputs from different .2dm meshes, which can't be compared with the [[RES_to_RES| res_to_res.exe]]. 
For some options (such as processing maximums or differences) the input (.asc or .flt) files must be of the same row/column dimensions. 
The inputs can be a combination of .asc and .flt grids and the -asc or -flt options can be used to set the output type. 
For a complete list to the operations available, please see the table of contents above.

=Operations=
==Convert==
'''"-conv"''' 
Converts between .flt and .asc format. For this operation the output file type is based on the input, for an input .asc file the output will be in .flt format.
Example: 
<li><tt>asc_to_asc.exe -conv *.flt</tt> 
Converts all .flt grids to .asc format.
 
<li><tt>asc_to_asc.exe -conv DEM_M01.asc</tt> 
Converts the file "DEM_M01.asc" for .flt format.
==Maximum==
'''"-max"''' 
Determines the maximum value in all the input .asc files. Two output grids are created: 
*A numerical grid containing the maximum value. 
*A classified grid with the name _src.asc which contains the source grid for the maximum value.
<li><tt>asc_to_asc.exe -max Q100_30min_h.asc Q100_45min_h.asc Q100_60min_h.asc</tt> 
Creates a new grid containing the maximum of the 3 input water level grids.</li>
<li><tt>asc_to_asc.exe -out Q100_Max_Levels.asc -max Q100_30min_h.asc Q100_45min_h.asc Q100_60min_h.asc</tt> 
As per item 2 above, but specifies the output name "Q100_Max_Levels.asc".</li>
Note that the wildcard character "*" is supported in filenames. E.g. 
<li><tt>asc_to_asc.exe -out Q100_Max_Levels.asc -max Q100_*min_h.asc</tt></li> 

==Difference==
'''"-dif"''' 
Takes the difference between the first two .asc files, the second grid is subtracted from the first. If an optional third .asc file is specified, this is used as the output file, otherwise, asc_to_asc creates its own output filename using the names of the two input .dat files. The output is the first .asc file minus the second .asc file.
Two .asc grids are output:
*The first is the difference values between the two .asc files. A difference value only occurs at grid cells that have a value in both grids. If the cell has a null value (ie. the TUFLOW output was dry at that location) in either or both .asc grids, a null value is output.
*A second grid with a “_wd” suffix is output to indicate which .asc grid cells were either previously wet and are now dry or vica versa. Importing this grid into Vertical Mapper creates a .grc (grid classification) grid that has two categories: “Was Wet Now Dry” and “Was Dry Now Wet”. This grid is particularly useful for displaying areas that were previously inundated or previously flood-free.
<li><tt>asc_to_asc.exe -out difference.asc -dif after_h.asc before_h.asc</tt> 
Creates new grids comparing the differences in flood levels and extents for: 
"difference.asc" = "after_h.asc" - "before_h.asc"</li> 
==Cutoff Depth==
'''"-cd<cutoff value>"''' 
Outputs a new file only where the value is greater than the cutoff value. 
*If only one grid is specified this grid is processed. 
*If two grids are specified, the first value is used for setting the cutoff depth and the values from the second grid are processed. 
*If three grids are specified, the third grid is used for setting the filename for the output grid. This is ignored if the "-out" option is used.
<li><tt>asc_to_asc.exe -cd0.1 depth.asc</tt> 
Creates a new depth grid only where the depth is greater than 0.1m.</li> 
<li><tt>asc_to_asc.exe -cd0.1 depth.asc levels.asc</tt> 
Creates a new level grid only where the depth is greater than 0.1m.</li> 
<li><tt>asc_to_asc.exe -cd0.1 -out filtered_levels.asc depths.asc levels.asc</tt> 
As per the example above, but sets the output name as "filtered_levels.asc".</li> 

==Resize==
'''"-resize<factor>"''' 
Resize the grid based on the factor above. The factor must be an integer (greater than 1). The output grid has the same origin (lower left) coordinates as the input grid. The new cell size is the factor times the old cell size. For example if a -resize5 is used on a 2m resolution grid the output grid will be 10m. For processing the grid three options are available
===Average (default)===
This is the defualt processing method, which can also be specified with the '''-rm_avg''' (resize method - average) input flag. When processing for each tile in the new grid, the average of all non-null values in the input grid is taken. For example with a resize factor of 5, the 25 values in the input grid are averaged.
<li><tt>asc_to_asc.exe -resize5 -out DEM_10m.asc DEM_2m.asc</tt> 
Creates a new 10m DEM (DEM_10m.asc) based on the the 2m DEM using an averaging approach.</li> 
===Minimum===
Alternative processing method for resize, specified with the '''-rm_min''' (resize method - minimum) flag. At each output grid the values is the minimum of the values in the input grid.
<li><tt>asc_to_asc.exe -resize5 -rm_min -out DEM_10m_min.asc DEM_2m.asc</tt> 
Creates a new 10m DEM (DEM_10m_min.asc) based on the the 2m DEM using an minimum approach.</li> 
===Maximum===
Alternative processing method for resize, specified with the '''-rm_max''' (resize method - maximum) flag. At each output grid the values is the maximum of the values in the input grid.
<li><tt>asc_to_asc.exe -resize5 -rm_max -out DEM_10m_max.asc DEM_2m.asc</tt> 
Creates a new 10m DEM (DEM_10m_max.asc) based on the the 2m DEM using an maximum approach.</li> 
==Transform==
Transforms the values using a simple y = mx + c approach the multiplier (m) is specified with flag '''-trans_m<value>'''. The add value (c)'''-trans_c<value>'''. Only one values is required to be specified.
<li><tt>asc_to_asc.exe -trans_m0.3048 DEM.asc</tt> 
Multiplies all values by 0.3048.</li> 
<li><tt>asc_to_asc.exe -trans_m0.3048 -trans_c10 DEM.asc</tt> 
Multiplies all values by 0.3048 and then adds 10.0.</li> 
==Classify==
Classifies the grid based on the input classifications. The output file is a classified .asc grid. The classification .csv file should have two columns cutoff value and name (in that order). The first line in .csv treated as a header line and ignored. Any values over the greatest cutoff with be outputted to class "above". 
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Cutoff Value
! style="background-color:#005581; font-weight:bold; color:white;" width=50% | Name
|-
|0.5|| Less than 0.5
|-
|1.0|| 0.5 to 1.0
|-
|2.0|| 1.0 to 2.0
|} 

<li><tt>asc_to_asc.exe -classify classifications.csv results_VMax.asc</tt> 
Outputs a classified grid, based on the cut off values and names in the "classifications.csv".</li> 

If using vertical mapper the -grc option can be used to create the .asc file in classified grid format, in this format rather than storing a numerical value when interrogating an area a label is returned. This format is not recognised by ArcMap or QGIS. If using the grc option it is also possible to specify the desired RGB (red, green, blue) values for the output grid in the .csv file used for the classification. The RGB values should be specified in the 3-5th columns of the .csv file. 
<li><tt>asc_to_asc.exe -RGB -grc -classify depth_classify.csv results_dMax.asc</tt> 

{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;" width=20% | Cutoff Value
! style="background-color:#005581; font-weight:bold; color:white;" width=20% | Name
! style="background-color:#005581; font-weight:bold; color:white;" width=20% | R
! style="background-color:#005581; font-weight:bold; color:white;" width=20% | G
! style="background-color:#005581; font-weight:bold; color:white;" width=20% | B
|-
|0.5|| Less than 0.5 || 0 || 0 || 192
|-
|1.0|| 0.5 to 1.0 || 0 || 0 || 128
|-
|2.0|| 1.0 to 2.0 || 0 || 0 || 64
|} 

In the image below two grids are shown in MapInfo / Vertical Mapper, one is classified without the -grc option and a class number is returned for the grid. The second grid has been created with the -grc option shown, when querying this the label is returned instead.

[[File:TUFLOW Utilities GRC01.jpeg|600px]]

==Extract Breaklines from DEM==
'''"-brkline <gis file in 2d_zsh format>"''' 
This feature was added to the 2013-06-AA version of the utility. 
Extracts elevations from a DEM for breaklines in the 2d_zsh format. This GIS input should have four attributes, z, dz, width and shape_options, as described in the TUFLOW manual. For the utility the '''dz''', '''shape_width''' and the '''shape_options''' are used. Valid shape_options are "Max" and "Min" or blank (average used). The utility will extract an elevation at each vertex along the line. Depending on the line width and DEM cell size, the following methods are used: 
* If the width is set to 0, the closest DEM value to the vertex is used. If a "shape_option" is specified this is ignored.
* If the width is greater than 0, but less than 1.5 times the DEM cell size, the four DEM values surrounding the vertex are used. If max or min is specified in the "shape_option" the max or min of the four values is used. If max or min option is not specified (attribute is blank), the average of the four values is used.
* If the width is greater than 1.5 times the DEM cell size, at each vertex a buffer region is created and all non null DEM values within the buffer object are processed. The diameter of the buffer region is equal to the width specified. If max or min option is not specified, the average of the values within the region is used. These buffer regions are outputted as a separate file. 
If a '''dz''' value is specified (for the 2014-01-AA version or later) this can be used to control the spacing of vertices along the line. If a '''dz''' value of 100 is specified the maximum spacing along the line is 100 (metres or feet), if the existing vertices along the line are greater than 100 (m or ft) apart additional vertices are inserted. The method for inserting additional vertices creates equally spaced vertices. For example, if two vertices along a line are spaced 250m apart and a dz attribute of 100m is specified three line segments of 83.3m will be created as opposed to two segments of 100m and one segment of 50m. 
'''NOTE:''' For the output GIS file, the '''dz''' attribute is set to 0.0 regardless of the value set in the input field.

Example: 
<li><tt>asc_to_asc.exe -brkline 2d_zsh_breaklines_L.shp DEM.asc</tt> 

==Fuzzy Map==
'''"-fuzzy <input grids>"''' 
This feature was added to the 2014-03-AB version of the utility. 
A fuzzy map can be used when comparing a large number of simulations. 
For each input grid (or scenario) the grid is classed as either 1 if the results grid is wet or 0 if dry. The total score for each grid cell is is calculated and then divided by the total number of input grids. A value of 1 indicates that the cell was wet in each simulation a value of 0 is dry in all simulations. Grids with a value of 0.5 are most sensitive. 
This can be useful for quantifying the sensitivity of the model to parameters. 
Example: 
<li><tt>asc_to_asc.exe -fuzzy *_d_Max.flt</tt> 
Create a fuzzy map from all maximum depth grids in the directory.
==Histogram==
'''"-histogram bins.csv <input grid>"''' 
This feature was added to the 2014-03-AB version of the utility. 
Calculates the number of cells and percentage of cells that fall in each range. Requires and input .csv file containing the bin values. 
An example inputs bin file is: 
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Bin
! style="background-color:#005581; font-weight:bold; color:white;" width=50% | Label
|-
|0.25|| Less than 0.25
|-
|0.5|| 0.25 to 0.50
|-
|1.0|| 0.5 to 1.0
|-
|2.0|| 1.0 to 2.0
|-
|3.0|| 2.0 to 3.0
|-
|5.0|| 3.0 to 5.0
|}

An example output looks like the below:
{| class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Bin
! style="background-color:#005581; font-weight:bold; color:white;" width=25% | Label
! style="background-color:#005581; font-weight:bold; color:white;" width=25% | Count
! style="background-color:#005581; font-weight:bold; color:white;" width=25% | Percentage
|-
|0.25|| Less than 0.25 || 986,434 || 58.61
|-
|0.5|| 0.25 to 0.50 || 334,422 || 19.87
|-
|1.0|| 0.5 to 1.0 || 216,449 || 12.86
|-
|2.0|| 1.0 to 2.0 || 118,452 || 7.04
|-
|3.0|| 2.0 to 3.0 || 10,206 || 0.61
|-
|5.0|| 3.0 to 5.0 || 15,998 || 0.95
|-
|Above 5.0|| Above 5.0 || 973 || 0.06
|}
 
Example:
<li><tt>asc_to_asc_w64.exe –histogram histogram_bins.csv results_d_Max.asc</tt></li>

==Extract 1D Model Inputs==
'''"-egc control_file.egc"''' 
This allows 1D Network (1d_nwk) and/or 1D Cross-Sections to be extracted from a series of grids. 
A simple input file similar to the TUFLOW geometry control file is input into the utility. This is nominally given the extension .egc (Estry Geometry Control). 
 
Two input GIS layers can be used, these are the branch lines (channels) and cut lines (cross sections). The branch line is split into the 1d_nwk layer, a new 1D channel is created for each section. The GIS attributes of these are defined in the sections below.
===Branch Lines===
The branch lines are split into channels using the cross-section cut lines detailed below. A number of channel characteristics can be set for branch lines. The required attribute names and data types for branch line are as follows:
{| align="center" class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Attribute (type)
! style="background-color:#005581; font-weight:bold; color:white;" width=80% | Description
|-
|Name (character 10)|| Sets the branch name, unique chainage identifier is added to all output channels.
|-
|n_or_nF (float)|| Sets the output "n_or_nF" attribute for all output channels in the 1d_nwk layer.
|-
|UCS (float)|| Sets the "UCS" attribute for all output channels in the 1d_nwk layer.
|-
|FLC (float)|| Sets the "FLC" attribute for all output channels in the 1d_nwk layer. If a value of greater than 0 is specified the FLC is split between channels within the branch. For example if 0.5 is specified and the branch is split into 10 channels, each channel will have an output "Form_Loss" of 0.05.
|-
|ChanType (character 4)|| Sets the "Type" attribute for all output channels in the 1d_nwk layer. If left blank a default channel type of "S" is applied.
|}

===Cut Lines===
For each line in the cut line layer a cross-section will be extracted and output into .csv file format ready for use in TUFLOW. A number of cross section characteristics can be set for each cut line. The required attributes for the cross-section cut line are:
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;"| Attribute (type)
! style="background-color:#005581; font-weight:bold; color:white;" width=80% | Description
|-
|Source (character 50)|| Optional output cross-section file name. If left blank the name and chainage of the branch the cross-section intersects is used.
|-
|Distance (float)|| Optional distance along the line for sampling from grids. If not specified the value specified in the .egc file is used.
|-
|Split (character 1)|| "T" (True) or "F" (False) for splitting the branch, set to false and the branch will not be split (used for centre sections)
|-
|Extract_XS (character 1)|| "T" (True) or "F" (False) for cross-section extraction. If set to "F" no cross-section is extracted for the cut line.
|-
|Extract_Method (character 50)|| Specify the method for extract the elevations from the grid (does not apply to Material grids). Options are: 
* Min
* Max
* Average (default)
|-
|Buffer_Method (character 50)|| Optional method for extracting the elevations from the grid (does not apply to Material grids) values from grid. Options are: 
* Point {default} - Value at the cross-section point is used.
* Buffer - circular buffer region around each cross-section point is created and elevation is extracted from this, using Min, Max or Average as described above.
* Perpendicular - A line perpendicular to section direction is used and elevation is extracted from this, using Min, Max or Average as described above. This can be useful if the section follows a hydraulic control (such as embankment) to ensure that the high / or low point is extracted.
|-
|Buffer_Distance (float)|| Sets the distance for when using the "Buffer" or "Perpendicular" methods above.
|}

===EGC commands===
The .egc file is read in a similar manner to the .tgc (TUFLOW geometry control) file. This file is read in a sequential order and for repeated commands the final one prevails. 
A full list of the availble .egc commands is detailed in the table below.
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;"| Attribute (type)
! style="background-color:#005581; font-weight:bold; color:white;" width=70% | Description
|-
|Read GIS Branch == <1d_br GIS file>|| Reads the branch lines, these are described above.
|-
|Read GIS XS == <1d_cut GIS file>|| Reads the cross-section cut lines, these are described above.
|-
|Read GIS FLC == <GIS file>|| Optional GIS layer of polygons that can be used to specify form loss coefficients to the 1d_nwk layer. A single GIS (float) attribute is required. A FLC value of greater than 0 will be split between all 1d_nwk channels within the region. A FLC value of less than 0, will apply the absolute value to all channels within the polygon. For example if an FLC value of -0.1 is specified, all channels that fall within the polygon will have a form_loss attribute of 0.1. If a channel falls within multiple polygons, the form loss values will be added.
Reads the polygons off losses from GIS layer. cross-section cut lines, these are described above.
|-
|Set XS dx == <distance>|| Sets the default distance across section to extract elevations and materials data. This can be specified on the cut lines as detailed above.
|-
|Set XS Z == <elevation>|| Sets the elevation for all points in all cross-sections.
|-
|Set XS Mat == <Material ID>|| Sets the material ID for all points in all cross-sections.
|-
|Read Grid Z == <grid layer of elevations>|| Read elevations from DEM and assign this to all cross-section extraction points that fall within active DEM pixels.
|-
|Read Grid Mat == <grid layer of Material IDs>|| Read material IDs from raster grid and assign this to all cross-section extraction points that fall within active DEM pixels. This should be an integer grid.
|-
| Write XS == ON or '''OFF'''|| Turns on or off the writing of the 1d_xs layer. The default is off.
|-
| Write NWK == ON or '''OFF'''|| Turns on or off the writing of the 1d_nwk layer. The default is off.
|-
|Output XS == <output gis layer> || Sets the output GIS layer for the 1D cross-sections.
|-
|Output NWK == <output gis layer> || Sets the output GIS layer for the 1D channel cross-sections.
|-
|Output NWK == <output gis layer> || Sets the output GIS layer for the 1D channel cross-sections.
|-
|FLC per Unit Length == <form loss per unit length> || The form loss per unit length is written to the "exit_loss" attribute of all 1d_nwk channels.
|}
Example: 
<li><tt>asc_to_asc.exe -egc MR_1d_001.egc</tt> 
An example .egc file is: 
<pre>
Read GIS Branch == 1d_br_MR_001.MIF
Read GIS XS == 1d_cut_MR_001.MIF
Output Nwk == 1d_nwk_MR_001.MIF
Output XS == 1d_xs_MR_001.MIF
Write NWK == ON !Write 1d_nwk layer
Write XS == ON !Write 1d_xs layer

Set XS dx == 5 !set default spacing, can be specified on xs or cut line

Set XS Mat == 1 !default Material ID of 1
Read Grid Mat == grid\grid_5m_2d_mat_MR_001.flt

Set XS Z == 99
Read Grid Z == grid\dem_5m_regional.flt
Read Grid Z == grid\dem_1m_bathymetry.flt
Read Grid Z == grid\dem_1m_survey.flt
</pre>

==Extract 1D Nodal Area Tables from Grid==
'''"-na <gis_region_file> <input grid>"''' 
Can be used to extract nodal-area (elevation-area) tables from a DEM, and output these in a .csv file format suitable for input into the 1D domain of a TUFLOW model. 
The input GIS region file should have the same attributes as the 1d_tab file format produced by TUFLOW. The first attribute ("Source" ) should contain a valid .csv file name. 
The out nodal area table extends from the minimum to the maximum elevation in the DEM. A user defined minimum value can be specified using the "Skew" attribute of the GIS region. 
Example: 
<li><tt>asc_to_asc.exe -na 1d_na_storgae_R.shp DEM_1m.flt</tt> 

==Statistics==

<big>'''"-stat<type>"'''</big>

As of the 2017-10-AA build, the ASC_to_ASC.exe utility allows the user to perform a number of statistical analyses on a group of input grids (*.flt or *.asc format). This is particularly useful when extracting information from assessments that produce multiple result files for a single event, for example, processing grids from an ensemble assessment with numerous temporal pattern arrangements.

The available options are:
* Median
* Mean
* Frac
* Min
* Max
* All
* Rank<integer id>

The below gives a description on each option as well as an example. It is also useful to consider using wildcards in the batch file to supplement typing out each input grid file individually. Several of the examples below utilise this ability to demonstrate how it can be done. 
 
==="-statMedian"===

The -statMedian flag outputs the median value at each grid cell from all the input grids. All the input grids are considered, regardless of if the grid cell is dry in some of the input grids (dry areas are still ranked).

If the number of input grids is an even number, the median value is taken from the grid that is ranked ''n / 2 + 1'' (where n is the number of input grids). For example if the number of input grids is 10, at each grid cell the values are ranked lowest to highest (from 1 to 10). The result is taken from the 6th ranked grid. The median command outputs two grids:
* A value grid: the resulting median value
* An SRC grid: a grid listing which source input grid the median result value came from (a corresponding .csv file is also written as a legend) 
<li><tt>asc_to_asc.exe -statMedian Q100_30min_TP1_h.asc Q100_30min_TP2_h.asc Q100_30min_TP3_h.asc Q100_30min_TP4_h.asc Q100_30min_TP5_h.asc</tt> 
[[File: asc_to_asc_statsMedian_eg.PNG|1000px|]] 

==="-statMean"===

The -statMean flag outputs the mean value at each grid cell. Unlike the median, the mean is only calculated at grid cells that are wet (that show flooding) in all input grids. Please note that the source grid is the next grid above the mean value. The mean command outputs two grids:
* A value grid: the resulting value
* An SRC grid: a grid listing which source input grid the result value came from or was the next above (a corresponding .csv file is also written as a legend) 
<li><tt>asc_to_asc.exe -statMean Q100_30min_*_h.asc</tt> 

==="-statFrac"===

The -statFrac flag outputs a value at each grid cell that represents the fraction of the events that the grid cell is wet in. For example, if the number of input grids is 10, and a value of 0.2 is returned, this means this grid cell experienced flooding in 2 out of the 10 events. A value of 1.0 means that the grid cell was wet in all events.

The utility outputs one grid:
* A Frac grid: the resulting Fraction value 
<li><tt>asc_to_asc.exe -statFrac Q100_30min_*_h.asc</tt> 

==="-statMin"===

The -statMin flag outputs the minimum value at each grid cell from all the input grids.

The utility outputs two grids:
* A value grid: the resulting value
* An SRC grid: a grid listing which source input grid the minimum result value came from (a corresponding .csv file is also written as a legend) 
<li><tt>asc_to_asc.exe -statMin Q100_30min_*_h.asc</tt> 

==="-statMax"===

The -statMax flag outputs the maximum value at each grid cell from all the input grids. This flag is analogous with the [[#Maximum|-Max]] operation flag.

The utility outputs two grids:
* A value grid: the resulting value
* An SRC grid: a grid listing which source input grid the maximum result value came from (a corresponding .csv file is also written as a legend) 
<li><tt>asc_to_asc.exe -statMax Q100_30min_*_h.asc</tt> 

==="-statAll"===

The -statAll flag undertakes and creates results for all the statistic operations mentioned above.

The utility outputs 9 grids:
* A median, mean, max, min and frac grid (as detailed above)
* An SRC grid: for the median, mean, min and max calculations (calculation of source grids as detailed above)
* A .csv file that contains the legend for all SRC grids 
<li><tt>asc_to_asc.exe -statAll Q100_30min_*_h.asc</tt> 

==="-statRank<integer id>"===

The -statRank<integer> flag outputs the ''n<integer>'' ranked value at each grid cell from all the input grids. All the input grids are considered, regardless of if the grid cell is dry in some of the input grids (dry areas are still ranked). For example, if the number of input grids is 10, at each grid cell the values are ranked lowest to highest (from 1 to 10). -statRank8 will output results taken from the 8th ranked grid. In this example, -statRank1 is equivalent to ''Min'', -statRank10 is equivalent to ''Max'', and -statRank6 is equivalent to ''Median''. The Rank flag allows additional functionality that lets users extract results in between those that are pre-programmed.

The utility outputs two grids:
* A value grid: the resulting value
* An SRC grid: a grid listing which source input grid the ranked result value came from (a corresponding .csv file is also written as a legend) 
<li><tt>asc_to_asc.exe -statRank5 Q100_30min_*_h.asc</tt> 

=Other Options (switches)=
A list of the general switches is provided in the table below, these are available for all operations listed above: 
{| align="center" class="wikitable"

! style="background-color:#005581; font-weight:bold; color:white;"| Switch
! style="background-color:#005581; font-weight:bold; color:white;" width=80% | Description
|-
|"-b"|| Run the utility in batch mode, this suppresses the prompt to press enter at the end of processing. Used in .bat files where two or more files are to be processed. The -b flag should be placed after the asc_to_asc.exe call, before the function command. For example: <tt>asc_to_asc.exe -b -brkline 2d_zsh_breaklines_L.shp DEM.asc</tt> 
|-
|"-out <output grid name>"||Specify the output filename for the new grid. '''Note:''' a space is required between the -out and the filename.
|-
|"-flt"||Set the output grid format to binary float (.flt).
|-
|"-asc"||Set the output grid format to ESRI ascii format (.asc).
|-
|"-grc"||For use with the "-classify" option and .asc format output. This creates a classified grid (uses name rather than number). This is only valid if using Vertical Mapper, neither QGIS or ArcMap will recognise this format. This can also be used with the -RGB option to specify the output colouring of your grid.
|}

</ol>
{{Tips Navigation
|uplink=[[TUFLOW_Utilities | Back to TUFLOW Utilities]]
}}

Python Library TUFLOW Results

2018-05-10T05:48:13Z

Par: /* Getting the TUFLOW results python library */

[[File:TUPython.png | 435px]]

=Introduction=
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
* Combines the 1D results, 2D plot outputs and new reporting location data
* The outputs are stored in a separate '''Plot''' folder in the TUFLOW results directory
* .tpc (TUFLOW Plot Control file links to data in csv and gis folders
* Has additional Node and Channel information files contain connectivity information
This is the default approach for the 2016 version but can be modified with the TUFLOW command "<tt>Output Approach == Pre 2016</tt>" (refer to the manual for more information on this command. 
To make this data easier to work with an open source python library has been created and made available. This allows the user to load results and then interact with these. This library does not have any plotting functionality directly, with the returns typically being arrays (e.g. time and flows) however, the examples below give some examples using common plotting libraries such as matplotlib. 
=Getting the TUFLOW results python library=
You can find the TUFLOW_results.py (previously TUFLOW_Results2016.py) on the QGIS plugin repository, on the TUFLOW support GitHub repository or if you have QGIS and the TUFLOW plugin installed, you will already have it on your computer.
<ol>
<li>QGIS plugin repo: [https://plugins.qgis.org/plugins/tuflow/ https://plugins.qgis.org/plugins/tuflow/] 
: If you select '''Download Latest''' and save the .zip file, the TUFLOW_results.py sits inside the .zip file.</li>
<li>GitHub: [https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin QGIS plugin https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin] 
: If you select '''Clone or Download''' and then select '''Download Zip''' and save the .zip file, the TUFLOW_results.py sits inside the .zip file.</li>
<li>QGIS 
: If you have QGIS2 with the TUFLOW plugin installed via the plugin repository, the TUFLOW_results.py sits within: C:\Users\<User Name>\.qgis2\python\plugins\tuflow 
: If you have QGIS3 with the TUFLOW plugin installed via the plugin repository, the TUFLOW_results.py sits within: C:\Users\<User Name>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\tuflow </li>
</ol>
The TUFLOW python library does not need to be installed in python (through pip or otherwise) like other common modules, the TUFLOW_results.py file just needs to be in the same location as your python project.

Note it shouldn’t matter if you’re using python 2 or python 3.

=Dependencies=
The TUFLOW results library calls a number of python modules, these are:
* csv
* numpy
* os
* sys
Of these the csv, os and sys functionality should be available directly with the python install. Depending on the method used to install python, numpy may need to be installed. If installation of numpy is required, please refer to the numpy documentation [http://www.numpy.org/ http://www.numpy.org/].
=Compatible Python Versions=
The functionality has been developed for Python 2.7, but should be compatible with Python 3.5. Other versions of python are currently untested.
=Usage=

==Import==
This library is imported with the typical python syntax. 
<pre>import TUFLOW_results</pre>
==Initialise Results (ResData)==
The results data functionality has a class defined, this is named '''ResData'''. An instance of the results can be initialised with the following syntax:
<pre>res = TUFLOW_results.ResData()</pre>
==Defined Methods (Functions)==
The following are the defined '''functions''' in the results data class (ResData).
===Load Results===
Results are loaded in with the syntax below.
<pre>error, message = res.Load(r'D:\TUFLOW\QGIS\test\plot\Plot_Example.tpc')</pre>
The two return arguments are:
* error (logical) set to True if an error has been encountered.
* message (string), if an error has occurred the message string will be populated with an error message.
===Get Time-series===
Time-series at a 1D, 2D or reporting location can be returned using the following syntax:
<pre>
found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)
</pre>
The inputs to this are:
<li>ID - The ID of the 1D, 2D or reporting location feature.</li>
<li>Domain - The domain to return the results for, this will be one of '''1D''', '''2D''' or '''RL''' (for reporting location data)</li>
<li>Results Type - The results type to be returned. This includes H (level), Q (flow), V (velocity), E (energy), QA (flow area) depending on the data types that have been output!</li>
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point. If unsure or unknown this can be set to a blank string such as ''.</li>
The return arguments are:
<li>found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.</li>
<li>results (numpy array) - The return array for the requested data.</li>
<li>message (string) - If the data is not found, this message string contains information.</li>
For example:
<pre>
found, results, message = res.getTS('ds3','1D','Q','L')
</pre>
Will return flow (Q) data for the 1D channel with ID ds3. The optional 'L' geometry indicates that this is stored on a line object in the GIS plot objects.
'''Note''' As the time data typically does not change (this is not a return argument) but can be accessed by the <tt>res.times</tt>. See the examples below.
===Long Profile Functions===
When dealing with 1D long profile data, if a single 1D channel is specified the data for all channels downstream will returned. If two channels are specified, long profile data will only be returned for the channels between the specified channels.

====Get Long Profile Connectivity (LP_getConnectivity)====
This determines and stores the connectivity of the specified channels. This is used in later routines to determine the channels and nodes to plot for the long profile. The syntax is:
<pre>error, message = res.LP_getConnectivity(<US Channel ID>,<US Channel ID or None>)</pre>
The inputs to this are:
<li>Upstream Channel ID - The ID of the Upstream 1D channel.</li>
<li>Downstream Channel ID - The ID of the Downstream 1D channel, if no downstream channel is to be used this can be set to '''None'''.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getConnectivity('FC01.40',None)
</pre>
Determines all the channels downstream of '''FC01.40'''.
<pre>
error, message = res.LP_getConnectivity('FC01.40','ds3')
</pre>
Determines the channels between '''FC01.40''' and '''ds3''', an error will be returned if these channels are not connected.
====Get Long Profile Static Data (LP_getStaticData)====
Once the connectivity between two channels has been determined, this routine can be used to get data that does not change between time-steps. This includes:
* distance information
* maximum data
* bed levels
The syntax is:
<pre>error, message = res.LP_getStaticData()</pre>
There are no input arguments as the channel connectivity is stored in the res.LP class. The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
====Get Long Profile Data (LP_getData)====
This function gets data at a specific time. If looping through timesteps (e.g. for an animation) the channel connectivity and static data will not change between timesteps and therefore only the '''LP_getData''' will need to be repeated. The syntax is:
<pre>
error, message = res.LP_getData(<data type>,<time>,<time search tolerance>)
</pre>
The inputs to this are:
<li>Data type - The results data to return, this is one of 'Head' or 'Energy'</li>
<li>Time - The time in hours to get the data for.</li>
<li>Time search tolerance - If the closest output time is greater than the time search tolerance from the specified time an error will be returned.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getData('Head',1,0.01)
</pre>
Returns the water level (head) data at time 1 hours using a search tolerance of 0.01 hours.
==Other Attributes==
Once initialised the ResData class also has a number of '''attributes''' associated with it as well as the '''defined functions''' described above, these are outlined in the table below.
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Attribute Name
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Type
! style="background-color:#005581; font-weight:bold; color:white;" width=70% | Description
|-
|script_version|| string || Contains a version number of the TUFLOW results library, e.g. '2016-01-AA'
|-
|filename|| string|| The full filepath to the .tpc file.
|-
|fpath|| string|| The path of the folder which contains the .tpc file.
|-
|nTypes|| integer|| The number of data types that are stored in the dataset.
|-
|Types || list || A lists of the data types that are stored in the dataset.
|-
|LP || class (LP) || Contains Long profile information, connectivity, distances etc.
|-
|Data_1D|| class(Data_1D) || The 1D results are all stored in this class.
|-
|Data_2D|| class(Data_2D) || The 2D results are all stored in this class.
|-
|Data_RL|| class(Data_RL) || The reporting location results are all stored in this class.
|-
|GIS|| class(GIS)|| This contains the information read in from the <tt>GIS Plot Layer</tt> csv files.
|-
|formatVersion|| integer || The format version of the results as defined in the .tpc file.
|-
|units || string || The units as defined in the .tpc. E.g. "Metric" or "English"
|-
|displayname || string || The simulation name e.g. "M04_5m_001_2015"
|-
|Index || class(PlotObjects)|| This contains data read from the "GIS Plot Objects"
|-
|nodes|| class(NodeInfo) || Contains information on the 1D nodes, as read from the "1D Node Info" .csv file.
|-
|Channels|| class(ChanInfo)|| Contains information on the 1D nodes, as read from the "1D Channel Info" .csv file.
|-
|times || numpy ndarray|| The active times. This is typically static, however calls to function '''getTS''' may cause this array to be updated (if the 1D or 2D outputs have a different output interval)
|}
 

=Examples=
These examples work with the Tutorial Model module 4 results. The tutorial model can be downloaded on the [https://www.tuflow.com/Tuflow%20Tutorial%20Models.aspx TUFLOW website].
==Plot Flow in Channel==
<pre>
import os #operating system functions
import sys #system functions
import matplotlib.pyplot as plt
import TUFLOW_results

input_res = r'C:\TUFLOW\Models\Tutorials\QGIS\Complete_Model\TUFLOW\results\M04\2d\plot\M04_5m_001.tpc'

# initialise the results class
res = TUFLOW_results.ResData()

# Load the data and terminate if error returned
error, message = res.Load(input_res)
if error:
print(message)
sys.exit()
print('loaded')

#create a figure
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

#Get flow data
chan_id = 'ds3' # this is the channel ID to use
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax1.set_title('Example time-series - single location')
ax1.grid()
ax1.legend()
plt.show()
</pre>

 
[[File:Python Results 2016 Q Example 01.png|600px]]
 
This will create a figure that looks like the above.
 

==Plot Multiple Water Levels==
In this example, it is assumed that the results data has been loaded as per the above.
<pre>
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

# list of nodes to plot
node_ids = ['FC01.14.1','FC01.15.1','FC01.16.1','FC01.17.1']

#Get water level data
for node_id in node_ids: #for each node in the list above
found, results, message = res.getTSData(node_id,'1D','H','P')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,label='Level - '+node_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Water Level (mAHD)')
ax1.set_title('Example time-series - multiple locations')
ax1.set_ybound((38.,44.)) #overwrite the y axis bounds
ax1.grid()
ax1.legend(loc='lower right')
plt.show()
</pre>
 
[[File:Python Results 2016 H Example 01.png|600px]]
This will create a figure that looks like the above. 
 
==Dual Axis (flow and velocity) Plot==
In this example it is assumed the results have been loaded as per example 1.
<pre>
# specify channel to plot
chan_id = 'ds3'

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.80,0.75)) #add axis to figure
ax2 = ax1.twinx() #create new axis with same x properties

#Get flow data
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()

#Get velocity data
found, results, message = res.getTSData(chan_id,'1D','V','L')
if found:
print('found requested data')
ax2.plot(res.times,results,color='r',label='Velocity - '+chan_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax2.set_ylabel('Velocity (m/s)')
ax1.set_title('Example time-series - twin axis')
ax1.grid()
h1, l1 = ax1.get_legend_handles_labels()
h2, l2 = ax2.get_legend_handles_labels()
ax1.legend(h1+h2, l1+l2, loc='upper left')
plt.show()
</pre>
 
[[File:Python Results 2016 QV Example 01.png|600px]]
 
This will create a figure that looks like the above. 
==Long Profile Peak Levels==
This also assumes that the data has been loaded as per example 1 above. The long profile data for all channels downstream of '''FC01.40''' will be plotted.
<pre>
us_chan = 'FC01.40' #upstream channel
ds_chan = None

#get connectivity between channels
error, message = res.LP_getConnectivity(us_chan,ds_chan)
if error:
print(message)
sys.exit()
else:
print('LP connectivity determined.')

print('Get LP static data')
error, message = res.LP_getStaticData()
if error:
print(message)
sys.exit()
else:
print('LP static data retrieved')

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.80)) #add axis to figure

#plot data
# Max WL
ax1.plot(res.LP.dist_nodes, res.LP.Hmax,color='r',label = 'Max Water Level')

# Bed Level
ax1.plot(res.LP.dist_chan_inverts, res.LP.chan_inv,color='brown',linewidth = '3',label = 'Bed Level Level')

# manage plot
ax1.set_xlabel('Distance (m)')
ax1.set_ylabel('Level (mAHD)')
ax1.set_title('Example Long Profile - Peak Levels')
ax1.grid()
ax1.legend(loc='upper right')
plt.show()
</pre>
 
[[File:Python Results 2016 LP Example 01.png|600px]]
 
This will create a figure that looks like the above. 

=Other Versions=
An older version of the library that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results) is also available. This is currently undocumented, however, if you would like this please contact support@tuflow.com.

Python Library TUFLOW Results

2018-05-10T05:28:12Z

Par:

[[File:TUPython.png | 435px]]

=Introduction=
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
* Combines the 1D results, 2D plot outputs and new reporting location data
* The outputs are stored in a separate '''Plot''' folder in the TUFLOW results directory
* .tpc (TUFLOW Plot Control file links to data in csv and gis folders
* Has additional Node and Channel information files contain connectivity information
This is the default approach for the 2016 version but can be modified with the TUFLOW command "<tt>Output Approach == Pre 2016</tt>" (refer to the manual for more information on this command. 
To make this data easier to work with an open source python library has been created and made available. This allows the user to load results and then interact with these. This library does not have any plotting functionality directly, with the returns typically being arrays (e.g. time and flows) however, the examples below give some examples using common plotting libraries such as matplotlib. 
=Getting the TUFLOW results python library=
You can find the TUFLOW_results.py (previously TUFLOW_Results2016.py) on the QGIS plugin repository, on the TUFLOW support GitHub repository or if you have QGIS and the TUFLOW plugin installed, you will already have it on your computer.
<ol>
<li>QGIS plugin repo: [https://plugins.qgis.org/plugins/tuflow/ https://plugins.qgis.org/plugins/tuflow/] 
: If you select '''Download Latest''' and save the .zip file, the TUFLOW_results.py sits inside the .zip file.</li>
<li>GitHub: [https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin QGIS plugin https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin] 
: If you select '''Clone or Download''' and then select '''Download Zip''' and save the .zip file, the TUFLOW_results.py sits inside the .zip file.</li>
<li>QGIS 
If you have QGIS2 with the TUFLOW plugin installed via the plugin repository, the TUFLOW_results.py sits within: C:\Users\<User Name>\.qgis2\python\plugins\tuflow 
If you have QGIS3 with the TUFLOW plugin installed via the plugin repository, the TUFLOW_results.py sits within: C:\Users\<User Name>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\tuflow </li>
</ol>
The TUFLOW python library does not need to be installed in python (through pip or otherwise) like other common modules, the TUFLOW_results.py file just needs to be in the same location as your python project.

Note it shouldn’t matter if you’re using python 2 or python 3.
=Dependencies=
The TUFLOW results library calls a number of python modules, these are:
* csv
* numpy
* os
* sys
Of these the csv, os and sys functionality should be available directly with the python install. Depending on the method used to install python, numpy may need to be installed. If installation of numpy is required, please refer to the numpy documentation [http://www.numpy.org/ http://www.numpy.org/].
=Compatible Python Versions=
The functionality has been developed for Python 2.7, but should be compatible with Python 3.5. Other versions of python are currently untested.
=Usage=

==Import==
This library is imported with the typical python syntax. 
<pre>import TUFLOW_results</pre>
==Initialise Results (ResData)==
The results data functionality has a class defined, this is named '''ResData'''. An instance of the results can be initialised with the following syntax:
<pre>res = TUFLOW_results.ResData()</pre>
==Defined Methods (Functions)==
The following are the defined '''functions''' in the results data class (ResData).
===Load Results===
Results are loaded in with the syntax below.
<pre>error, message = res.Load(r'D:\TUFLOW\QGIS\test\plot\Plot_Example.tpc')</pre>
The two return arguments are:
* error (logical) set to True if an error has been encountered.
* message (string), if an error has occurred the message string will be populated with an error message.
===Get Time-series===
Time-series at a 1D, 2D or reporting location can be returned using the following syntax:
<pre>
found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)
</pre>
The inputs to this are:
<li>ID - The ID of the 1D, 2D or reporting location feature.</li>
<li>Domain - The domain to return the results for, this will be one of '''1D''', '''2D''' or '''RL''' (for reporting location data)</li>
<li>Results Type - The results type to be returned. This includes H (level), Q (flow), V (velocity), E (energy), QA (flow area) depending on the data types that have been output!</li>
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point. If unsure or unknown this can be set to a blank string such as ''.</li>
The return arguments are:
<li>found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.</li>
<li>results (numpy array) - The return array for the requested data.</li>
<li>message (string) - If the data is not found, this message string contains information.</li>
For example:
<pre>
found, results, message = res.getTS('ds3','1D','Q','L')
</pre>
Will return flow (Q) data for the 1D channel with ID ds3. The optional 'L' geometry indicates that this is stored on a line object in the GIS plot objects.
'''Note''' As the time data typically does not change (this is not a return argument) but can be accessed by the <tt>res.times</tt>. See the examples below.
===Long Profile Functions===
When dealing with 1D long profile data, if a single 1D channel is specified the data for all channels downstream will returned. If two channels are specified, long profile data will only be returned for the channels between the specified channels.

====Get Long Profile Connectivity (LP_getConnectivity)====
This determines and stores the connectivity of the specified channels. This is used in later routines to determine the channels and nodes to plot for the long profile. The syntax is:
<pre>error, message = res.LP_getConnectivity(<US Channel ID>,<US Channel ID or None>)</pre>
The inputs to this are:
<li>Upstream Channel ID - The ID of the Upstream 1D channel.</li>
<li>Downstream Channel ID - The ID of the Downstream 1D channel, if no downstream channel is to be used this can be set to '''None'''.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getConnectivity('FC01.40',None)
</pre>
Determines all the channels downstream of '''FC01.40'''.
<pre>
error, message = res.LP_getConnectivity('FC01.40','ds3')
</pre>
Determines the channels between '''FC01.40''' and '''ds3''', an error will be returned if these channels are not connected.
====Get Long Profile Static Data (LP_getStaticData)====
Once the connectivity between two channels has been determined, this routine can be used to get data that does not change between time-steps. This includes:
* distance information
* maximum data
* bed levels
The syntax is:
<pre>error, message = res.LP_getStaticData()</pre>
There are no input arguments as the channel connectivity is stored in the res.LP class. The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
====Get Long Profile Data (LP_getData)====
This function gets data at a specific time. If looping through timesteps (e.g. for an animation) the channel connectivity and static data will not change between timesteps and therefore only the '''LP_getData''' will need to be repeated. The syntax is:
<pre>
error, message = res.LP_getData(<data type>,<time>,<time search tolerance>)
</pre>
The inputs to this are:
<li>Data type - The results data to return, this is one of 'Head' or 'Energy'</li>
<li>Time - The time in hours to get the data for.</li>
<li>Time search tolerance - If the closest output time is greater than the time search tolerance from the specified time an error will be returned.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getData('Head',1,0.01)
</pre>
Returns the water level (head) data at time 1 hours using a search tolerance of 0.01 hours.
==Other Attributes==
Once initialised the ResData class also has a number of '''attributes''' associated with it as well as the '''defined functions''' described above, these are outlined in the table below.
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Attribute Name
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Type
! style="background-color:#005581; font-weight:bold; color:white;" width=70% | Description
|-
|script_version|| string || Contains a version number of the TUFLOW results library, e.g. '2016-01-AA'
|-
|filename|| string|| The full filepath to the .tpc file.
|-
|fpath|| string|| The path of the folder which contains the .tpc file.
|-
|nTypes|| integer|| The number of data types that are stored in the dataset.
|-
|Types || list || A lists of the data types that are stored in the dataset.
|-
|LP || class (LP) || Contains Long profile information, connectivity, distances etc.
|-
|Data_1D|| class(Data_1D) || The 1D results are all stored in this class.
|-
|Data_2D|| class(Data_2D) || The 2D results are all stored in this class.
|-
|Data_RL|| class(Data_RL) || The reporting location results are all stored in this class.
|-
|GIS|| class(GIS)|| This contains the information read in from the <tt>GIS Plot Layer</tt> csv files.
|-
|formatVersion|| integer || The format version of the results as defined in the .tpc file.
|-
|units || string || The units as defined in the .tpc. E.g. "Metric" or "English"
|-
|displayname || string || The simulation name e.g. "M04_5m_001_2015"
|-
|Index || class(PlotObjects)|| This contains data read from the "GIS Plot Objects"
|-
|nodes|| class(NodeInfo) || Contains information on the 1D nodes, as read from the "1D Node Info" .csv file.
|-
|Channels|| class(ChanInfo)|| Contains information on the 1D nodes, as read from the "1D Channel Info" .csv file.
|-
|times || numpy ndarray|| The active times. This is typically static, however calls to function '''getTS''' may cause this array to be updated (if the 1D or 2D outputs have a different output interval)
|}
 

=Examples=
These examples work with the Tutorial Model module 4 results. The tutorial model can be downloaded on the [https://www.tuflow.com/Tuflow%20Tutorial%20Models.aspx TUFLOW website].
==Plot Flow in Channel==
<pre>
import os #operating system functions
import sys #system functions
import matplotlib.pyplot as plt
import TUFLOW_results

input_res = r'C:\TUFLOW\Models\Tutorials\QGIS\Complete_Model\TUFLOW\results\M04\2d\plot\M04_5m_001.tpc'

# initialise the results class
res = TUFLOW_results.ResData()

# Load the data and terminate if error returned
error, message = res.Load(input_res)
if error:
print(message)
sys.exit()
print('loaded')

#create a figure
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

#Get flow data
chan_id = 'ds3' # this is the channel ID to use
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax1.set_title('Example time-series - single location')
ax1.grid()
ax1.legend()
plt.show()
</pre>

 
[[File:Python Results 2016 Q Example 01.png|600px]]
 
This will create a figure that looks like the above.
 

==Plot Multiple Water Levels==
In this example, it is assumed that the results data has been loaded as per the above.
<pre>
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

# list of nodes to plot
node_ids = ['FC01.14.1','FC01.15.1','FC01.16.1','FC01.17.1']

#Get water level data
for node_id in node_ids: #for each node in the list above
found, results, message = res.getTSData(node_id,'1D','H','P')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,label='Level - '+node_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Water Level (mAHD)')
ax1.set_title('Example time-series - multiple locations')
ax1.set_ybound((38.,44.)) #overwrite the y axis bounds
ax1.grid()
ax1.legend(loc='lower right')
plt.show()
</pre>
 
[[File:Python Results 2016 H Example 01.png|600px]]
This will create a figure that looks like the above. 
 
==Dual Axis (flow and velocity) Plot==
In this example it is assumed the results have been loaded as per example 1.
<pre>
# specify channel to plot
chan_id = 'ds3'

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.80,0.75)) #add axis to figure
ax2 = ax1.twinx() #create new axis with same x properties

#Get flow data
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()

#Get velocity data
found, results, message = res.getTSData(chan_id,'1D','V','L')
if found:
print('found requested data')
ax2.plot(res.times,results,color='r',label='Velocity - '+chan_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax2.set_ylabel('Velocity (m/s)')
ax1.set_title('Example time-series - twin axis')
ax1.grid()
h1, l1 = ax1.get_legend_handles_labels()
h2, l2 = ax2.get_legend_handles_labels()
ax1.legend(h1+h2, l1+l2, loc='upper left')
plt.show()
</pre>
 
[[File:Python Results 2016 QV Example 01.png|600px]]
 
This will create a figure that looks like the above. 
==Long Profile Peak Levels==
This also assumes that the data has been loaded as per example 1 above. The long profile data for all channels downstream of '''FC01.40''' will be plotted.
<pre>
us_chan = 'FC01.40' #upstream channel
ds_chan = None

#get connectivity between channels
error, message = res.LP_getConnectivity(us_chan,ds_chan)
if error:
print(message)
sys.exit()
else:
print('LP connectivity determined.')

print('Get LP static data')
error, message = res.LP_getStaticData()
if error:
print(message)
sys.exit()
else:
print('LP static data retrieved')

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.80)) #add axis to figure

#plot data
# Max WL
ax1.plot(res.LP.dist_nodes, res.LP.Hmax,color='r',label = 'Max Water Level')

# Bed Level
ax1.plot(res.LP.dist_chan_inverts, res.LP.chan_inv,color='brown',linewidth = '3',label = 'Bed Level Level')

# manage plot
ax1.set_xlabel('Distance (m)')
ax1.set_ylabel('Level (mAHD)')
ax1.set_title('Example Long Profile - Peak Levels')
ax1.grid()
ax1.legend(loc='upper right')
plt.show()
</pre>
 
[[File:Python Results 2016 LP Example 01.png|600px]]
 
This will create a figure that looks like the above. 

=Other Versions=
An older version of the library that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results) is also available. This is currently undocumented, however, if you would like this please contact support@tuflow.com.

TUFLOW NetCDF Cell Centre Output Format

2018-05-10T05:06:27Z

Par:

=Introduction=
This page contains information on the NetCDF file format used for cell centered model outputs from a TUFLOW simulation. To specify cell centered NetCDF output from TUFLOW, the 2017 version or later must be used and "CC" must be included in the Map Output Data Formats, e.g. 
<tt>Map Output Format </tt> <tt>==</tt><tt> xmdf cc </tt><tt>! Output both xmdf and Cell Centered NetCDF formats</tt> 
 
There are a range of additional NetCDF related commands, to control the output further these are: 
<tt>NetCDF Output Compression </tt> <tt>==</tt><tt> OFF | {ON} | compression level <0 – 9>
</tt> 
<tt>NetCDF Output Start Date </tt> <tt>==</tt><tt> {2000-01-01 00:00} | OFF | <date in isodate format>
</tt> 
<tt>NetCDF Output Time Unit </tt> <tt>==</tt><tt> DAY | {HOUR} | MINUTE
</tt> 
<tt>NetCDF Output Direction </tt> <tt>==</tt><tt> {ANGLE} | BEARING</tt> 
<tt>NetCDF Output Format </tt> <tt>==</tt><tt> {FEWS} | Generic</tt> 
 
Please refer to the TUFLOW manual for more details on these commands.

==Global Attributes==
The NetCDF file has four global attributes: 
* Title - The simulation name
* Source - The TUFLOW version which has been used
* References - The documentation of the NetCDF file, i.e. this page!
* Comment - A description of the output.
* NetCDF File Format Version - A unique value for file version, for the 2017 version this is 2.
* NetCDF Data Type - This is 1 for [[TUFLOW_NetCDF_Raster_Output_Format | "NC" raster output]] and 2 for cell centered results.
An example of the '''Global Attributes''' is:
<pre>
Global Attributes:
title = 'M01_5m_002_NC2'
source = 'TUFLOW Build: 2015-12-BB-Dev-iSP-w64'
references = 'TUFLOW NetCDF Raster Output Format (http://wiki.tuflow.com/index.php?title=TUFLOW_NetCDF_Raster_Output_Format)'
comment = 'Contains raster TUFLOW output, TUFLOW netcdf version: 1'
</pre>

==Dimensions==
The output NetCDF will have three or four dimensions depending on if the '''Generic''' or '''FEWS''' format has been specified. These are:
* x - the number of x coordinates (columns of data)
* y - the number of y coordinates (rows of data)
* time - the number of outputs. Note that this is an unlimited dimension meaning that the number of time changes each time a new output is written
* static_time (FEWS Format only) - This has a size of 1 and is used for storing a time for the static data (such as maximums)
An example of the '''Dimensions''' is:
<pre>
Dimensions:
x = 1946
y = 856
static_time = 1
time = 161 (UNLIMITED)
</pre>
==Variables==
All outputs for the simulation are written to a single NetCDF file. These are split into three categories:
* Common variables
* Temporal variables
* Non Temporal variables.
For example if the model writes depths our every 10 minutes and tracking maximums is enabled (default) then two depth datasets are written: '''depths''' and '''maximum_depths'''. These are described further below.

Python Library TUFLOW Results

2018-05-10T05:05:37Z

Par: /* Examples */

[[File:TUPython.png | 435px]]

=Introduction=
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
* Combines the 1D results, 2D plot outputs and new reporting location data
* The outputs are stored in a separate '''Plot''' folder in the TUFLOW results directory
* .tpc (TUFLOW Plot Control file links to data in csv and gis folders
* Has additional Node and Channel information files contain connectivity information
This is the default approach for the 2016 version but can be modified with the TUFLOW command "<tt>Output Approach == Pre 2016</tt>" (refer to the manual for more information on this command. 
To make this data easier to work with an open source python library has been created and made available. This allows the user to load results and then interact with these. This library does not have any plotting functionality directly, with the returns typically being arrays (e.g. time and flows) however, the examples below give some examples using common plotting libraries such as matplotlib. 
=Getting the TUFLOW results python library=
You can find the TUFLOW_results.py (previously TUFLOW_Results2016.py) on our GitHub repository, QGIS plugin repository, or if you have QGIS and the TUFLOW plugin installed, you will already have it on your computer.

GitHub: [https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin] 
QGIS plugin repo: [https://plugins.qgis.org/plugins/tuflow/ https://plugins.qgis.org/plugins/tuflow/] 
If you have QGIS2 already: C:\Users\<User Name>\.qgis2\python\plugins\tuflow 

The TUFLOW python library does not need to be installed in python (through pip or otherwise) like other common modules, the TUFLOW_results.py file just needs to be in the same location as your python project.

Note it shouldn’t matter if you’re using python 2 or python 3.
=Dependencies=
The TUFLOW results library calls a number of python modules, these are:
* csv
* numpy
* os
* sys
Of these the csv, os and sys functionality should be available directly with the python install. Depending on the method used to install python, numpy may need to be installed. If installation of numpy is required, please refer to the numpy documentation [http://www.numpy.org/ http://www.numpy.org/].
=Compatible Python Versions=
The functionality has been developed for Python 2.7, but should be compatible with Python 3.5. Other versions of python are currently untested.
=Usage=

==Import==
This library is imported with the typical python syntax. 
<pre>import TUFLOW_results</pre>
==Initialise Results (ResData)==
The results data functionality has a class defined, this is named '''ResData'''. An instance of the results can be initialised with the following syntax:
<pre>res = TUFLOW_results.ResData()</pre>
==Defined Methods (Functions)==
The following are the defined '''functions''' in the results data class (ResData).
===Load Results===
Results are loaded in with the syntax below.
<pre>error, message = res.Load(r'D:\TUFLOW\QGIS\test\plot\Plot_Example.tpc')</pre>
The two return arguments are:
* error (logical) set to True if an error has been encountered.
* message (string), if an error has occurred the message string will be populated with an error message.
===Get Time-series===
Time-series at a 1D, 2D or reporting location can be returned using the following syntax:
<pre>
found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)
</pre>
The inputs to this are:
<li>ID - The ID of the 1D, 2D or reporting location feature.</li>
<li>Domain - The domain to return the results for, this will be one of '''1D''', '''2D''' or '''RL''' (for reporting location data)</li>
<li>Results Type - The results type to be returned. This includes H (level), Q (flow), V (velocity), E (energy), QA (flow area) depending on the data types that have been output!</li>
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point. If unsure or unknown this can be set to a blank string such as ''.</li>
The return arguments are:
<li>found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.</li>
<li>results (numpy array) - The return array for the requested data.</li>
<li>message (string) - If the data is not found, this message string contains information.</li>
For example:
<pre>
found, results, message = res.getTS('ds3','1D','Q','L')
</pre>
Will return flow (Q) data for the 1D channel with ID ds3. The optional 'L' geometry indicates that this is stored on a line object in the GIS plot objects.
'''Note''' As the time data typically does not change (this is not a return argument) but can be accessed by the <tt>res.times</tt>. See the examples below.
===Long Profile Functions===
When dealing with 1D long profile data, if a single 1D channel is specified the data for all channels downstream will returned. If two channels are specified, long profile data will only be returned for the channels between the specified channels.

====Get Long Profile Connectivity (LP_getConnectivity)====
This determines and stores the connectivity of the specified channels. This is used in later routines to determine the channels and nodes to plot for the long profile. The syntax is:
<pre>error, message = res.LP_getConnectivity(<US Channel ID>,<US Channel ID or None>)</pre>
The inputs to this are:
<li>Upstream Channel ID - The ID of the Upstream 1D channel.</li>
<li>Downstream Channel ID - The ID of the Downstream 1D channel, if no downstream channel is to be used this can be set to '''None'''.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getConnectivity('FC01.40',None)
</pre>
Determines all the channels downstream of '''FC01.40'''.
<pre>
error, message = res.LP_getConnectivity('FC01.40','ds3')
</pre>
Determines the channels between '''FC01.40''' and '''ds3''', an error will be returned if these channels are not connected.
====Get Long Profile Static Data (LP_getStaticData)====
Once the connectivity between two channels has been determined, this routine can be used to get data that does not change between time-steps. This includes:
* distance information
* maximum data
* bed levels
The syntax is:
<pre>error, message = res.LP_getStaticData()</pre>
There are no input arguments as the channel connectivity is stored in the res.LP class. The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
====Get Long Profile Data (LP_getData)====
This function gets data at a specific time. If looping through timesteps (e.g. for an animation) the channel connectivity and static data will not change between timesteps and therefore only the '''LP_getData''' will need to be repeated. The syntax is:
<pre>
error, message = res.LP_getData(<data type>,<time>,<time search tolerance>)
</pre>
The inputs to this are:
<li>Data type - The results data to return, this is one of 'Head' or 'Energy'</li>
<li>Time - The time in hours to get the data for.</li>
<li>Time search tolerance - If the closest output time is greater than the time search tolerance from the specified time an error will be returned.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getData('Head',1,0.01)
</pre>
Returns the water level (head) data at time 1 hours using a search tolerance of 0.01 hours.
==Other Attributes==
Once initialised the ResData class also has a number of '''attributes''' associated with it as well as the '''defined functions''' described above, these are outlined in the table below.
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Attribute Name
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Type
! style="background-color:#005581; font-weight:bold; color:white;" width=70% | Description
|-
|script_version|| string || Contains a version number of the TUFLOW results library, e.g. '2016-01-AA'
|-
|filename|| string|| The full filepath to the .tpc file.
|-
|fpath|| string|| The path of the folder which contains the .tpc file.
|-
|nTypes|| integer|| The number of data types that are stored in the dataset.
|-
|Types || list || A lists of the data types that are stored in the dataset.
|-
|LP || class (LP) || Contains Long profile information, connectivity, distances etc.
|-
|Data_1D|| class(Data_1D) || The 1D results are all stored in this class.
|-
|Data_2D|| class(Data_2D) || The 2D results are all stored in this class.
|-
|Data_RL|| class(Data_RL) || The reporting location results are all stored in this class.
|-
|GIS|| class(GIS)|| This contains the information read in from the <tt>GIS Plot Layer</tt> csv files.
|-
|formatVersion|| integer || The format version of the results as defined in the .tpc file.
|-
|units || string || The units as defined in the .tpc. E.g. "Metric" or "English"
|-
|displayname || string || The simulation name e.g. "M04_5m_001_2015"
|-
|Index || class(PlotObjects)|| This contains data read from the "GIS Plot Objects"
|-
|nodes|| class(NodeInfo) || Contains information on the 1D nodes, as read from the "1D Node Info" .csv file.
|-
|Channels|| class(ChanInfo)|| Contains information on the 1D nodes, as read from the "1D Channel Info" .csv file.
|-
|times || numpy ndarray|| The active times. This is typically static, however calls to function '''getTS''' may cause this array to be updated (if the 1D or 2D outputs have a different output interval)
|}
 

=Examples=
These examples work with the Tutorial Model module 4 results. The tutorial model can be downloaded on the [https://www.tuflow.com/Tuflow%20Tutorial%20Models.aspx TUFLOW website].
==Plot Flow in Channel==
<pre>
import os #operating system functions
import sys #system functions
import matplotlib.pyplot as plt
import TUFLOW_results

input_res = r'C:\TUFLOW\Models\Tutorials\QGIS\Complete_Model\TUFLOW\results\M04\2d\plot\M04_5m_001.tpc'

# initialise the results class
res = TUFLOW_results.ResData()

# Load the data and terminate if error returned
error, message = res.Load(input_res)
if error:
print(message)
sys.exit()
print('loaded')

#create a figure
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

#Get flow data
chan_id = 'ds3' # this is the channel ID to use
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax1.set_title('Example time-series - single location')
ax1.grid()
ax1.legend()
plt.show()
</pre>

 
[[File:Python Results 2016 Q Example 01.png|600px]]
 
This will create a figure that looks like the above.
 

==Plot Multiple Water Levels==
In this example, it is assumed that the results data has been loaded as per the above.
<pre>
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

# list of nodes to plot
node_ids = ['FC01.14.1','FC01.15.1','FC01.16.1','FC01.17.1']

#Get water level data
for node_id in node_ids: #for each node in the list above
found, results, message = res.getTSData(node_id,'1D','H','P')
if found:
print('found requested data')
# plot data
ax1.plot(res.times,results,label='Level - '+node_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Water Level (mAHD)')
ax1.set_title('Example time-series - multiple locations')
ax1.set_ybound((38.,44.)) #overwrite the y axis bounds
ax1.grid()
ax1.legend(loc='lower right')
plt.show()
</pre>
 
[[File:Python Results 2016 H Example 01.png|600px]]
This will create a figure that looks like the above. 
 
==Dual Axis (flow and velocity) Plot==
In this example it is assumed the results have been loaded as per example 1.
<pre>
# specify channel to plot
chan_id = 'ds3'

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.80,0.75)) #add axis to figure
ax2 = ax1.twinx() #create new axis with same x properties

#Get flow data
found, results, message = res.getTSData(chan_id,'1D','Q','L')
if found:
print('found requested data')
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print(message)
sys.exit()

#Get velocity data
found, results, message = res.getTSData(chan_id,'1D','V','L')
if found:
print('found requested data')
ax2.plot(res.times,results,color='r',label='Velocity - '+chan_id)
else:
print(message)
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax2.set_ylabel('Velocity (m/s)')
ax1.set_title('Example time-series - twin axis')
ax1.grid()
h1, l1 = ax1.get_legend_handles_labels()
h2, l2 = ax2.get_legend_handles_labels()
ax1.legend(h1+h2, l1+l2, loc='upper left')
plt.show()
</pre>
 
[[File:Python Results 2016 QV Example 01.png|600px]]
 
This will create a figure that looks like the above. 
==Long Profile Peak Levels==
This also assumes that the data has been loaded as per example 1 above. The long profile data for all channels downstream of '''FC01.40''' will be plotted.
<pre>
us_chan = 'FC01.40' #upstream channel
ds_chan = None

#get connectivity between channels
error, message = res.LP_getConnectivity(us_chan,ds_chan)
if error:
print(message)
sys.exit()
else:
print('LP connectivity determined.')

print('Get LP static data')
error, message = res.LP_getStaticData()
if error:
print(message)
sys.exit()
else:
print('LP static data retrieved')

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.80)) #add axis to figure

#plot data
# Max WL
ax1.plot(res.LP.dist_nodes, res.LP.Hmax,color='r',label = 'Max Water Level')

# Bed Level
ax1.plot(res.LP.dist_chan_inverts, res.LP.chan_inv,color='brown',linewidth = '3',label = 'Bed Level Level')

# manage plot
ax1.set_xlabel('Distance (m)')
ax1.set_ylabel('Level (mAHD)')
ax1.set_title('Example Long Profile - Peak Levels')
ax1.grid()
ax1.legend(loc='upper right')
plt.show()
</pre>
 
[[File:Python Results 2016 LP Example 01.png|600px]]
 
This will create a figure that looks like the above. 

=Other Versions=
An older version of the library that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results) is also available. This is currently undocumented, however, if you would like this please contact support@tuflow.com.

Python Library TUFLOW Results

2018-05-10T04:52:29Z

Par: Par moved page Python Library TUFLOW Results 2016 to Python Library TUFLOW Results: Renamed library

[[File:TUPython.png | 435px]]

=Introduction=
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
* Combines the 1D results, 2D plot outputs and new reporting location data
* The outputs are stored in a separate '''Plot''' folder in the TUFLOW results directory
* .tpc (TUFLOW Plot Control file links to data in csv and gis folders
* Has additional Node and Channel information files contain connectivity information
This is the default approach for the 2016 version but can be modified with the TUFLOW command "<tt>Output Approach == Pre 2016</tt>" (refer to the manual for more information on this command. 
To make this data easier to work with an open source python library has been created and made available. This allows the user to load results and then interact with these. This library does not have any plotting functionality directly, with the returns typically being arrays (e.g. time and flows) however, the examples below give some examples using common plotting libraries such as matplotlib. 
=Getting the TUFLOW results python library=
You can find the TUFLOW_results.py (previously TUFLOW_Results2016.py) on our GitHub repository, QGIS plugin repository, or if you have QGIS and the TUFLOW plugin installed, you will already have it on your computer.

GitHub: [https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin] 
QGIS plugin repo: [https://plugins.qgis.org/plugins/tuflow/ https://plugins.qgis.org/plugins/tuflow/] 
If you have QGIS2 already: C:\Users\<User Name>\.qgis2\python\plugins\tuflow 

The TUFLOW python library does not need to be installed in python (through pip or otherwise) like other common modules, the TUFLOW_results.py file just needs to be in the same location as your python project.

Note it shouldn’t matter if you’re using python 2 or python 3.
=Dependencies=
The TUFLOW results library calls a number of python modules, these are:
* csv
* numpy
* os
* sys
Of these the csv, os and sys functionality should be available directly with the python install. Depending on the method used to install python, numpy may need to be installed. If installation of numpy is required, please refer to the numpy documentation [http://www.numpy.org/ http://www.numpy.org/].
=Compatible Python Versions=
The functionality has been developed for Python 2.7, but should be compatible with Python 3.5. Other versions of python are currently untested.
=Usage=

==Import==
This library is imported with the typical python syntax. 
<pre>import TUFLOW_results</pre>
==Initialise Results (ResData)==
The results data functionality has a class defined, this is named '''ResData'''. An instance of the results can be initialised with the following syntax:
<pre>res = TUFLOW_results.ResData()</pre>
==Defined Methods (Functions)==
The following are the defined '''functions''' in the results data class (ResData).
===Load Results===
Results are loaded in with the syntax below.
<pre>error, message = res.Load(r'D:\TUFLOW\QGIS\test\plot\Plot_Example.tpc')</pre>
The two return arguments are:
* error (logical) set to True if an error has been encountered.
* message (string), if an error has occurred the message string will be populated with an error message.
===Get Time-series===
Time-series at a 1D, 2D or reporting location can be returned using the following syntax:
<pre>
found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)
</pre>
The inputs to this are:
<li>ID - The ID of the 1D, 2D or reporting location feature.</li>
<li>Domain - The domain to return the results for, this will be one of '''1D''', '''2D''' or '''RL''' (for reporting location data)</li>
<li>Results Type - The results type to be returned. This includes H (level), Q (flow), V (velocity), E (energy), QA (flow area) depending on the data types that have been output!</li>
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point. If unsure or unknown this can be set to a blank string such as ''.</li>
The return arguments are:
<li>found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.</li>
<li>results (numpy array) - The return array for the requested data.</li>
<li>message (string) - If the data is not found, this message string contains information.</li>
For example:
<pre>
found, results, message = res.getTS('ds3','1D','Q','L')
</pre>
Will return flow (Q) data for the 1D channel with ID ds3. The optional 'L' geometry indicates that this is stored on a line object in the GIS plot objects.
'''Note''' As the time data typically does not change (this is not a return argument) but can be accessed by the <tt>res.times</tt>. See the examples below.
===Long Profile Functions===
When dealing with 1D long profile data, if a single 1D channel is specified the data for all channels downstream will returned. If two channels are specified, long profile data will only be returned for the channels between the specified channels.

====Get Long Profile Connectivity (LP_getConnectivity)====
This determines and stores the connectivity of the specified channels. This is used in later routines to determine the channels and nodes to plot for the long profile. The syntax is:
<pre>error, message = res.LP_getConnectivity(<US Channel ID>,<US Channel ID or None>)</pre>
The inputs to this are:
<li>Upstream Channel ID - The ID of the Upstream 1D channel.</li>
<li>Downstream Channel ID - The ID of the Downstream 1D channel, if no downstream channel is to be used this can be set to '''None'''.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getConnectivity('FC01.40',None)
</pre>
Determines all the channels downstream of '''FC01.40'''.
<pre>
error, message = res.LP_getConnectivity('FC01.40','ds3')
</pre>
Determines the channels between '''FC01.40''' and '''ds3''', an error will be returned if these channels are not connected.
====Get Long Profile Static Data (LP_getStaticData)====
Once the connectivity between two channels has been determined, this routine can be used to get data that does not change between time-steps. This includes:
* distance information
* maximum data
* bed levels
The syntax is:
<pre>error, message = res.LP_getStaticData()</pre>
There are no input arguments as the channel connectivity is stored in the res.LP class. The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
====Get Long Profile Data (LP_getData)====
This function gets data at a specific time. If looping through timesteps (e.g. for an animation) the channel connectivity and static data will not change between timesteps and therefore only the '''LP_getData''' will need to be repeated. The syntax is:
<pre>
error, message = res.LP_getData(<data type>,<time>,<time search tolerance>)
</pre>
The inputs to this are:
<li>Data type - The results data to return, this is one of 'Head' or 'Energy'</li>
<li>Time - The time in hours to get the data for.</li>
<li>Time search tolerance - If the closest output time is greater than the time search tolerance from the specified time an error will be returned.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getData('Head',1,0.01)
</pre>
Returns the water level (head) data at time 1 hours using a search tolerance of 0.01 hours.
==Other Attributes==
Once initialised the ResData class also has a number of '''attributes''' associated with it as well as the '''defined functions''' described above, these are outlined in the table below.
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Attribute Name
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Type
! style="background-color:#005581; font-weight:bold; color:white;" width=70% | Description
|-
|script_version|| string || Contains a version number of the TUFLOW results library, e.g. '2016-01-AA'
|-
|filename|| string|| The full filepath to the .tpc file.
|-
|fpath|| string|| The path of the folder which contains the .tpc file.
|-
|nTypes|| integer|| The number of data types that are stored in the dataset.
|-
|Types || list || A lists of the data types that are stored in the dataset.
|-
|LP || class (LP) || Contains Long profile information, connectivity, distances etc.
|-
|Data_1D|| class(Data_1D) || The 1D results are all stored in this class.
|-
|Data_2D|| class(Data_2D) || The 2D results are all stored in this class.
|-
|Data_RL|| class(Data_RL) || The reporting location results are all stored in this class.
|-
|GIS|| class(GIS)|| This contains the information read in from the <tt>GIS Plot Layer</tt> csv files.
|-
|formatVersion|| integer || The format version of the results as defined in the .tpc file.
|-
|units || string || The units as defined in the .tpc. E.g. "Metric" or "English"
|-
|displayname || string || The simulation name e.g. "M04_5m_001_2015"
|-
|Index || class(PlotObjects)|| This contains data read from the "GIS Plot Objects"
|-
|nodes|| class(NodeInfo) || Contains information on the 1D nodes, as read from the "1D Node Info" .csv file.
|-
|Channels|| class(ChanInfo)|| Contains information on the 1D nodes, as read from the "1D Channel Info" .csv file.
|-
|times || numpy ndarray|| The active times. This is typically static, however calls to function '''getTS''' may cause this array to be updated (if the 1D or 2D outputs have a different output interval)
|}
 

=Examples=
These examples can be downloaded in .py format along with the example results from the TUFLOW website (link required).
==Plot Flow in Channel==
<pre>
import os #operating system functions
import sys #system functions
import matplotlib.pyplot as plt
import TUFLOW_results

# initialise the results class
res = TUFLOW_results.ResData()

# Load the data and terminate if error returned
error, message = res.Load(input_res)
if error:
print(message)
sys.exit()
print('loaded')

#create a figure
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

#Get flow data
chan_id = 'ds3' # this is the channel ID to use
found, results, message = res.getTS(chan_id,'1D','Q','L')
if found:
print 'found requested data'
# plot data
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print message
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax1.set_title('Example time-series - single location')
ax1.grid()
ax1.legend()
plt.show()
</pre>

 
[[File:Python Results 2016 Q Example 01.png|600px]]
 
This will create a figure that looks like the above.
 

==Plot Multiple Water Levels==
In this example, it is assumed that the results data has been loaded as per the above.
<pre>
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

# list of nodes to plot
node_ids = ['FC01.14.1','FC01.15.1','FC01.16.1','FC01.17.1']

#Get water level data
for node_id in node_ids: #for each node in the list above
found, results, message = res.getTS(node_id,'1D','H','P')
if found:
print 'found requested data'
# plot data
ax1.plot(res.times,results,label='Level - '+node_id)
else:
print message
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Water Level (mAHD)')
ax1.set_title('Example time-series - multiple locations')
ax1.set_ybound((38.,44.)) #overwrite the y axis bounds
ax1.grid()
ax1.legend(loc='lower right')
plt.show()
</pre>
 
[[File:Python Results 2016 H Example 01.png|600px]]
This will create a figure that looks like the above. 
 
==Dual Axis (flow and velocity) Plot==
In this example it is assumed the results have been loaded as per example 1.
<pre>
# specify channel to plot
chan_id = 'ds3'

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.80,0.75)) #add axis to figure
ax2 = ax1.twinx() #create new axis with same x properties

#Get flow data
found, results, message = res.getTS(chan_id,'1D','Q','L')
if found:
print 'found requested data'
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print message
sys.exit()

#Get velocity data
found, results, message = res.getTS(chan_id,'1D','V','L')
if found:
print 'found requested data'
ax2.plot(res.times,results,color='r',label='Velocity - '+chan_id)
else:
print message
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax2.set_ylabel('Velocity (m/s)')
ax1.set_title('Example time-series - twin axis')
ax1.grid()
h1, l1 = ax1.get_legend_handles_labels()
h2, l2 = ax2.get_legend_handles_labels()
ax1.legend(h1+h2, l1+l2, loc='upper left')
plt.show()
</pre>
 
[[File:Python Results 2016 QV Example 01.png|600px]]
 
This will create a figure that looks like the above. 
==Long Profile Peak Levels==
This also assumes that the data has been loaded as per example 1 above. The long profile data for all channels downstream of '''FC01.40''' will be plotted.
<pre>
us_chan = 'FC01.40' #upstream channel
ds_chan = None

#get connectivity between channels
error, message = res.LP_getConnectivity(us_chan,ds_chan)
if error:
print message
sys.exit()
else:
print 'LP connectivity determined.'

print 'Get LP static data'
error, message = res.LP_getStaticData()
if error:
print message
sys.exit()
else:
print 'LP static data retrieved'

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.80)) #add axis to figure

#plot data
# Max WL
ax1.plot(res.LP.dist_nodes, res.LP.Hmax,color='r',label = 'Max Water Level')

# Bed Level
ax1.plot(res.LP.dist_chan_inverts, res.LP.chan_inv,color='brown',linewidth = '3',label = 'Bed Level Level')

# manage plot
ax1.set_xlabel('Distance (m)')
ax1.set_ylabel('Level (mAHD)')
ax1.set_title('Example Long Profile - Peak Levels')
ax1.grid()
ax1.legend(loc='upper right')
plt.show()
</pre>
 
[[File:Python Results 2016 LP Example 01.png|600px]]
 
This will create a figure that looks like the above. 

=Other Versions=
An older version of the library that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results) is also available. This is currently undocumented, however, if you would like this please contact support@tuflow.com.

Python Library TUFLOW Results

2018-05-10T04:46:44Z

Par:

[[File:TUPython.png | 435px]]

=Introduction=
For the 2016 version of TUFLOW a new output format for time-series was made available, this has the following changes from previous versions:
* Combines the 1D results, 2D plot outputs and new reporting location data
* The outputs are stored in a separate '''Plot''' folder in the TUFLOW results directory
* .tpc (TUFLOW Plot Control file links to data in csv and gis folders
* Has additional Node and Channel information files contain connectivity information
This is the default approach for the 2016 version but can be modified with the TUFLOW command "<tt>Output Approach == Pre 2016</tt>" (refer to the manual for more information on this command. 
To make this data easier to work with an open source python library has been created and made available. This allows the user to load results and then interact with these. This library does not have any plotting functionality directly, with the returns typically being arrays (e.g. time and flows) however, the examples below give some examples using common plotting libraries such as matplotlib. 
=Getting the TUFLOW results python library=
You can find the TUFLOW_results.py (previously TUFLOW_Results2016.py) on our GitHub repository, QGIS plugin repository, or if you have QGIS and the TUFLOW plugin installed, you will already have it on your computer.

GitHub: [https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin https://github.com/TUFLOW-Support/QGIS-TUFLOW-Plugin] 
QGIS plugin repo: [https://plugins.qgis.org/plugins/tuflow/ https://plugins.qgis.org/plugins/tuflow/] 
If you have QGIS2 already: C:\Users\<User Name>\.qgis2\python\plugins\tuflow 

The TUFLOW python library does not need to be installed in python (through pip or otherwise) like other common modules, the TUFLOW_results.py file just needs to be in the same location as your python project.

Note it shouldn’t matter if you’re using python 2 or python 3.
=Dependencies=
The TUFLOW results library calls a number of python modules, these are:
* csv
* numpy
* os
* sys
Of these the csv, os and sys functionality should be available directly with the python install. Depending on the method used to install python, numpy may need to be installed. If installation of numpy is required, please refer to the numpy documentation [http://www.numpy.org/ http://www.numpy.org/].
=Compatible Python Versions=
The functionality has been developed for Python 2.7, but should be compatible with Python 3.5. Other versions of python are currently untested.
=Usage=

==Import==
This library is imported with the typical python syntax. 
<pre>import TUFLOW_results</pre>
==Initialise Results (ResData)==
The results data functionality has a class defined, this is named '''ResData'''. An instance of the results can be initialised with the following syntax:
<pre>res = TUFLOW_results.ResData()</pre>
==Defined Methods (Functions)==
The following are the defined '''functions''' in the results data class (ResData).
===Load Results===
Results are loaded in with the syntax below.
<pre>error, message = res.Load(r'D:\TUFLOW\QGIS\test\plot\Plot_Example.tpc')</pre>
The two return arguments are:
* error (logical) set to True if an error has been encountered.
* message (string), if an error has occurred the message string will be populated with an error message.
===Get Time-series===
Time-series at a 1D, 2D or reporting location can be returned using the following syntax:
<pre>
found, results, message = res.getTSData(<ID>,<domain>,<results type>,<geometry>)
</pre>
The inputs to this are:
<li>ID - The ID of the 1D, 2D or reporting location feature.</li>
<li>Domain - The domain to return the results for, this will be one of '''1D''', '''2D''' or '''RL''' (for reporting location data)</li>
<li>Results Type - The results type to be returned. This includes H (level), Q (flow), V (velocity), E (energy), QA (flow area) depending on the data types that have been output!</li>
<li>Geometry - The GIS geometry of the object, '''L''' for line, or '''P''' for point. If unsure or unknown this can be set to a blank string such as ''.</li>
The return arguments are:
<li>found (logical) - Returns True if the data has been found, False if the data can not be found or an error has occurred.</li>
<li>results (numpy array) - The return array for the requested data.</li>
<li>message (string) - If the data is not found, this message string contains information.</li>
For example:
<pre>
found, results, message = res.getTS('ds3','1D','Q','L')
</pre>
Will return flow (Q) data for the 1D channel with ID ds3. The optional 'L' geometry indicates that this is stored on a line object in the GIS plot objects.
'''Note''' As the time data typically does not change (this is not a return argument) but can be accessed by the <tt>res.times</tt>. See the examples below.
===Long Profile Functions===
When dealing with 1D long profile data, if a single 1D channel is specified the data for all channels downstream will returned. If two channels are specified, long profile data will only be returned for the channels between the specified channels.

====Get Long Profile Connectivity (LP_getConnectivity)====
This determines and stores the connectivity of the specified channels. This is used in later routines to determine the channels and nodes to plot for the long profile. The syntax is:
<pre>error, message = res.LP_getConnectivity(<US Channel ID>,<US Channel ID or None>)</pre>
The inputs to this are:
<li>Upstream Channel ID - The ID of the Upstream 1D channel.</li>
<li>Downstream Channel ID - The ID of the Downstream 1D channel, if no downstream channel is to be used this can be set to '''None'''.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getConnectivity('FC01.40',None)
</pre>
Determines all the channels downstream of '''FC01.40'''.
<pre>
error, message = res.LP_getConnectivity('FC01.40','ds3')
</pre>
Determines the channels between '''FC01.40''' and '''ds3''', an error will be returned if these channels are not connected.
====Get Long Profile Static Data (LP_getStaticData)====
Once the connectivity between two channels has been determined, this routine can be used to get data that does not change between time-steps. This includes:
* distance information
* maximum data
* bed levels
The syntax is:
<pre>error, message = res.LP_getStaticData()</pre>
There are no input arguments as the channel connectivity is stored in the res.LP class. The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
====Get Long Profile Data (LP_getData)====
This function gets data at a specific time. If looping through timesteps (e.g. for an animation) the channel connectivity and static data will not change between timesteps and therefore only the '''LP_getData''' will need to be repeated. The syntax is:
<pre>
error, message = res.LP_getData(<data type>,<time>,<time search tolerance>)
</pre>
The inputs to this are:
<li>Data type - The results data to return, this is one of 'Head' or 'Energy'</li>
<li>Time - The time in hours to get the data for.</li>
<li>Time search tolerance - If the closest output time is greater than the time search tolerance from the specified time an error will be returned.</li>
The return arguments are:
<li>error (logical) - Returns True if an error has been encountered when detecting the connectivity between the specified channel(s).</li>
<li>message (string) - If an error is returned this message string contains information on the issue.</li>
<pre>
error, message = res.LP_getData('Head',1,0.01)
</pre>
Returns the water level (head) data at time 1 hours using a search tolerance of 0.01 hours.
==Other Attributes==
Once initialised the ResData class also has a number of '''attributes''' associated with it as well as the '''defined functions''' described above, these are outlined in the table below.
{| align="center" class="wikitable"
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Attribute Name
! style="background-color:#005581; font-weight:bold; color:white;" width=15% | Type
! style="background-color:#005581; font-weight:bold; color:white;" width=70% | Description
|-
|script_version|| string || Contains a version number of the TUFLOW results library, e.g. '2016-01-AA'
|-
|filename|| string|| The full filepath to the .tpc file.
|-
|fpath|| string|| The path of the folder which contains the .tpc file.
|-
|nTypes|| integer|| The number of data types that are stored in the dataset.
|-
|Types || list || A lists of the data types that are stored in the dataset.
|-
|LP || class (LP) || Contains Long profile information, connectivity, distances etc.
|-
|Data_1D|| class(Data_1D) || The 1D results are all stored in this class.
|-
|Data_2D|| class(Data_2D) || The 2D results are all stored in this class.
|-
|Data_RL|| class(Data_RL) || The reporting location results are all stored in this class.
|-
|GIS|| class(GIS)|| This contains the information read in from the <tt>GIS Plot Layer</tt> csv files.
|-
|formatVersion|| integer || The format version of the results as defined in the .tpc file.
|-
|units || string || The units as defined in the .tpc. E.g. "Metric" or "English"
|-
|displayname || string || The simulation name e.g. "M04_5m_001_2015"
|-
|Index || class(PlotObjects)|| This contains data read from the "GIS Plot Objects"
|-
|nodes|| class(NodeInfo) || Contains information on the 1D nodes, as read from the "1D Node Info" .csv file.
|-
|Channels|| class(ChanInfo)|| Contains information on the 1D nodes, as read from the "1D Channel Info" .csv file.
|-
|times || numpy ndarray|| The active times. This is typically static, however calls to function '''getTS''' may cause this array to be updated (if the 1D or 2D outputs have a different output interval)
|}
 

=Examples=
These examples can be downloaded in .py format along with the example results from the TUFLOW website (link required).
==Plot Flow in Channel==
<pre>
import os #operating system functions
import sys #system functions
import matplotlib.pyplot as plt
import TUFLOW_results

# initialise the results class
res = TUFLOW_results.ResData()

# Load the data and terminate if error returned
error, message = res.Load(input_res)
if error:
print(message)
sys.exit()
print('loaded')

#create a figure
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

#Get flow data
chan_id = 'ds3' # this is the channel ID to use
found, results, message = res.getTS(chan_id,'1D','Q','L')
if found:
print 'found requested data'
# plot data
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print message
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax1.set_title('Example time-series - single location')
ax1.grid()
ax1.legend()
plt.show()
</pre>

 
[[File:Python Results 2016 Q Example 01.png|600px]]
 
This will create a figure that looks like the above.
 

==Plot Multiple Water Levels==
In this example, it is assumed that the results data has been loaded as per the above.
<pre>
#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.75)) #add axis to figure

# list of nodes to plot
node_ids = ['FC01.14.1','FC01.15.1','FC01.16.1','FC01.17.1']

#Get water level data
for node_id in node_ids: #for each node in the list above
found, results, message = res.getTS(node_id,'1D','H','P')
if found:
print 'found requested data'
# plot data
ax1.plot(res.times,results,label='Level - '+node_id)
else:
print message
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Water Level (mAHD)')
ax1.set_title('Example time-series - multiple locations')
ax1.set_ybound((38.,44.)) #overwrite the y axis bounds
ax1.grid()
ax1.legend(loc='lower right')
plt.show()
</pre>
 
[[File:Python Results 2016 H Example 01.png|600px]]
This will create a figure that looks like the above. 
 
==Dual Axis (flow and velocity) Plot==
In this example it is assumed the results have been loaded as per example 1.
<pre>
# specify channel to plot
chan_id = 'ds3'

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.80,0.75)) #add axis to figure
ax2 = ax1.twinx() #create new axis with same x properties

#Get flow data
found, results, message = res.getTS(chan_id,'1D','Q','L')
if found:
print 'found requested data'
ax1.plot(res.times,results,color='b',label='Flow - '+chan_id)
else:
print message
sys.exit()

#Get velocity data
found, results, message = res.getTS(chan_id,'1D','V','L')
if found:
print 'found requested data'
ax2.plot(res.times,results,color='r',label='Velocity - '+chan_id)
else:
print message
sys.exit()

# manage plot
ax1.set_xlabel('Time (hours)')
ax1.set_ylabel('Flow (m3/s)')
ax2.set_ylabel('Velocity (m/s)')
ax1.set_title('Example time-series - twin axis')
ax1.grid()
h1, l1 = ax1.get_legend_handles_labels()
h2, l2 = ax2.get_legend_handles_labels()
ax1.legend(h1+h2, l1+l2, loc='upper left')
plt.show()
</pre>
 
[[File:Python Results 2016 QV Example 01.png|600px]]
 
This will create a figure that looks like the above. 
==Long Profile Peak Levels==
This also assumes that the data has been loaded as per example 1 above. The long profile data for all channels downstream of '''FC01.40''' will be plotted.
<pre>
us_chan = 'FC01.40' #upstream channel
ds_chan = None

#get connectivity between channels
error, message = res.LP_getConnectivity(us_chan,ds_chan)
if error:
print message
sys.exit()
else:
print 'LP connectivity determined.'

print 'Get LP static data'
error, message = res.LP_getStaticData()
if error:
print message
sys.exit()
else:
print 'LP static data retrieved'

#create plot
fig = plt.figure() #create new figure
ax1 = fig.add_axes((0.10, 0.15, 0.85,0.80)) #add axis to figure

#plot data
# Max WL
ax1.plot(res.LP.dist_nodes, res.LP.Hmax,color='r',label = 'Max Water Level')

# Bed Level
ax1.plot(res.LP.dist_chan_inverts, res.LP.chan_inv,color='brown',linewidth = '3',label = 'Bed Level Level')

# manage plot
ax1.set_xlabel('Distance (m)')
ax1.set_ylabel('Level (mAHD)')
ax1.set_title('Example Long Profile - Peak Levels')
ax1.grid()
ax1.legend(loc='upper right')
plt.show()
</pre>
 
[[File:Python Results 2016 LP Example 01.png|600px]]
 
This will create a figure that looks like the above. 

=Other Versions=
An older version of the library that is compatible with results from the 2013 version of TUFLOW (this is limited to the 1D results) is also available. This is currently undocumented, however, if you would like this please contact support@tuflow.com.

File:Osgeo4w matplotlib.PNG

2018-04-20T13:53:33Z

Par:

File:Osgeo4w qgis-ltr.PNG

2018-04-20T13:51:03Z

Par: