Difference between revisions of "Naming Convention"

From Tuflow
Jump to navigation Jump to search
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The establishment of a sound naming convention is fundamental to the easy management of models and their associated files. For suggestions of naming conventions, refer to Naming Conventions section of the TUFLOW Manual.  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:<br>
+
__TOC__
 +
<br>
 +
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 understand modelling logic;
 
* Easier to check for errors;
 
* Easier to check for errors;
Line 5: Line 7:
 
* Transferable between different users; and
 
* Transferable between different users; and
 
* Ease of handover of the model to the Client or Authorities.
 
* Ease of handover of the model to the Client or Authorities.
Additional to the above list, a sound naming convention can significantly reduce the time taken to locate files, especially in folders where hundreds of files are present.<br>
+
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 <u>[[TUFLOW_Modelling_Log|modelling log]]</u> can more easily be kept.<br>
The naming conventions used within this tutorial are consistent with the recommendations of the TUFLOW user manual.
+
<br>
 +
There is some simple advice on naming conventions in the <u>[https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]</u>.<br>
 +
Currently, most modelling incorporates use of the TUFLOW scenario and event management feature. This allows for wildcards to be incorporated in the file name. <u>[[TUFLOW Example Models|Example models]]</u> are available which demonstrate Scenario/Event management. A <u>[[ Run_TUFLOW_From_a_Batch-file#Looping_in_a_batch_file|batch file]]</u> can then be set up to run various scenario combinations from the one TUFLOW Control File (TCF).<br>
 +
<br>
 +
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.<br>
 +
<br>
 +
 
 +
=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.<br>
 +
<br>
 +
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 <u>[https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]</u>. The TCF command <font color="blue"><tt>Write Empty GIS Files</tt></font> 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 <u>[[TUFLOW Empty Files]]</u> page provides a reference list of the template (empty) GIS files, the associated TUFLOW command and a basic description of their function.<br>
 +
<br>
 +
It is strongly recommended that the prefixes described in the <u>[https://docs.tuflow.com/classic-hpc/manual/latest/ TUFLOW Manual]</u> 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.<br>
 +
 
 +
{| class="wikitable" width="75%"
 +
! style="background-color:#005581; font-weight:bold; color:white;" width=20%| GIS Data Type
 +
! style="background-color:#005581; font-weight:bold; color:white;" width=20%| Suggested File Prefix
 +
! style="background-color:#005581; font-weight:bold; color:white" width=60%| Description
 +
|-
 +
| style="text-align: left;" | 2D Boundaries and 2D/1D Links
 +
| style="text-align: left;" | 2d_bc_ <br><br>(2d_hx_) <br><br>(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. <br><br>Cell code values may also be defined in this layer.
 +
|-
 +
|}
 +
<br>
 +
 
 +
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<br>
 +
:* Database for GIS layer (single geometry type):
 +
:::'''FileTypePrefix'''_'''FileDescriptor'''_'''FileVersion'''_'''GeometryType'''.gpkg
 +
:::'''2d_bc'''_'''CreekInflow'''_'''001'''_'''L'''.gpkg<br>
 +
:* GeoPackage Layer (within a database):
 +
:::'''gpkgDatabaseName'''_'''GeometryType'''
 +
:::2d_bc_CreekInflow_001.gpkg >> '''2d_bc_CreekInflow'''_'''L'''<br>
 +
<br>
 +
 
 +
*Shapefile layer:
 +
:::'''FileTypePrefix'''_'''FileDescriptor'''_'''FileVersion'''_'''GeometryType'''.shp
 +
:::'''2d_bc'''_'''CreekInflow'''_'''001'''_'''L'''.shp<br>
 +
 
 +
:<b>Note:</b> 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).<br>
 +
<br>
 +
 
 +
*MIF formatted layer:
 +
:::'''FileTypePrefix'''_'''FileDescriptor'''_'''FileVersion'''.mif
 +
:::'''2d_bc'''_'''CreekInflow'''_'''001'''.mif<br>
 +
<br>
 +
 
 +
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.
 +
<br>
 +
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.
 +
 
 +
{| class="wikitable" width="100%"
 +
! style="background-color:#005581; font-weight:bold; color:white;" width=8%| TCF
 +
! style="background-color:#005581; font-weight:bold; color:white;" width=8%| TGC
 +
! style="background-color:#005581; font-weight:bold; color:white" width=15%| TGC Input Layers
 +
! style="background-color:#005581; font-weight:bold; color:white;" width=8%| TBC
 +
! style="background-color:#005581; font-weight:bold; color:white" width=12%| TBC Input Layers
 +
! style="background-color:#005581; font-weight:bold; color:white;" width=8%| ECF
 +
! style="background-color:#005581; font-weight:bold; color:white" width=8%| ECF Input Layers
 +
! style="background-color:#005581; font-weight:bold; color:white;" | Model Amendments
 +
|-
 +
| style="text-align: center;" | MODEL_001.tcf
 +
| style="text-align: center;" | MODEL_001.tgc
 +
|| gis\2d_loc_EG00_001_L.shp<br> gis\2d_code_001_R.shp<br> grid\DEM_2mLidar_01.tif
 +
| style="text-align: center;" | MODEL_001.tbc
 +
|| gis\2d_bc_EG00_001_L.shp
 +
| style="text-align: center;" |
 +
||
 +
|| Construct 2D only model  with base topography.<br>
 +
|-
 +
| style="text-align: center;" | '''MODEL_002.tcf'''
 +
| style="text-align: center;" | '''MODEL_002.tgc'''
 +
|| gis\2d_loc_EG00_001_L.shp<br> gis\2d_code_001_R.shp<br> grid\DEM_2mLidar_001.tif<br> '''gis\2d_zsh_Development_002_R.shp'''
 +
| style="text-align: center;" | MODEL_001.tbc
 +
|| gis\2d_bc_EG00_001_L.shp
 +
| style="text-align: center;" |
 +
||
 +
|| Add topographic  amendments for development.<br>
 +
|-
 +
| style="text-align: center;" | '''MODEL_003.tcf'''
 +
| style="text-align: center;" | MODEL_002.tgc
 +
|| gis\2d_loc_EG00_001_L.shp<br> gis\2d_code_001_R.shp<br> grid\DEM_2mLidar_001.tif<br> gis\2d_zsh_Development_002_R.shp
 +
| style="text-align: center;" | MODEL_001.tbc
 +
|| gis\2d_bc_EG00_001_L.shp
 +
| style="text-align: center;" | '''MODEL_003.ecf'''
 +
|| '''1d_nwk_Pipes_003.shp'''
 +
|| Add 1D elements.
 +
|-
 +
| style="text-align: center;" | '''MODEL_004.tcf '''
 +
| style="text-align: center;" | MODEL_002.tgc
 +
|| gis\2d_loc_EG00_001_L.shp<br> gis\2d_code_001_R.shp<br> grid\DEM_2mLidar_001.tif<br> gis\2d_zsh_Development_002_R.shp
 +
| style="text-align: center;" | '''MODEL_004.tbc'''
 +
|| gis\2d_bc_EG00_001_L.shp<br> '''gis\2f_rf_004_R.shp'''
 +
| style="text-align: center;" | MODEL_003.ecf
 +
|| 1d_nwk_003.shp
 +
|| Add 2D rainfall polygon boundary condition.<br>
 +
|-
 +
| style="text-align: center;" | '''MODEL_005.tcf'''
 +
| style="text-align: center;" | '''MODEL_005.tgc'''
 +
|| gis\2d_loc_EG00_001_L.shp<br> gis\2d_code_001_R.shp<br> grid\DEM_2mLidar_001.tif<br>'''gis\2d_zsh_Development_005_R.shp''' 
 +
| style="text-align: center;" | MODEL_004.tbc
 +
|| gis\2d_bc_EG00_001_L.shp<br> gis\2f_rf_004_R.shp
 +
| style="text-align: center;" | '''MODEL_005.ecf'''
 +
|| '''1d_nwk_Pipes_005.shp'''
 +
|| Make modifications to the original development + update the 1D elements.<br>
 +
|-
 +
|}
 +
 
 +
<br>
 +
{{Tips Navigation
 +
|uplink=[[TUFLOW_Modelling_Guidance | Back to TUFLOW Modelling Guidance]]
 +
}}

Latest revision as of 10:09, 23 September 2024


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 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
Go-up.png Back to TUFLOW Modelling Guidance