Naming Convention

The establishment of a sound naming convention is fundamental to the easy management of TUFLOW models and their associated files. A certain degree of flexibility regarding naming conventions is usually required due to differences between projects and users. However, early establishment of a system has the following benefits:

• Easier to understand modelling logic;
• Easier to check for errors;
• Traceability;
• Transferable between different users; and
• Ease of handover of the model to the Client or Authorities.

Additionally, a sound naming convention can significantly reduce the time taken to locate files, especially in folders where hundreds of files are present, which may be the case for large modelling projects. Once a naming and numbering convention is adopted, then a modelling log can more easily be kept.

There is some simple advice on naming conventions in the 2018 TUFLOW Manual.
Currently, most modelling incorporates use of the TUFLOW scenario and event management feature. This allows for wildcards to be incorporated in the file name. Example models are available which demonstrate Scenario/Event management. A batch file can then be set up to run various scenario combinations from the one TUFLOW Control File (TCF).

The below sections provide information on the recommended naming convention for clearly identifying different types of TUFLOW input files. Guidance is also provided on a version numbering convention for control and input files during model development.

Input File Type – Prefix Naming Conventions

As the bulk of the data input to TUFLOW is via GIS layers, efficient management of these datasets is essential. Different TUFLOW input files require different GIS attributes. For example, an initial water level input file only requires a single attribute on the GIS file (which is the initial water level), whereas, a 1D channel has a number of attributes (channel type, inverts etc.). Differentiating between these TUFLOW file types is therefore essential.

TUFLOW input files are given different recommended prefixes depending on their purpose. An example of this is demonstrated in the table below. The complete list of recommended prefixes can be found in the TUFLOW Manual. The TCF command Write Empty GIS Files can be used to automate the creation of the template (empty) files, which use these recommended prefixes. These empty files are created with the precise GIS file formats required for each input TUFLOW file. The TUFLOW Empty Files page provides a reference list of the template (empty) GIS files, the associated TUFLOW command and a basic description of their function.

It is strongly recommended that the prefixes described in the TUFLOW Manual be adhered to for all 1D and 2D GIS layers. This greatly enhances the data management efficiency and, importantly, allows for the differentiation of input files, making it easier for another modeller or reviewer to quickly interpret the model.

GIS Data Type	Suggested File Prefix	Description
2D Boundaries and 2D/1D Links	2d_bc_ (2d_hx_) (2d_sx_)	Mandatory layer(s) defining the locations of 2D boundaries and 2D/1D dynamic links. For large models it may be wise to separate the boundary conditions from the 1D/2D links, in which case the 2d_bc prefix can be substituted with 2d_hx_ and 2d_sx. Cell code values may also be defined in this layer.

TUFLOW control files are structured to allow the majority of commands to be repeated and layered. Input file types of the same prefix may need to be used more than once. Hence, additional information such as a descriptor and a file version number is conventionally included in the input file name. An example of a typical file name for an input file is shown below:

• GeoPackage:

• Database for the entire model:

ModelName_FileVersion.gpkg

M01_001.gpkg

• Database for GIS layer (multiple geometry types):

FileTypePrefix_FileDescriptor_FileVersion.gpkg

2d_bc_CreekInflow_001.gpkg

• Database for GIS layer (single geometry type):

FileTypePrefix_FileDescriptor_FileVersion_GeometryType.gpkg

2d_bc_CreekInflow_001_L.gpkg

• GeoPackage Layer (within a database):

gpkgDatabaseName_GeometryType

2d_bc_CreekInflow_001.gpkg >> 2d_bc_CreekInflow_L

• Shapefile layer:

FileTypePrefix_FileDescriptor_FileVersion_GeometryType.shp

2d_bc_CreekInflow_001_L.shp

Note: Only a single geometry type (points, lines or regions) can be included in a shapefile. Thus, for datasets made up of multiple geometries, for example points and lines, two separate files will be required. Therefore, the suggested file naming convention for shapefiles includes the geometry type (P for points, L for lines or R for regions).

• MIF formatted layer:

FileTypePrefix_FileDescriptor_FileVersion.mif

2d_bc_CreekInflow_001.mif

Many iterations of the same input file may be created as the model is developed. A suggested approach for the use of version numbering of input and control files is provided below.

Control and Input Files – Version Numbering Convention

The version numbering convention described below is presented as guidance only. Users are free to deviate from that suggested, however, establishing a sound naming and numbering convention is highly recommended throughout the model development. This can aid in quality control, allowing modellers to revert back to an earlier version of the model input if required.
Version numbering convention of the TCF control file is particularly important as its name determines the prefix assigned for the results and check files. The TCF is used as the basis for version numbering, following the below convention:

• Increment the TCF version number sequentially each time a change is made anywhere in the model;
• If a change is made in a sub-control file such as the TUFLOW Geometry Control File (TGC), Boundary Control File (TBC) or Estry Control File (ECF), then the version number of that sub-control file should be incremented. However, the numbering of these files should be incremented to correspond to the revised TCF version number. Numbering for a given sub-control file is not necessarily sequential;
• Similarly, if a change is made to any input GIS files listed in any of the control files, then the version number of that input file should be incremented, corresponding to the revised TCF version number. Numbering for a given input file is not necessarily sequential.

Generally, changes are made at the lowest level, i.e. the GIS input. That file, and all files in the hierarchy above it, are given a new version number consistent with the next TCF iteration. This provides an indication of at which point in the model development a GIS layer was introduced.

Each time a new element/s is introduced, the version number of the TCF is incremented. The above convention is demonstrated in the table below, showing file version numbering of input layers corresponding with the overarching control files. Each update is highlighted bold. The table below shows:

• When a new GIS layer is introduced or amendment made, a new TCF is created with the version number iterated up. The GIS layer is assigned the same version number as the TCF;
• The numbering of input layers doesn’t have to be sequential, as per the development Z shape and the 1d_nwk layers;
• Modifications can be made in a number of the sub-control files for a given TCF increment, as per Model_005.tcf.

TCF	TGC	TGC Input Layers	TBC	TBC Input Layers	ECF	ECF Input Layers	Model Amendments
MODEL_001.tcf	MODEL_001.tgc	gis\2d_loc_EG00_001_L.shp gis\2d_code_001_R.shp grid\DEM_2mLidar_01.tif	MODEL_001.tbc	gis\2d_bc_EG00_001_L.shp			Construct 2D only model with base topography.
MODEL_002.tcf	MODEL_002.tgc	gis\2d_loc_EG00_001_L.shp gis\2d_code_001_R.shp grid\DEM_2mLidar_001.tif gis\2d_zsh_Development_002_R.shp	MODEL_001.tbc	gis\2d_bc_EG00_001_L.shp			Add topographic amendments for development.
MODEL_003.tcf	MODEL_002.tgc	gis\2d_loc_EG00_001_L.shp gis\2d_code_001_R.shp grid\DEM_2mLidar_001.tif gis\2d_zsh_Development_002_R.shp	MODEL_001.tbc	gis\2d_bc_EG00_001_L.shp	MODEL_003.ecf	1d_nwk_Pipes_003.shp	Add 1D elements.
MODEL_004.tcf	MODEL_002.tgc	gis\2d_loc_EG00_001_L.shp gis\2d_code_001_R.shp grid\DEM_2mLidar_001.tif gis\2d_zsh_Development_002_R.shp	MODEL_004.tbc	gis\2d_bc_EG00_001_L.shp gis\2f_rf_004_R.shp	MODEL_003.ecf	1d_nwk_003.shp	Add 2D rainfall polygon boundary condition.
MODEL_005.tcf	MODEL_005.tgc	gis\2d_loc_EG00_001_L.shp gis\2d_code_001_R.shp grid\DEM_2mLidar_001.tif gis\2d_zsh_Development_005_R.shp	MODEL_004.tbc	gis\2d_bc_EG00_001_L.shp gis\2f_rf_004_R.shp	MODEL_005.ecf	1d_nwk_Pipes_005.shp	Make modifications to the original development + update the 1D elements.

Up
Back to TUFLOW Modelling Guidance