Appendix A Commands
This appendix provides the formal definitions of all TUFLOW FV commands referenced in the model construction chapters. Each command definition describes its purpose, syntax, and allowable usage and is the reference for command specification.
The model construction chapters reference this appendix for formal command definitions. Readers are expected to move between the model construction chapters and this appendix as needed.
Instructions for using the interactive tables deployed in this appendix are provided in the manual introduction. All TUFLOW FV commands and descriptions are listed in Table A.1.
Command syntax
TUFLOW FV commands are displayed using coloured formatting, for example
Argument syntax
Arguments expected by TUFLOW FV commands (that is, information provided after
Arguments are separated by commas and each argument is described in the description column.
Commands
All TUFLOW FV commands and descriptions are listed below. This page is intentionally wider than the main document to accommodate the level of detail provided in the command table.
Additional tips for interacting with the table include:
- Commands are
coloured . Although they appear underlined on mouse hover, they are not hyperlinks. - Corresponding arguments are
coloured and listed in the required order within angle brackets following each command. - The final line of each command description links back to the relevant model construction section, where the command syntax is shown in context.
| Command | Description |
|---|---|
|
|
Status: Conditional.
Description: Enables or disables the consideration of atmospheric stability when using the Kondo implementation of Wind Stress Model, Bulk Latent Heat Coefficient and Bulk Sensible Heat Coefficient.
Further Information: Ignored when other wind stress model implementations are selected.
|
|
|
Status: Optional.
Description: Sets the update timestep for atmospheric heat exchange calculations.
Further Information: None
|
|
|
Status: Optional.
Description: Selects the autoweir formulation for automatically generated weir behaviour.
Further Information: The globally assigned Autoweir feature instructs TUFLOW FV to identify all cell faces in the model domain that are elevated above the adjacent cell’s centroid elevations. These cell faces are then assigned a weir flow condition. Autoweirs are assigned TUFLOW FV’s default weir properties and this cannot be altered. The autoweir formulation should only be used where high resolution topographic data is available and the model grid is sufficiently refined to capture the topographic features of interest. It is not recommended to use the autoweir formulation with coarse grids or low resolution topographic data.
|
|
|
Status: Optional.
Description: Automatically stops a simulation when a specific water level condition is met.
Further Information: None
|
|
|
Status: Conditional - Required if Bed Adjust == bathy_database.
Description: Defines the CSV filepath to a DEM lookup table used to interpolate bathymetry values.
Further Information: Supported for zone structure connection types only. Example syntax and csv file formats are provided via the model construction link below.
|
|
|
Status: Required.
Description: Begins a boundary condition block and links a boundary type with its location and input data.
Further Information: Typically at least one boundary condition will be required for a TUFLOW FV simulation and often a number of different boundary condition types will be applied. Each boundary condition type is defined using a boundary condition (BC) block. The BC and End BC commands indicate the beginning and end of a boundary condition block. Different boundary_type options require different numbers and types of arguments. These are outlined in the boundary condition sections of the simulation class construction chapters. Generally:
• BC == boundary_type for the simplest BC types that require no location or input data specification (ZG, RS, RNS etc.). • BC == boundary_type, data_filepath for BC types that require input data but not location specification. Globally assigned boundary conditions are an example of this (PRECIP, QC etc.). • BC == boundary_type, location_id for BC types that require location specification but not input data. An automatic downstream water level boundary (QN) is an example of this. • BC == boundary_type, location_id, data_filepath for BC types that require both location specification and input data (most boundary conditions). Refer to the BC Block sections of each model construction chapter for boundary type specific argument requirements and refer to the boundary condition model implementation sections for example syntax and further explanation of the different boundary condition types. |
|
|
Status: Optional.
Description: Sets fallback value(s) when a BC Header cannot be located in the input file, or if missing data is within an input file. Arguments are a comma delimited list of values that correspond to the expected number of variables for the simulation.
Further Information: Can be used to apply a constant boundary value.
|
|
|
Status: Optional.
Description: Sets the global update timestep for boundary conditions. This is the frequency at which boundary data are refreshed or interpolated during the simulation.
Further Information: The default of 0.0 s means that boundary default values are updated at every simulation timestep. This can be overridden on a per boundary condition basis using the BC Update dt command. Sits globally outside of BC blocks and applies to all boundary conditions that use the BC Default values. For long simulations with slowly varying boundary conditions, setting this to a value greater than 0.0 can reduce model run times by reducing the frequency of boundary data updates.
|
|
|
Status: Conditional - Required if using model events functionality..
Description: Assigns dynamic text replacement for user defined text in .fvc files and is used in conjunction with event simulation management commands.
Further Information: Allows alternative boundary conditions, include files, or model parameters to be modified using a single .fvc file. Will dynamically replace bc_event_text with the value of bc_event_name in the .fvc file. Can be used with any simulation class but it is not supported within the sediment, water quality or particle tracking control files.
|
|
|
Status: Required.
Description: Maps input file columns or variables to the boundary variables required by the selected boundary type.
Further Information: The number of headers depends on the selected BC type. The expected default header names depend on the simulated quantities for that boundary. The command should immediately follow BC. It applies to CSV column names or NetCDF variable names.
|
|
|
Status: Conditional - Required when using the OBC_GRID boundary type..
Description: Defines the nodestring IDs to interpolate boundary conditions onto for the OBC_GRID boundary type. This allows different boundary conditions to be applied to different nodestrings along the same boundary.
Further Information: None
|
|
|
Status: Optional.
Description: Applies additive offsets to boundary data values after any scaling is applied.
Further Information: Applied after any scaling is applied to the boundary data values. Can be used to apply a constant offset to boundary values, for example to adjust a tidal boundary condition up or down by a constant value.
|
|
|
Status: Optional.
Description: Sets the reference date and time used with relative boundary time units such as hours or days.
Further Information: Defaults to {0.0} if Time Format == HOURS or {DD/MM/YYYY HH:MM:SS} if Time Format == ISODATE. If not specified, the BC Reference Time is assumed to be consistent with the Reference Time. Applicable to CSV and NetCDF input files.
|
|
|
Status: Optional.
Description: Applies multiplicative scale factors to boundary data values read from the input file.
Further Information: Applied to boundary data values after they are read from the input file and before any offsets are applied. Can be used to apply a constant scale factor to boundary values, for example to adjust an inflow boundary by 10% by applying a scale factor of 1.1.
|
|
|
Status: Optional.
Description: BC block command that specifies the time units used by the boundary input data when time is not provided as full dates. Defaults to {HOURS} if Time Format == HOURS or {ISODATE} if Time Format == ISODATE.
Further Information: The time values entered into the boundary condition time field will be in BC Time Units relative to the BC Reference Time.
|
|
|
Status: Optional.
Description: BC block command that sets how often boundary data are refreshed or interpolated during the simulation. Overrides the global BC Default Update dt command on a per boundary condition basis.
Further Information: The default of 0.0 s means that boundary data are updated at every simulation timestep. For long simulations with slowly varying boundary conditions, setting this to a value greater than 0.0 can reduce model run times by reducing the frequency of boundary data updates.
|
|
|
Status: Optional.
Description: Structure block command that defines the bathymetric modification model for variable bathymetry structures. Supported bed adjustment model options include:
• ZB_adjust: Adjustable bed elevations for a series of cells with a specified crest level • DZB_adjust: Adjustable bed elevations for a series of cells with a specified crest level dz above existing bed levels • bathy_database: A lookup table of digital elevation models (DEMs) that are used to adjust bed elevations.
Further Information: Used in conjunction with a control specification to modify bed elevations during the simulation. Supported for zone structure connection types.
|
|
|
Status: Optional.
Description: Material block command that assigns material specific lower and upper limits to local bed elevation values. Overrides the global bed elevation limits assigned by the Global Bed Elevation Limits command.
Further Information: None
|
|
|
Status: Optional.
Description: Boundary condition block command that allows bedload fluxes to pass through open polyline (nodestring) boundaries as a zero gradient bedload flux boundary. Used in conjunction with the TUFLOW FV Sediment Transport Module.
Further Information: None
|
|
|
Status: Optional.
Description: Structure block command that defines a blockage profile to reduce effective flow width for bridges or flow constrictions.
Further Information: The blockage file is a comma separated variable file with a relationship of flow fraction and depth. Example syntax and file formats are provided via the model construction link below.
|
|
|
Status: Required.
Description: Sets the bed resistance model to:
• {Manning}: The Manning equation • ks: Log-law velocity profile
Further Information: The values assigned to the Bottom Roughness command depend on the selected bed resistance model. The Manning implementation requires a Manning’s ‘n’ coefficient, while the ks implementation requires a Nikuradse roughness length. This is further explained in the Bottom Roughness command entry.
|
|
|
Status: Optional.
Navigation row for this command. Argument syntax depends on the selected implementation of the Bottom Drag Model. Refer to the implementation specific rows immediately below.
|
|
|
Status: Optional.
Description: Material block command that sets the Manning’s ‘n’ bed roughness coefficient for a given material ID when the Manning Bottom Drag Model is selected.
Further Information: None
|
|
|
Status: Optional.
Description: Set the Nikuradse bed roughness length for a given material ID when the ks Bottom Drag Model is selected.
Further Information: If using the ks Bottom Drag Model, it can be optionally coupled with the Sediment Transport Module to allow bed roughness to vary with sediment characteristics. See the Sediment Transport Module documentation for more details. Global value is assigned by the Global Bottom Roughness command and can be overridden on a per material basis using this command.
|
|
|
Status: Conditional - Required when using OBC_GRID boundary type.
Description: Grid Definition block that controls whether interpolation weightings are calculated from the grid onto boundary nodestrings.
Further Information: None
|
|
|
Status: Optional.
Description: Alters the neutral conditions bulk latent heat coefficient when using the Constant Bulk Aerodynamic Latent Heat Transfer Coefficient model.
Further Information: The default coefficient is a well established value that would require considerable justification to alter.
|
|
|
Status: Optional.
Description: Specifies the constant bulk momentum transfer coefficient when using the Constant Wind Stress Model.
Further Information: None
|
|
|
Status: Optional.
Description: Alters the neutral conditions bulk sensible heat coefficient when using the Constant Sensible Heat model.
Further Information: The default coefficient is a well established value that would require considerable justification to alter.
|
|
|
Status: Optional.
Description: Sets the depth threshold below which 3D momentum calculations are disabled while mass flux calculations are maintained. Useful for model stability in shallow water depths.
Further Information: Use this threshold to suppress 3D momentum calculations in very shallow water while retaining mass flux calculations.
|
|
|
Status: Optional.
Description: Updates cell centre elevations using preprocessed inputs. Can be used to update all model cell elevations or a subset. This command is provided for legacy models or when optimising model initialisation times.
Further Information: The required header names and expected formats depend on the selected xy_type. Supported xy_type options include:
• Cell_ID: Requires an ID column that matches the TUFLOW FV assigned cell IDs and a Z column with the updated elevation values. This is the most efficient option because it is a direct cell mapping and requires no spatial interpolation. • Coordinate: Requires X, Y, and Z columns. This option is more flexible because it does not require a direct cell mapping, but it is less efficient than the Cell_ID option. Examples of both file types are provided in the linked construction section below. |
|
|
Status: Legacy.
Description: Legacy command. Superseeded by Read GIS Z Line.
Further Information: None
|
|
|
Status: Legacy.
Description: Legacy command. Superseeded by Read GIS Z Line.
Further Information: None
|
|
|
Status: Optional.
Description: Grid definition block command that controls whether interpolation weightings are calculated from the grid onto model cells.
Further Information: May be more efficient to set as 0 if the intent of the boundary is to only supply data to the boundary nodestrings via Boundary Gridmap and not to the interior cells.
|
|
|
Status: Conditional - Required if using a structured mesh..
Description: Sets the x and y cell resolution when using regular mesh specification.
Further Information: In units of meters for Cartesian metric models, feet for Cartesian US Customary models, or decimal degrees for Spherical models.
|
|
|
Status: Optional.
Description: Sets the minimum water depth at which water quality calculations are undertaken. Water quality calculations are not undertaken in columns (i.e. 2D cells) where the depth is less than the threshold value.
Further Information: Cell WQ depth == also supported.
|
|
|
Status: Optional.
Description: Sets the cell dry and wetting depths used to switch off momentum and mass calculations in regions of shallow flow.
Further Information: Used to control wetting and drying behaviour in shallow regions of the model domain.
|
|
|
Status: Optional.
Description: Assigns the global maximum Courant- Friedrichs- Lewy (CFL) computational stability condition.
Further Information: The default value is 1.0, which is the theoretical stability limit. In practice this value is commonly lowered to provide additional stability for models that exhibit large gradients in flow, density or constituent concentrations such as the assessment of Tsunami, dam break or lakes with strong vertical stratification. Also see CFL external and CFL internal.
|
|
|
Status: Optional.
Description: Overrides the global maximum Courant- Friedrichs- Lewy (CFL) condition for external free surface calculations.
Further Information: None
|
|
|
Status: Optional.
Description: Overrides the global maximum Courant- Friedrichs- Lewy (CFL) condition for internal advective flux calculations.
Further Information: None
|
|
|
Status: Optional.
Description: Specifies a constant simulation timestep instead of using the variable CFL controlled timestep.
Further Information: If this command is not entered then a variable timestep is applied according to the CFL stability criterion. Due to explicit variable time stepping a constant timestep is not typically recommended unless there is a specific reason to use one. Using this option overrides CFL, CFL Internal, CFL External, and Timestep Limits controls.
|
|
|
Status: Conditional - Required if using operational control hydraulic structures or variable bathymetry structures..
Description: Structure block command that begins a control sub block used to define operational logic or variable bathymetry behaviour.
Further Information: For comparative explanation of the different control types, refer to the operational control and variable bathymetry sections of the model construction chapters. For example models that you can run with a license to test opertional control structure configurations see the TUFLOW FV Hydraulic Structures Example Model.
|
|
|
Status: Conditional - Required if using operational control hydraulic structures or variable bathymetry structures..
Description: Control block command that sets the CSV filepath to the structure control file. This file defines how the control parameter varies during the simulation.
Further Information: Used for Trigger, Timeseries, Sample Rule and Target Rule control types. Not used for Sample control type.
|
|
|
Status: Optional.
Description: Specifies the column header used by a structure control definition. Overides the default header name (which is the same wording as the control parameter) for the control parameter column in the control file. This is useful when using a single control file with multiple control definitions that require different column names for the control parameter.
Further Information: None
|
|
|
Status: Conditional - Required if using operational control hydraulic structures or variable bathymetry structures..
Description: Control block command that sets the control parameter used by the active control type. Supported control_parameter values include:
• Fraction_Open • Min_Flow • Weir_Crest • Weir_dz • Zb • dZb • Bathy_Control
Further Information: Used within a Control block to define the parameter that will be adjusted by the selected control logic.
|
|
|
Status: Optional.
Description: Control block command that sets the interval to call the control update function.
Further Information: If not specified, or if set to 0.0, the control logic is evaluated every model timestep.
|
|
|
Status: Conditional - Required when using the Culvert flux function..
Description: Structure block command that specifies a CSV file containing the properties for one or more culvert structures.
Further Information: Reads a CSV file containing the properties for a list of culverts. The file contains a header row followed by one row per culvert definition. The required culvert file entries are described in Table B.10.
|
|
|
Status: Optional.
Description: Controls the behaviour of the culvert invert validation check. If a 1D culvert invert is specified below the minimum ground elevation of the connected nodestring or zone TUFLOW FV outputs an error by default. Setting the command to
WARNING changes the message from an error to a warning. The message is written to the .log file and to the GIS messages layer in the log directory when GIS integration is enabled. This message highlights locations where the 1D/2D connection may require improvement or where mesh elevations at the culvert inlet or outlet may need adjustment to reflect surveyed invert levels.
Further Information: Set to
WARNING to downgrade the default error to a warning when a culvert invert falls below the connected ground elevation.
|
|
|
Status: Optional.
Description: Sets optional culvert parameters including critical headwater behaviour and culvert energy loss options.
Further Information: Culvert parameter science is described in Appendix B.12.1.2.
|
|
|
Status: Conditional - Required for the decay tracer model implementation.
Description: Tracer block command that specifies first order decay rate for tracers in the active tracer block.
Further Information: None
|
|
|
Status: Conditional - Required when using event simulation management logic..
Description: Begins an event definition block used for simulation management logic.
Further Information: Used with the event simulation management commands to apply conditional logic or text substitution based on the active event.
|
|
|
Status: Optional.
Description: See Tutorial Model.
Further Information: See Tutorial Model.
|
|
|
Status: Optional.
Description: Specifies the air density used in atmospheric heat calculations.
Further Information: This reference value should not generally be modified. It is a default reference value used to calculate wind stress and atmospheric heat exchange source terms. It is overridden by model implementation specific values when using the Tropical Cyclone boundary condition. It is internally calculated when the Kondo Wind Stress Model is specified.
|
|
|
Status: Conditional - Required for supported bubble plume structures..
Description: Selects the destratification unit type used for supported bubble plume structures.
Further Information: Supported for zone structures only.
|
|
|
Status: Optional.
Description: Set the default NVIDIA GPU Device ID to run a simulation on.
Further Information: Can be used to select the GPU Device ID if multiple GPU Devices exist. gpu_device_id may be overwritten at runtime via command line argument switches: -cpu, -gpu, and -pu.
|
|
|
Status: Optional.
Description: Optional command used in combination with the Particle Tracking Module. Setting to 1 will switch off the hydrodynamic calculations in TUFLOW FV. Rather than obtain advective forcings from TUFLOW FV’s internal hydrodynamic scheme, gridded boundary conditions are used to provide the water level, depth and velocity information, and if required wind and wave inputs to the Particle Tracking Module. Disabling the hydrodynamics has a couple of key advantages:
• PT Module simulations can be completed rapidly as they are not needing to wait for hydrodyncmic calculations to be computed. • The PT Module can be driven by a number of global circulation or ocean forecast models, for example HYCOM, BRAN, FVCOM.
Further Information: None
|
|
|
Status: Optional.
Description: Disables water quality calculations and can be used as a diagnostic switch for TUFLOW or external water quality models.
Further Information: If set to 1, water quality calculations are disabled. This applies to both the TUFLOW FV water quality module and external water quality model couplings.
|
|
|
Status: Optional.
Description: Suppresses result output where local water depth is below the specified display depth threshold.
Further Information: This affects result display and output only. It does not alter the hydraulic calculations and should not be confused with the wetting and drying controls. Typically used with direct rainfall models to threshold out the display of results in areas of very shallow water that are not of interest. This can help to improve the clarity of visual outputs.
|
|
|
Status: Optional.
Description: See Screen/Log Display Interval.
Further Information: None
|
|
|
Status: Optional.
Description: Controls whether geometry check outputs are written to the log directory.
Further Information: When enabled, the geometry outputs can include mesh details, cell elevations and materials, externally updated cell elevations, nodestring locations, and output locations. This command outputs both CSV and NetCDF formats. Use Echo Geometry CSV or Echo Geometry NetCDF to control the output formats more specifically.
|
|
|
Status: Optional.
Description: Controls whether geometry check CSV files are written to the log directory.
Further Information: When enabled, CSV geometry outputs can include mesh details, cell elevations and materials, externally updated cell elevations, nodestring locations, and output locations.
|
|
|
Status: Optional.
Description: Controls whether the NetCDF geometry check file is written to the log directory.
Further Information: When enabled, a *_geo.nc file is written containing geometry information for cells, faces, and nodes.
|
|
|
Status: Optional.
Description: Separates conditional logic branches within an event or scenario condition block.
Further Information: None
|
|
|
Status: Optional.
Description: Adds an alternative conditional branch within an event based simulation management block.
Further Information: Used after an If Event or another Else If Event statement to test additional event names.
|
|
|
Status: Optional.
Description: Adds an alternative conditional branch within a scenario based simulation management block.
Further Information: Used after an If Scenario or another Else If Scenario statement to test additional scenario names.
|
|
|
Status: Required.
Description: Closes a boundary condition block.
Further Information: None
|
|
|
Status: Conditional - Required if using operational control hydraulic structures or variable bathymetry structures..
Description: Closes a control sub block used to define operational logic or variable bathymetry behaviour within a structure block.
Further Information: None
|
|
|
Status: Conditional - Required if using event simulation management logic..
Description: Closes an event definition block used for simulation management logic.
Further Information: None
|
|
|
Status: Conditional - Required if using either Grid Definition or Grid Definition File..
Description: Closes a grid definition block.
Further Information: None
|
|
|
Status: Conditional - Required if using event simulation management logic or nested scenario definitions..
Description: Closes an If Event or If Scenario block used for simulation management logic or nested scenario definitions.
Further Information: Closes an If Event or If Scenario block.
|
|
|
Status: Required to close a material block..
Description: Closes a material block.
Further Information: None
|
|
|
Status: Requried to close an output block..
Description: Closes a model output block.
Further Information: None
|
|
|
Status: Conditional - Required if using hydraulic structures..
Description: Closes a hydraulic structure block.
Further Information: None
|
|
|
Status: Required.
Description: Specifies the end time for the simulation in the selected Time Format.
Further Information: The format of simulation_end_time depends on the selected Time Format:
• For Time Format == Hours, units are in decimal hours. For Time Format == ISODate, inputs are in date form dd/mm/yyyy HH:MM:SS (or some truncation thereof) |
|
|
Status: Conditional - Required if using tracer blocks..
Description: Closes a tracer block used to define tracer properties and behaviour.
Further Information: None
|
|
|
Status: Conditional - Required if using the table Energy Loss Function..
Description: File specifying the head loss relationship for the table energy loss function.
Further Information: The file is a CSV that defines the relationship between discharge and head loss for the table based energy loss formulation. It should not be used in combination with blockage or width files, otherwise double counting of energy losses may occur. It is typically used to represent head loss through a structure such as a bridge where the head loss relationship is known from field measurements or detailed CFD modelling. See the model construction chapter on hydraulic structures for more details and example file format.
|
|
|
Status: Conditional - Required when representing a bridge or other structure with sub grid scale energy losses..
Description: Configures energy loss structures such as bridges. Required when representing head loss within a structure block.
Further Information: Coefficient uses the Form Loss Coefficient command. Table uses the Energy Loss File command to define the head loss relationship.
|
|
|
Status: Optional.
Description: Tracer block command to control whether tracer concentration increases due to evaporation.
Further Information: When enabled, as water evaporates from the surface, the mass of tracer in the cell is conserved, resulting in an increase in tracer concentration. This can be used to simulate the concentration of salts or other constituents as water evaporates.
|
|
|
Status: Optional.
Description: An extension of the .fvc file used to house event definitions for simulation management. This allows event definitions to be stored in a separate file to the main simulation control file, which can help with organisation and clarity when using a large number of events for complex simulation management logic.
Further Information: Should be specified as the last command in the .fvc file.
|
|
|
Status: Optional.
Description: Outputs the result at the exact computational timestep.
Further Information: Set to 1 to write results at the exact computational timestep rather than the nearest available output time.
|
|
|
Status: Legacy.
Description: Specifies the directory containing external turbulence model definition files.
Further Information: If not specified, external turbulence model files must be located in the same directory as the simulation control file.
|
|
|
Status: Optional.
Description: Output block command to define the final output time of the model output. If not specified, uses the model End Time.
Further Information: The time value must be consistent with the selected simulation Time Format. Useful for debugging or developing high temporal resolution outputs for a specific period of interest within a longer simulation. Can be used in combination with the Start Output command to define a specific output window within the overall simulation period.
|
|
|
Status: Conditional - Required when using the Matrix or Timeseries Flux Function implementations.
Description: Specifies the hQh flux matrix or flow timeseries file used when the Matrix or Timeseries flux function is selected.
Further Information: Reads the file defining either a timeseries or an hQh relationship, depending on the selected Flux Function implementation. Detailed descriptions of the required file structure for each implementation are provided in the referenced 2D HD construction section below.
|
|
|
Status: Conditional.
Description: Modifies the flow condition using the following structure flux function types:
• NLSWE: No structure • Weir: Weir structure with RL weir crest elevation • Weir_dz: Weir structure with bed offset weir crest elevation • Culvert: Culvert structure • Porous: Permeable barrier • Matrix: User defined flow hQh relationship • Timeseries: User defined flow timeseries or pump • Wall: No flow
Further Information: Detailed descriptions of each flux function type and the required and optional commands associated with each are provided in the below model construction chapter on hydraulic structures.
|
|
|
Status: Conditional - Required when using the coefficient Energy Loss Function..
Description: Represents sub grid scale energy losses as a function of velocity head.
Further Information: Commonly used to model bridge or flow obstructions. Can be optionally used in combination with either Width File or Blockage File.
|
|
|
Status: Optional.
Description: Specifies gravitational acceleration for the selected unit system.
Further Information: Would not typically be modified from the default.
|
|
|
Status: Conditional - Required if using an unstructured mesh..
Description: Reads the mesh topology from a .2dm unstructured mesh file. This mesh may contain triangles, quadrilaterals, or a combination of these geometries. The mesh can optionally contain spatially varying bathymetric and material data.
Further Information: Only one Geometry 2d command and mesh can be used per simulation. If multiple are specified, the latter command takes precedence.
|
|
|
Status: Required.
Description: Sets the format of all output GIS files.
Further Information: Typically set to SHP to align with the TUFLOW Plugin workflow. Note that the format of an input layer is solely controlled by the file extension (i.e. .mif for the MIF format and .shp for the SHP format).
|
|
|
Status: Optional.
Description: Sets the error behavior when comparing input GIS layer projections with the model projection set by SHP Projection or MI Projection:
• ERROR: Will stop the simulation and report an error • WARNING: Will report a message to the GIS messages check file, but not stop simulation
Further Information: During model start-up, checks are completed by comparing each input GIS .shp layer projection with that specified by the SHP Projection or MI Projection command. If they are not equivalent, ERROR 0305 - Projection of .shp file is different to that specified by the SHP Projection == command. will result. This error typically occurs if trying to read a layer with a different coordinate system. However, if mixing layers created by differing GIS packages, slight differences in the text string format can result in ERROR 305 being reported despite there being no material difference in the projection string. In such cases, this command can be used to adjust the error reporting behaviour.
|
|
|
Status: Optional.
Description: Sets a spatially constant lower limit (zb_min) and upper limit (zb_max) to the model bathymetry. Model elevations below zb_min will be set to zb_min, and likewise model elevations above zb_max will be set to zb_max.
Further Information: This command is executed after all other bathymetry commands, and will overwrite any preceeding bathymetry below or above the zb_min or zb_max values. Can also be applied to specific material types (see Bed Elevation Limits).
|
|
|
Status: Required.
Navigation row for this command. Argument syntax depends on the selected implementation. Refer to the implementation specific rows immediately below.
|
|
|
Status: Conditional - Required if Bottom Drag Model == Manning.
Description: Set the global Manning’s ‘n’ bed roughness coefficient.
Further Information: None
|
|
|
Status: Conditional - Required if Bottom Drag Model == ks.
Description: Set the global Nikuradse bed roughness length.
Further Information: Can be overridden locally by Material specific values.
|
|
|
Status: Conditional - Required when using the Constant, Smagorinsky or Wu Momentum Mixing Model implementations..
Navigation row for this command. Argument syntax depends on the selected Momentum Mixing Model implementation. Refer to the implementation specific rows immediately below.
Further Information: This command is used by the Constant, Smagorinsky and Wu Momentum Mixing Model implementations. It is not required when Momentum Mixing Model == None. Can be locally overridden by Material specific values.
|
|
|
Status: Conditional - Required when Momentum Mixing Model == Constant.
Description: Sets the global value of horizontal eddy viscosity when Momentum Mixing Model == Constant.
Further Information: None
|
|
|
Status: Conditional - Required when Momentum Mixing Model == Smagorinsky.
Description: Sets the global value of the Smagorinsky eddy viscosity coefficient when Momentum Mixing Model == Smagorinsky.
Further Information: None
|
|
|
Status: Conditional - Required when Momentum Mixing Model == Wu.
Description: Sets the global value of the Wu eddy viscosity coefficient when Momentum Mixing Model == Wu.
Further Information: None
|
|
|
Status: Conditional - Required when using the Smagorinsky or Wu Momentum Mixing Model implementations..
Description: Applies global minimum and maximum limits to computed horizontal eddy viscosity.
Further Information: Can be used with the Smagorinsky and Wu Momentum Mixing Model implementations to apply global limits to the computed horizontal eddy viscosity. It is not used when Momentum Mixing Model == Constant.
|
|
|
Status: Conditional - Required when using the Constant, Smagorinsky or Elder Scalar Mixing Model implementations..
Navigation row for this command. Argument syntax depends on the selected Scalar Mixing Model implementation. Refer to the implementation specific rows immediately below.
Further Information: This command is used by the Constant, Smagorinsky and Elder Scalar Mixing Model implementations. It is not required when Scalar Mixing Model == None or Scalar Mixing Model == Warmup. Can be locally overridden by Material specific values.
|
|
|
Status: Conditional - Required when Scalar Mixing Model == Constant.
Description: Sets a global value of horizontal scalar diffusivity.
Further Information: None
|
|
|
Status: Conditional - Required when Scalar Mixing Model == Smagorinsky.
Description: Sets the global value of the Smagorinsky scalar diffusivity coefficient.
Further Information: None
|
|
|
Status: Conditional - Required when Scalar Mixing Model == Elder.
Description: Sets the global longitudinal and transverse Elder scalar diffusivity coefficients.
Further Information: None
|
|
|
Status: Optional.
Description: Applies global minimum and maximum limits to computed scalar diffusivity.
Further Information: Used with Smagorinsky and Elder scalar mixing model implementations that compute horizontal scalar diffusivity from the selected model coefficients or settings. Can be overridden locally by Material specific values. Not used if Scalar Mixing Model == None or Scalar Mixing Model == Warmup.
|
|
|
Status: Optional.
Description: Sets the global behaviour when boundary input data are extrapolated beyond their available time range.
Further Information: Used to control how the model responds when boundary input data are requested outside their available time range. Can be applied on a BC block basis using the Temporal Extrapolation Check command. If extrapolation occurs and Global Temporal Extrapolation Check == ERROR, the model will stop and report an error. If Global Temporal Extrapolation Check == WARNING, the model will continue to run and a message will be written to the log file.
|
|
|
Status: Optional.
Description: Sets a minimum and maximum limit on computed eddy viscosity.
Further Information: Used with Parametric, K-Epsilon, K-Omega or External vertical mixing models. It is not used when the vertical mixing model is Constant. Can be overridden locally by Material specific values.
|
|
|
Status: Optional.
Description: A user specified minimum limit on the calculated turbulent dissipation rate.
Further Information: None
|
|
|
Status: Optional.
Description: Applies global minimum and maximum limits to computed vertical scalar diffusivity for Parametric or External vertical mixing models.
Further Information: Used with Parametric or External vertical mixing models. It is not used when the vertical mixing model is Constant.
|
|
|
Status: Optional.
Description: A user specified minimum limit on the calculated turbulent kinetic energy when using the K-Epsilon or K-Omega vertical mixing models.
Further Information: None
|
|
|
Status: Conditional - Required when using gridded boundary condition input (Grid Definition File is a supported alternative)..
Description: Opens a grid definition block for user defined grid coordinates used by gridded boundary condition inputs.
Further Information: Used to define grid coordinates for gridded boundary inputs such as wind or atmospheric forcing. Not supported if the boundary condition grid requires a z dimension.
|
|
|
Status: Conditional - Required when using gridded boundary condition inputs (Grid Definition is a supported alternative)..
Description: Opens a grid definition file block and specifies the NetCDF file containing grid coordinates for gridded boundary conditions.
Further Information: Commands nested within this block can define the grid label, coordinate variable names, vertical coordinate type, and grid mapping options.
|
|
|
Status: Conditional - Required if using Grid Definition or Grid Definition File..
Description: Grid definition block command that assigns a name to the grid definition so it can be referenced by multiple boundary conditions later.
Further Information: None
|
|
|
Status: Conditional - Required when using gridded boundary condition inputs with user defined grid coordinates specified in a NetCDF file.
Description: If using the Grid Definition File option, this command specifies which variables should be read from the NetCDF to create the grid.
Further Information: Typically uses Easting and Northing or Longitude and Latitude variable names from the NetCDF grid definition file. The z_variable_name is only required if the grid definition file contains vertical coordinate information and the boundary condition requires a z dimension (e.g. a 3D QC_GRID boundary condition). If z_variable_name is not specified the boundary wil be applied as a depth averaged condition.
|
|
|
Status: Optional.
Description: Use the grid extent as a mask to reduce the calculation footprint of boundary updates. For example, if the computational mesh contains 40,000 cells and the boundary grid extent is cooincident with 1,000 of the cells, only process the 1,000 cells when reading and updating model boundary data.
Further Information: None
|
|
|
Status: Conditional - Required if using a structured mesh..
Description: Sets the x and y grid origin when using regular mesh specification.
Further Information: In meters for Cartesian metric models, feet for Cartesian US Customary models, or decimal degrees for Spherical models.
|
|
|
Status: Optional..
Description: Sets the grid rotation when using regular mesh specification.
Further Information: Units are in degrees anticlockwise from East. See the model construction chapter link below for instructive figures on angle convention and example syntax.
|
|
|
Status: Conditional - Required if using a structured mesh..
Description: Sets the x and y extent of the mesh when using regular mesh specification.
Further Information: This is the absolute extent of the grid, not the number of cells. For example a grid with 10 cells at 100 m cell size would have a size_x of 1000 m, not 10. Units are a function of the selected coordinate reference frame. In meters for Cartesian metric models, feet for Cartesian US Customary models, or decimal degrees for Spherical models.
|
|
|
Status: Optional.
Description: Sets the model default to compute the simulation using:
• CPU: Central Processing Unit • GPU: Central Processing Unit with Graphical Processing Unit acceleration
Further Information: This may be overwritten at runtime via command line argument switches: -cpu, -gpu, and -pu. Running on GPU requires a supported NVIDIA graphics card and access to TUFLOW FV’s GPU Module.
|
|
|
Status: Optional.
Description: Sets a reduction factor to scale between first and second order horizontal spatial reconstructions for depth, velocity and scalar model variable fields.
Further Information: This may be implemented to solve for depth/water level and velocity in 1st order whilst solving plume/constituents in 2nd order as they may exhibit high spatial gradients (or vice-versa). Set factors to 1.0 for full 2nd order reconstruction, or 0.0 for full 1st order reconstruction. Values between 0 and 1 will blend between the two orders of reconstruction. Ignored if using first order spatial reconstruction Spatial Order == 1,1.
|
|
|
Status: Optional.
Navigation row for this command. Argument syntax depends on the selected Momentum Mixing Model implementation. Refer to the implementation specific rows immediately below.
Further Information: This command applies material specific overrides to the global horizontal eddy viscosity settings. It is used by supported active implementations only and is not used when Momentum Mixing Model == None.
|
|
|
Status: Optional.
Description: Assigns a material specific constant horizontal eddy viscosity value. Overrides the global horizontal eddy viscosity value.
Further Information: None
|
|
|
Status: Optional.
Description: Assigns a material specific Smagorinsky horizontal eddy viscosity coefficient. Overrides the global horizontal eddy viscosity coefficient.
Further Information: None
|
|
|
Status: Optional.
Description: Assigns a material specific Wu horizontal eddy viscosity coefficient. Overrides the global horizontal eddy viscosity coefficient.
Further Information: None
|
|
|
Status: Optional.
Description: Assigns material specific minimum and maximum limits on horizontal eddy viscosity, overriding the corresponding global values.
Further Information: Used within a Material block to apply local minimum and maximum limits to computed horizontal eddy viscosity. Global value placeholders refer to the values set by the Global Horizontal Eddy Viscosity Limits command.
|
|
|
Status: Optional.
Description: Sets the Total Variation Diminishing (TVD) limiting scheme for second order horizontal spatial reconstruction:
• LCD: Limited Central Difference • MLG: Maximum Limited Gradient
Further Information: Ignored if using first order spatial reconstruction Spatial Order == 1, 1.
|
|
|
Status: Optional.
Navigation row for this command. Argument syntax depends on the selected Scalar Mixing Model implementation. Refer to the implementation specific rows immediately below.
Further Information: This command applies material specific overrides to the global horizontal scalar diffusivity settings. It is used by supported active implementations only and is not used when Scalar Mixing Model == None or Scalar Mixing Model == Warmup.
|
|
|
Status: Optional.
Description: Assigns a material specific constant horizontal scalar diffusivity value. Overrides the global horizontal scalar diffusivity value. Here the global value placeholder refers to the value set by the Global Horizontal Scalar Diffusivity command.
Further Information: None
|
|
|
Status: Optional.
Description: Assigns a material specific Smagorinsky horizontal scalar diffusivity coefficient. Overrides the global horizontal scalar diffusivity coefficient. Global value placeholder refers to the value set by the Global Horizontal Scalar Diffusivity command.
Further Information: None
|
|
|
Status: Optional.
Description: Assigns material specific longitudinal and transverse Elder scalar diffusivity coefficients. Overrides the global scalar diffusivity coefficients. Global value placeholders refer to the values set by the Global Horizontal Scalar Diffusivity command.
Further Information: None
|
|
|
Status: Optional.
Description: Assigns material specific horizontal scalar diffusivity limits, overriding the corresponding global values.
Further Information: Used within a Material block to apply local minimum and maximum limits to computed horizontal scalar diffusivity. Global value placeholders refer to the values set by the Global Horizontal Scalar Diffusivity Limits command.
|
|
|
Status: Optional.
Description: Enables use of conditional programming statement using event names.
Further Information: None
|
|
|
Status: Conditional - Required if using scenario based conditional programming..
Description: Controls which commands are to be applied depending on the scenario or combination of scenarios specified by the user.
Further Information: None
|
|
|
Status: Legacy.
Description: The inactive flag allows users to switch the cells with a given material ID off for the purposes of the hydrodynamic calculations. Can only be used for materials defined directly in the .2dm unstructured mesh file.
Further Information: None
|
|
|
Status: Optional.
Description: Reads commands from an include file as if they were listed directly in the simulation control file. Commonly used to group like commands together for improved control file navigation and structure.
Further Information: Can be used in any part of the main simulation control file (.fvc) body, but not within blocks such as Material, If Event, If Scenario, BC, Structure etc. Commands contained in the include file will be read as if they are listed in the .fvc file at the location they are read. The file extension for the include file can be .fvc or .txt, or any other extension as desired. The include file should be located in the same directory as the main simulation control file, or the file path should be specified. Provides the same functionality as the Read File command. Also see Section @(CF-CF-IF-3).
|
|
|
Status: Optional.
Description: Controls whether bed friction is included in the momentum equations. Used for analysis purposes to isolate the effects of bed friction on the modelled system, or to simulate an idealised fluid with no bed friction. Not recommended to modify for general use.
Further Information: None
|
|
|
Status: Optional.
Description: Controls whether Coriolis forcing is included in the momentum equations. Used for analysis purposes to isolate the effects of Coriolis forcing on the modelled system, or to simulate an idealised fluid with no Coriolis forcing. Not recommended to modify for general use.
Further Information: None
|
|
|
Status: Conditional - Required for water quality simulation, otherwise optional..
Description: Enables atmospheric heat exchange budget in temperature simulations.
Further Information: None
|
|
|
Status: Conditional - Required for water quality modelling, otherwise optional..
Description: Activates salinity simulation and optionally density coupling using active and baroclinic flags.
Further Information: None
|
|
|
Status: Optional.
Description: Activates sediment simulation and optionally density coupling using active and baroclinic flags.
Further Information: If sediment is included a Sediment Control File is also required to be specified.
|
|
|
Status: Optional.
Description: Controls whether Stokes mass transport is included in the momentum and mass equations when spectral wave boundary conditions are applied.
Further Information: Calculated for depths in deepwater and surfzone, if cells are between these depths the mass transport is interpolated between the deepwater and surfzone mass transport. Can be used in combination with the Surfzone Undertow Factor command to help with cross shore transport
|
|
|
Status: Conditional - Required for water quality modelling and atmospheric heat exchange, otherwise optional..
Description: Activates temperature simulation and optionally density coupling using active and baroclinic flags.
Further Information: If the active_switch is set to 1 and density_switch is set to 0 then temperature effectively is modelled as a passive tracer.
|
|
|
Status: Optional.
Description: Controls whether wind stress terms are included in the momentum and mass transport equations. Only relevant if wind is a specified input using the BC command. Used for analysis purposes to isolate the effects of wind forcing on the modelled system, or to simulate an idealised fluid with no wind forcing. Not recommended to modify for general use.
Further Information: None
|
|
|
Status: Optional.
Description: BC block command that allows the user to specify whether a water level boundary condition (WL or OBC variants) input data already includes an inverse barometer offset.
Further Information: Set to zero to have TUFLOW FV apply the inverse barometer correction to the boundary condition based on the local MSLP difference from the Reference MSLP. Set to 1 if the boundary condition input data already includes the inverse barometer correction. This is a BC block level command and can be set independently for each water level boundary condition.
|
|
|
Status: Optional.
Description: Used to specify spatially varying depth averaged initial water level, velocity and scalar fields. Can be used to apply initial conditoins to all 2D model cells or a subset.
Further Information: For example file format and syntax examples refer to the linked model construction sections below. This file will override previously defined initial conditions for the 2D cells selected by the initial condition file.
|
|
|
Status: Optional.
Description: Used to specify spatially varying initial water level, 3D velocity and 3D scalar fields. Can be used to apply initial conditions to all 3D model cells or a subset.
Further Information: For example file format and syntax examples refer to the linked model construction sections below. This file overrides previously defined initial conditions for the 3D cells selected by the initial condition file.
Typically it’s more common to generate 3D initial conditions from a restart file and warmup simulation period. This reduces the likelihood of spurious model behaviour due to imbalances in the initial conditions. However, this command can be used to apply 3D initial conditions directly if desired. |
|
|
Status: Optional.
Description: Sets the initial u and v velocity fields to zero when used in combination with the Initial Condition OGCM command.
Further Information: Used with Initial Condition OGCM to start from quiescent velocity while still reading water level and constituent fields from the OGCM source. Can be used to reduce the likihood of shocks being introduced into the model at startup due to imbalances between the initial water level and velocity fields.
|
|
|
Status: Optional.
Description: Uses OBC_GRID boundary data to assign initial water level, velocity, salinity, and temperature fields.
Further Information: Commonly used with ocean model inputs such as HYCOM to initialise water level, currents, salinity, and temperature. Typically the initial water level is not an absolute elevation but a mean sea level anomaly that is added to a pre-existing astronomical tidal boundary condition.
|
|
|
Status: Optional.
Description: Sets a spatially constant initial salinity across the model domain.
Further Information: None
|
|
|
Status: Optional.
Description: Used to assign spatially constant but depth varying 3D initial condition profiles.
Further Information: Example file format and syntax can be found in the linked model construction sections below.
|
|
|
Status: Optional.
Description: Sets a spatially constant suspended sediment concentration for each simulated sediment fraction. This value is also constant for all water depths.
Further Information: None
|
|
|
Status: Optional.
Description: Sets a spatially constant initial water temperature for all water depths.
Further Information: None
|
|
|
Status: Optional.
Description: Sets a spatially constant tracer concentration for each simulated tracer. This value is also constant for all water depths.
Further Information: None
|
|
|
Status: Optional.
Description: Sets the initial, quiescent water level to a global user specified value.
Further Information: None
|
|
|
Status: Optional.
Description: Sets spatially constant initial concentrations for each simulated water quality constituent.
Further Information: The number of required arguments depends on the number of water quality constituents being simulated. Refer to linked model construction sections below for further information. The alias Initial Water Quality Concentration is also supported.
|
|
|
Status: Optional.
Description: Selects the internal wave mixing formulation used to represent mixing below the thermocline or halocline.
Further Information: Optionally extends the K-Epsilon and K-Omega Vertical Mixing Model.
|
|
|
Status: Optional.
Description: Sets the input parameters for the Internal Wave Mixing Model.
Further Information: Use this command to define the coefficients for the selected internal wave mixing formulation. Parameter meaning depends on the internal wave mixing model in use.
|
|
|
Status: Optional.
Description: Specifies the background water kinematic viscosity.
Further Information: This value is used as a lower limit in the parametric vertical eddy viscosity and is also used in various formulae within the Sediment Transport and Particle Tracking Modules.
|
|
|
Status: Optional.
Description: Selects the vapour pressure and specific humidity model.
Further Information: • Model 1 uses the Magnus-Tetens formulation and requires air temperature and relative humidity inputs.
• Model 2 uses modified Lowe and Reed equations and requires air temperature and cloud cover inputs. The TUFLOW FV Get Atmos tool can be used to generate the required meteorological input files for Latent Heat Model == 1. |
|
|
Status: Conditional - Required if Spherical == 0.
Description: Sets the latitude for Coriolis calculations when a cartesian coordinate system is used.
Further Information: Negative values for the southern hemisphere and positive values for the northern hemisphere. Not required if using a spherical coordinate system Spherical == 1, as the latitude is inferred from the spatial location of each cell.
If spatially varying Coriolis forcing is required it is recommended to use the spherical (metric units) coordinate reference frame. |
|
|
Status: Conditional - Required for the 3D simulation class.
Description: Specifies the CSV file containing the vertical face distribution used by the selected vertical mesh type.
Further Information: The file format is a function of the selected Vertical Mesh Type. Refer to the linked model construction sections below for example file formats and syntax.
|
|
|
Status: Optional.
Description: Sets the model log directory.
Further Information: This command specifies the directory for TUFLOW FV simulation log file (.log) output. A log file is automatically generated for each simulation, the contents of which are the same as that displayed in the simulation window. The log filename has the same prefix as the simulation control file.
If not specified, the log file is written either beside the simulation control file or to the runs\log sub-directory if that folder exists. CFL diagnostic files, geometry diagnostics and restart files are also written to the specified log directory. |
|
|
Status: Optional.
Description: Sets the local longwave radiation albedo (reflectivity).
Further Information: None
|
|
|
Status: Optional.
Description: Selects the longwave radiation heat transfer implementation. Available options are:
• 1 Net. Uses net downward longwave radiation and accounts for incident and emitted longwave radiation at the water surface. Requires net downward longwave radiation.• 2 Incident Direct. Uses specified incident longwave radiation with albedo reflection and emitted longwave radiation from the water surface based on the Stefan-Boltzmann law. Requires incident downward longwave radiation.• 3 Incident TVA. Calculates incident longwave radiation from air temperature and cloud cover using the TVA (1972) approach. Requires cloud cover and air temperature.• 4 Incident Zillman. Calculates incident longwave radiation using a latitudinal cloud correction and computes emitted longwave radiation using the air water temperature difference following Zillman (1972). Requires cloud cover and air temperature.• 5 Incident Chapra. Calculates incident longwave radiation from air temperature and vapour pressure following Chapra (2008). Requires air temperature and relative humidity.
Further Information: None
|
|
|
Status: Required.
Description: Instantiates a material block for a given material ID.
Further Information: Defines a Material block used to assign local properties to one or more material IDs. See the model construction section links below for example syntax and file formats for the commands that can be used within a Material block.
|
|
|
Status: Optional.
Description: Scale factor that multiplies the control value change over a control update timestep. Reduces the maximum change in control value over a control update timestep to improve numerical stability when simulating rapidly changing structure operations.
Further Information: Should be a number between 0.01 and 1.0. Not used for the trigger control type.
|
|
|
Status: Conditional - Required for some structures using the Linked Zones connection type when the maximum effective flow width cannot be inferred from other structure inputs..
Description: Used for structures with the Linked Zones connection type when flux limiting requires a maximum effective flow width. Not required for culverts where width is calculated from structure geometry or defined by other structure specific inputs.
Further Information: Not required for culverts.
|
|
|
Status: Conditional - Required if reading Mapinfo .mif file layers or if using GIS Format == MIF.
Description: Defines a Mapinfo Interchange Format (MIF) projection string or .mif file that sets the geographical coordinate system for all input and output Mapinfo .mif GIS layers.
Further Information: Sets the geographic projection for all GIS input and output in MID/MIF format. If this command is omitted, TUFLOW FV searches for a file “Header.mif” in each folder it opens GIS files and extracts the projection from this file. The “Header.mif” file can be any GIS layer in the correct projection exported in MID/MIF format. If no “Header.mif” file is found, non-earth coordinates are assumed.
Alternatively, a projection line extracted from a .mif file may be entered, although specifying a .mif file is the recommended approach. Example: MI Projection == .._Projection.mif MI Projection == CoordSys Earth Projection 8, 13, “m”, 153, 0, 0.9996, 500000, 10000000 Bounds (-7745874.38492, 1999.40969607) (8745874.38492, 19998000.5903) All MID/MIF GIS layers read by TUFLOW FV must use this projection. |
|
|
Status: Optional.
Description: Sets a minimum allowable bottom layer thickness to improve numerical robustness in shallow bottom cells. Not applicable to the sigma vertical mesh type.
Further Information: During model preprocessing, if the thickness of the bottom 3D layer is less than the specified value, the bottom layer is merged with the layer above it to create a thicker bottom layer.
|
|
|
Status: Optional.
Description: Controls whether the mode splitting approach is enabled for 2D simulations. Not applicable for 3D simulations.
Further Information: Can be disabled to improve runtime efficiencies for 2D simulations where the internal and external timestep are similarly restrictive.
|
|
|
Status: Optional.
Description: Used to set the default event(s).
Further Information: In practice these defaults are typically overridden at runtime using the -e1, -e2, …, -e9 command line argument to specify which events are active for a given simulation run.
Up to nine events can be specified for a given simulation. Model events are separated using the | character. |
|
|
Status: Optional.
Description: Used to set the default scenario(s).
Further Information: In practice these defaults are typically overridden at runtime using the -s1, -s2, …, -s9 command line argument to specify which scenarios are active for a given simulation run.
Up to nine scenarios can be specified for a given simulation. Model scenarios are separated using the | character. |
|
|
Status: Required - An alternative to the default None model should be specified for general use..
Description: Selects the horizontal eddy viscosity mixing model.
Further Information: Available options are:
• None. No supporting commands are required. • Constant. Uses a user specified constant horizontal eddy viscosity. • Smagorinsky. Uses the Smagorinsky horizontal eddy viscosity model. • Wu. Uses the Wu horizontal eddy viscosity model. The Global Horizontal Eddy Viscosity command is used in combination with this command to specify the constant horizontal eddy viscosity value or coefficient. |
|
|
Status: Optional.
Description: Structure block command that assigns a name to the structure for identification in CSV outputs and log files.
Further Information: If not specified, the structure will be assigned a default name based on the structure type and an incremental number, for example Structure_1, Structure_2, etc.
|
|
|
Status: Conditional - Required when modelling a pump with Flux Function == Timeseries.
Description: Disables structure flux limit checks.
Further Information: Set to
0 to disable the non linear shallow water equation flux limiter.
|
|
|
Status: Legacy.
Description: Superseded by Read GIS Nodestring.
Further Information: None
|
|
|
Status: Required.
Description: Specifies the number of tracers to be simulated.
Further Information: Up to 100 tracers can be specified.
|
|
|
Status: Required.
Description: Defines the beginning of the output block and the result output format. Each output block configures one result output type or file format and is closed using End Output.
Available output_type options include:• NetCDF, XMDF, Datv. Mesh output formats for spatial results written across the full model mesh.• Points. CSV timeseries at defined point locations.• Profile. CSV timeseries through the water column at defined profile locations.• Flux. CSV timeseries of net flow across nodestrings or monitoring polylines.• Structflux. CSV timeseries of flow through hydraulic structures.• Massbalance. CSV balance diagnostics for simulated quantities.• Mass. CSV output of global water volume, mass, and related diagnostics.• Transport. Hydrodynamic transport forcing output for reuse in other simulations.
Further Information: Example syntax and file formats for the various output types can be found in the linked model construction sections below.
|
|
|
Status: Optional.
Description: Controls whether internal and external CFL diagnostic CSV files are written to the log directory.
Further Information: Set to 0 to disable output of internal and external CFL diagnostic CSV files to the log directory. These files contain the CFL number for each computational cell at each model timestep and can be used to identify where and when CFL conditions are most restrictive in the model. The internal CFL diagnostic file is named “CFL_internal.csv” and the external CFL diagnostic file is named “CFL_external.csv”.
|
|
|
Status: Optional.
Description: Output block command to enable or disable file compression for NetCDF output format used for mesh, transport and profile output implementations.
Further Information: Reduces NetCDF file size by typically 20-30% when enabled. This does affect run times and can result in a performance penalty of between 5-10% depending on the specific application and computing resources. If runtime performance is critical, it is recommended to experiment with this setting. Compression is not available for XMDF or Datv output formats.
|
|
|
Status: Required - The default (.fvc directory) should be overridden for general use..
Description: Defines the directory where model results are saved.
Further Information: By default model output is written to the same location as the simulation control file (.fvc) however this is typically not desired and it is recommended to specify an output directory using this command. Output Folder == is an alias for this command and is also supported.
|
|
|
Status: Required - The default (0.0) should be overridden for general use..
Description: BC block command that defines the simulation time interval at which results are saved. If not specified, results are output at the model computational timestep.
Further Information: By default, results are output at the model computational timestep which for many applications will not be desired and will lead to extremely large output files. It is typically more appropriate to specify an output interval of 10min (600s) or 30min (1800s) for hydrodynamic outputs, although the optimal output interval will depend on the specific application and the desired temporal resolution of results.
If the model result output interval is less than the model timestep an error will be reported and the model execution ceased. |
|
|
Status: Conditional - Required for points, profiles and mesh model output implementations.
Description: BC command that selects the model output parameters to be included in the output files.
Further Information: A wide range of output parameters are available for selection. For example: water level, velocity, vertical velocity, salinity, temperature, sediment concentration, tracer concentration, water quality constituent concentration, etc. Refer to the linked model construction sections below for tabulated output parameter options with descriptions and units.
|
|
|
Status: Legacy.
Description: Superseded by Read GIS PO
Further Information: None
|
|
|
Status: Optional.
Description: Output block command to track minimum or maximum map output parameters on a user specifed Output Statistics dt.
Further Information: This feature is available with Datv, XMDF, and NetCDF output types. Either min, max or both min and max and one or both can be specified via a comma separated list. Will track all output parameters specified by the Output Parameters command for the specified output block.
|
|
|
Status: Optional.
Description: Sets the interval to track map output statistics.
Further Information: The default of 0.0 uses the model computational timestep.
|
|
|
Status: Conditional - Required if using the particle tracking simulation class.
Description: Specifies the particle tracking control file used to configure the particle tracking simulation.
Further Information: None
|
|
|
Status: Optional.
Description: Scenario or event block command that cause the model to pause with a user specified message.
Further Information: The Pause command is typically used as a catch point if an unexpected scenario or event is specified during a simulation.
|
|
|
Status: Legacy.
Description: Superseeded by Read GIS Zone.
Further Information: None
|
|
|
Status: Conditional - Required for hydraulic structure implementations and some destratification unit implementations to define the applicable properties for the selected implementation. See description for details..
Navigation row for this command. Argument syntax depends on the selected implementation. Use the applicable implementation entry below:
• Weir. Required when Flux Function == Weir. • Weir_dz. Required when Flux Function == Weir_dz. • Porous. Required when Flux Function == Porous. • Bubbler. Required when Destratification Unit == Bubbler. • Compressor. Required when Destratification Unit == Compressor. |
|
|
Status: Conditional - Required if Flux Function == Weir.
Description: Structure block command that sets the hydraulic properties for the weir structure. The parameter definitions are:
• H {No default} Weir crest elevation (mRL or ftRL) • C {1.705} Weir discharge coefficient • Ex {1.5} Weir exponent • a {8.55} Weir submergence exponent • b {0.556} Weir submergence exponent • Csf_min {0.7} Submergence factor minimum value • B_user {Nodestring width or Max Open Width} User defined weir width (m or ft)
Further Information: This implementation uses an absolute crest elevation for the weir. For full description of the weir implementation and arguments refer to linked model construction sections below and hydraulics structure science documentation.
The optional user defined weir width B_user argument can be used to override the default width calculated from the structure geometry. This can be useful for representing flow through a partially open gate, for example. It is not available if using the single nodestring structure connection type is used Structure == Nodestring, nodestring_id. The default B_user is the average nodestring length if using Linked Nodestrings or Max Open Width if using the Linked Zones connection type. |
|
|
Status: Conditional - Required if Flux Function == Weir_dz.
Description: Structure block command that sets the hydraulic properties for the weir structure. The parameter definitions are:
• dZ {No default} Weir crest elevation offset (mRL or ftRL) • C {1.705} Weir discharge coefficient • Ex {1.5} Weir exponent • a {8.55} Weir submergence exponent • b {0.556} Weir submergence exponent • Csf_min {0.7} Submergence factor minimum value
Further Information: This implementation uses a crest elevation offset above the existing bed elevation. For a full description of the arguments, refer to the linked model construction sections below and the hydraulic structure science documentation.
The user defined width override is not available for this weir implementation. |
|
|
Status: Conditional - Required if Destratification Unit == Bubbler.
Description: Structure block command that sets the properties for the bubble plume,
bubbler destratification unit option. The parameter definitions are:• Z {No default} Pipe Elevation (mRL) • F {No default} Airflow at diffuser head (m^3/s/plume) • N {No default} Number of plumes • alpha {No default} Calculation coefficient (recommended 0.0833) • b1 {No default} Calculation coefficient (recommended 4.7) • Lr {No default} Calculation coefficient (recommended 0.1) • Gamma {No default} Detrainment coefficient (recommended 0.95)
Further Information: Use this implementation for bubbler destratification units. For a full description of the arguments refer to linked model construction sections below and hydraulics structure science documentation.
|
|
|
Status: Conditional - Required if Destratification Unit == Compressor.
Description: Structure block command that sets the properties for the bubble plume,
compressor destratification unit option. The parameter definitions are:• Z {no default} Pipe Elevation (mRL) • F {no default} Airflow at atmospheric pressure (m^3/s/plume) • N {no default} Number of plumes • alpha {no default} Calculation coefficient (recommended 0.0833) • b1 {no default} Calculation coefficient (recommended 4.7) • Lr {no default} Calculation coefficient (recommended 0.1) • Gamma {no default} Detrainment coefficient (recommended 0.95)
Further Information: Use this implementation for compressor destratification units. For a full description of the arguments refer to linked model construction sections below and hydraulics structure science documentation.
|
|
|
Description: Structure block command that sets the hydraulic properties for the porous structure. The parameter definitions are:
• K {No default} Hydraulic conductivity (m/s) • flowpath_length {No default} Effective flowpath length through the porous structure (m) • B_user {Nodestring width or Max Open Width} User defined structure cross sectional width (m)
Further Information: Use this implementation to define porous structure resistance and effective flowpath geometry. The structure width override is not supported for single nodestring structure connection types.
|
|
|
Status: Optional.
Description: Alias for Include
Further Information: None
|
|
|
Status: Optional.
Description: Spatially vary cell materials using a GIS layer of polygons.
Further Information: Reads a
2d_mat polygon layer in shp or mif format and assigns material IDs to cells within each polygon. Multiple Read GIS Mat commands can be used. If polygons overlap the material ID from the last layer read is applied in the overlap area.Attribute(s): • Material: The material ID to be assigned to cells within the polygon. |
|
|
Status: Conditional - Required for nodestring boundary condition types, nodestring and linked nodestring hydraulic structure types, and for user-specified flux output reporting..
Description: Defines the location of model nodestrings.
Further Information: Reads a
2d_ns polyline layer in shp or mif format and defines model nodestring locations. Line direction is important for sign convention and for some connection types. Multiple Read GIS Nodestring commands can be used to read multiple layers.Attribute(s): • ID: The nodestring name or ID. This is used to link the nodestring to boundary conditions, structures, and output reporting. This ID must be independent or an error will occur. • Flags: Setting to BD will enforce the nodestring algorithm to follow the edge of the model mesh, treating the nodestring as an open boundary condition. Nodestrings may overlap if being used for flux reporting. They may not overlap if being used as open boundary or hydraulic structure connections. |
|
|
Status: Conditional - Required for points model output.
Description: Output block command to define the GIS layer containing the output point locations for points model output.
Further Information: Reads a
3d_po point layer in shp or mif format and defines the locations used by points output. The layer includes point naming attributes and optional vertical averaging overrides for 3D applications.Attribute(s): • Type: Reserved for future use (Not used) • Label: Name of the point • Comment: Optional comment for the point • Vert_min: 3D Vertical averaging override. Not applicable to the 2D HD simulation class. • Vert_max: 3D Vertical averaging override. Not applicable to the 2D HD simulation class. |
|
|
Status: Conditional - Required for point, profile or polygon boundary conditions.
Description: Required to define the location of boundary cells. Point geometry is required for single cell boundary types, polygon geometry for polygon (_POLY) boundary types.
Further Information: Reads a
2d_sa layer in shp or mif format and defines boundary condition locations. Use point geometry for single cell boundary types and polygon geometry for polygon boundary types.Attribute(s): • Name: The name or ID of the boundary condition. This is used to link the GIS features to boundary conditions defined in the model. |
|
|
Status: Optional.
Description: Reads GIS files containing polylines and points that are treated as breaklines in the model’s bathymetry.
Further Information: Reads a
2d_zln line and point layer in shp or mif format and updates bathymetry as a 3D breakline(s). A single polyline layer is required followed by one or more point layers. Thes are associated using the | syntax. If points are snapped to the polyline vertices the breakline can vary in height along its length and elevations are interpolated between snapped points. If no points are snapped to the line the breakline is treated as horizontal using the line Elevation value. Up to nine point layers can be specified on one command line.Attribute(s): • Elevation: The polyline or point elevation (mRL or ftRL). |
|
|
Status: Conditional - Required for Zone and Linked Zone hydraulic structure connections..
Description: Reads zone polygons used to define linked zone and zone hydraulic structure connections.
Further Information: Reads a
2d_zn polygon layer in shp or mif format and defines the spatial extents used by linked zone and zone hydraulic structure connections. Each polygon is identified by name and linked to the relevant structure connection definition. For linked zones use separate upstream and downstream polygons. For zone connections use a single polygon.Attributes: • Name: The zone name or ID used to link the polygon to the hydraulic structure definition. |
|
|
Status: Optional.
Description: Updates cell centre elevations via a Digital Elevation Model (DEM) file.
Further Information: Supports ESRI ArcGrid (.asc) or binary float (.flt) formats.
|
|
|
Status: Optional.
Description: Updates selected cell centre elevations via a Triangulated Irregular Network (TIN) file.
Further Information: Supports Aquaveo SMS TIN (.tin) format.
|
|
|
Status: Optional.
Description: Sets the reference water density used in baroclinic pressure calculations.
Further Information: Should not be changed from the default value for typical applications. For baroclinic simulations, where density may vary locally based on salinity, temperature or suspended sediment concentration, this value is used as the baseline from which density gradients are calculated. Numerical accuracy of baroclinic simulations can be marginally improved by setting this value close to a typical value expected in the model, for example 1027 kg/m^3 for ocean simulations. For non-baroclinic simulations this command will globally set the density used in various source term and sediment transport formulae.
|
|
|
Status: Optional.
Description: Sets the reference mean sea level pressure value.
Further Information: This value is used in the atmosphere module when a mean sea level pressure boundary condition has not been explicitly specified. The global MSLP value is used in various atmosphere module heat exchange routines. Used for inverse barometer correction with Includes MSLP.
|
|
|
Status: Optional.
Description: Sets the model reference salinity for baroclinic simulations.
Further Information: Numerical accuracy of baroclinic terms in NLSWE can be marginally improved by setting this value close to a typical value expected in the model, for example 35.0 psu for ocean simulations. For non-baroclinic simulations this command will globally set the salinity. It may also be used to globally initialise salinity in the absence of other relevant initial conditions.
|
|
|
Status: Optional.
Description: Sets the model reference temperature for baroclinic simulations.
Further Information: Numerical accuracy of baroclinic terms can be marginally improved by setting this value close to a typical value expected in the model. For non-baroclinic simulations this command will globally set the temperature. It may also be used to globally initialise temperature in the absence of other relevant initial conditions.
|
|
|
Status: Optional.
Description: Sets the simulation reference time used for time based inputs and outputs. This is the time datum used for all time based inputs and outputs including boundary condition time series, structure operation time series, and output timestamps.
Further Information: Sets the time datum used for time based inputs and outputs. When Time Format is HOURS the default reference time is
0. When Time Format is ISODATE the default reference time is 01/01/1990 00:00:00.
|
|
|
Status: Optional.
Description: Adjusts the response rate of the control structure as a function of positively or negatively trending sample parameter value.
Further Information: For use with the Timeseries or Sample_Rule control types. Typically used in conjunction with the Control Parameter == Bathy_Control and Bed Adjust == Bathy_Database.
|
|
|
Status: Optional.
Description: Used to initialise salinity, temperature, suspended sediment, tracer and wq constituent fields from a prior simulation.
Further Information: Unless Use Restart File Time is specified, the simulation start time is set from the timestamp stored in the restart file. Restart is also supported.
|
|
|
Status: Optional.
Description: Controls whether each new restart write overwrites the previous restart file or creates a separate file.
Further Information: Set to
1 to overwrite the same restart file at each write interval. Set to 0 to write a new restart file at each restart output time.
|
|
|
Status: Conditional - Required for trigger, sample, sample_rule and target_rule control types..
Description: Control block command that sets the frequency in hours for sampling the sample parameter from the model.
Further Information: Used for the trigger, sample, sample_rule and target_rule control types.
|
|
|
Status: Conditional - Required for trigger, sample, sample_rule and target_rule control types..
Description: Defines the model parameter sampled for structure control.
Further Information: Used with trigger, sample, sample_rule and target_rule control types.
Supported Sample Parameters are as follows. • Sample Nodestring: FLOW • Sample Point: WL, V, SAL, TEMP, SED_1, …, SED_N, TR_1, …, TR_N, WQ_1, …, WQ_N, DOSAT |
|
|
Status: Conditional - Optionally used for trigger, sample, sample_rule and target_rule control types. If not used Sample Nodestring is required..
Description: Control block command that defines the point location used to sample the Sample Parameter.
Further Information: This feature does not have GIS integration and requires manual entry of point coordinates.
|
|
|
Status: Conditional - Optionally used for trigger, sample, sample_rule and target_rule control types. If not used Sample Point is required..
Description: Control block command that defines the nodestring location used to sample the Sample Parameter.
Further Information: None
|
|
|
Status: Required for AD simulation class.
Description: Selects the horizontal scalar mixing model implementation.
Further Information: Related commands depend on the selected scalar mixing implementation. If None or Warmup is selected no supporting scalar diffusivity commands are required. For Constant, Elder and Smagorinsky refer to the Global Horizontal Scalar Diffusivity navigation row and the associated implementation entries below.
|
|
|
Status: Optional.
Description: The simulation time (model time) interval for displaying timestep information to the log file and terminal window.
Further Information: Sets the interval for reporting timestep information to the screen and log output during a simulation. Display dt is also supported.
|
|
|
Status: Optional.
Description: Selects the second order vertical turbulence closure used for vertical momentum and scalar mixing.
Further Information: See the vertical mixing model science documentation for details on the available second order vertical mixing model options.
|
|
|
Status: Optional.
Description: Selects the parameter group used by the second order vertical turbulence closure.
Further Information: See the vertical mixing model science documentation for details on the available second order vertical mixing model parameter group options. This command is only relevant if a second order vertical mixing model is selected.
|
|
|
Status: Optional.
Description: Sets fallback suspended sediment boundary values when specified suspended sediment headers are not found.
Further Information: Sets fallback suspended sediment values to use when expected sediment headers are not found in the boundary input data file.
|
|
|
Status: Conditional - Required for the sediment transport simulation class..
Description: Maps suspended sediment input headers in the boundary data file to simulated suspended sediment fields.
Further Information: Maps suspended sediment fields in the boundary input file to the sediment classes used in the simulation. The number of headers should match the number of simulated sediment classes.
|
|
|
Status: Optional.
Description: Applies additive offsets to suspended sediment boundary inputs.
Further Information: Offsets are applied after BC Scale factors and to the scaled sediment boundary inputs.
|
|
|
Status: Optional.
Description: Applies multiplicative scale factors to suspended sediment boundary inputs.
Further Information: Applies multiplicative scale factors to suspended sediment boundary inputs before any offsets are applied.
|
|
|
Status: Conditional - Required for the sediment transport simulation class.
Description: Specifies the sediment control file used to configure the sediment simulation.
Further Information: Specifies the sediment control file used to configure the sediment transport simulation. The configuration of commands within the sediment control file is outside the scope of this manual. Please refer to the Sediment Transport and Particle Tracking User Manual for details on the available commands and configuration options.
|
|
|
Status: Optional.
Description: Sets all material in the domain to a single user specified value.
Further Information: Sets all cells in the domain to the specified material ID. The value should correspond to a defined Material block or other supported material assignment workflow.
Typically used to set the default material type which is subsequently overridden by more spatially specific material assignment via the Read GIS Mat command. |
|
|
Status: Optional.
Description: Assigns a user specified value to a variable for dynamic substitution in other commands.
Further Information: Defines a named variable that can be reused for dynamic substitution in other commands or included files. Refer to examples within the simulation management chapter for usage guidance.
|
|
|
Status: Optional.
Description: Sets all elevations in the domain to a user specified value.
Further Information: Sets all cell elevations in the domain to the specified value. This is typically used for simple test models or as a base elevation before applying other bathymetry updates.
|
|
|
Status: Conditional - Required for the settling tracer model implementation.
Description: Specifies settling velocity for tracers in the active tracer block.
Further Information: None
|
|
|
Status: Optional.
Description: Sets the local shortwave radiation albedo (reflectivity).
Further Information: Sets the shortwave radiation albedo used to represent reflected incoming shortwave radiation at the water surface.
|
|
|
Status: Optional.
Description: Sets the proportion of shortwave radiation that is absorbed by the sediment and water column.
Further Information: The default values specify that 45% of the shortwave radiation heat is absorbed into the sediment and 45% is radiated into the water column (this implies that 10% is reflected off the bed). This reflected shortwave radiation is absorbed in the water column as it reflects back towards the surface. Anything remaining will then leave the water column back into the atmosphere.
|
|
|
Status: Optional.
Description: Sets the extinction coefficient for each shortwave radiation fraction (PAR, UVA, UVB and NIR).
Further Information: • nir_eta: Extinction coefficient of near-infrared (NIR) in short wave radiation.
• par_eta: Extinction coefficient of photosynthetically active radiation (PAR) in short wave radiation. • uva_eta: Extinction coefficient of ultraviolet A (UVA) in short wave radiation. • uvb_eta: Extinction coefficient of ultraviolet B (UVB) in short wave radiation. |
|
|
Status: Optional.
Description: Sets the fraction of total incoming shortwave radiation into Photosynthetically Active Radiation (PAR), Ultraviolet A (UVA), Ultraviolet B (UVB) and Near Infrared (NIR), in that order.
Further Information: Sets how total incoming shortwave radiation is partitioned into the NIR, PAR, UVA, and UVB bands. The fractions should sum to
1.0.
|
|
|
Status: Optional.
Description: Selects the shortwave radiation implementation.
Further Information: 1 = Incident short wave radiation estimated according to Jacquet (1983). Requires downward short wave radiation input. Positive is downwards.
2 = Incident short wave radiation under clear sky estimated according to Zillman (1972) with cloud cover correction factor given by Reed (1977). Requires air temperature, relative humitidy (%) and optionally cloud cover inputs (fraction 0.0-1.0), where 0.0 is no cloud and 1.0 is full cloud. If cloud is not specified a clear sky with no cloud correction is assumed. |
|
|
Status: Optional.
Description: Sets sediment dependent extinction modifiers for the PAR, UVA, UVB, and NIR shortwave radiation bands.
Further Information: Sets sediment dependent extinction modifiers for the NIR, PAR, UVA, and UVB shortwave radiation bands, in that order.
|
|
|
Status: Conditional - Required if reading ESRI shape file layers or if GIS Format == SHP.
Description: Defines an ESRI shapefile projection string or .shp file that sets the geographical coordinate system for all input and output ESRI .shp GIS layers.
Further Information: Sets the shapefile projection used for input checking and output GIS layers in ESRI
.shp format. If a model uses both .shp and .mif layers, specify both SHP Projection and MI Projection.Example using a .prj file: SHP Projection == ...prj Example using a PROJ string: SHP Projection == PROJCS[“WGS_1984_UTM_Zone_60S”,GEOGCS[“GCS_WGS_1984”,DATUM[“D_WGS_1984”,SPHEROID[“W GS_1984”,6378137,298.257223563]],PRIMEM[“Greenwich”,0],UNIT[“Degree”,0.017453292519 943295]],PROJECTION[“Transverse_Mercator”],PARAMETER[“latitude_of_origin”,0],PARAME TER[“central_meridian”,177],PARAMETER[“scale_factor”,0.9996],PARAMETER[“false_easti ng”,500000],PARAMETER[“false_northing”,10000000],UNIT[“Meter”,1]] |
|
|
Status: Optional.
Description: Sets the snapping tolerance used when associating specified GIS lines with points.
Further Information: Used to adjust the snapping tolerance applied when pairing Read GIS Z Line polylines with associated point layers.
|
|
|
Status: Optional.
Description: Sets the spatial reconstruction to first or second order.
Further Information: Specifies the spatial order of accuracy of the solution schemes used in the simulation:
1 = first order scheme 2 = second order scheme The first-order schemes assume a piecewise constant value of the modelled variables in each cell, whereas the second-order schemes perform a linear reconstruction. Higher order spatial schemes will produce more accurate results in the vicinity of sharp gradients; however, they will be more prone to developing instabilities and are more computationally expensive. Generally, initial model development should be undertaken using low-order schemes, with higher-order spatial schemes tested during the latter stages of development. If a significant difference is observed between low-order and high-order results then the high-order solution is probably necessary, or alternatively further mesh refinement is required. Second order spatial accuracy will typically be required in the vertical direction when trying to resolve sharp stratification. See also the horizontal gradient limiter and vertical gradient limiter commands, which may be used to specify the Total Variation Diminishing (TVD) limiting schemes employed during the higher-order reconstructions. When running in second order the Horizontal AlphaR and Vertical AlphaR horizontal and vertical gradient reduction factor commands may be of use for regions of high spatial gradients or to assist with improving model stability. |
|
|
Status: Optional.
Description: Material block command used to revert an area to first order calculations where the model is otherwise a second order model. If a first order model is being used then this flag will have no effect.
Further Information: Options: 0 = False (i.e. no higher order reconstruction)
1 = True (i.e. higher order reconstruction) |
|
|
Status: Optional.
Description: Specifies the specific heat capacity of air.
Further Information: Used to calculate atmospheric heat exchange source terms. The specific heat capacity value will be calculated internally when the Kondo wind stress model is specified.
|
|
|
Status: Optional.
Description: Specifies the specific heat capacity of water.
Further Information: Used to calculate atmospheric heat exchange source terms. The specific heat capacity value will be calculated internally when the Kondo wind stress model is specified.
|
|
|
Status: Optional.
Description: Defines the computational coordinate system as Cartesian or Spherical.
Further Information: • 0 = Cartesian where geometry inputs and horizontal coordinates are in metres or feet depending on the selected units.
• 1 = Spherical where geometry inputs and horizontal coordinates are in decimal degrees. For Cartesian models (Spherical == 0) a representative latitude should be set using the Latitude command. If Coriolis forcing is likely to be important, Spherical coordinates are recommended. |
|
|
Status: Optional.
Description: Set a user specified maximum water level and maximum velocity which may indicate an unstable model. The simulation will stop if these limits are exceeded.
Further Information: None
|
|
|
Status: Optional.
Description: Control block command that sets the initial value of the control parameter. For example to set a gate to closed or open at the start of the simulation.
Further Information: Not used for the Trigger control type. Not used for the Timeseries control type unless the Response Function command is used in combination with Timeseries.
|
|
|
Status: Optional.
Description: Output block command that defines the start time of the model output. If not specified, uses the model Start Time.
Further Information: Useful for isolating specific time periods of interest in the model output for example to output high frequency results during a storm event but not for the entire simulation. The input format must be consistent with the selected Time Format. For Time Format == Hours the value is specified in decimal hours. For Time Format == ISODate the value is specified as
dd/mm/yyyy HH:MM:SS.
|
|
|
Status: Required.
Description: Specifies the start time for the simulation in the selected Time Format.
Further Information: For Time Format == Hours the value is specified in decimal hours. For Time Format == ISODate the value is specified as
dd/mm/yyyy HH:MM:SS.
|
|
|
Status: Optional.
Description: Sets scalar specific factors used to scale Stokes drift transport.
Further Information: Provide one scalar specific multiplier for each simulated scalar constituent (salinity, temperature, tracers, suspended sediment and water quality constituents). Values greater than
1 increase Stokes drift transport for that constituent, values between 0 and 1 reduce it, and negative values reverse the transport direction.For example: Stokes Transport Factor == 1., -1., 0.2, -0.2, 1.5 The first scalar has a value of 1. This scalar’s mass transport will have Stokes drift applied as calculated by TUFLOW FV without modification. The second scalar has a value of -1. This scalar’s mass transport will have Stokes drift applied as calculated by TUFLOW FV but with the direction reversed. The third scalar with a value of 0.2 will have its Stokes drift reduced to 20% of that calculated. The fourth scalar with a value of -0.2 will have its Stokes drift transport reduced to 20% of that calculated and with the direction reversed. The fifth scalar has a value of 1.5. This scalar’s mass transport will have Stokes drift applied as calculated by TUFLOW FV but with the direction reversed but increased by 50%. |
|
|
Status: Conditional - Required if including any hydraulic structures or variable bathymetry..
Description: Begins the structure block and defines the connection type linking the structure to the 2D or 3D domain.
Further Information: For detailed structure_definition examples and descriptions, see the model construction chapter hydraulic structures section(s). The required arguments depend on the selected structure type. It may optionally be configured with operational control.
|
|
|
Status: Optional.
Description: Controls whether a structural log file recording operational behaviour is written.
Further Information: Setting this to 1 will write a structural log file (.slf) that contains the operational behaviour of included structures through time.
|
|
|
Status: Optional.
Description: BC block command that modifies the numerical implementation of the boundary condition. The available options depend on the selected boundary condition type. Refer to the relevant boundary condition sections for details. A summary of available options is provided below.
Further Information: Boundary type:
• Q {1} | 2 | 3 | 4 • 1 = Applied as a flux and distributed across a nodestring by cell width. Momentum is applied implicitly through the resulting velocity field • 2 = Applied as a source term and distributed across a nodestring by cell width • 3 = Applied as a flux and distributed across a nodestring by cell width and depth (WH^1.5). Momentum is applied implicitly through the resulting velocity field • 4 = Applied as a source term and distributed across a nodestring by cell width and depth (WH^1.5) • Notes: • The net flow matches the input specification. For Sub-Type 1 or 3 in 3D simulations, inflow may not be uniform through the water column and local flow reversal may occur. Sub-Type 2 or 4 is recommended for 3D models • Sub-Type 2 and 4 treat the boundary as a reflective wall with a distributed internal source • For overland flow with wetting and drying or highly non-uniform cross sections, Sub-Type 3 is recommended for 2D models and Sub-Type 4 for 3D models • QN {1} | 2 • 1 = Default solver method • 2 = Legacy QN boundary flux calculation method. Use only to reproduce legacy simulations • OBC, OBC_CURT, OBC_GRID {1} | 2 | 3 | 4 | 5 | 6 • 1 = Water level is specified. The model calculates the boundary velocity so that flow can exit the domain naturally • 2 = Reserved • 3 = Velocity is specified. The model calculates the corresponding water level at the boundary. Not recommended in regions of wetting and drying • 4 = Legacy overspecified boundary. Sub-Type 6 should be used unless reproducing legacy simulations • 5 = Water levels are applied as an increment to an existing boundary condition. The change in water level is added to the current boundary state. Commonly used to add tidal variations to non-tidal water levels or currents • 6 = Water level and velocity are specified. The velocity is adjusted using internal model conditions through a barotropic Flather relaxation, where differences between external and internal water levels allow waves to pass through the boundary with reduced reflection. Typically used when forcing from an ocean circulation model such as HYCOM • WL, WLS, WL_CURT {1} | 2 | 3 | 4 | 5 | 6 • 1 = Water level is specified. The model calculates the boundary velocity so that flow can exit the domain naturally • 2 = Not supported • 3 = Not supported • 4 = Not supported • 5 = Water levels are applied as an increment to an existing boundary condition. Commonly used to add tidal variations, for example to an OBC_GRID boundary • 6 = Not supported • QG, QC, QC_POLY, QCM, QC_GRID {1} | 2 • 1 = When outflow is specified (Q<0), scalar flux is determined from the interior model concentration • 2 = When outflow is specified (Q<0), scalar flux is taken from the BC file • PRECIP, PRECIP_GRID • 1 = Applied to all cells as a source term • 2 = Applied to wet cells only as a source term |
|
|
Status: Optional.
Description: Enables multiple results of the same output format to be saved from the same simulation. Appends the suffix onto the result file name to ensure each result file name is unique.
Further Information: None
|
|
|
Status: Optional.
Description: Sets the number of surface sigma layers for the Z vertical mesh type.
Further Information: Used with the Z Vertical Mesh Type to create uniformly distributed sigma layers between the highest always wet Z layer and the free surface.
|
|
|
Status: Optional.
Description: Scales the onshore Stokes transport in the surfzone. Increasing the factor increases the compensating offshore undertow required for mass conservation
Further Information: Values greater than
1.0 increase the compensating offshore undertow and values less than 1.0 reduce offshore transport.
|
|
|
Status: Conditional - Required with the Target_Rule control type.
Description: Control block command that sets a timeseries of the desired value of the sample parameter at the sample point or sample nodestring.
Further Information: For further information on target file commands and setup, refer to the model construction chapter control section listed below.
|
|
|
Status: Optional.
Description: BC block command that sets the behaviour when boundary input data are extrapolated beyond their available time range.
Further Information: Used to control how the model responds when boundary input data are requested outside their available time range for a specific BC block. This command overrides the global setting for that boundary condition only. If Temporal Extrapolation Check == ERROR, the model will stop and report an error. If Temporal Extrapolation Check == WARNING, the model will continue to run and a message will be written to the log file.
|
|
|
Status: Optional.
Description: Specifies the simulation time format.
• Hours: Time in decimal hours.• ISODATE: Date and time in the form dd/mm/yyyy HH:MM:SS.
Further Information: Subsequent simulation time commands and simulation inputs must be in the specified time format. Simulation outputs will be in the specified time format.
|
|
|
Status: Required.
Description: Sets the limiting values for the lower and upper computational timestep.
Further Information: The value of timestep_max should typically be set to ten times the value of timestep_min.
|
|
|
Status: Optional.
Description: BC block command that sets fallback tracer boundary values when specified tracer headers are not found.
Further Information: None
|
|
|
Status: Conditional - Required if modelling tracers.
Description: Maps tracer input headers in the boundary data file to simulated tracer fields. Not required if no tracers are modelled.
Further Information: The number of headers should match the number of active tracers set by NTracer.
|
|
|
Status: Optional.
Description: BC block command that applies additive offsets to tracer boundary inputs.
Further Information: Applies additive offsets to tracer boundary inputs after any scaling by Trace_Scale is applied.
|
|
|
Status: Optional.
Description: Applies multiplicative scale factors to tracer boundary inputs.
Further Information: Applies multiplicative scale factors to tracer boundary inputs before any offsets are applied via Trace Offset.
|
|
|
Status: Conditional - Required for the decay, settling or water age implementations or when disabling evapo-concentration..
Description: Starts a tracer block for the specified tracer ID(s).
Further Information: Not required for conservative tracers with default behaviour.
|
|
|
Status: Optional.
Description: Sets the threshold water depth below which transport calculations are disabled in shallow cells.
Further Information: Can be used to suppress transport calculations in shallow water where wetting and drying may otherwise cause instability in transport style boundaries.
|
|
|
Status: Optional.
Description: After a trigger event occurs, if the control parameter equals the trigger_reset_value then the trigger condition will be reset allowing the trigger to reoccur if the trigger value is exceeded again later in the simulation. If not specified, the trigger will only occur once.
Further Information: None
|
|
|
Status: Conditional - Required if Control == Trigger.
Description: The value of the sample parameter that once exceeded will trigger the structure to commence.
Further Information: None
|
|
|
Status: Optional.
Description: Sets the update timestep for the K-Epsilon, K-Omega and External vertical mixing models.
Further Information: Specifies how often the vertical turbulence mixing eddy viscosity and scalar diffusivity equations are updated. If not specified, turbulence terms are updated every timestep.
|
|
|
Status: Optional.
Description: Allows TUFLOW FV tutorial models to be run without a licence.
Further Information: Set to
ON to allow simulation of supported tutorial models without a TUFLOW licence. Demo Model is also supported. See Section 3.1.1.
|
|
|
Status: Optional.
Description: Sets all simulation input, model parameter, and output units to:
• Metric: SI units.• US Customary: US Customary units.• Imperial: Alias for US Customary units.• English: Alias for US Customary units.US Customary, Imperial, and English are equivalent.
Further Information: US Customary units are available for use with 2D HD Simulation Class Cartesian models only. If the model is likely to be extended to a more advanced simulation class (any of 3D HD, AD, ST, WQ or PT) it is recommended to use Metric units during initial model setup.
|
|
|
Status: Optional.
Description: Structure block command that sets how often hydraulic structure calculations are updated during the simulation.
Further Information: If not specified, hydraulic structure calculations are updated every timestep.
|
|
|
Status: Optional.
Description: Switch to choose whether to use the timestamp written to the restart file (.rst) or to use the simulation Start Time.
Further Information: Set to
1 to use the timestamp stored in the restart file. Set to 0 to use the simulation Start Time even when a restart file is read.
|
|
|
Status: Optional.
Description: Command to apply a vapour pressure (and therefore evaporation) correction for hyper saline conditions
Further Information: Applies a vapour pressure correction for hyper saline conditions in supported evaporation and humidity calculations.
|
|
|
Status: Optional.
Description: Sets a reduction factor to scale between first and second order vertical spatial reconstructions for vertical velocity and scalar variable fields. Not used for first order vertical spatial construction.
Further Information: Set to 0.0 to use first order reconstruction and 1.0 to use second order reconstruction. Values between 0.0 and 1.0 will blend between first and second order reconstructions, which may be useful for improving model stability in regions of high vertical gradients away from the study region of interest.
|
|
|
Status: Optional.
Description: Defines the vertical coordinate type and range over which 3D results are averaged to produce point or 2D mesh outputs.
Further Information: •
Depth-All: Averaged over the entire depth.• Depth-Range: Averaged over the vertical distance between two specified depths measured positive down from the water surface.• Height-Range: Averaged over the vertical distance between two specified heights measured positive up from the bed.• Elevation-Range: Averaged over the vertical distance between two specified absolute elevations measured positive up from the model datum.• Sigma-Range: Averaged over the vertical distance between two specified proportions of the water depth measured positive up from the bed (0.0) to the water surface (1.0).• Layer-Range-Top: Averaged over the vertical distance spanned by two specified layers inclusive. Layer 1 is the top layer and layer number increases positive down. If the same layer is specified only that layer is output.• Layer-Range-Bot: Averaged over the vertical distance spanned by two specified layers inclusive. Layer 1 is the bottom layer and layer number increases positive up. If the same layer is specified only that layer is output.
|
|
|
Status: Optional.
Navigation row for this command. Argument syntax depends on the selected implementation. Refer to the implementation specific rows immediately below.
|
|
|
Status: Optional.
Description: Specifies the vertical coordinate system used to interpret a 3D boundary distribution profile.
Further Information: If not specified, the boundary condition is distributed evenly over the water column.
|
|
|
Status: Optional.
Description: Specifies the vertical coordinate system used to connect a structure to the 3D layer structure of the model domain.
Further Information: If not specified, the structure flow is distributed evenly over the water column.
|
|
|
Status: Optional.
Description: Provides the vertical weighting profile used to distribute a 3D boundary condition or hydraulic structure flow over the water column.
Further Information: The file contains vertical coordinate values and associated weighting factors, which are normalised during application. For examples of the required format of the vertical distribution file, refer to the model construction chapter boundary conditions and hydraulic structures sections listed below.
|
|
|
Status: Optional.
Description: Material block command that assigns material specific minimum and maximum limits on computed vertical eddy viscosity.
Further Information: The Global value is set by the Global Vertical Eddy Viscosity Limits command. This command allows material specific limits to be set that override the global limits for cells with the specified material ID.
|
|
|
Status: Optional.
Description: Sets the Total Variation Diminishing (TVD) limiting scheme for 2nd order vertical spatial integration scheme. Not used for first order vertical spatial construction.
Further Information: Refer to the science section of the manual for further information on the available options.
|
|
|
Status: Conditional - Required for the 3D HD simluation class..
Description: Selects the vertical discretisation method for the 3D mesh.
Further Information: Supported vertical mesh type options are:
• Sigma: Uses sigma coordinate layers that follow the bed and occupy the full water column.• Z: Uses fixed elevation z layers across the model domain. By default one Surface Sigma Layer resides between the top z layer and the water surface. This can be modified to include more surface sigma layers using the Surface Sigma Layers command.
|
|
|
Status: Optional.
Description: Applies the Galperin turbulent length scale limiter for the K-Epsilon and K-Omega vertical mixing models.
Further Information: Used to optionally extend the
0.53 value follows the standard Galperin formulation.
|
|
|
Status: Conditional - Required for 3D HD simulations..
Description: Selects the vertical mixing model used to calculate vertical eddy viscosity and scalar diffusivity.
Further Information: See the science section of the manual for further information on the available options. The specification of the Vertical Mixing Parameters command is dependent on the selected vertical mixing model.
|
|
|
Status: Conditional - Required if Vertical Mixing Model is set to Constant as no default parameters are available for this model. Optional for other models as default parameters are provided for all other models..
Navigation row for this command. Argument syntax depends on the selected implementation. Refer to the implementation specific rows immediately below.
|
|
|
Status: Conditional.
Description: Sets the constant vertical mixing value for the Constant vertical mixing model.
Further Information: None
|
|
|
Status: Conditional.
Description: Sets the required parameter values for the Parametric vertical mixing model.
Further Information: None
|
|
|
Status: Conditional.
Description: Sets the required parameter values for the K-Epsilon vertical mixing model.
Further Information: None
|
|
|
Status: Conditional.
Description: Sets the required parameter values for the K-Omega vertical mixing model.
Further Information: None
|
|
|
Status: Conditional.
Description: Sets the eddy viscosity and scalar diffusivity scale factors for the External vertical mixing model.
Further Information: Use the argument form that matches the selected Vertical Mixing Model.
|
|
|
Status: Optional.
Description: Material block command that assigns material specific minimum and maximum limits on vertical scalar diffusivity, overriding corresponding global values.
Further Information: Global values are set using the Global Vertical Scalar Diffusivity Limits command.
|
|
|
Status: Optional.
Description: Tracer block command that enables water age source term accumulation for tracers in the active tracer block.
Further Information: Set to
1 within a tracer block to enable water age accumulation for that tracer. Water age is commonly used to estimate residence or flushing time.
|
|
|
Status: Optional.
Description: Reference water emissivity.
Further Information: None
|
|
|
Status: Conditional - Required for the water quality simulation class..
Description: Specifies the water quality control file used to configure the water quality simulations.
Further Information: Specifies the TUFLOW FV water quality control file, typically using the
.fvwq extension. Use Water Quality Model Directory to define a common base directory when the control file is stored outside the simulation folder.
|
|
|
Status: Conditional - Required for the water quality simulation class..
Description: Activates water quality simulations using either the TUFLOW FV Water Quality Module or a user compiled external water quality model.
Further Information: If the external option is selected, Water Quality Update dt controls the external model timestep.
Default note: construction syntax and SIMULATION_COMMANDS.docx defaults differ. |
|
|
Status: Optional.
Description: Specifies an optional directory path that is concatenated with the Water Quality Control File path.
Further Information: None
|
|
|
Status: Optional.
Description: Sets the timestep used for external water quality model calculations.
Further Information: Only used when Water Quality Model is set to External. The setting is ignored when Water Quality Model is set to TUFLOW because the TUFLOW FV Water Quality Module timestep is defined within the water quality control file.
|
|
|
Status: Optional.
Description: Controls whether bottom orbital velocity from wave inputs is depth corrected when wave and hydrodynamic depths differ.
Further Information: Applicable if the DEPTH variable is applied using an uncoupled WAVE BC type; or, if running in coupled mode via the WAVE_COUPLED BC type.
If Wave Depth Correction is set to 1, compare the model depths in the wave model and TUFLOW FV model. Where TUFLOW FV is deeper, translate the bottom orbital velocity (UBOT) down to the greater depth using: Ubot=Ubot x depth_corr Where: • depth_corr = COSH(MIN(k/h*(h-d),10.)) • h = water depth in TUFLOW FV • d = water depth in Wave model • k is the dimensionless wavenumber If Wave Depth Correction == 0, no depth correction is applied. |
|
|
Status: Optional.
Description: Sets the wave gamma limit and the depth threshold below which wave stresses are switched off.
Further Information: Arguments:
• wave_gamma: Maximum ratio of wave height to depth. Typically 0.35 - 0.8 • wave_depth_limit: Wave stresses are switched off at cells below this depth. If not specified the default is to use the model wetting depth as set by Cell Wet/Dry Depths. |
|
|
Status: Optional.
Description: Structure block command that defines a variable effective flow width for bridges or flow constrictions.
Further Information: Specifies a CSV file defining effective flow width as a function of elevation, commonly used for bridge or constriction modelling. See the linked model construction sections for further details and example file format.
|
|
|
Status: Optional for model simulations not using atmospheric heat exchange. Conditional for the AD simulation class if using the Kondo wind stress implementation in conjunction with Atmospheric Stability..
Description: Selects the wind stress parameterisation.
Further Information: Related commands depend on the selected wind stress implementation. For
|
|
|
Status: Conditional.
Navigation row for this command. Argument syntax depends on the selected implementation. Refer to the implementation specific rows immediately below.
|
|
|
Status: Conditional.
Description: Sets the Wu wind stress parameters Wa, Ca, Wb, and Cb used to define the piecewise linear wind speed dependent transfer coefficient.
Further Information: None
|
|
|
Status: Conditional.
Description: Sets the Kondo wind stress scale factor applied to the internally calculated transfer coefficient.
Further Information: None
|
|
|
Status: Optional.
Description: Sets fallback WQ constituent boundary values when specified WQ constituent headers are not found.
Further Information: The number of arguments varies depending on the suite of water quality constituents. Refer to the linked model construction section(s) for further details.
|
|
|
Status: Conditional - Required for water quality boundary conditions that reference constituent headers in a boundary data file..
Description: Maps WQ constituent input headers in the boundary data file to simulated WQ constituent fields.
Further Information: The number of arguments varies depending on the suite of water quality constituents. Refer to the linked model construction section(s) for further details.
|
|
|
Status: Optional.
Description: Applies additive offsets to WQ constituent boundary inputs after any scaling by WQ Scale is applied.
Further Information: The number of arguments varies depending on the suite of water quality constituents. Refer to the linked model construction section(s) for further details.
|
|
|
Status: Optional.
Description: Applies multiplicative scale factors to WQ constituent boundary inputs.
Further Information: Applies multiplicative scale factors to water quality constituent boundary inputs before any offsets by WQ Offset are applied. The number of arguments varies depending on the suite of water quality constituents. Refer to the linked model construction section(s) for further details.
|
|
|
Status: Optional.
Description: Writes model GIS check files to the specified directory.
Further Information: Writes GIS and CSV check outputs used to review model setup, input interpretation, and derived geometry during initialisation.
|
|
|
Status: Required - only needs to be run once during model initialisation. After the empty files are written, this command can be commented out in subsequent runs..
Description: Creates empty GIS files in either
.mid/.mif or .shp format. Each layer is produced with the required attribute definitions pre-defined, but contains no geographic objects. Empty GIS layers are prefixed and given the suffix _empty. GIS files are saved to the folder \(FPath_{empty}\), which must already exist. After writing the files, TUFLOW stops executing.
Further Information: Creates the empty GIS template layers required for model setup in the selected GIS format. The output directory must already exist. After writing the templates TUFLOW FV stops, so this command is usually run once during initial setup and then removed or commented out.
|
|
|
Status: Optional.
Description: Writes a restart file (.rst) to the log directory location at the time interval specified.
Further Information: Writes restart files at the specified interval so a later simulation can resume from saved model state. The large default value writes a restart file at the end of the simulation only.
A restart file will be written for all TUFLOW FV simulations. |
|
|
Status: Conditional - Required for structures using the Linked Zones connection type.
Description: Defines upstream and downstream orientation for flux limiting calculations.
Further Information: Orientation is defined in degrees anticlockwise from the positive x-axis. For example, for a structure aligned with flow from east to west, both the inlet and outlet orientation would be 180 degrees.
|
