Required Input Data Files for VELMA Simulations
The primary input file for a given simulation run is an XML file of initialization parameters known as the simulator configuration file (often abbreviated as the "simconfig" or "the XML" file). In addition to the simulator configuration file, the following data files must be complete and available for the VELMA Simulator to run:
| FILE | TYPE | CONTAINS |
| Flat-Processed DEM | Spatial / Grid ASCII (.asc) | Elevation in meters |
| Cover Species ID Map | Spatial / Grid ASCII (.asc) | Cover Species ID integers |
| Cover Species Age Map | Spatial / Grid ASCII (.asc) | Cover Species age in years |
| Soil Parameters ID Map | Spatial / Grid ASCII (.asc) | Soil Parameterization ID integers |
| Precipitation Driver Data | Temporal / (.csv or .txt) | Precipitation per in mm |
| Air Temperature Driver Data | Temporal / (.csv or .txt) | Air Temperature in degrees C |
If your simulation is using the optional spatially-explicit weather model, the following files must also be complete and available:
| FILE | TYPE | CONTAINS |
| Head Index Map | Spatial / ESRI Grid ASCII (.asc) | Heat index values |
| Precipitation Coefficients | Tabular (.csv) | Coefficient values |
| Air Temperature Coefficients | Tabular (.csv) | Coefficient values |
Finally, the following files are not required for the VELMA Simulator to run, but providing them for a simulation run is recommended. Their availability allows the simulator to provide more run-time information and some additional results data. (E.g. The VELMA Simulator can only compute a Nash- Sutcliffe coefficient value for a simulation run's runoff data if the Observed Runoff data file was provided as part of the input data).
| FILE | TYPE | CONTAINS |
| Observed Runoff | Temporal (.csv or .txt) | Observed runoff in mm |
| Observed Stream Chemistry | Temporal Tabular (.csv) | Observed chemistry values |
"Simulator Configuration" and "Simulation Configuration" are both used as the term for this primary file. The former emphasizes the fact that the file's contents configure the simulator, while the latter emphasizes the (equally true) fact that the file's contents form a particular configuration of a given simulation scenario.
The Simulator Configuration file specifies the Names of all other input data files.
When you run a VELMA Simulation, the simulator engine is given the simulator configuration file. The first thing the simulator engine does is initialize itself, using the key-value pairs in the file. Each of the required or optional files mentioned above is present as a key-value pair in the simulator configuration file.
| FILE | CONFIGURATION ID KEY |
| Flat-Processed DEM | /calibration/VelmaInputs.properties/input_dem |
| Cover Species ID Map | /calibration/VelmaInputs.properties/coverSpeciesIndexMapFileName |
| Cover Species Age Map | /calibration/VelmaInputs.properties/coverAgeMapFileName |
| Soil Parameters ID Map | /calibration/VelmaInputs.properties/soilParametersIndexMapFileName |
| Precipitation Driver Data | /weather/SpatialWeatherModel/rainDriverDataFileName |
| Air Temperature Driver Data | /weather/SpatialWeatherModel/airTemperatureDriverDataFileName |
| Head Index Map | /weather/SpatialWeatherModel/heatIndexMapFileName |
| Precipitation Coefficients | /weather/SpatialWeatherModel/rainCoefficientDataFileName |
| Air Temperature Coefficients | /weather/SpatialWeatherModel/airTemperatureCoefficientsDataFileName |
| Observed Runoff | /calibration/VelmaInputs.properties/input_runoff |
| Observed Stream Chemistry | /calibration/VelmaInputs.properties/input_stream_chem |
ID keys for required input data files must have the name of an existing, valid and readable file specified, while optional input data files ID keys may be left blank.
Note: Sometimes just the name and extension of the file will do, sometimes the fully-specified path must be included as part of the name, and sometimes the path is optional. This unfortunately-confusing state of affairs exists due the history of the Simulator's development. For the input data files discussed here, supply only the name and extension as an ID Key's value.
The Simulator Configuration file specifies the Location of all other input data files.
The simulation configuration specifies the location of a directory (a.k.a. "folder") and the VELMA simulator engine looks in that directory for the input data files specified by the appropriate ID Keys (as listed in the previous table). The simulation configuration uses two, separate ID Keys to specify one fully-qualified path + directory name:
| Location Path | /startups/VelmaStartups.properties/inputDataLocationRootName |
| Directory Name | /startups/VelmaStartups.properties/inputDataLocationDirName |
The fully-qualified location of input data files is Location Path + "/" + Directory Name. For example, the following ID Key values:
| ID Key | Value |
| /startups/VelmaStartups.properties/inputDataLocationRootName | C:/MyVELMA_InputData |
| /startups/VelmaStartups.properties/inputDataLocationDirName | LittleMtn_Watershed |
… indicate that the VELMA simulator should look for input data files in this directory: C:\MyVELMA_InputData\LittleMtn_Watershed
IMPORTANT NOTE
The example above uses Microsoft Window file system "back slash" separators, however you should ALWAYS use "forward slash" (a.k.a. Unix-style) separators when specifying path name values for the simulator configuration's ID Keys.
Given the fully-qualified input data location in the example above, suppose the LittleMtn_Watershed's DEM file name (for ID Key /calibration/VelmaInputs.properties/input_dem) was specified as: LittleMtn_30m_DEM.asc
The VELMA simulator would attempt to open and read elevation data from the file:
C:\MyVELMA_InputData\LittleMtn_Watershed\LittleMtn_30m_DEM.asc