Output

Kestrel simulation results are contained in a number of output files. The main numerical results of the simulation are cell-averaged values of quantities at locations within the flow domain. There are two types of numerical result files:

  • snapshot files that contain data produced by Kestrel at a single point in time. The files have sequential numeric names, e.g. 000001.nc, 000002.nc, …. The snapshot file 000000.nc contains the initial conditions of the flow.

  • aggregated files that contain data that summarise the flow up to the point at which they are written. These files are updated throughout the simulation. Aggregated results are stored in a single file with the filename set using the optional input maximums filename with default value Maximums.

The numerical results are only stored in active regions of the domain, and therefore, the data volume in later snapshot files is larger than in earlier files, and aggregated results files increase in size as simulations progress.

Solution data files can be provided in two main formats: as plain text in column-headed comma-separated values (with a .txt extension), or as NetCDF files (with a .nc extension). Here we first describe the output files in these two formats. Additionally, Kestrel produces:

  • a RunInfo.txt file that summaries the settings used in the model;

  • a Volume.txt file that summaries the time series of volumes of material;

  • (when using .txt output) files that record topographic data at cell vertices.

NetCDF format

NetCDF files are typically smaller in size and record contain data at higher numerical precision than Kestrel’s text file outputs, and are georeferenced when simulations use topographic data. Therefore, NetCDF files are the preferred data format. However, they require a compatible NetCDF library for installation (see Installation) and post-processing tools that are able to read NetCDF files. Many GIS software packages are capable of reading NetCDF, and packages are available in Julia, MatLab, Python, and other languages.

Computed solution fields are stored as Float64 variables.

The NetCDF files contain global attributes that contain some of the important settings of the model. These include the attribute time that gives the simulated time, in seconds, of the snapshot data or latest write for aggregated results.

For georeferenced simulations, the global attribute crs_epsg gives the EPSG code for the UTM coordinate reference system.

There are four NetCDF dimensions defined:

  • x - the Easting dimension, for cell centres;

  • y - the Northing dimension for cell centres;

  • x_vertex - the Easting dimension for cell vertices (only for snapshot files);

  • y_vertex - the Northing dimension for cell vertices (only for snapshot files).

Note

For one-dimensional simulations, y has size 1, and y_vertex has size 2.

Note

The vertex data is required when restarting simulations but should not be used for post-processing. Therefore, the vertex data is not georeferenced.

For georeferenced simulations, the NetCDF files contain a variable

crs

A NetCDF variable to store the following attributes defining the coordinate reference system:

  • grid_mapping_name taking the value transverse_mercator.

  • false_easting taking the value 500000.

  • false_northing taking the value 0 for domain centres in the Northern hemisphere and 10000000 for domain centres in the Southern hemisphere.

  • latitude_of_projection_origin taking the value 0.

  • longitude_of_central_meridian with value dependent on the central longitude of the domain.

  • scale_factor_at_central_meridian taking the value 0.9996.

Warning

The aggregated results NetCDF file is overwritten during the simulation. This will fail is the NetCDF file is open during an attempt to write. This will result in an error and termination of the simulation.

It is recommended to copy the file before opening to perform analysis and processing while a Kestrel simulation is in progress.

Text format

The text format output files produced by Kestrel contain column-headed, comma-separated numerical data. The text files contain the same data fields as NetCDF files, but at a reduced numerical precision. In order to aid post-processing of these files, when simulations are georeferenced there are additional columns providing the cell-centre latitude and longitude in the WGS84 coordinate reference system. Furthermore, to reduce file size, fields that are appropriate only for two-dimensional simulations are not recorded when one-dimensional simulations are performed.

Computed solution fields are stored in scientific form (ES18.10E3).

For restarting simulations, topographic data is required at cell vertices as well as at cell centres. These data are stored in separate files with extension .txt_topo.

The first column of text data files is named tile and refers an internal integer identifier of domain tiles within Kestrel, which is required for restarting simulations from an existing result file.

Output fields

The snapshot and aggregated result files contain the following fields for location:

x

The Easting coordinate of cell centres [m].

When georeferenced, the coordinate is in the UTM coordinate reference system given by crs_epsg.

y

The Northing coordinate of cell centres [m].

When georeferenced the coordinate is in the UTM coordinate reference system given by crs_epsg.

For one-dimensional simulations y = 0 in NetCDF files and is absent from text files.

x_vertex

The Easting coordinate of cell vertices [m].

These values are not georeferenced, so are relative to the domain centre.

Only defined in NetCDF snapshot files.

y_vertex

The Northing coordinate of cell vertices [m].

These values are not georeferenced, so are relative to the domain centre.

Only defined in NetCDF snapshot files.

For one-dimensional simulations y_vertex = -0.5, 0.5.

The snapshot files contain the following solution fields:

flow_depth

The flow depth, \(H\) [m].

flow_speed

The flow slope-aligned speed, \(\left|\mathbf{u}\right|\) [m/s].

x_velocity

The \(x\)-component of the flow velocity, \(\bar{u}\) [m/s].

y_velocity

The \(y\)-component of the flow velocity, \(\bar{v}\) [m/s].

density

The density of the mixture, \(\bar{\rho}\) [kg/m3].

solids_fraction

The volume fraction of solids in the mixture, \(\bar{\psi}\) [dimensionless].

x_flux

The \(x\)-component of the mass flux per unit area, \(\bar{\rho} H\bar{u}\) [m3/s].

y_flux

The \(y\)-component of the volumetric flux per unit area, \(\bar{\rho} H\bar{v}\) [m3/s].

Hnpsi

The volume of solids per unit area, \(H\bar{\psi}\) [m].

base_elevation

The initial topographic elevation, \(b_{0} = b(x,y,0)\) [m].

elevation_change

The change in topographic elevation, \(\delta b_{t} = b(x,y,t) - b(x,y,0)\) [m].

x_slope

The topographic slope along the \(x\) coordinate, \(\partial b/\partial x\) [dimensionless].

y_slope

The topographic slope along the \(y\) coordinate, \(\partial b/\partial y\) [dimensionless].

B0_vertex

The initial topographic elevation at cell vertices, \(b_{0} = b(x,y,0)\) [m]. This data is required when restarting simulations, but should not be used for post-processing. It is not georeferenced. Stored in .txt_topo files, when using text output.

Bt_vertex

The change in topographic elevation at cell vertices, \(\delta b_{t} = b(x,y,t) - b(x,y,0)\) [m]. This data is required when restarting simulations, but should not be used for post-processing. It is not georeferenced. Stored in .txt_topo files, when using text output.

w

The conserved quantity \(w = H/\gamma + b\) that is computed in the model. This is required for restarting simulations but should not be used for post-processing.

The aggregated result files contain the following solution fields:

max_depth

The maximum flow depth that has occurred in each cell of the domain [m].

t_max_depth

The time at which the maximum flow depth occurred in each cell of the domain [s].

max_speed

The maximum flow speed that has occurred in each cell of the domain [m/s].

t_max_speed

The time at which the maximum flow depth occurred in each cell of the domain [s].

max_erosion

The maximum depth of erosion that has occurred in each cell of the domain [m].

t_max_erosion

The time at which the maximum depth of erosion occurred in each cell of the domain [s].

max_deposit

The maximum depth of deposition that has occurred in each cell of the domain [m].

t_max_deposit

The time at which the maximum depth of deposition occurred in each cell of the domain [s].

max_solids_frac

The maximum solids volume fraction that has occurred in each cell of the domain [dimensionless].

t_max_solids_frac

The time at which the maximum volume fraction occurred in each cell of the domain [s].

inundation_time

The time at which flow material first reaches each cell of the domain [s].

Flow Volumes

The file Volume.txt contains time series recording the evolution of flow volumes and masses during the simulation. These are summary values, integrated numerically over the full simulation domain, whenever a snapshot is recorded.

The data are stored as column-headed, comma-separated values with the first row recording the time, and subsequent columns recording quantities calculated from computed fields. The calculated values are written at high precision (sixteen figures) as they can be used to verify accurate computation of conserved quantities.

The following columns are stored:

volume

The total volume of material in the flow domain.

This volume includes material added in initial conditions, material added by flux sources, and material entrained into flows by erosion, and is given mathematically (following the notation of Physical model) by

\[V_{total} = \int_{A} H\gamma\ \mathrm{d}A,\]

where \(\mathrm{d}A\) denotes a Cartesian area element in the horizontal plane. Kestrel computes a approximation to this (and the other integrals defined given below) in accordance with its finite volume numerical scheme.

total_bed_volume

The total volume of material derived from the bed.

This is the difference of material eroded from the bed from that deposited to the bed, and is given by

\[V_{bed} = \int_{A} \left(b(\mathbf{x},t) - b(\mathbf{x},0)\right)\ \mathrm{d}A.\]

total_mass

The total mass of material in the flow domain.

This mass includes material added in initial conditions, material added by flux sources, and material entrained into flows by erosion, and is given by

\[M_{total} = \int_{A} \bar{\rho}H\gamma\ \mathrm{d}A.\]

bed_mass

The total mass of material derived from the bed.

This mass is the difference of material eroded from the bed from that deposited to the bed, and is given by

\[M_{bed} = \rho_{b}V_{bed}\]

where \(\rho_{b}\) is the density of bed material.

total_solids_mass

The total mass of solids in the flow domain.

This mass includes solids added in initial conditions, solids added by flux sources, and solids entrained into flows by erosion, and is given by

\[M_{solids} = \int_{A} \rho_{s}H\bar{\psi}\gamma\ \mathrm{d}A.\]

bed solids mass

The total mass of solids derived from the bed.

This mass is the difference of solid mass added by erosion from the bed from the solid mass deposited to the bed, and is given by

\[M_{bed solids} = \psi_b\rho_{s}V_{bed}.\]

where \(p\) is the bed porosity.

RunInfo

The RunInfo.txt file contains information of the simulation settings and progress, including quantities calculated from user inputs within Kestrel.

The file provides a valuable summary of the parameter and input settings used in the model and can assist in analysis of the numerical outputs. Additionally, the RunInfo.txt file is required for restarting simulations.

The file is structured in a similar way to Kestrel input files, with blocks corresponding to Domain, Initial conditions, Parameters, Solver settings, Output settings, and Topography. Within these blocks, settings and calculated quantities are recorded in the form keyword = value. In many cases the keywords are fully descriptive or identical to keywords in the input files.