VELMA Topography Output Data Summary

Overview

VELMA configurations include a boolean-valued parameter named enableTopographySpatialDataOutput that defaults to false.
Setting it to true causes the VELMA simulator to write several .asc map files as part of its simulation results.

Each file written contains a specific topographic or watershed-related type of data, and each file name starts with a mnemonic indicating the data it contains.

File Prefix	File Data Description
`CHANNEL_`	delineated cell channel identification mask
`DEM_`	cell elevation (in meters)
`FACC_`	cell flow accumulation value
`FDIR_`	cell primary flow direction indicator
`FID_`	delineated cell identification mask
`SID_`	delineated cell simulation sequence number

Each file's name also contains the name provided as the configuration's input_dem parameter value, e.g. if input_dem == my_dem_30m.asc, then the FID_ files full name would be FID_my_dem_30m.asc.

Collectively these files provide additional context about the results of the simulation run. In turn, that context may prove useful for changing the configuration's parameterization for subsequent runs ...

as part of site calibration refinement.
for adapting the configuration to include additional simulation features (e.g. contaminant or sediment simulation)
as information for other models that may use the VELMA results as part of their own input.

Although you must successfully start a VELMA simulation run in order to generate the topography output files, you do not need to wait until the simulation has completed in order to view their contents. When enabled, the topography output files are written as part of the first simulation step, and are available by the time the second simulation step has completed.

A common practice when calibrating a new simulation site is to create a simplified configuration file with enableTopographySpatialDataOutput == true, then stop the run after the 2nd simulation step. The topography files from this run can be used to further refine and revise the simplified configuration file's parameter values. (E.g. the CHANNEL_ and/or FACC_ map data can be used to determine placement of sub-reach outlets or cell data writers.)

File Formats and Data Details

All the files written will have the same grid dimensions and header information as the DEM file specified for the configuration's input_dem parameter unless the trimTopographyOutputToWatershedBoundary parameter has also been set true. In that case, the grid dimensions and x and y offsets of the topography file headers will be set to the bounding box of the delineated watershed.
Setting trimTopographyOutputToWatershedBoundary == true can be useful if your input_dem map is very large and your delineated area in that map is very small, however trimming is optional: .asc maps can be post-processed with GIS tools to trim them as-needed.

The CHANNEL_ Map

The CHANNEL_ map contains ternary mask data that categorizes cells as follows:

Cell Value	Meaning
-1	The cell is not part of the watershed delineation.
0	The cell is part of the delineation but not a channel cell.
1	The cell is part of the delineation and is a channel cell.

A cell within the delineation is a channel cell IFF the log10 of its flow accumulation (FACC_) value is >= the configuration's setChannelThreshold value. (In the results directory, the setChannelThreshold value is stored in the SimulationConfiguration[.csv,.xml] files.)

Note: typically, setChannelThreshold == 2.5, and it is considered unwise to change this default value without a deep understanding of how VELMA evaluates and computes runoff and loss amounts. Astute readers will note that the CHANNEL_ map can be computed by overlaying the FACC_ and FID_ maps, and assigning values based on a cells log10(FACC_) and FID_ map values.

The DEM_ Map

The DEM_ map is a copy of the map file specified for the configuration's input_dem parameter.
It is included in the results directory as a convenience, and for reference should the results directory become "separated" by time and location from the input data directory used by the VELMA simulator to generate the results.

The FACC_ Map

The FACC_ map contains each cell's VELMA-computed flow accumulation value.
VELMA-computed flow accumulation values are related to, but are also distinct and different from JPDEM-computed flow accumulation values.

FACC value	Description
JPDEM-computed	relative elevation based, accumulation of primary flow direction counts, integer values.
VELMA-computed	relative elevation based, accumulation of multiple-flow direction scores, floating-point values.

VELMA flow accumulation is based on multiple flow directions. Each cell contributes 1 to its flow accumulation and each upstream cell that flows directly to it contributes an amount of its flow accumulation that is proportional to its water flow to the cell. The waterflow is the ratio of its slope to the sum of slopes of all cells that flow to the cell. This is distinct from the JPDEM flow accumulation calculation which simply sums the number of cells in a path of primary flow direction to the final headwater cell.

Note: FACC_ map cells outside of the delineated watershed have the facc value "1.0", however some cells within the delineated watershed may also have a facc value of "1.0". Do not infer delineation status from a cell's facc value. Determine a cell's delineation status from the FID_ map.

The FDIR_ Map

The FDIR_ map contains each cell's primary flow direction, as a integer-value direction identifier in the range [1, 8]. In VELMA a cell's primary flow direction is defined as the direction identifier of the downhill-adjacent cell with the largest slope, where slope is calculated as:

(cell_elevation - downhill_adjacent_cell_elevation) / centroid_to_centroid_distance

The following ascii-diagram inidicates which cell adjacent to cell "c" corresponds which direction code:

+---+---+---+     The direction codes "start" 
| 6 | 7 | 8 |     at the cell east (to the right) of cell "c"
+---+---+---+     and continue clockwise around the eight
| 5 | c | 1 |     adjacent cells.
+---+---+---+  
| 4 | 3 | 2 |
+---+---+---+

Any value outside the range [1, 8] indicates a cell without a valid flow direction, and is an indication that there were basic problems processing the original DEM grid map. If you find such values, re-evaluate your original DEM grid map: check that it is properly flat-processed, and passes JPDEM's flow test function.

The FID_ Map

The FID_ map is a binary mask that distinguishes delineated and non-delineated cells.

Cell Value	Meaning
-1	The cell is not part of the watershed delineation.
1	The cell is part of the delineation.

The FID_ map is primarily useful as an overlay mask when combining other VELMA data maps using either a GIS tool, or utility scripts like Python + GDAL or Numpy.

The SID_ Map

In the SID_ map, each cell's value indicates its evaluation order within the VELMA simulation. The cell with value == "0" is the first cell processed, and the cell with the highest value is the last cell processed (and is also the outlet cell of the delineated watershed). Cells outside of the watershed are set to the value "-1". In each simulation step VELMA must process the delineated cells of the watershed in an order that ensures no cell's results (e.g. per-step water balance) are determined before any uphill-adjacent cells (whose results might affect its own) are processed. The sid ordering is how VELMA enforces this rule.

Submit a Suggestion