Tuflow - User contributions [en]

QGIS ARR to TUFLOW

2026-05-27T10:57:25Z

Ellis Symons: /* Climate Change */

The ARR to TUFLOW utility has been developed to help users set up a TUFLOW model that uses Australian Rainfall and Runoff (ARR) input parameters and the Australian Bureau of Meteorology (BOM) rainfall by automating the collection and processing of the data. The inputs and outputs of the tool are explained in detail below. '''''Note:''''' this tool helps with data processing, however is not a substitute to reading ARR. Similarly this wiki page discusses the use of the tool and the options, however context should be derived from ARR directly. Please see the [https://arr.ga.gov.au/arr-guideline ARR Website] for more information. 

 
__TOC__
=Getting Started=
===Installation===
The ARR to TUFLOW tool is a free tool that comes as part of the TUFLOW plugin in QGIS. For instructions on how to install the plugin, please see: [[TUFLOW_QGIS_Plugin#Installation_of_Plugin | QGIS TUFLOW Plugin Installation]]

There are also instructions on installing plugins in the QGIS documentation - if you choose to follow the QGIS documentation, the plugin is called "TUFLOW" in the repository: [https://docs.qgis.org/3.16/en/docs/training_manual/qgis_plugins/fetching_plugins.html Link to QGIS Documentation - Installing and Managing Plugins] 

===QGIS Version===
The ARR to TUFLOW tool is, for the most part (see note below), a Python tool that runs independently of QGIS. Therefore the tool should not be sensitive to the installed QGIS version, however occasionally QGIS will update the Python version that is packaged with the installation which means there is a small risk that the tool will break between QGIS versions. If the tool does break, please see [[#The_Tool_Isn.27t_Working | The Tool Isn't Working]] for information (the solution is most likely to update the plugin rather than re-install an older version of QGIS).

''Note:'' The tool does use QGIS for pre-processing tasks, such as area and centroid calculation as well as reprojection or cartesian to long-lat.

===Opening The ARR to TUFLOW Tool===
Once the TUFLOW plugin is installed, the ARR to TUFLOW tool can be opened by clicking the following icon in the plugin toolbar: 
 
[[File: tuflow_plugin_toolbar_ARR_tool_01a.png]] 

=Quickstart=
<ol>
<li> Load a catchment GIS file (e.g. shp file) into QGIS - this can either be a polygon or point layer
<li> Open the '''ARR to TUFLOW''' tool
<li> Select the GIS catchment layer in '''Input Catchment File''' dropdown box. 
[[File: ARR_dialog_input_catchment_file_01a.png]] 
 
<li> Select the attribute field to use as the catchment name in the '''Unique Catchment Identifier Field''' dropdown. 
[[File: ARR_dialog_unique_catchment_identifier_01a.png]] 
 
<li> Select storm event combinations from the list of magnitudes and durations. 
[[File: ARR_dialog_storm_events_01a.png]] 
 
<li> Choose an output location. 
[[File: ARR_dialog_output_location_01a.png]] 
 
<li> Click '''OK''' and wait for the tool to finish. 
[[File: ARR_tool_complete_dialog_01a.png]]
</ol>
 

=Output=
===Log File===
A log file ('''<catchment_name>_log.txt''') will be written to the output folder. The log file will contain all WARNING and ERROR messages as well as logged inputs and processing steps. It's recommended to check the log file after running the tool for any warning or error messages. Most warning messages will be grouped together near the bottom of the log file to make it easier to review them.

===Data Output===
The following outputs are located in the folder '''<output_folder>\data'''
<ol>
<li> '''Raw BOM and ARR Datahub outputs'''
* ARR_Web_data_<catchment_name>.txt
* BOM_raw_web_<catchment_name>.html
* Areal_<TP_Zone>_Increments.csv (Areal temporal patterns)
<li> '''Rainfall depths'''
* BOM_Rainfall_Depths_<catchment_name>.csv - processed rainfall depths (after ARF factors)
<li> '''ARF Factors'''
* <catchment_name>_ARF_Factors.csv - calculated ARF factors
<li> '''Storm Burst Rainfall Losses'''
* <catchment_name>_Burst_Initial_Loss.csv - calculated Storm Burst Initial Rainfall Losses (Complete Storm Initial Loss - Preburst Rainfall Depth)
</ol>

===TUFLOW Output===
The following outputs are generated by the utility for input into TUFLOW. Please see the example below on how to use the output files for a model.
<ol>
<li> '''TUFLOW Rainfall Inflows'''
* The rainfall inflows are output in the following location '''<output_folder>\rf_inflows'''. This output folder is where all the direct rainfall inflows that would be used in the TUFLOW model are output. An inflow file is generated for each event magnitude - duration combination. All available temporal patterns are included in a single file (including climate change options).
<li> '''bc_dbase.csv'''
* TUFLOW boundary condition database. Setup to point to the '''RF''' folder with wildcards applied.
<li> '''event_file.tef'''
* TUFLOW Event File. Setup with wildcards applied. To keep the file names from becoming overly long and complicated, Climate Change scenarios are labelled as '''CC1''', '''CC2'''.. etc. These correspond to the combinations of climate change scenarios requested by the user e.g. 2090_8.5 (climate change year: 2090, RCP: 8.5)
<li> '''soil_infiltration.trd''' or '''rainfall_losses.trd''' - the name of the file will be dependent on the selected loss method, but they are essentially the same file
* This file is a TUFLOW Read File (.trd) that contains variable initialisation for initial and continuing loss values
<li> '''soils.tsoilf''' or '''materials.csv''' - which file is output will be dependent on the selected loss method
* soils.tsoilf - rainfall loss file for the infiltration loss method
* materials.csv - rainfall loss file for the rainfall excess method
</ol> 

===Example: Using the outputs in a TUFLOW model===
* [[QGIS_ARR_to_TUFLOW_Example | Example use of the ARR to TUFLOW tool]]
 

=Additional Options=
===Climate Change===
Climate change options can be added by clicking on '''Edit''' under the climate change section. This opens up a table widget that the user can then add/remove climate change scenarios based on the guidance in ARR v4.2. Once a user adds a scenario (green plus), they can double click on the values to change them. For example, double clicking on SSP2-4.5 under the 'SSP' heading will show the available Shared Socioeconomic Pathway (SSP) options. Scenarios added in the table will be displayed in the climate change section (underneath the edit button). Note: each scenario name must be unique and generally the table widget will force unique names. The scenario names will be used throughout the outputs and the user is free to customise the scenario names as they want. 

The table columns within the table widget are based on ARR guidelines v4.2 and the examples presented in Book 1, Chapter 6. Please note the following assumptions: 
* Near-term horizon = 2030
* Medium-term horizon = 2050
* Long-term horizon = 2090
* Temperature Change - Setting this to -1 will adopt the temperature changes output in the climate change part of the ARR datahub download. If a value of zero or greater is set by the user, this will be adopted instead of the datahub values and it will be assumed that these are changes relative to the pre-industrial period. Note: the temperature change will be stopped from going negative within the calculation.

By adding climate change scenarios, the following outputs will be turned on:
* An extra boundary database file: '''bc_dbase_CC.csv'''
* Climate change inflows will be appended to the end of each event's inflow file
* One additional event option will also be added to the event file for each combination of selected climate change scenarios labelled based on the scenario name. It is intended that the climate change scenarios would be treated as a separate event (e1 = magnitude, e2 = duration, e3 = temporal pattern, e4 = climate change scenario) however the output files can easily be manipulated by the user to configure the model differently.
* The following CSV files will be written to the '''data''' output folder:
** ''<scen_name>_rainfall_factors.csv''
** ''<scen_name>_rainfall_depths.csv''
** ''<scen_name>_losses.csv'' 
[[File: ARR_dialog_climate_change_01b.png]] 
[[File: ARR_example_climate_change_rf_inflow_01a.png|1200px]] 
[[File: ARR_example_climate_change_tef_01a.png]]
 

====LIMB Data and Climate Change====

The LIMB sub-daily rainfall data midpoint is 2002, which differs from the ARR baseline period which is 1990. Below is a worked example of applying a baseline change in the tool for the Near term and SSP2-4.5 scenario. Note, this is not required for daily or longer rainfall durations.

Reference document: 
https://data.arr-software.org/static/pdf/LIMB_Addendum_climate_change_considerations.pdf

<ol>
<li> Calculate the difference in temperature, comparing the ARR values to the LIMB values:
<ol>
<li> From [https://www.arr-software.org/pdfs/ARR_190514_V4.2.pdf ARR v4.2] Book 1, Chapter 6, Table 1.6.2: Temperature change = 1.2
<li> From the LIMB reference document above, Table 3: Temperature change = 0.66
<li> Therefore, baseline temperature change = 0.54
</ol>
<li> Update the "Baseline Change" value in the climate change dialog within the ARR to TUFLOW tool 
[[File:Climate_change_scenario_dialog_limb_baseline_change.png]]
<li> Run the tool and check that the climate change uplift factors match the values referenced in the LIMB reference document Appendix A tables
</ol>

===Temporal Patterns===
Temporal pattern options can be found by expanding the '''Temporal Patterns''' section in the dialog.
* '''Manually Specify Point Temporal Patterns (csv)''' - lets the user specify the point temporal patterns which is expected to be in the ARR datahub format
* '''Manually Specify Areal Temporal Patterns (csv)''' - lets the user specify the arealtemporal patterns which is expected to be in the ARR datahub format
* '''Optional Additional Temporal Patterns''' - Lets the user add additional temporal patterns in a couple of different ways: 
** The user can choose to add temporal patterns from other temporal pattern regions. This is only if the user wishes to included ''additional'' temporal patterns. The temporal patterns from the catchment location (taken at the catchment centroid) will always be included. The additional temporal patterns will be included in the inflow files and added to the event file.
** The user can choose to add temporal patterns from other temporal pattern bins within the same region. For point temporal patterns, this would add temporal patterns from the 'frequent', 'intermediate', and 'rare' bins. For areal temporal patterns, this would add temporal patterns from other "Area" bins. The "correct" bin will always make up the first 10 temporal patterns (TP01 to TP10).
*** For Areal temporal patterns - The user has the additional option to choose how many additional areal temporal pattern sets to add. The default is 2 as this matches the number of additional point temporal patterns that would be added (but it doesn't necessarily have to be the same). The "Area" bins chosen will be the next closest in order.
[[File: ARR_Dialog_temporal_patterns_01a.png]] 
[[File: ARR_example_additional_temporal_patterns_rf_inflow_01a.png]] 
[[File: ARR_example_additional_temporal_patterns_tef_01a.png]] 

===Rainfall===
[https://data.arr-software.org/limb_specific LIMB Rainfall Data] 
Since v3.8.2.16 ([[Installing_the_Latest_Development_Version_of_the_TUFLOW_Plugin | development version]]), LIMB data will be used for rainfall depths where available (SEQ specific). The user has the option of selecting the IFD curve from the available sets:
* Enveloped (Default)
* High Resolution
* BOM Resolution
The user also has the option of turning off LIMB data and using BOM 2016 rainfall data instead. If LIMB data is not available, the tool will default to BOM data. 
 
If the user has selected AEP or durations outside of the provided LIMB data range, the tool will use BOM 2016 rainfall data. If the user has selected AEP or durations within the LIMB data range, but the value is not part of the provided IFD, the tool will interpolate the rainfall depth from the provided LIMB data. 
[[File: arr2016_limb_selector_01a.png]] 

===Rainfall Losses===
The following sections summarise the available loss options. Please note, as recommended in ARR2019, [https://data.arr-software.org/ ARR datahub] losses are only intended for rural use. They are not for direct use in urban areas. Furthermore, applications in New South Wales and Victoria should consider the following jurisdiction specific guidance:
* [https://data.arr-software.org/nsw_specific NSW Specific Guidance]
* [https://data.arr-software.org/vic_specific VIC Specific Guidance]

''Note: Since version v3.5 initial loss for durations greater than 72 hrs is assumed to be the same as the initial loss for 72 hrs. Previous to this version, these losses were output as zeros.'' 

=====Probability Neutral Losses=====
Probability neutral losses can be toggled on / off in the dialog (default is on). If 'on', this option will use probability neutral losses for the design burst initial loss rather than using the storm initial loss and pre-burst depths. If probability neutral losses are not available in the catchment area, then the method will automatically revert to using the storm initial loss). Currently this option cannot be used in conjunction with the '''complete storm''' option. 
[[File: ARR_dialog_probability_neutral_losses_01a.png]]
 

=====NSW Continuing Loss=====
Continuing loss values for NSW will be automatically multiplied by 0.4. This will be reported in the log file as:
* "Catchment is in NSW, multiplying Datahub continuing loss by 0.4"
 

=====Pre-burst Percentile=====
The pre-burst percentile used to calculate design burst initial loss, or for pre-burst rainfall depth for the complete storm option, can be changed using the dropdown box in the dialog. 
[[File: ARR_dialog_preburst_01a.png]]
 

=====User Defined Losses=====
Users can use their own rainfall loss values. The initial loss value will be treated as a complete storm value and not just for the design burst. For most regions, the design burst loss will be calculated my removing the pre-burst depth from the input loss value. If probability neutral losses are available, the burst initial loss will be calculated using the following equation: 
: <tt>IL burst = User IL x IL ARR Prob Neutral / IL ARR Complete Storm</tt> 
[[File: ARR_dialog_user_losses_01a.png]]
 

=====Event Independent Continuing Loss=====
The event independent continuing loss only affects how the TUFLOW output files are written. This option will remove the continuing loss variable and will instead input the value directly. Ths option was added since the continuing loss value is (currently) event independent and therefore simplifies the output and also makes editing this value easier.
 

=====Impervious Losses=====
The impervious loss value adds the impervious loss values to the materials.csv output. This option only affects the rainfall excess loss approach. 
[[File: ARR_example_impervious_losses_01a.png]]
 

=====TUFLOW Loss Method=====
The loss method used by TUFLOW can be changed using the '''TUFLOW Loss Method''' dropdown box:
* '''Infiltration (soil file)''' - will output files for the infiltration approach in TUFLOW. This approach in TUFLOW applies the total rainfall to the 2D grid and ponded water in the 2D domain can then infiltrate based on the underlying soil type and impervious fraction. See [https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual] for more information.
* '''Rainfall Excess (material file)''' - will output files for the rainfall excess approach in TUFLOW. This approach removes the losses from the rainfall inflow prior to application so only excess rainfall is added to the model.
 
[[File: ARR_dialog_tuflow_loss_method_01a.png]]
 

=====Initial Losses For Durations Less Than 1 Hour=====
This selects the method for determining intial loss values for events less than 1 hr in duration:
* '''Interpolate to zero''' - will linearly interpolate loss values (assuming a loss value of 0 mm for 0 min)
* '''Log-Interpolate to zero''' - will use a log-linear interpolation (duration will use a log scale) (assuming a loss value of 0 mm for 0 min)
* '''Static Value''' - uses a user defined value for all event magnitudes
* '''Use 60 min Losses''' - uses the 60 min loss values
* '''Rahmen et al 2002''' - uses an equation determined by a study conducted by Rahmen et all in 2002
* '''Hill et al 1996:1998''' - uses an equation determined by a study conducted by Hill et all 1996:1998. This requires the user to provide a mean annual rainfall value.
* '''Interpolate pre-burst''' - will linearly interpolate pre-burst depths (rather than losses) (assuming a depth of 0 mm for 0 min)
* '''Log-Interpolate pre-burst''' - will use a log-linear interpolation on the pre-burst depths (duration will use a log scale) (assuming a depth of 0 mm for 0 min)
 
[[File: ARR_dialog_losses_less_than_1h_01a.png]]
 
An example of the differences in initial losses from a few of the methods: 
[[File: arr_to_tuflow_loss_interpolation.png]]
 

====Output Complete Storm====
The user can choose to output the complete storm (preburst + design burst) rather than just the design burst by checking on the following option (please see ARR Book 2 Chapter 5 [Section 5.9.9] for more information): 
[[File: ARR_complete_storm_checkbox_01a.png]] 
The complete storm generated by the tool will be the preburst depth (from the '''Preburst percentile''' extracted from the datahub) plus the design burst. The user will be required to select a preburst temporal pattern from the options listed below. The options below have been included at the request of users and are not a direct reference to any specific methodology outline in ARR. If you would like to see another method included, please email [mailto:support@tuflow.com support@tuflow.com]. 
Currently the ARR to TUFLOW tool supports the following preburst temporal pattern methods:
* '''Constant Rate''' - This will apply the preburst depth equally over a given time period. The time period can be specified as an absolute time (either as minutes or hours) or proprotional to the design storm e.g. a proportional value of 0.5 will apply a 30 min preburst to a 1 hr storm and a 15 min preburst to a 30 min storm.
* '''Temporal Pattern''' - This will apply the preburst depth using a temporal pattern obtained from the datahub for a given duration. The preburst duration can either be an absolute time or be proportional to the design storm. The user will need to select which temporal pattern to use (e.g. TP01, TP02,... TP10). Note: there is a minimum preburst duration of 10 min for this method.
** If "design burst" is selected, this will cause the pre-burst temporal pattern to use the same temporal pattern number as the design burst (e.g. TP01 design burst will use TP01 pre-burst, TP02 design burst will use TP02 pre-burst, etc.)
The initial loss value output in this method will be the raw storm initial loss value from the datahub with no post processing. Note, the complete storm option and using probability neutral losses are mutually exclusive and aren't able to be used together. 

Preburst temporal pattern and duration details are ignored if the "Use Complete Storm" checkbox is not selected.
 

====Why Is the Tool Outputting Negative Loss Values?====
The tool will output negative loss values when the preburst depth is greater than the storm initial loss. The tool will not floor loss values at zero since the value may be useful in helping the user determine the appropriate course of action. E.g. if IL = -1mm, this may be considered negligible and can be simply set to zero. An IL = -50mm may be considered significant enough that it simply can't be set to zero and alternate, or sensitivity runs, may need to be carried out, like using a [[#Output_Complete_Storm | Complete Storm]].

===Areal Reduction Factors===
Areal reduction factor options can be changed in the '''ARF''' section:
* '''Calculate Area''' - will calculate the catchment area using the GIS feature in QGIS. For point objects, this will be set to zero and no ARF will be applied (i.e. a value of 1.0)
* '''User Area''' - will let the user define the area. This can either be done by selecting an attribute field that contains the catchment area, or by entering a value. All user inputs will be assumed to be in square km.
* '''Minimum ARF''' - this value sets a floor for the calculated ARF values
* '''ARF for events < 50% AEP''' - this will calculate ARF values using the same equations used for larger events
 
[[File: ARR_dialog_ARF_01a.png]]
 

===Additional Output Options===
Additional output options include:
* '''Output Format''' - can choose to output in either csv or ts1 format. Ts1 files will be quicker to read in by TUFLOW, however the difference may not be substantial depending on how many are being read in. TUFLOW will also use .xf files by default which means that the raw data is only processed if there is a change, and subsequent runs will not suffer from any slow down from having to read csv files.
* '''Output Notation''' - users can toggle between '% AEP' and 'yr ARI' output notation.
 
[[File: ARR_dialog_output_options_01a.png]]
 

===Offline Mode===
Offline can be used to pass in data that has already been pulled from the ARR datahub and BOM. This can be useful if the user would like to make use of new features in the tool, however would like to ensure they are getting consistent results with previous data that was pulled from the BOM and the ARR datahub. The files required to process offline are saved as part of the tool's process when pulling from the web. Currently offline mode doesn't support areal temporal patterns directly, however this can easily be added by using the '''manually specify areal temporal pattern''' option:
* ARR_Web_data_<catchment_name>.txt
* BOM_raw_web_<catchment_name>.html
 
[[File: ARR_dialog_offline_inputs_01a.png]]
 

=The Tool Isn't Working=
The first step in identifying the problem is to check the log file. The issue may be something simple like:
* one of the files the tool is trying to write to is locked by a process or user (e.g. one of the outputs is open in Excel)
* the tool can't access a network location
* there is no internet connection
* the ARR Datahub or BOM is down (see [[#Can.27t_access_the_websites | Can't Access the Websites]] section below)
A useful check if you're unsure if the issue is with the tool or with something else (like the Datahub), is to check if you can manually access and pull data from the Datahub for your catchment site.
 
The second step is to ensure you're using the latest version of the QGIS plugin. Occasionally updates to the ARR Datahub will break the tool and this may have already been caught and fixed in the latest update. 
===Issue With The Tool===
If there's an issue with the tool, or you are unsure, please contact [mailto:support@tuflow.com support@tuflow.com] for help. Please include a description of the problem, the log file, and the GIS catchment layer with your email. 
===Can't access the websites===
Sometimes the BOM or ARR Datahub websites are down or unable to be accessed by the tool (e.g. sometimes to manage traffic, the Datahub server will limit, or disallow scraping). The below are a set of instructions that can be used as a workaround should this occur:
*[[ARR_DATAHUB_CANNOT_BE_ACCESSED | ARR Datahub website cannot be accessed by the tool]]
 
{{Tips Navigation
|uplink=[[TUFLOW_QGIS_Plugin#Usage| Back to TUFLOW QGIS Plugin Main Page]]
}}

File:Climate change scenario dialog limb baseline change.png

2026-05-27T10:47:06Z

Ellis Symons:

QGIS Installation with OSGeo4W

2026-04-02T16:37:10Z

Ellis Symons: /* Installing Python Dependencies (works for any installation method) */

=Installation Steps=
<ol>
<li> Download OSGeo4W setup installer
:[https://qgis.org/en/site/forusers/download.html https://qgis.org/en/site/forusers/download.html] 
: [[File:Osgeo4w download network installer.png|alt=|873x873px]]
<li> Run the downloaded EXE
<li> Select '''Advanced Install'''
: [[File: osgeo4w_installation_1.PNG]]
<li> Select '''Install from Internet'''
: [[File: osgeo4w_installation_2.PNG]]
<li> Select a directory and other installation options (Note some options may require admininstrator rights)
: [[File: osgeo4w_installation_3.PNG]]
<li> Click '''Next'''
: [[File: osgeo4w_installation_4.PNG]]
<li> Select '''Direct Connection''' (Note some firewall systems will require proxy settings)
: [[File: osgeo4w_installation_5.PNG]]
<li> Select a download site. It is recommended to use with one with an SSL certificate (i.e. starts with https://)
: [[File: osgeo4w_installation_6.PNG]]
<li> Use the search bar to search for "QGIS". Expand the '''Desktop''' dropdown and find "qgis: QGIS Desktop" under the '''package''' column. Left-click the "skip" text and the text will change to the latest version number. Once the version number is showing, this will be the version installed when you proceed. If you left-click again, the version number may change again to the previous version. If you keep left-clicking it will cycle back to "skip". (Note: you could also choose the "qgis-ltr: QGIS Desktop (long term release)" instead, and this would install the long term release version).
: [[File: osgeo4w_installation_7.PNG]]
<li> The installation also requires manually choosing several Python libraries. Use the search bar again and search for "scipy". Expand the '''Libs''' dropdown and find "python3-scipy". Left-click the "skip" text once to choose the latest scipy library version.
: [[File: osgeo4w_installation_8.PNG]]
<li> The following python libraries should be added:
* scipy
* matplotlib
* netcdf4
* pandas
* pyarrow
* fiona
* geopandas
* rtree
* shapely
* colorama
<li> Click '''Next'''
<li> Continue to work through the steps of the installation process - the installer will ask you to also install a number of dependencies (make sure to click yes to these) and prompt for license agreements
<li> Once installed, QGIS should be installed in the location specified in an earlier step
</ol>
 
 
=Upgrading Steps=
<ol>
<li> As part of the installation, OSGeo4W should install a program called "setup" which you can search in the Windows start bar. You can also run the downloaded OSGeo4W installer again (they are the same).
<li> Once running the setup, simply continue clicking '''Next'''. The setup should remember all your previous settings and automatically choose the latest version of the installed libraries at the '''Packages Selection''' stage of the installation
</ol>
 
==Upgrading Silently==
It's possible to upgrade silently from the Windows CMD prompt or from a batch file. 
 
===From CMD===
<ol>
<li> Search "osgeo4w" in the Windows start bar and choose '''OSGeo4W Shell'''
<li> Type the following command and press enter
<pre>setup -q -g</pre>
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
</ol>
 
===From BAT===
<ol>
<li> In the OSGeo4W installation folder under the "bin" folder find the following batch file "o4w_env.bat" (e.g. "C:\OSGeo4W\bin\o4w_env.bat").
<li> In your batch file call the "o4w_env.bat" file
<li> On the next line, type "setup -q -g"
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
<li> Your final batch file should look like the below with the path to "o4w_env.bat" customised to match your installation
<pre>
call C:\OSGeo4W\bin\o4w_env.bat
setup -q -g
</pre>
<li> Run the batch file
</ol>
 
 

=Installing Python Dependencies (works for any installation method)=

It's also possible to install Python dependencies in your QGIS installation without having installed QGIS via OSGeo4W. This is done via the OSGeo4W shell, which is installed regardless of installation method.

<ol>
<li> Open start menu and search for OSGeo4W Shell
<li> Type "setup" and press return
<li> Follow the [[#Installation_Steps|Installation Steps]] above starting at Step 3. Note, you may want to select "keep" as the default method, otherwise OSGeo4W may try and update all your packages. 
[[File:Osgeo_default_keep.png]]
</ol>

{{Tips Navigation
|uplink=[[QGIS_Tips| Back to QGIS Tips page]]
}}

QGIS Installation with OSGeo4W

2026-04-02T16:35:00Z

Ellis Symons: /* Installing Python Dependencies (works for any installation method) */

=Installation Steps=
<ol>
<li> Download OSGeo4W setup installer
:[https://qgis.org/en/site/forusers/download.html https://qgis.org/en/site/forusers/download.html] 
: [[File:Osgeo4w download network installer.png|alt=|873x873px]]
<li> Run the downloaded EXE
<li> Select '''Advanced Install'''
: [[File: osgeo4w_installation_1.PNG]]
<li> Select '''Install from Internet'''
: [[File: osgeo4w_installation_2.PNG]]
<li> Select a directory and other installation options (Note some options may require admininstrator rights)
: [[File: osgeo4w_installation_3.PNG]]
<li> Click '''Next'''
: [[File: osgeo4w_installation_4.PNG]]
<li> Select '''Direct Connection''' (Note some firewall systems will require proxy settings)
: [[File: osgeo4w_installation_5.PNG]]
<li> Select a download site. It is recommended to use with one with an SSL certificate (i.e. starts with https://)
: [[File: osgeo4w_installation_6.PNG]]
<li> Use the search bar to search for "QGIS". Expand the '''Desktop''' dropdown and find "qgis: QGIS Desktop" under the '''package''' column. Left-click the "skip" text and the text will change to the latest version number. Once the version number is showing, this will be the version installed when you proceed. If you left-click again, the version number may change again to the previous version. If you keep left-clicking it will cycle back to "skip". (Note: you could also choose the "qgis-ltr: QGIS Desktop (long term release)" instead, and this would install the long term release version).
: [[File: osgeo4w_installation_7.PNG]]
<li> The installation also requires manually choosing several Python libraries. Use the search bar again and search for "scipy". Expand the '''Libs''' dropdown and find "python3-scipy". Left-click the "skip" text once to choose the latest scipy library version.
: [[File: osgeo4w_installation_8.PNG]]
<li> The following python libraries should be added:
* scipy
* matplotlib
* netcdf4
* pandas
* pyarrow
* fiona
* geopandas
* rtree
* shapely
* colorama
<li> Click '''Next'''
<li> Continue to work through the steps of the installation process - the installer will ask you to also install a number of dependencies (make sure to click yes to these) and prompt for license agreements
<li> Once installed, QGIS should be installed in the location specified in an earlier step
</ol>
 
 
=Upgrading Steps=
<ol>
<li> As part of the installation, OSGeo4W should install a program called "setup" which you can search in the Windows start bar. You can also run the downloaded OSGeo4W installer again (they are the same).
<li> Once running the setup, simply continue clicking '''Next'''. The setup should remember all your previous settings and automatically choose the latest version of the installed libraries at the '''Packages Selection''' stage of the installation
</ol>
 
==Upgrading Silently==
It's possible to upgrade silently from the Windows CMD prompt or from a batch file. 
 
===From CMD===
<ol>
<li> Search "osgeo4w" in the Windows start bar and choose '''OSGeo4W Shell'''
<li> Type the following command and press enter
<pre>setup -q -g</pre>
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
</ol>
 
===From BAT===
<ol>
<li> In the OSGeo4W installation folder under the "bin" folder find the following batch file "o4w_env.bat" (e.g. "C:\OSGeo4W\bin\o4w_env.bat").
<li> In your batch file call the "o4w_env.bat" file
<li> On the next line, type "setup -q -g"
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
<li> Your final batch file should look like the below with the path to "o4w_env.bat" customised to match your installation
<pre>
call C:\OSGeo4W\bin\o4w_env.bat
setup -q -g
</pre>
<li> Run the batch file
</ol>
 
 

=Installing Python Dependencies (works for any installation method)=

It's also possible to install Python dependencies in your QGIS installation without having installed QGIS via OSGeo4W. This is done via the OSGeo4W shell, which is installed regardless of installation method.

<ol>
<li> Open start menu and search for OSGeo4W Shell
<li> Type "setup" and press return
<li> Follow the [[#Installation_Steps|Installation Steps]] above starting at Step 3. Note, you may want to select "keep" as the default method, otherwise OSGeo4W may try and update all your packages. 
[[File:Osgeo_default_keep.png|left]]
</ol>

It's possible to
{{Tips Navigation
|uplink=[[QGIS_Tips| Back to QGIS Tips page]]
}}

File:Osgeo default keep.png

2026-04-02T16:34:50Z

Ellis Symons:

QGIS Installation with OSGeo4W

2026-02-27T09:02:57Z

Ellis Symons:

=Installation Steps=
<ol>
<li> Download OSGeo4W setup installer
:[https://qgis.org/en/site/forusers/download.html https://qgis.org/en/site/forusers/download.html] 
: [[File:Osgeo4w download network installer.png|alt=|873x873px]]
<li> Run the downloaded EXE
<li> Select '''Advanced Install'''
: [[File: osgeo4w_installation_1.PNG]]
<li> Select '''Install from Internet'''
: [[File: osgeo4w_installation_2.PNG]]
<li> Select a directory and other installation options (Note some options may require admininstrator rights)
: [[File: osgeo4w_installation_3.PNG]]
<li> Click '''Next'''
: [[File: osgeo4w_installation_4.PNG]]
<li> Select '''Direct Connection''' (Note some firewall systems will require proxy settings)
: [[File: osgeo4w_installation_5.PNG]]
<li> Select a download site. It is recommended to use with one with an SSL certificate (i.e. starts with https://)
: [[File: osgeo4w_installation_6.PNG]]
<li> Use the search bar to search for "QGIS". Expand the '''Desktop''' dropdown and find "qgis: QGIS Desktop" under the '''package''' column. Left-click the "skip" text and the text will change to the latest version number. Once the version number is showing, this will be the version installed when you proceed. If you left-click again, the version number may change again to the previous version. If you keep left-clicking it will cycle back to "skip". (Note: you could also choose the "qgis-ltr: QGIS Desktop (long term release)" instead, and this would install the long term release version).
: [[File: osgeo4w_installation_7.PNG]]
<li> The installation also requires manually choosing several Python libraries. Use the search bar again and search for "scipy". Expand the '''Libs''' dropdown and find "python3-scipy". Left-click the "skip" text once to choose the latest scipy library version.
: [[File: osgeo4w_installation_8.PNG]]
<li> The following python libraries should be added:
* scipy
* matplotlib
* netcdf4
* pandas
* pyarrow
* fiona
* geopandas
* rtree
* shapely
* colorama
<li> Click '''Next'''
<li> Continue to work through the steps of the installation process - the installer will ask you to also install a number of dependencies (make sure to click yes to these) and prompt for license agreements
<li> Once installed, QGIS should be installed in the location specified in an earlier step
</ol>
 
 
=Upgrading Steps=
<ol>
<li> As part of the installation, OSGeo4W should install a program called "setup" which you can search in the Windows start bar. You can also run the downloaded OSGeo4W installer again (they are the same).
<li> Once running the setup, simply continue clicking '''Next'''. The setup should remember all your previous settings and automatically choose the latest version of the installed libraries at the '''Packages Selection''' stage of the installation
</ol>
 
==Upgrading Silently==
It's possible to upgrade silently from the Windows CMD prompt or from a batch file. 
 
===From CMD===
<ol>
<li> Search "osgeo4w" in the Windows start bar and choose '''OSGeo4W Shell'''
<li> Type the following command and press enter
<pre>setup -q -g</pre>
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
</ol>
 
===From BAT===
<ol>
<li> In the OSGeo4W installation folder under the "bin" folder find the following batch file "o4w_env.bat" (e.g. "C:\OSGeo4W\bin\o4w_env.bat").
<li> In your batch file call the "o4w_env.bat" file
<li> On the next line, type "setup -q -g"
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
<li> Your final batch file should look like the below with the path to "o4w_env.bat" customised to match your installation
<pre>
call C:\OSGeo4W\bin\o4w_env.bat
setup -q -g
</pre>
<li> Run the batch file
</ol>
 
 

=Installing Python Dependencies (works for any installation method)=

It's also possible to install Python dependencies in your QGIS installation without having installed QGIS via OSGeo4W. This is done via the OSGeo4W shell, which is installed regardless of installation method.

<ol>
<li> Open start menu and search for OSGeo4W Shell
<li> Type "setup" and press return
<li> Follow the [[#Installation_Steps|Installation Steps]] above starting at Step 3
</ol>

It's possible to
{{Tips Navigation
|uplink=[[QGIS_Tips| Back to QGIS Tips page]]
}}

QGIS Installation with OSGeo4W

2026-02-16T11:59:09Z

Ellis Symons:

=Installation Steps=
<ol>
<li> Download OSGeo4W setup installer
:[https://qgis.org/en/site/forusers/download.html https://qgis.org/en/site/forusers/download.html] 
: [[File:Osgeo4w download network installer.png|alt=|873x873px]]
<li> Run the downloaded EXE
<li> Select '''Advanced Install'''
: [[File: osgeo4w_installation_1.PNG]]
<li> Select '''Install from Internet'''
: [[File: osgeo4w_installation_2.PNG]]
<li> Select a directory and other installation options (Note some options may require admininstrator rights)
: [[File: osgeo4w_installation_3.PNG]]
<li> Click '''Next'''
: [[File: osgeo4w_installation_4.PNG]]
<li> Select '''Direct Connection''' (Note some firewall systems will require proxy settings)
: [[File: osgeo4w_installation_5.PNG]]
<li> Select a download site. It is recommended to use with one with an SSL certificate (i.e. starts with https://)
: [[File: osgeo4w_installation_6.PNG]]
<li> Use the search bar to search for "QGIS". Expand the '''Desktop''' dropdown and find "qgis: QGIS Desktop" under the '''package''' column. Left-click the "skip" text and the text will change to the latest version number. Once the version number is showing, this will be the version installed when you proceed. If you left-click again, the version number may change again to the previous version. If you keep left-clicking it will cycle back to "skip". (Note: you could also choose the "qgis-ltr: QGIS Desktop (long term release)" instead, and this would install the long term release version).
: [[File: osgeo4w_installation_7.PNG]]
<li> The installation also requires manually choosing several Python libraries. Use the search bar again and search for "scipy". Expand the '''Libs''' dropdown and find "python3-scipy". Left-click the "skip" text once to choose the latest scipy library version.
: [[File: osgeo4w_installation_8.PNG]]
<li> The following python libraries should be added:
* scipy
* matplotlib
* netcdf4
* pandas
* pyarrow
* fiona
* geopandas
* rtree
* shapely
<li> Click '''Next'''
<li> Continue to work through the steps of the installation process - the installer will ask you to also install a number of dependencies (make sure to click yes to these) and prompt for license agreements
<li> Once installed, QGIS should be installed in the location specified in an earlier step
</ol>
 
 
=Upgrading Steps=
<ol>
<li> As part of the installation, OSGeo4W should install a program called "setup" which you can search in the Windows start bar. You can also run the downloaded OSGeo4W installer again (they are the same).
<li> Once running the setup, simply continue clicking '''Next'''. The setup should remember all your previous settings and automatically choose the latest version of the installed libraries at the '''Packages Selection''' stage of the installation
</ol>
 
==Upgrading Silently==
It's possible to upgrade silently from the Windows CMD prompt or from a batch file. 
 
===From CMD===
<ol>
<li> Search "osgeo4w" in the Windows start bar and choose '''OSGeo4W Shell'''
<li> Type the following command and press enter
<pre>setup -q -g</pre>
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
</ol>
 
===From BAT===
<ol>
<li> In the OSGeo4W installation folder under the "bin" folder find the following batch file "o4w_env.bat" (e.g. "C:\OSGeo4W\bin\o4w_env.bat").
<li> In your batch file call the "o4w_env.bat" file
<li> On the next line, type "setup -q -g"
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
<li> Your final batch file should look like the below with the path to "o4w_env.bat" customised to match your installation
<pre>
call C:\OSGeo4W\bin\o4w_env.bat
setup -q -g
</pre>
<li> Run the batch file
</ol>
 
 

=Installing Python Dependencies (works for any installation method)=

It's also possible to install Python dependencies in your QGIS installation without having installed QGIS via OSGeo4W. This is done via the OSGeo4W shell, which is installed regardless of installation method.

<ol>
<li> Open start menu and search for OSGeo4W Shell
<li> Type "setup" and press return
<li> Follow the [[#Installation_Steps|Installation Steps]] above starting at Step 3
</ol>

It's possible to
{{Tips Navigation
|uplink=[[QGIS_Tips| Back to QGIS Tips page]]
}}

QGIS Installation with OSGeo4W

2026-02-16T11:57:44Z

Ellis Symons:

=Installation Steps=
<ol>
<li> Download OSGeo4W setup installer
:[https://qgis.org/en/site/forusers/download.html https://qgis.org/en/site/forusers/download.html] 
: [[File:Osgeo4w download network installer.png|alt=|873x873px]]
<li> Run the downloaded EXE
<li> Select '''Advanced Install'''
: [[File: osgeo4w_installation_1.PNG]]
<li> Select '''Install from Internet'''
: [[File: osgeo4w_installation_2.PNG]]
<li> Select a directory and other installation options (Note some options may require admininstrator rights)
: [[File: osgeo4w_installation_3.PNG]]
<li> Click '''Next'''
: [[File: osgeo4w_installation_4.PNG]]
<li> Select '''Direct Connection''' (Note some firewall systems will require proxy settings)
: [[File: osgeo4w_installation_5.PNG]]
<li> Select a download site. It is recommended to use with one with an SSL certificate (i.e. starts with https://)
: [[File: osgeo4w_installation_6.PNG]]
<li> Use the search bar to search for "QGIS". Expand the '''Desktop''' dropdown and find "qgis: QGIS Desktop" under the '''package''' column. Left-click the "skip" text and the text will change to the latest version number. Once the version number is showing, this will be the version installed when you proceed. If you left-click again, the version number may change again to the previous version. If you keep left-clicking it will cycle back to "skip". (Note: you could also choose the "qgis-ltr: QGIS Desktop (long term release)" instead, and this would install the long term release version).
: [[File: osgeo4w_installation_7.PNG]]
<li> The installation also requires manually choosing several Python libraries. Use the search bar again and search for "scipy". Expand the '''Libs''' dropdown and find "python3-scipy". Left-click the "skip" text once to choose the latest scipy library version.
: [[File: osgeo4w_installation_8.PNG]]
<li> The following python libraries should be added:
* scipy
* matplotlib
* netcdf4
* pandas
* pyarrow
* fiona
* geopandas
* rtree
* shapely
<li> Click '''Next'''
<li> Continue to work through the steps of the installation process - the installer will ask you to also install a number of dependencies (make sure to click yes to these) and prompt for license agreements
<li> Once installed, QGIS should be installed in the location specified in an earlier step
</ol>
 
 
=Upgrading Steps=
<ol>
<li> As part of the installation, OSGeo4W should install a program called "setup" which you can search in the Windows start bar. You can also run the downloaded OSGeo4W installer again (they are the same).
<li> Once running the setup, simply continue clicking '''Next'''. The setup should remember all your previous settings and automatically choose the latest version of the installed libraries at the '''Packages Selection''' stage of the installation
</ol>
 
==Upgrading Silently==
It's possible to upgrade silently from the Windows CMD prompt or from a batch file. 
 
===From CMD===
<ol>
<li> Search "osgeo4w" in the Windows start bar and choose '''OSGeo4W Shell'''
<li> Type the following command and press enter
<pre>setup -q -g</pre>
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
</ol>
 
===From BAT===
<ol>
<li> In the OSGeo4W installation folder under the "bin" folder find the following batch file "o4w_env.bat" (e.g. "C:\OSGeo4W\bin\o4w_env.bat").
<li> In your batch file call the "o4w_env.bat" file
<li> On the next line, type "setup -q -g"
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
<li> Your final batch file should look like the below with the path to "o4w_env.bat" customised to match your installation
<pre>
call C:\OSGeo4W\bin\o4w_env.bat
setup -q -g
</pre>
<li> Run the batch file
</ol>
 
 

=Installing Python Dependencies Without OSGeo4W=

It's also possible to install Python dependencies in your QGIS installation without having installed QGIS via OSGeo4W. This is done via the OSGeo4W shell, which is installed regardless of installation method.

<ol>
<li> Open start menu and search for OSGeo4W Shell
<li> Type "setup" and press return
<li> Follow the [[#Installation_Steps|Installation Steps]] above starting at Step 3
</ol>

It's possible to
{{Tips Navigation
|uplink=[[QGIS_Tips| Back to QGIS Tips page]]
}}

QGIS Installation with OSGeo4W

2026-02-16T11:57:34Z

Ellis Symons:

=Installation Steps=
<ol>
<li> Download OSGeo4W setup installer
:[https://qgis.org/en/site/forusers/download.html https://qgis.org/en/site/forusers/download.html] 
: [[File:Osgeo4w download network installer.png|alt=|873x873px]]
<li> Run the downloaded EXE
<li> Select '''Advanced Install'''
: [[File: osgeo4w_installation_1.PNG]]
<li> Select '''Install from Internet'''
: [[File: osgeo4w_installation_2.PNG]]
<li> Select a directory and other installation options (Note some options may require admininstrator rights)
: [[File: osgeo4w_installation_3.PNG]]
<li> Click '''Next'''
: [[File: osgeo4w_installation_4.PNG]]
<li> Select '''Direct Connection''' (Note some firewall systems will require proxy settings)
: [[File: osgeo4w_installation_5.PNG]]
<li> Select a download site. It is recommended to use with one with an SSL certificate (i.e. starts with https://)
: [[File: osgeo4w_installation_6.PNG]]
<li> Use the search bar to search for "QGIS". Expand the '''Desktop''' dropdown and find "qgis: QGIS Desktop" under the '''package''' column. Left-click the "skip" text and the text will change to the latest version number. Once the version number is showing, this will be the version installed when you proceed. If you left-click again, the version number may change again to the previous version. If you keep left-clicking it will cycle back to "skip". (Note: you could also choose the "qgis-ltr: QGIS Desktop (long term release)" instead, and this would install the long term release version).
: [[File: osgeo4w_installation_7.PNG]]
<li> The installation also requires manually choosing several Python libraries. Use the search bar again and search for "scipy". Expand the '''Libs''' dropdown and find "python3-scipy". Left-click the "skip" text once to choose the latest scipy library version.
: [[File: osgeo4w_installation_8.PNG]]
<li> The following python libraries should be added:
* scipy
* matplotlib
* netcdf4
* pandas
* pyarrow
* fiona
* geopandas
* rtree
* shapely
<li> Click '''Next'''
<li> Continue to work through the steps of the installation process - the installer will ask you to also install a number of dependencies (make sure to click yes to these) and prompt for license agreements
<li> Once installed, QGIS should be installed in the location specified in an earlier step
</ol>
 
 
=Upgrading Steps=
<ol>
<li> As part of the installation, OSGeo4W should install a program called "setup" which you can search in the Windows start bar. You can also run the downloaded OSGeo4W installer again (they are the same).
<li> Once running the setup, simply continue clicking '''Next'''. The setup should remember all your previous settings and automatically choose the latest version of the installed libraries at the '''Packages Selection''' stage of the installation
</ol>
 
==Upgrading Silently==
It's possible to upgrade silently from the Windows CMD prompt or from a batch file. 
 
===From CMD===
<ol>
<li> Search "osgeo4w" in the Windows start bar and choose '''OSGeo4W Shell'''
<li> Type the following command and press enter
<pre>setup -q -g</pre>
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
</ol>
 
===From BAT===
<ol>
<li> In the OSGeo4W installation folder under the "bin" folder find the following batch file "o4w_env.bat" (e.g. "C:\OSGeo4W\bin\o4w_env.bat").
<li> In your batch file call the "o4w_env.bat" file
<li> On the next line, type "setup -q -g"
: <tt>"-q"</tt> : quiet installation flag
: <tt>"-g"</tt> : upgrade installed packages flag
<li> Your final batch file should look like the below with the path to "o4w_env.bat" customised to match your installation
<pre>
call C:\OSGeo4W\bin\o4w_env.bat
setup -q -g
</pre>
<li> Run the batch file
</ol>
 
 

=Installing Python Dependencies in without OSGeo4W=

It's also possible to install Python dependencies in your QGIS installation without having installed QGIS via OSGeo4W. This is done via the OSGeo4W shell, which is installed regardless of installation method.

<ol>
<li> Open start menu and search for OSGeo4W Shell
<li> Type "setup" and press return
<li> Follow the [[#Installation_Steps|Installation Steps]] above starting at Step 3
</ol>

It's possible to
{{Tips Navigation
|uplink=[[QGIS_Tips| Back to QGIS Tips page]]
}}

PyTuflow

2025-12-17T06:32:20Z

Ellis Symons:

=Introduction=
PyTUFLOW is a library that acts as an API for your TUFLOW model. It allows easy interaction with the model results, contains a number of useful utilities for building TUFLOW models, and contains some useful parsers for files within the TUFLOW eco-system.

==Latest Documentation==
The PyTUFLOW documentation has moved to a new location: [https://docs.tuflow.com/pytuflow/ PyTUFLOW Documentation].

The previous PyTUFLOW API has been deprecated and the wiki documentation has been archived. However, if needed, the archived documentation can still be accessed via the link in the section below.

==Archive Documentation==
Guidance for earlier version of PyTuflow can be accessed via the following link: [[PyTuflow_Archive| PyTuflow_Archive]].

 
{{Tips Navigation
|uplink=[[Main_Page| Back to Wiki Main Page]]
}}

PyTuflow

2025-12-17T06:26:48Z

Ellis Symons:

=Introduction=
PyTUFLOW is a library that acts as an API for your TUFLOW model. It allows easy interaction with the model results, contains a number of useful utilities for building TUFLOW models, and contains some useful parsers for files within the TUFLOW eco-system.

=Latest Documentation=
Follow the link for the latest documentation [https://docs.tuflow.com/pytuflow/ PyTUFLOW].

=Archive Documentation=
Guidance for earlier version of PyTuflow can be accessed via the following link: [[PyTuflow_Archive| PyTuflow_Archive]].

 
{{Tips Navigation
|uplink=[[Main_Page| Back to Wiki Main Page]]
}}

Run TUFLOW From a Batch-file

2025-12-10T09:14:49Z

Ellis Symons:

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 console 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 Option==
Using the -nc switch will run a simulation without opening a 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>

It is possible to get a text output of the console using:
<pre>Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_5m_001.tcf > M01_5m_001.txt
Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_2.5m_001.tcf > M01_2.5m_001.txt</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. 
;*“L” (list); 
: The addition of the “L” flag will output the files used by TUFLOW into a .tcl (TUFLOW Copy List) file but not copy the files to a destination folder. This can be useful if scripting the copying of models. To run the copy list the character “L” needs to be specified after the -c input argument. This works for all copy options, for example, the following are all valid; -cL, -caL, -capL. The .tcl file produced is output in the same directory as the .tcf and takes the simulation name.
;* “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: 
<pre> start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -cp "C:\put_model_here" "C:\TUFLOW\runs\M01_5m_001.tcf" </pre> 
;* “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.

A tool in QGIS (as part of the TUFLOW Plugin) exists which provides a dialog to the package model options, which allows users to bypass the creation of a batch file: 
[[Package_Model_in_QGIS | Package Model in QGIS]]

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. Note, scenarios and events are specified to help the package model utility find files that use scenario or event variable names in file names and does not limit the package to specific event and scenarios. To limit the scenarios and events, please use the [[#Copy_a_TUFLOW_model | copy model functionality]]. See the example below for more information. 

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>

====INI files with Events and Scenarios====
An example of .ini file to overwrite the default base and destination folders, and specify events/scenarios for models with events/scenarios in filenames. 
The model scenario and event options are required only if there are files that use the event or scenario variables in file names. This option does not limit the files that TUFLOW will package by scenario or event.
E.g. you may have the following command to read in either a base or development TIF grid:
<pre>
Read GRID Zpts == ..\model\grid\DEM_<<~s1~>>.tif
</pre>
In this example, we can assume that the <tt><<~s1~>></tt> variable could be replaced with either <tt>"Base"</tt> or <tt>"Dev"</tt>. The example ini file below shows how to ensure that TUFLOW will package both the "Base" and "Dev" files correctly. The same concept applies for event variables, noting that events defined in the event file (TEF) and their associated boundary files are not required to use this. It is only required if the event variable is used i.e. <tt><<~e1~>></tt>.
<pre>
Base Folder == C:\TUFLOW\Model_to_Package
Copy Destination == C:\TUFLOW\Packaged_Model
Model Scenario ~s1~ == Base | Dev
Model Event ~e1~ == 60m | 90m
</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%)

===Set Hardware===
The -hwgpu or -hwcpu switches can be used overwrite any "Hardware ==' command specified in the .tcf to GPU or CPU, respectively. This feature was first introduced for Build 2023-03-AB and is not available for TUFLOW builds prior to this.

These switches can be used in conjunction with the -nt (number of threads) or -pu (processing unit id) to provide full control over the hardware usage via the command line.

The following command could be used to run a model with CPU hardware on 8 threads:
<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwcpu -nt8 FS_Hardware_01.tcf </pre>

The following command could be used to run a model on GPU hardware using 2 devices (GPU 0 and GPU1):
<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwgpu -pu0 -pu1 FS_Hardware_01.tcf </pre>

===Set Start Time for a Simulation===
The use of the -st<time_in_hours> (start time) switch allows the user to specify the start time for a simulation. Any start time specified via this run option argument is given the highest priority and overrides the "Start Time ==" settings in the .tcf, event files (.tef) and override files. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -st0 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Set End Time for a Simulation===
The use of the -et<time_in_hours> (end time) switch allows the user to specify the end time for a simulation. Any end time specified via this run option argument is given the highest priority and overrides the "End Time ==" settings in the .tcf, event files (.tef) and override files. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -et3 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Suppress Message Box Prompts===
The use of the -nmb (no message boxes) switch suppresses the use of Windows message boxes to prompt the user. All prompts will be via the console window. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nmb "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Search for a Network License===
The use of the -nwk (network) switch forces TUFLOW to search for a network licence. I.e. Skip the search for a local license. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nwk "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Search for a WIBU License===
The use of the -wibu (WIBU license) switch forces TUFLOW to search only for a WIBU Codemeter license. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -wibu "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Specify the Output Drive===
The -od<drive> (output drive) switch allows the user to specify the Output Drive for a simulation. 
For example, the following will redirect all outputs to the C:\ drive: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -odC "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Specify Map Output===
The -oz<name> (output zone) switch specifies that the map output includes the input zone. 
For example, the following would include output for 'Zone A': 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -ozZoneA "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Query the Creation of a Folder===
The -qcf (query the creation of a folder) switch is useful if you would prefer to have the create folder query dialog appear (rather than TUFLOW automatically creating folders - see [[Run_TUFLOW_From_a_Batch-file#Automatically_Create_Folders_in_a_TUFLOW_model | -acf]]). 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -qcf "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Execute a Simulation (the Default)===
The -x (execute) switch executes the simulation. This switch is used by default and does not need to be included on the TUFLOW command line.

===Copy or Test Model License Free===
For Build 2018-03-AA or later, it is possible to use the [[Run_TUFLOW_From_a_Batch-file#Copy_a_TUFLOW_model | copy model]] (-c option) or [[Run_TUFLOW_From_a_Batch-file#Testing_a_simulation | test model]] (-t option) without using a license. To utilise this licence free copy/test, the -nlc (no license check) input argument must be specified. If running without a TUFLOW licence, no diagnostic output is generated (e.g. messages layer). If these are required, the -nlc option must be removed.

===Simulation Log Path (Legacy)===
The -slp (simulation log path) switch is a legacy option for Solftlock (blue) dongles to set the path to a folder on the intranet to log all simulation initiated from the lock. Refer to the [https://www.tuflow.com/downloads/ TUFLOW Manual] (2018 or earlier) for details. 

==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: [https://support.microsoft.com/kb/310519 https://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 the TUFLOW executable path – 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 console window output. In the example above the console window 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" "C:\TUFLOW\Releases\2020-10-AE\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 "C:\TUFLOW\Releases\2020-10-AE\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>

===Copy model, checks and results in a looped batch file===
This batch file uses the copy model function to copy the model (inputs and check files), of both scenarios 5m and 2.5m, to a specified folder location. After copying, [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] is used to copy the results, based off the tcf filename and specified scenarios, to the destination result folder.
<pre>
@echo off

set TUFLOWEXE_iSP="C:\Releases\2023-03-AF\TUFLOW_iSP_w64.exe"
set RUN_iSP=start "TUFLOW" /wait %TUFLOWEXE_iSP% -cp "D:\tuflow_models\copy"

set A=5m 2.5m
set source_results=..\results
set destination_results=C:\tuflow_models\copy\results

FOR %%a in (%A%) do (
:: Copy model
%RUN_iSP% -s1 %%a M01_~s1~_001.tcf

:: Copy results folder to copy model location
robocopy "%source_results%" "%destination_results%" "M01_%%a_001*" /S

)
pause
</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="C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.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>

Run TUFLOW From a Batch-file

2025-12-02T08:31:30Z

Ellis Symons: /* Package a TUFLOW model */

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 console 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 Option==
Using the -nc switch will run a simulation without opening a 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>

It is possible to get a text output of the console using:
<pre>Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_5m_001.tcf > M01_5m_001.txt
Start "TUFLOW" /wait /min "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nc M01_2.5m_001.tcf > M01_2.5m_001.txt</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. 
;*“L” (list); 
: The addition of the “L” flag will output the files used by TUFLOW into a .tcl (TUFLOW Copy List) file but not copy the files to a destination folder. This can be useful if scripting the copying of models. To run the copy list the character “L” needs to be specified after the -c input argument. This works for all copy options, for example, the following are all valid; -cL, -caL, -capL. The .tcl file produced is output in the same directory as the .tcf and takes the simulation name.
;* “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: 
<pre> start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -cp "C:\put_model_here" "C:\TUFLOW\runs\M01_5m_001.tcf" </pre> 
;* “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.

A tool in QGIS (as part of the TUFLOW Plugin) exists which provides a dialog to the package model options, which allows users to bypass the creation of a batch file: 
[[Package_Model_in_QGIS | Package Model in QGIS]]

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. Note, scenarios and events are specified to help the package model utility find files that use scenario or event variable names in file names and does not limit the package to specific event and scenarios. To limit the scenarios and events, please use the [[#Copy_a_TUFLOW_model | copy model functionality]]. See the example below for more information. 

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>

====INI files====
An example of .ini file to overwrite the default base and destination folders, and specify events/scenarios for models with events/scenarios in filenames. 
The model scenario and event options are required only if there are files that use the event or scenario variables in file names. This option does not limit the files that TUFLOW will package by scenario or event.
E.g. you may have the following command to read in either a base or development TIF grid:
<pre>
Read GRID Zpts == ..\model\grid\DEM_<<~s1~>>.tif
</pre>
In this example, we can assume that the <tt><<~s1~>></tt> variable could be replaced with either <tt>"Base"</tt> or <tt>"Dev"</tt>. The example ini file below shows how to ensure that TUFLOW will package both the "Base" and "Dev" files correctly. The same concept applies for event variables, noting that events defined in the event file (TEF) and their associated boundary files are not required to use this. It is only required if the event variable is used i.e. <tt><<~e1~>></tt>.
<pre>
Base Folder == C:\TUFLOW\Model_to_Package
Copy Destination == C:\TUFLOW\Packaged_Model
Model Scenario ~s1~ == Base | Dev
Model Event ~e1~ == 60m | 90m
</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%)

===Set Hardware===
The -hwgpu or -hwcpu switches can be used overwrite any "Hardware ==' command specified in the .tcf to GPU or CPU, respectively. This feature was first introduced for Build 2023-03-AB and is not available for TUFLOW builds prior to this.

These switches can be used in conjunction with the -nt (number of threads) or -pu (processing unit id) to provide full control over the hardware usage via the command line.

The following command could be used to run a model with CPU hardware on 8 threads:
<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwcpu -nt8 FS_Hardware_01.tcf </pre>

The following command could be used to run a model on GPU hardware using 2 devices (GPU 0 and GPU1):
<pre>"C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -b -hwgpu -pu0 -pu1 FS_Hardware_01.tcf </pre>

===Set Start Time for a Simulation===
The use of the -st<time_in_hours> (start time) switch allows the user to specify the start time for a simulation. Any start time specified via this run option argument is given the highest priority and overrides the "Start Time ==" settings in the .tcf, event files (.tef) and override files. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -st0 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Set End Time for a Simulation===
The use of the -et<time_in_hours> (end time) switch allows the user to specify the end time for a simulation. Any end time specified via this run option argument is given the highest priority and overrides the "End Time ==" settings in the .tcf, event files (.tef) and override files. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -et3 "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Suppress Message Box Prompts===
The use of the -nmb (no message boxes) switch suppresses the use of Windows message boxes to prompt the user. All prompts will be via the console window. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nmb "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Search for a Network License===
The use of the -nwk (network) switch forces TUFLOW to search for a network licence. I.e. Skip the search for a local license. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -nwk "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Search for a WIBU License===
The use of the -wibu (WIBU license) switch forces TUFLOW to search only for a WIBU Codemeter license. 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -wibu "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Specify the Output Drive===
The -od<drive> (output drive) switch allows the user to specify the Output Drive for a simulation. 
For example, the following will redirect all outputs to the C:\ drive: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -odC "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Specify Map Output===
The -oz<name> (output zone) switch specifies that the map output includes the input zone. 
For example, the following would include output for 'Zone A': 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -ozZoneA "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Query the Creation of a Folder===
The -qcf (query the creation of a folder) switch is useful if you would prefer to have the create folder query dialog appear (rather than TUFLOW automatically creating folders - see [[Run_TUFLOW_From_a_Batch-file#Automatically_Create_Folders_in_a_TUFLOW_model | -acf]]). 
An example is: 
<pre>start "TUFLOW" "C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.exe" -qcf "C:\TUFLOW\Tutorial_Wiki\TUFLOW\runs\M01_5m_001.tcf"</pre>

===Execute a Simulation (the Default)===
The -x (execute) switch executes the simulation. This switch is used by default and does not need to be included on the TUFLOW command line.

===Copy or Test Model License Free===
For Build 2018-03-AA or later, it is possible to use the [[Run_TUFLOW_From_a_Batch-file#Copy_a_TUFLOW_model | copy model]] (-c option) or [[Run_TUFLOW_From_a_Batch-file#Testing_a_simulation | test model]] (-t option) without using a license. To utilise this licence free copy/test, the -nlc (no license check) input argument must be specified. If running without a TUFLOW licence, no diagnostic output is generated (e.g. messages layer). If these are required, the -nlc option must be removed.

===Simulation Log Path (Legacy)===
The -slp (simulation log path) switch is a legacy option for Solftlock (blue) dongles to set the path to a folder on the intranet to log all simulation initiated from the lock. Refer to the [https://www.tuflow.com/downloads/ TUFLOW Manual] (2018 or earlier) for details. 

==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: [https://support.microsoft.com/kb/310519 https://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 the TUFLOW executable path – 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 console window output. In the example above the console window 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" "C:\TUFLOW\Releases\2020-10-AE\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 "C:\TUFLOW\Releases\2020-10-AE\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>

===Copy model, checks and results in a looped batch file===
This batch file uses the copy model function to copy the model (inputs and check files), of both scenarios 5m and 2.5m, to a specified folder location. After copying, [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] is used to copy the results, based off the tcf filename and specified scenarios, to the destination result folder.
<pre>
@echo off

set TUFLOWEXE_iSP="C:\Releases\2023-03-AF\TUFLOW_iSP_w64.exe"
set RUN_iSP=start "TUFLOW" /wait %TUFLOWEXE_iSP% -cp "D:\tuflow_models\copy"

set A=5m 2.5m
set source_results=..\results
set destination_results=C:\tuflow_models\copy\results

FOR %%a in (%A%) do (
:: Copy model
%RUN_iSP% -s1 %%a M01_~s1~_001.tcf

:: Copy results folder to copy model location
robocopy "%source_results%" "%destination_results%" "M01_%%a_001*" /S

)
pause
</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="C:\TUFLOW\Releases\2020-10-AE\TUFLOW_iSP_w64.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>

TUFLOW Message 0645

2025-09-17T07:17:30Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0645 - Could not determine layer name, please check syntax. Please use " >> " instead of "layername=" 
|alt_msg=NA

|type=[[ERROR]]
|message_desc=Could not determine layer name in GeoPackage input file.
|suggestions=Please use " >> " to specify the layer name inside a GeoPackage, e.g. <tt>/path/to/database.gpkg >> Layer_Name</tt>

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

TUFLOW Message 0645

2025-09-17T07:17:16Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0645 - Could not determine layer name, please check syntax. Please use " >> " instead of "layername=" 
|alt_msg=NA

|type=[[ERROR]]
|message_desc=Could not determine layer name in GeoPackage input file.
|suggestions=Please use " >> " to specify the layer name inside a GeoPackage, e.g. /path/to/database.gpkg >> Layer_Name.

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

TUFLOW Message 5200

2025-07-17T09:54:42Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 5200 - Extracting boundary for <boundary location>.
|alt_msg=NA
|type=[[ERROR]]
|message_desc=An error has occurred extracting (2d_sa) boundary data for a given 2d_sa feature from the bc_database.csv.
|suggestions=Check the TLF for the specific error. It could be that the boundary name doesn't exist in the bc_dbase.csv, or the source file doesn't exist, or there could be an issue with how the data is stored in the source file. It is also worth double checking the encoding of the source file to make sure it is a plain CSV (UTF-8 or ANSI encoding) and not different flavour of CSV e.g. that uses UTF-8 BOM encoding.

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

TUFLOW Message 5099

2025-07-17T09:50:20Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 5099 - Reading CATCH SA boundary attribute in GIS layer.
|alt_msg=NA
|type=[[ERROR]]
|message_desc=An error occurred reading the GIS attributes in the 2d_sa layer.
|suggestions=Make sure the 2d_sa attribute fields are correct. The 2d_sa requires the first attribute to be a string field. It is permissible to append attributes after this, however there needs to be at least one attribute.

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

TUFLOW Setup with Kart QGIS Plugin

2025-06-26T14:25:50Z

Ellis Symons: /* Set up the TUFLOW Model and Initialise Kart Repository */

== Introduction ==
Kart is a version control tool which stores geospatial data (and tabular data) in Git, providing a neat version control system whilst building TUFLOW models. Despite using Git, there is no requirement for the user to have a thorough understanding of Git, it's processes and commands. The Kart QGIS plugin provides a user interface for Kart which provides tools for reviewing changes to geospatial data as it is iteratively edited. This page describes a workflow for setting up a TUFLOW project, utilising Kart, and provides some of the benefits of using the Kart tools for version control. Kart can be used with remote repositories to allow multiple users to access the data and work simultaneously with merge control, however, the example below is a local repository for the purposes of version control and ease of quality assurance checking.

== Benefits of using Kart ==
The video below shows an initial model build with some a number of TUFLOW model layers and where the layer geometry has undergone a number of iterative changes. The video shows:
* The Kart commit history table.
* Tags for specific commits. For instance for models that have undergone QA, been sent to a client or sent to [mailto:support@tuflow.com support@tuflow.com].
* The evaluation in differences between commit versions both in text form and in geometry form.
{{Video|name=Kart Tools History.mp4|width=1123}}
All of these are useful from a quality assurance perspective, allowing a history of the development of a TUFLOW model geometry files to be understood and analysed. Kart is very easy to use once it is set up. The set up of Kart to be used with TUFLOW is a little cumbersome but the steps below provide information of how to set up the Kart QGIS Plugin, set up the TUFLOW folders and initialise the Kart repository.

== Install the Kart Plugin ==
The first step is to install the Kart QGIS plugin. This is done using the '''Manage and Install Plugins''' tool within QGIS. Search for Kart and install the plugin.

[[File:Kart QGIS Plugin.png|thumb|600x600px|Kart QGIS Plugin|alt=|none]]The plugin requires that you install Kart from https://kartproject.org/
Once the plugin and Kart is installed, there is a Kart menu within QGIS with some settings. Specify the path to the installed Kart executable. There's an option to Auto Commit which will commit your changes to the repository when you 'Toggle editing' off within QGIS. This can be a useful option, although the drawback is that you are not prompted to add a commit message.[[File:Kart Settings.png|thumb|Kart Settings|alt=|none]]

The Kart Repositories panel should show something similar to the following, with no repositories showing.
[[File:Kart Repository.png|thumb|Initial Kart Repository|alt=|none]]

== Set up the TUFLOW Model and Initialise Kart Repository ==
With Kart set up, we can now move towards setting up your TUFLOW model. To use Kart, you would need to be using a Geopackage GIS Format. We will start at the beginning of a TUFLOW model build but it would be possible to set up kart with an existing model with a similar workflow. However, in this instance, commits and changes would only be tracked for edits to the geometry data after the TUFLOW model is initialised within a Kart folder.

Firstly, we'll set up our TUFLOW folder structure and template files. To set up your TUFLOW folders, you can use your chosen method of either the [[QGIS TUFLOW Create Project|TUFLOW Create Project]] tool or the [[Create TUFLOW Project]] tool.

With the TUFLOW folders set up, there is now some fiddly steps to go through so that we can set up a Kart repository. Kart probably works best with a single Geopackage for the whole TUFLOW model, although it would be possible to use with seperate Geopackages. The steps below are for a single Geopackage.

* Cut and paste the '''empty''' folder and the model Geopackage file from the '''TUFLOW\Model\GIS''' folder to TUFLOW\Model. This is because Kart can not initialise a repository if the folder is not empty.
* Rename the '<nowiki/>'''GIS'''<nowiki/>' folder to ''''*Model_Name*'''<nowiki/>' where '*Model_Name*' is the same as your Geopackage name.

* Use the Kart Create new repository tool to create a new Kart repository.

[[File:Create Kart Repository.png|thumb|Create Kart Repository|alt=|none]]

* Select the '''TUFLOW\Model\Model_Name''' folder and ensure 'Geopackage in repository folder' is selected in the Storage type option. Click OK.

[[File:Kart Repository Setup.png|alt=Kart Repository Setup|thumb|none]]
* Cut and paste the ''''empty'''<nowiki/>' folder from '''TUFLOW\Model''' to the '''TUFLOW\Model\Model_Name''' folder.
* Rename the ''''Model_Name'''<nowiki/>' folder to ''''GIS'''<nowiki/>'

* We will now remap the <nowiki/>repository to th<nowiki/>e '''GIS''' folder. In the Kart repositories panel, highlight the current repositiry and choose to 'remove this repository'. Click Yes when the prompt dialogue comes up.

[[File:Remove Repository.png|thumb|Remove Repository|alt=|none]]

* We now need to add the renamed folder as an existing repository. Right click on the repositories option and select 'Add existing repository'. Navigate to the '''TUFLOW\Model\GIS''' folder and choose select folder.

[[File:Add Existing Respository.png|thumb|Add Existing Repository|alt=|none]]

* We can now import the '''Model_Name.gpkg''' into the repository. This is done by right clicking on the repository and selecting 'Import dataset from file'. Navigate to the '''TUFLOW\Model\Model_Name.gpkg''' and select open.

[[File:Import dataset from File.png|thumb|Import Dataset from File|alt=|none]]
* The repository will now show the Geopackage layers, which at present is only the projection layer generate during the create TUFLOW project step.

[[File:Repository.png|thumb|Repository after Importing the Geopackage Dataset|alt=|none]]

* Finally, the Model_Name.gpkg can be deleted from the '''TUFLOW\Model''' folder.

The above steps are by far and away the fiddliest steps with the TUFLOW model Kart set up. Now we can start building the TUFLOW model and utilising Kart.

== TUFLOW Model Build ==
We can now start to build our TUFLOW model using the traditional steps of the [[QGIS TUFLOW Import Empty|Import Empty File]] tool within the QGIS TUFLOW Plugin. When importing the empty files, we can import to the gpkg in Kart repository using the options in the following image, ensuring to select the 'All to one' option and choosing to 'Import into Kart repo folder'.
[[File:Import Empty File.png|thumb|Import Empty File|alt=|none]]

Once the empty file is imported, you can refresh the Kart Repository, and see the additional layers with there.
[[File:Kart Repository 2.png|thumb|Kart Respository Showing the Imported Empty File|alt=|none]]

We can now build the TUFLOW model geometry as we would do usually. As we add additional layers to the geodatabase, they will start to appear in the Kart repositories panel.

If the option to 'Commit automatically after closing editing' then the changes will be automatically committed. This is useful to avoid forgetting to commit, similar to how an autosave can be beneficial. Alternatively, it is possible to commit manually, either by clicking the repository or the individual layers and using the 'Commit working copy changes' or 'Commit working copy changes for this dataset' option respectively. The benefit of the latter approach is that there are less frequent commits and the user is prompted for a commit message prior to committing the working changes.
[[File:Commit message.png|none|frame|Manual commit with prompt for commit message]]
If you select the Kart repository or an individual layer dataset then you can choose to 'Show log' which provides a table of the commit history.
[[File:Commit History.png|none|frame|Kart Layer Dataset Commit History]]
The commit history can then be interrogated to show the details of the commits, the differences between versions, adding tags and other git like tools such as branching, merging, reverting back to older versions as well as replacing working copy changes.It is also possible to apply temporal filters for changes. For a full list of Kart tools, the user is recommended to consult the Kart documentation [https://docs.kartproject.org/en/latest/ here].

== Using Remote Repositories ==
The above steps are for a local Kart repository. However, it is possible to use Kart with remote repositories. This is done by cloning a remote repository on Gitlab/Github or similar. Once a repository is cloned, changes can be push/pulled to and from the remote repository.
[[File:Remote repository.png|none|frame|Kart Push/Pull Functions to Remote Repository]]It should be noted that the TUFLOW team have not made sufficient use of Kart with remote repository so cannot suggest that it is a recommended approach.

{{Tips Navigation
|uplink=[[Kart_Git_And_TUFLOW| Back to Kart Git and TUFLOW Main Page]]
}}

TUFLOW Message 2831

2025-05-28T10:58:15Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2831 - More than 1 parent polygon for polygon with nesting level "<>".
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=This error is triggered if a nesting level polygon sits completely within more than one parent polygon. A parent polygon is any nesting level polygon that completely encompasses a given polygon and has a lower nesting value. It is also only considered a direct parent if it has the closest nesting level value to the child polygon of all polygons that encompass it. Example, a polygon with nesting level 4 can sit completely within a nesting level 3 polygon and completely within a nesting level 2 polygon. It can also sit completely within a nesting level 2 polygon (skipping level 3), but it cannot sit completely within two level 3 polygons or within two level 2 polygons.
|suggestions=Double check the <tt>2d_qnl</tt> layers to ensure that each polygon only has a single direct parent. View the <tt>messages_P.shp</tt> to view which nesting level polygon is causing the issue. Quite often, intermediate polygons are not required as TUFLOW will automatically transition between nesting levels. E.g., it is common that nesting levels are drawn without any parents, and TUFLOW will assume the domain extent to be the level 1 nesting polygon and create transition mesh elements accordingly.

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

TUFLOW Message 0640

2025-05-28T10:38:42Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0640 - Cannot have more than "<>" GRID layers open at once.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=This error will trigger if more than 100 grids are opened concurrently by TUFLOW (for reading or writing). This error should never be triggered as there are very few processes (if any) within TUFLOW that read or write grids concurrently.
|suggestions=If your model is triggering this error, it is most likely caused by grids not being closed properly by TUFLOW (caused by an internal logic error). If this is the case, please contact [mailto:support@tuflow.com support@tuflow.com].

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

TUFLOW Message 3552

2025-05-27T15:10:05Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 3552 - End of file encountered writing xf file.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=An error occurred writing to an xf file.
|suggestions=XF Files can be turned off (<tt>XF Files == OFF</tt>) to remove this error. XF files can also be turned off individually for a command by adding "<tt>XF OFF</tt>" to the end of the left-hand side of the command e.g. <tt>Read GRID Zpts XF OFF == </tt>. The error could also be occurring due to network connectivity if the model is not being run locally. It may be fixed if the model is moved locally (e.g. to the C drive) or if the outputs are written locally using the command <tt> Output Drive == </tt>.

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

TUFLOW Message 3540

2025-05-27T15:02:37Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=WARNING 3540 - "Map Cutoff SGS" set to different datum than "SGS Depth Interpolation Approach".
|alt_msg=NA 

|type=[[WARNING]]
|message_desc="Map Cutoff SGS" set to different datum than "SGS Depth Interpolation Approach".
|suggestions=These commands should be set to the same value. Since 2020-10-AB, these commands have been merged together into "<tt>SGS Depth Output == </tt>". It is therefore recommended to replace the two commands with the single <tt>SGS Depth Output</tt> command.

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

TUFLOW Message 3528

2025-05-27T14:54:36Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=CHECK 3528 - Both "<tt>Map Cutoff Depth </tt> <tt>== </tt>" and "<tt>Map Cutoff SGS </tt> <tt>== </tt> <tt>MIN</tt>" have been specified...
|alt_msg=NA 

|type=[[CHECK]]
|message_desc=Both "<tt>Map Cutoff Depth </tt> <tt>== </tt>" and "<tt>SGS Depth Output </tt> <tt>== </tt> <tt>MIN</tt>" (or the legacy command <tt>Map Cutoff SGS == MIN</tt>) have been specified.

These commands conflict with one another (they do similar things) and the maximum value of the two is adopted.
|suggestions=Remove one of the commands to remove the conflict.

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

TUFLOW Message 2823

2025-05-27T14:43:11Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2823 - Reading PO / RL attribute data.
|alt_msg=ERROR 2823 - Reading LP attribute data. 

|type=[[ERROR]]
|message_desc=This error is triggered when TUFLOW did not correctly read the <tt>2d_po</tt> or <tt>2d_lp</tt> GIS layer attribute data. This is commonly caused by the incorrect data types or incorrect number of attributes.
|suggestions=Double check the GIS layer attributes for the 2d_po/2d_lp that is causing the issue. Check the attribute type and number of attributes against the equivalent empty type or compare against what is listed in the TUFLOW User Manual.

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

TUFLOW Message 2823

2025-05-27T14:42:51Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2823 - Reading PO / RL attribute data.
|alt_msg=ERROR 2823 - Reading LP attribute data. 

|type=[[ERROR]]
|message_desc=This error is triggered when TUFLOW did not correctly read the 2d_po or 2d_lp GIS layer attribute data. This is commonly caused by the incorrect data types or incorrect number of attributes.
|suggestions=Double check the GIS layer attributes for the 2d_po/2d_lp that is causing the issue. Check the attribute type and number of attributes against the equivalent empty type or compare against what is listed in the TUFLOW User Manual.

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

TUFLOW Message 3507

2025-05-27T14:39:14Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 3507 - Reading parameter values for a "<tt>SGS SAMPLE DISTANCE</tt>" command.
|alt_msg=ERROR 3507 - Reading parameter values for a "<tt>SGS GRID SAMPLE DISTANCE</tt>" command. 
ERROR 3507 - Reading parameter values for a "<tt>SGS TIN SAMPLE DISTANCE</tt>" command. 
ERROR 3507 - Reading parameter values for a "<tt>SGS ZH SAMPLE RATIO</tt>" command. 

|type=[[ERROR]]
|message_desc=This error is reported when there was an issue reading the "SGS Sample" command in the TGC.
|suggestions=Ensure that the "SGS Sample" command in the TGC matches the expected syntax (i.e. the value is a number).

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

TUFLOW Message 3507

2025-05-27T14:38:54Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 3507 - Reading parameter values for a "<tt>SGS SAMPLE DISTANCE</tt>" command.
|alt_msg=ERROR 3507 - Reading parameter values for a "<tt>SGS GRID SAMPLE DISTANCE</tt>" command. 
ERROR 3507 - Reading parameter values for a "<tt>SGS TIN SAMPLE DISTANCE</tt>" command. 
ERROR 3507 - Reading parameter values for a "<tt>SGS ZH SAMPLE RATIO</tt>" command. 

|type=[[ERROR]]
|message_desc=This error is reported when there was an issue reading the listed "SGS Sample" commands.
|suggestions=Ensure that the "SGS Sample" command in the TGC matches the expected syntax (i.e. the value is a number).

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

TUFLOW Message 2853

2025-05-27T14:34:30Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2853 - Exceeded GIS point limit - limit = "<>".
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=The number of Quadtree cells selected by the boundary (one of <tt>HT</tt>, <tt>HQ</tt>, <tt>SX</tt>, <tt>QT</tt>) has exceeded the limit within TUFLOW. The limit is a hardcoded value of 500,000.
|suggestions=This is typically triggered by a downstream boundary (<tt>HT</tt> or <tt>HQ</tt>) being snapped to the perimeter of the code polygon and selecting every cell along the edge of the model. The boundary should be split into smaller sections so that each line selects less than 500,000 cells.

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

TUFLOW Message 2842

2025-05-27T14:23:24Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2842 - QPC [Cell id=<>, x=<>, y=<>] has no active cell connected.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=A cell within Quadtree is isolated and has no active cell faces that connect to another cell.
|suggestions=Check the message_P.shp layer to find the isolated cell and reconfigure the 2d_code and 2d_bc layers to stop the particular cell from being isolated (or remove it).

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

TUFLOW Message 2833

2025-05-27T14:12:42Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2833 - Exceeded limit of "<>" mesh boundary polygons.
|alt_msg=WARNING 2833 - Exceeded limit of "<>" polygon internal regions - trying to write simplified polygon. 

|type=[[ERROR]] [[WARNING]]
|message_desc='''ERROR 2833''' - This error can occur in Quadtree during the domain calculation where TUFLOW will create a polygon of the active mesh area. If there are a number of inactive areas in the domain, then these are stored as polygons (or "rings" in GIS geometry terminology). The error is triggered if the number of rings has unexpectedly exceeded the allowed memory. This is most likely an internal logic error within TUFLOW (similar to a "should not be here").

'''WARNING 2833''' - The number of internal polygons (or "rings") has exceed the allowed number within TUFLOW. This is a hard coded value in TUFLOW.
|suggestions='''ERROR 2833''' - Since this most likely an internal logic error within TUFLOW, you will need to contact [mailto:support@tuflow.com support@tuflow.com]. Workarounds include double checking the Quadtree mesh for "messy" holes around nesting transition zones. Moving transition areas away from deactivated areas may fix the logic error.

'''WARNING 2833''' - Most likely the only workaround is to remove the number of inactive areas in the Quadtree mesh. These are typically caused by building footprints being used to deactivate areas within the mesh. Simplifying, or grouping buildings together will reduce the number of total holes in the domain polygon.
|uplink=[[2xxx_TUFLOW_Messages|2xxx Messages]]
}}

TUFLOW Message 2817

2025-05-27T13:58:49Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2817 - Reading data in 2d_bc format.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=There was an error reading in the 2d_bc GIS layer attributes. This is typically caused by incorrect attribute types or the number of attributes.
|suggestions=Ensure that the 2d_bc GIS layer that is causing the issue has the correct attribute types (compare them to an empty 2d_bc layer or check the TUFLOW User Manual) and that the layer contains all the required attributes (e.g. you aren't accidentally using a 1d_bc GIS input).

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

TUFLOW Message 2499

2025-05-27T13:54:34Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2499 - Maximum number of zpts in grid read exceeds 4 byte integer limit in this version of TUFLOW: Limit <>.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=The size of the grid (number of cells) has exceeded the limit of a signed 32 bit integer. The limit is 2,147,483,647 cells.
|suggestions=Split the input grid into smaller tiles and read them in separately.

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

TUFLOW Message 2477

2025-05-27T13:50:22Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=CHECK 2477 - 12da file has more than 1 tin, without super_tin.
|alt_msg=NA 

|type=[[CHECK]]
|message_desc=The 12da file that is being used has more than 1 tin, but is not using a super tin.
|suggestions=Ensure 12da file has only 1 tin. If more than 1 tin is required, a super tin should be used. This should be generated within 12d.

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

TUFLOW Message 2464

2025-05-27T13:44:42Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 2464 - Exceeded limit of devices: "<>" for HPC Device Split.
|alt_msg=ERROR 2464 - No values found after HPC Device Split command. 

|type=[[ERROR]]
|message_desc=The number of values found in the command "<tt>HPC Device Split == Value1, Value2,...</tt>" exceeds the number of GPU devices found in the machine or the number of devices that model was told to run on.

Alternative message: No values were specified after the command "<tt>HPC Device Split == </tt>"
|suggestions=Double check the command "<tt>HPC Device Split == </tt>" is appropriate. I.e. that it has at least one value specified and that it matches the number of devices the model is trying to run on. E.g. the number of values should match the list of devices in this command <tt>GPU Device IDs == <list_of_device_ids></tt> or the number of devices could also be specified in the batch file with <tt>-pu0 -pu1...</tt>. Also check that the number of values does not exceed the number of available GPU cards on the machine.

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

}}

TUFLOW Message 0647

2025-05-27T13:35:27Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0647 - Reached maximum concurrent SQLite statements - please contact [mailto:support@tuflow.com support@tuflow.com].
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=Reached maximum concurrent SQLite statements. There is an internal limit within TUFLOW on the number of sqlite queries that can be active concurrently. Typically this limit should never be exceeded and often indicates that some GPKG layers are not being closed correctly by TUFLOW.
|suggestions=Please contact [mailto:support@tuflow.com support@tuflow.com].

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

TUFLOW Message 0643

2025-05-27T13:33:00Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0643 - extracting projection from "<>" <nowiki>|</nowiki> "<>".
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=Error occurred while extracting projection from a GPKG. The first "<>" will be the database file path and the second "<>" will be the layer name. E.g. ERROR 0643 - extracting projection from "database.gpkg" <nowiki>|</nowiki> "projection".
|suggestions=Check the .tlf and the console for any prior error messages that might indicate why there was an issue extraction the projection. Check the layer in a GIS program to see if there are any issues. Can also try and recreate the layer in QGIS (be re-exporting the data into a new GPKG) to see if this fixes the issue as a last resort.

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

TUFLOW Message 0641

2025-05-27T13:14:40Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0641 - No X dimension found in netCDF grid file.
|alt_msg=ERROR 0641 - No Y dimension found in netCDF grid file. 
ERROR 0641 - No X coordinate data found in netCDF grid file. 
ERROR 0641 - No Y coordinate data found in netCDF grid file. 
ERROR 0641 - GRID should have more than 1 column. 
ERROR 0641 - GRID should have more than 1 row. 
ERROR 0641 - Layer does not exist in netCDF grid file - "<>" >> "<>". 
ERROR 0641 - Layer does not have the correct number of dimensions to be a grid: no. dim="<>" - "<>" >> "<>". 
ERROR 0641 - Layer is not dimensioned by X, Y : dim="<>","<>" - "<>" >> "<>". 

|type=[[ERROR]]
|message_desc=This error is suggesting that the NetCDF grid is missing an "x" dimension or a "y" dimension for grid TUFLOW is trying to read. A NetCDF grid is made up of a "x" dimension, "y" dimension, and sometimes a third "time" dimension.

Other reasons for this error:
* The error could also be triggered if the NetCDF grid only has one column or one row.
* If the NetCDF grid is being used as an input grid for zpts, mat, soil etc then it requires the format "file.nc >> layer_name". This error is triggered if the "layer_name" was not found within the NetCDF file.
* The order of the "x" and "y" dimensions is not correct or there are other dimensions other than "x", "y", and "time" being used.

|suggestions=Double check the validity of the NetCDF grid by loading it into a GIS program. If it is a rainfall grid, then it needs to have specific names to be compatible with TUFLOW.
Check the NetCDF header content to ensure it matches the required TUFLOW names/format. The required TUFLOW format is listed here: [[https://wiki.tuflow.com/TUFLOW_NetCDF_Rainfall_Format | TUFLOW NetCDF Rainfall Format]].

Double check the syntax in the control file is correct and that the layer exists with the NetCDF file. Double check the header content of the NetCDF to check if the grid dimensions make sense.

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

TUFLOW Message 0637

2025-05-27T13:02:54Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0637 - netcdf must use double ">" to reference layers: <>.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=When using a NetCDF grid as an input for Zpts, Mat, Soil, etc then it should be treated as a database (similar to GPKG) and it requires the format "<tt>file.nc >> layer_name</tt>". This error suggests that the line contains only a single ">" rather than two of them ">>".
|suggestions=Double check the referenced command to ensure it's using a double ">>".

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

TUFLOW Message 0637

2025-05-27T13:02:32Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0637 - netcdf must use double ">" to reference layers: <>.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=When using a NetCDF grid as an input for Zpts, Mat, Soil, etc then it should be treated as a database (similar to GPKG) and it requires the format "<tt>file.nc >> layer_name</tt>". This error suggests that the line contains only a single ">" rather than two of them ">>". This syntax is not required for rainfall NC references.
|suggestions=Double check the referenced command to ensure it's using a double ">>".

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

TUFLOW Message 0626

2025-05-27T12:58:40Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0626 - TUFLOW currently only supports 'float' data type for GPKG grids. Data type = "<>".
|alt_msg=NA

|type=[[ERROR]]
|message_desc=TUFLOW only supports 32 bit floating point data for GPKG grids. The data type of the input grid should be listed in the error message in place of "<>". An example might be that the format of the GPKG grid is actually in 64 bit floating point data, or integer data, which TUFLOW doesn't support yet.
|suggestions=Use a GIS program (e.g. QGIS) to convert the data into 32 bit floating point data. This can be done using the "Translate (Convert Format)" toolbox in QGIS and selecting "Float32" for the "Output data type" option under the advanced section.

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

TUFLOW Message 0320

2025-05-27T12:52:17Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=WARNING 0320 – Unable to open messages.csv file – please contact support@tuflow.com. Non-spatial messages will not appear in the _messages GIS layer.
|alt_msg=NA
|type=[[WARNING]]
|message_desc=A number of error messages can be triggered before TUFLOW initialises any GIS properties (projection, format etc.) and therefore these messages cannot be written to the messsage_P.shp file immediately. When the GIS properties are initialised, any messages that occurred prior to this will be copied into the messages_P.shp file. This error occurs when the message.csv cannot be opened (or does not exist) and therefore it is unable to copy any prior messages. TUFLOW will be able to write any subsequent messages to the message_P.shp but the GIS layer may be missing some message entries that occurred very early on in the pre-processing.
|suggestions=Double check the existence of the messages.csv file. This warning should not stop the simulation, but the user should be aware that the message_P.shp layer may be missing some initial logging. Please get into contact with
[mailto:support@tuflow.com support@tuflow.com] if this error message persists.
|uplink=[[0xxx_TUFLOW_Messages|0xxx Messages]]
}}

TUFLOW Message 0320

2025-05-27T12:49:36Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=WARNING 0320 – Unable to open messages.csv file – please contact support@tuflow.com. Non-spatial messages will not appear in the _messages GIS layer.
|alt_msg=NA
|type=[[WARNING]]
|message_desc=A number of error messages can be triggered before TUFLOW initialises any GIS properties (projection, format etc.) and therefore these messages cannot be written to the messsage_P.shp file immediately. When the GIS properties are initialised, any messages that occurred prior to this will be copied into the messages_P.shp file. This error occurs when the message.csv cannot be opened (or does not exist) and therefore it is unable to copy any prior messages. TUFLOW will be able to write any subsequent messages to the message_P.shp but the GIS layer may be missing some message entries that occurred very early on in the pre-processing.
|suggestions=Double check the existence of the messages.csv file. This warning should not stop the simulation, but the user should be aware that the message_P.shp layer may be missing some initial logging.

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

TUFLOW Message 0625

2025-05-27T12:33:42Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=ERROR 0625 - .PRJ parameter already loaded - <>.
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=This error is triggered if a given parameter within the shapefile or GPKG projection has already been loaded. For example, the projection string (from a .prj file) might have the following parameter <tt>GEOGCS["GCS_WGS_1984"...]</tt>. This should only appear once, and if it appears twice then it may mean there is an issue with the shapefile projection.
|suggestions=Check the .prj file in a text editor or load it into QGIS to see if there are any projection issues. This error can be bypassed if the projection string parsing method is switched back to "SIMPLE" with the following command: "<tt>SHP Projection Check Method == Simple</tt>". If the projection looks correct and this error is persisting, then please contact [mailto:support@tuflow.com support@tuflow.com].

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

TUFLOW Message 1622

2025-05-07T06:32:20Z

Ellis Symons: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 1622 - "Blockage Method == " must be specified |alt_msg=NA |type=ERROR |message_desc=The command <tt><nowiki>"Blockage Method == {}..."

{{TUFLOW_Message
|tuflow_message=ERROR 1622 - "Blockage Method == " must be specified
|alt_msg=NA
|type=[[ERROR]]
|message_desc=The command <tt><nowiki>"Blockage Method == {} | ELM | RAM"</nowiki></tt> must be set if the blockage matrix is enabled.
|suggestions=Add the command "Blockage Method == " to the TCF.

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

1D Integrity Tool - Tutorial

2025-05-06T13:20:21Z

Ellis Symons: /* Accessing the Tutorial Data */

__TOC__
 

=Introduction=

The 1D Integrity Tool is a suite of tools that help modellers find and fix potential errors in 1D networks prior to running TUFLOW. The tool was primarily designed for sub-surface pipe drainage networks, but can be used for all 1D channel types, however not all checks will be available. The tool is designed to be fast and provide automated fixes as well as visualisations to help the process. The 1D Integrity Tool is a free tool that comes as part of the TUFLOW plugin in QGIS.

The 1D Integrity tool is designed to accept multiple inputs and will treat all inputs holistically as a complete system. Each tool is designed to be run separately and progressively as part of the entire tool suite. It is assumed that most of the channel attribute data has been populated, most importantly that each channel has been given a valid type.

The following exercises will take the user through the various tools using a pipe drainage network which contains a number of common errors which are found in these types of datasets.

=Accessing the Tutorial Data=

<ol>
1. Firstly download the tutorial dataset from [https://downloads.tuflow.com/TUFLOW/Wiki_Tute_Models/Integrity_Tool_Tutorial.zip here] and unzip the dataset. 
2. From the '''Integrity_Tool_Tutorial\Data''' folder, load the '''1d_nwk_MI01_Pits_001_L.shp''' , '''1d_nwk_MI01_Pipes_001_L.shp''' and '''dem_DEV_EG07.asc''' into QGIS. 
3. Review the dataset and use the [[QGIS TUFLOW Styles | ‘Apply TUFLOW Styles to open layers’]] tool, [[File:Check files open.png||30px]], to theme the data. 
[[File:Sub-surface drainage overview.png]] 
</ol>
This is a small sub-surface drainage network model. This example will showcase use of the tools to check the integrity of such a dataset, however the tool really comes into it’s own when assessing much larger datasets where checking things manually would be a time-consuming task. 
<ol>
4. From the TUFLOW plugin, open the 1D Integrity tool. 

[[File: integrity_tool_in_toolbar.PNG]]. 
</ol>
The resulting dialogue will pop up. The numbered fields are described below. 
<ol>
[[File:integrity_tool_overview.PNG]] 
 
*'''1. Input Network Lines''' - Input location of 1d_nwk lines such as pipes, culverts, and open channels. Use dropdown box and '+' button to add layers as inputs to tool. 
*'''2. Input Network Points''' - Input location of 1d_nwk points such as pits and nodes. Use dropdown box and '+' button to add layers as inputs to tool. 
*'''3. Input Tables''' - Input location of 1d_ta lines such as 1d_xs, 1d_cs, and 1d_hw. Use dropdown box and '+' button to add layers as inputs to tool. 
*'''4. Input DEM''' - Input raster. Currently only 1 input is supported, so if you are using tiled rasters datasets, they would need to be mosaiced into a single raster prior to running the tool. 
*'''5. Tool Selection''' - The active tab will determine the active tool. Prior to plugin version 3.2 a radio button was used to select the active tool. See [[1D_Integrity_Tool#Tool_Documentation|Tool Documentation]] for information on each tool. 
*'''6. Status Bar''' - Contains the progress bar and status of the integrity tool. Includes information such as the current active task being performed (if one of the tools is running), and the status of the previously run tool. 
*'''7. Run''' - Runs the currently active tool (active tool determined by the current active tool tab - prior to plugin version 3.2 a radio button was used to select the active tool). 
 

5. Within the Input Network Lines tool, select the '''1d_nwk_MI01_Pipes_001_L.shp''' in the dropdown menu and click the ‘+’ icon to add the '''1d_nwk_MI01_Pipes_001_L.shp''' to the list of 1D network lines as below. 

[[File:Input Network Lines.png]] 
</ol>

This will mean we will be undertaking the integrity tests on this layer. We could also use the integrity tools on point layers and/or Cross-section/Height-Width tables, but for the purpose of this demonstration we will only use the network line layers.

=Using the 1D Integrity Tool=

The following pages go through the various checks available within the 1D Integrity Tools. For the purpose of running through the tutorial these pages, and the steps within them, should be undertaken in order.
<ol>
<li> [[Integrity_Tool_-_Empty_Geometry_Check|Empty Geometry Check]] --> This tool loops through the inputs file and identifies any features that have an empty or NULL geometry.
<li> [[Integrity_Tool_-_Channel_ID|Channel ID Check]] -->Checks the ID of each channel in the network and flag channels that have duplicate names or a NULL / empty ID.
<li> [[Integrity_Tool_-_Snapping_Check|Snapping Check]] -->The snapping tool checks that all input 1D network lines (channels) and 1D network points are correctly snapped.
<li> [[Integrity_Tool_-_Pipe_Direction|Pipe Direction Check]] -->The pipe direction integrity tool will check the pipe direction and will correct based on the selected options.
<li> [[Integrity_Tool_-_Flow_Trace_Tool|Flow Trace Tool]] -->The flow trace tool creates traces upstream from the selected channel, selecting all upstream network objects in the QGIS map window (network lines and network points).
<li> [[Integrity_Tool_-_Continuity_Tool|Continuity Tool]] -->The continuity 1D integrity tool will check all 1D inputs for downstream continuity based on the selected processing options. This is similar to the above Flow trace check but will undertake the assessment on the whole set of inputs rather than upstream of a selected link.
</ol>

=Summary=
The 1D integrity tool provides a set of checks and fixes to ensure that the 1D input data is suitable to be used within a TUFLOW hydraulic model. The checks assess common errors within 1D datasets which will either cause TUFLOW errors, or influence results. Commonly these common errors are a consequence of digitisation and given the nature of large urban drainage networks are difficult to spot visually. The automated, 1D integrity tools provide a quick and easy approach to allow the modeller to be proactive in identifying problematic parts of a 1D system prior to loading into TUFLOW.
 
 
{{Tips Navigation
|uplink=[[1D_Integrity_Tool| Back to 1D Integrity Tool Main Page]]
}}

TUFLOW Message 1433

2025-05-01T07:56:57Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=WARNING 1433 - Reading XF file failed. Reverting to original file.
|alt_msg=ERROR 1433 - Upper Transition Elevation is lower than Lower Transition Elevation for an Arch Bridge channel. 
|type=[[WARNING]] [[ERROR]]
|message_desc=WARNING 1433: There was an issue in reading the binary (xf) version of the file.

ERROR 1433: For arch bridge channels (BArch), the start of the orifice flow transition needs to be lower than the end of the orifice transition. That is, the arch bridge channel will transition from using the arch bridge approach into orifice flow as the water level approaches the bridge obvert if the orifice flow flag is turned on (the default is turned off).
|suggestions=WARNING 1433: The original data is being re-read from the .csv file.

ERROR 1433: Ensure that the lower transition value is lower than the upper transition value in the BArch channel GIS attributes. "EntryC_or_WSa" = Lower transition (measured as depth below obvert) and "ExitC_or_WSb" = upper transition (measured as depth above obvert). If using the arch bridge editor in QGIS, the transition values can be found on the 'General Data' tab.

[[file: Arch_bridge_editor_general_tab.png]]

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

File:Arch bridge editor general tab.png

2025-05-01T07:52:33Z

Ellis Symons:

TUFLOW Message 1464

2025-04-15T09:55:02Z

Ellis Symons: Created page with "{{TUFLOW_Message |tuflow_message=ERROR 1464 - Limit of 100 input 1d_nwk/1d_pit files exceeded when using "MESHPARTS == ON" |alt_msg=NA |type=ERROR |message_desc=There..."

{{TUFLOW_Message
|tuflow_message=ERROR 1464 - Limit of 100 input 1d_nwk/1d_pit files exceeded when using "MESHPARTS == ON"
|alt_msg=NA 

|type=[[ERROR]]
|message_desc=There is a hard-coded limit of 100 input files for 1d_nwk + 1d_pit inputs when the option "Meshparts== ON" has been set for the model. Note, prior to the 2025.1.0 release, TUFLOW did not produce an error and exceeding this limit could potentially result in WLLs not producing outputs in some section of channels.

|suggestions=Meshparts can be turned off ("Meshparts == OFF") to remove this limit (this solution will only work for the 2025.1.0 release or onward). Alternatively, the limit is linked with the number of input files and not the number of features, so some of the input layers can be concatenated to bring the total number of files down to 100 or less. In QGIS, this can be done using the "Merge vector layers" processing tool.

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

TUFLOW Message 1443

2025-03-26T07:40:02Z

Ellis Symons:

{{TUFLOW_Message
|tuflow_message=WARNING 1443 - arch springing level <level> is below arch start bed elevation <elevation>: Bridge:<name> - Arch No.: <number>
|alt_msg=NA 

|type=[[WARNING]]
|message_desc=The arch springing level is below the cross-section bed elevation for the given 1d_nwk "BArch" channel. An example is given below where the springing level has been set to 38.2 m and the finish offset has been set to 12 m, which puts the springining level below the bed elevation on the right hand side. 
[[file: Springing_level_below_bed.png]]

|suggestions=TUFLOW will still calculate the flow area correctly, however it recommended to check if the arch geometry and/or the cross-section is correct. The [[QGIS_TUFLOW_Arch_Bridge_Editor | arch bridge editor]] in the TUFLOW QGIS plugin can help with visualising the bridge.

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

File:Springing level below bed.png

2025-03-26T07:32:09Z

Ellis Symons: