TUFLOW NetCDF Raster Output Format

Introduction

This page contains information on the NetCDF file format used for gridded (raster) outputs from a TUFLOW simulation. To specify NetCDF output from TUFLOW, the 2016 version or later must be used and "NC" must be included in the Map Output Data Formats, e.g.
Map Output Format == xmdf nc ! Output both xmdf and NetCDF formats

There are a range of additional NetCDF related commands, to control the output further these are:
NetCDF Output Compression == OFF | {ON} | compression level <0 – 9>
NetCDF Output Start Date == {2000-01-01 00:00} | OFF | <date in isodate format>
NetCDF Output Time Unit == DAY | {HOUR} | MINUTE
NetCDF Output Direction == {ANGLE} | BEARING
NetCDF Output Format == {FEWS} | Generic

Please refer to the TUFLOW Manual for more details on these commands.

File Format

The output file has been created to work with GIS and the Delft-FEWS software and therefore should be compliant with the NetCDF CF 1.6 conventions. It is noted that the CF 1.6 standard names do not include any allowance for number of the output names such as Hazard and Time of Peak but these are still output.
There are two slightly different formats (NetCDF Output Format == {Generic} | FEWS), which differ only in the storing of the Non Temporal Variables.

Global Attributes

The NetCDF file has four global attributes:

• Title - The simulation name
• Source - The TUFLOW version which has been used
• References - The documentation of the NetCDF file, i.e. this page!
• Comment - A description of the output.
• NetCDF File Format Version - A unique value for file version, for the 2017 version this is 2.
• NetCDF Data Type - This is 1 for "NC" raster output and 2 for "NC" cell centered results.

An example of the Global Attributes is:

Global Attributes:
           title      = 'M01_5m_002_NC2'
           source     = 'TUFLOW Build: 2015-12-BB-Dev-iSP-w64'
           references = 'TUFLOW NetCDF Raster Output Format (http://wiki.tuflow.com/index.php?title=TUFLOW_NetCDF_Raster_Output_Format)'
           comment    = 'Contains raster TUFLOW output, TUFLOW netcdf version: 1'

Dimensions

The output NetCDF will have three or four dimensions depending on if the Generic or FEWS format has been specified. These are:

• x - the number of x coordinates (columns of data)
• y - the number of y coordinates (rows of data)
• time - the number of outputs. Note that this is an unlimited dimension meaning that the number of time changes each time a new output is written
• static_time (FEWS Format only) - This has a size of 1 and is used for storing a time for the static data (such as maximums)

An example of the Dimensions is:

Dimensions:
           x           = 1946
           y           = 856
           static_time = 1
           time        = 161   (UNLIMITED)

Variables

All outputs for the simulation are written to a single NetCDF file. These are split into three categories:

• Common variables
• Temporal variables
• Non Temporal variables.

For example if the model writes depths our every 10 minutes and tracking maximums is enabled (default) then two depth datasets are written: depths and maximum_depths. These are described further below.

Common Variables

For each simulation the following variables are written:

• x - contains the x coordinates of the output grid
• y - contains the y coordinates of the output grid
• time - contains the times for the temporal outputs
• static time (FEWS only) - contains a single time which is used by FEWS to display the non time varying datasets (such as maximums)

Each of these variables has only a single dimension.

    time 
           Size:       7x1
           Dimensions: time
           Datatype:   double
           Attributes:
                       standard_name = 'time'
                       long_name     = 'time'
                       units         = 'hours since 2000-01-01 00:00'
                       axis          = 'T'
    y    
           Size:       467x1
           Dimensions: y
           Datatype:   double
           Attributes:
                       standard_name = 'projection_y_coordinate'
                       long_name     = 'y-coordinate in cartesian system'
                       units         = 'm'
                       axis          = 'Y'
    x    
           Size:       422x1
           Dimensions: x
           Datatype:   double
           Attributes:
                       standard_name = 'projection_y_coordinate'
                       long_name     = 'x-coordinate in cartesian system'
                       units         = 'm'
                       axis          = 'X'
    static_time                  
           Size:       1x1
           Dimensions: static_time
           Datatype:   double
           Attributes:
                       standard_name = 'static_time'
                       long_name     = 'static_time'
                       units         = 'hours since 2000-01-01 00:00'

Temporal Result Variables

For each of the map outputs data types specified in the control file, the outputs are written into a variable that has the dimensions x, y and time.
For vector variables, this is split into two components, for example for the velocity output this is split into "magnitude_of_velocity" and "direction_of_velocity". The notation for the direction can be controlled with the command:
NetCDF Output Direction == {ANGLE} | BEARING

An example of the temporal variables for a simulation with the h, d and v outputs is below:

    water_level                  
           Size:       1946x856x161
           Dimensions: x,y,time
           Datatype:   single
           Attributes:
                       _FillValue = -999
    depth                        
           Size:       1946x856x161
           Dimensions: x,y,time
           Datatype:   single
           Attributes:
                       _FillValue = -999
    magnitude_of_velocity        
           Size:       1946x856x161
           Dimensions: x,y,time
           Datatype:   single
           Attributes:
                       _FillValue = -999
    direction_of_velocity        
           Size:       1946x856x161
           Dimensions: x,y,time
           Datatype:   single
           Attributes:
                       _FillValue = -999

Non Temporal Variables

There are currently two output formats from TUFLOW, this is controlled with the command:
NetCDF Output Format == {FEWS} | Generic
The file formats are very similar, but for the FEWS format (default) the non-temporal variables have a time associated with them to allow them to display correctly in FEWS. For the generic output (which requires "NetCDF Output Format == Generic"), the data is stored in an array that has the dimensions x and y:

    maximum_depth                
           Size:       1946x856
           Dimensions: x,y
           Datatype:   single
           Attributes:
                       _FillValue = -999

For the FEWS output (which is the default or has "NetCDF Output Format == FEWS" specified), the data is stored in an array that has the dimensions x, y and static_time:

    maximum_depth                
           Size:       1946x856x1
           Dimensions: x,y,static_time
           Datatype:   single
           Attributes:
                       _FillValue = -999