+

Using VELMA Alt Command Line

Overview

The VelmaSimulatorAltCmdLine ("VelmaAlt") tool is a specialized version of VelmaSimulatorCmdLine ("VelmaSim").
Like VelmaSim, VelmaAlt allows you to run a VELMA simulation configuration directly from a command-line, without using VELMA's JVelma GUI environment ("VelmaGUI").
Unlike VelmaSim, VelmaAlt requires specification of the simulation configuration's watershed outlet on the command line.

VelmaAlt ignores the watershed outlet specified within the simulation configuration .xml file, and uses whatever location is specified on the command line as the watershed outlet for the simulation run. VelmaAlt does not check the validity of the specified watershed outlet in any way. It is quite easy to "break" a VelmaAlt run by providing it with a watershed outlet location that is invalid relative to the simulation configuration data in the .xml file. Given this, it may be unclear why you would ever want to use VelmaAlt instead of VelmaSim.

In fact, VelmaAlt was not originally created for VELMA users. VelmaAlt was created to be the "back-end" tool used by VelmaParallelCmdLine ("VelmaPar"). When you start a simulation run with VelmaPar, you are actually starting a top-level manager (VelmaPar itself) that runs sub-reaches by calling VelmaAlt for each sub-reach. In order to run a sub-reach, VelmaPar tells VelmaAlt the simulation configuration .xml file to use, plus the watershed outlet for that sub-reach.

However, there are cases when VelmaAlt is exactly the right tool to use to run a VELMA simulation.

The most important (and by far most common) case is when you are actually trying to run a simulation with VelmaPar, but one or more of your sub-reaches fails to run correctly. You can use the VelmaPar results log file information to determine which sub-reach failed first, and re-run that (and only that) specific sub-reach using VelmaAlt. This allows you to focus on a single simulation run and the simulation configuration parameters that affect that specific sub-reach. In many cases, this focus can in turn lead to a clearer idea of what went wrong for the sub-reach, and how to correct it.

A second use of VelmaAlt is for running multi-map and (possibly) multi-scale VELMA simulations, however, multi-map, multi-scale simulation runs are considerably more complicated to configure than "standard" single-map, single-scale runs, and are not covered in this document. To add to their complexity, it is possible to use either VelmaAlt or VelmaPar to initiate a multi-map, multi-scale VELMA simulation run, but the configuration requirements are different for VelmaAlt and VelmaPar.

Quickstart Guide

Requirements

All of the requirements for VelmaSim apply for VelmaAlt, plus the additional requirement of providing a valid watershed outlet location on the VelmaAlt command line.

Just like VelmaSim, it is possible to run VelmaAlt from a variety of consoles and operating systems, but we focus on Windows 10 and PowerShell in this document, because it is by far the most common combination VELMA is run under.

Running a Simulation via VelmaSimulatorAltCmdLine in PowerShell

The VelmaSim Quickstart Guide's istructions for opening a PowerShell console and for verifying the JRE apply without any changes to VelmaAlt.

Start a Simulation With VelmaSimulatorAltCmdLine

A typical VelmaAlt command line looks quite similar VelmaSim's, apart from the aformentioned watershed outlet location.

java -Xmx -cp \JVelma.jar gov.epa.velmasimulator.VelmaSimulatorAltCmdLine \

The items above must appear as shown, in the order shown:

Here is an example of an actual command line in the format outlined above:

PS C:\Users\meep> java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar gov.epa.velmasimulator.VelmaSimulatorAltCmdLine C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml 1217

Here is how the items in the specific example command line map back to the general command line format:

All other items are unchanged, and appear exactly as they are specified in the general command line format.

Once you have typed a command line in the format above into your PowerShell console, press the Enter key to start the simulation running.

Runtime logging statements will appear in the console window.

Providing a Valid Outlet

Generally, a "valid" outlet for VELMA is any linear-index cell location within the bounds of the specfied DEM grid that delineates to a watershed containing at least 1 channel and 1 non-channel cell.

However, VelmaAlt's requirements for a "valid outlet" may be stricter, depending upon your simulation configuration.

If your simulation configuration's enableReachMapping parameter value is set to MULTI_MODE, then the only "valid outlets" for the VelmaAlt command line are those specified for the initialReachOutlets parameter.
Additionally, amongst the initialReachOutlets values, if you specify an outlet that depends on other outlets, VelmaAlt assumes all the sub-reaches that your specified outlet depends on have already been run (either by other calls to VelmaAlt or by VelmaPar), and their results are available in the same results location specified for the VelmaAlt run you're starting.
If any of the above details are not true, VelmaAlt will fail to run correctly.

Suppose the following parameter values exist in your simulation configuration .xml file:

[ . . . ]
calibration/VelmaInputs.properties/run_index, OR_ws1_30m
/calibration/VelmaInputs.properties/enableReachMapping, MULTI_MODE
/calibration/VelmaInputs.properties/initialReachOutlets, 533 1282 1217 1424
/calibration/VelmaInputs.properties/initializeOutputDataLocationRoot, C:\Users\meep\Velma_Results
[ . . . ]

Reach outlet 1217 depends on data from reach outlet 1424 (note: that cannot be inferred from their initialReachOutlets ordering). Specifying 1217 as the command-line outlet for a VelmaAlt run is "valid", but at run time VelmaAlt will look for completed results for reach 1424 (because 1217 depends upon it) in directory C:\Users\meep\Velma_Results\OR_ws1_30m. If it fails to find results for 1424, outlet 1217 is still "invalid", even though it would be valid otherwise.

In contrast, when your simulation configuration's enableReachMapping parameter value is set to SOLO_MODE, only the general validity requirements apply. The specified outlet can be any location within the DEM grid that meets the watershed-delineation cell/type counts.

In summary:

Validity requirements when enableReachMapping = MULTI_MODE:

Validity requirements when enableReachMapping = SOLO_MODE:

Watershed Delineation Area

Like outlet validity requirements, the watershed area that VelmaAlt delineates for the outlet specified on the command line depends upon the simulation configuration's enableReachMapping parameter value.

When enableReachMapping = MULTI_MODE, VelmaAlt treats the specified outlet as a sub-reach of a larger watershed. The other outlets specified for initialReachOutlets are taken into account. If any of them are contributors to the specified outlet, their watershed area is not included in the specified outlet's watershed area.

When enableReachMapping = SOLO_MODE, VelmaAlt treats the specified outlet as a stand-alone watershed and delineates it as if it was being run with VelmaSim. Other outlets specified for initialReachOutlets that might serve as contributors are ignored, the area delineated is based solely upon the command-line outlet and the topology of the DEM grid.

Locating Results Data

Because VelmaAlt was created as a sub-tool for VelmaPar, it shares VelmaPar's "mindset" regarding where to place simulation results data files.

When you run VelmaSim, simulation results are placed under the directory specified by the initializeOutputDataLocationRoot parameter value, in a subdirectoy named by the run_index parameter value.

VelnmSim results location = <`initializeOutputDataLocationRoot`>\<`run_index`>

When you run VelmPar, the directory specified by the initializeOutputDataLocationRoot + the subdirectoy named by the run_index parameter value is considered a "root" results directory and contains subdirectories of its own, each containing the results for one of the sub-reach outlets specified by the initialReachOutlets parameter's value. Each outlet-specific results subdirectory name starts with Results_ and end with an outlet cell-location index number.

VelmaPar (and VelmaAlt) results location = <`initializeOutputDataLocationRoot`>\<`run_index`>\Results_<`outlet`>
 Where: there is a .\Results_<`outlet`> dir for each `outlet` specified in `initialReachOutlets`.

For example, Given a simulation configuration .xml file with these parameter values:

[ . . . ]
calibration/VelmaInputs.properties/run_index, OR_ws1_30m
/calibration/VelmaInputs.properties/outx, 5			
/calibration/VelmaInputs.properties/outy, 8
/calibration/VelmaInputs.properties/enableReachMapping, MULTI_MODE
/calibration/VelmaInputs.properties/initialReachOutlets, 533 1282 1217 1424
/calibration/VelmaInputs.properties/initializeOutputDataLocationRoot, C:\Users\meep\Velma_Results
[ . . . ]

VelmaSim will place simulation results under the directory:

C:\Users\meep\Velma_Results\OR_ws1_30m

However, for the same simulation configuration, VelmaPar places simulation results under the directories:

C:\Users\meep\Velma_Results\OR_ws1_30m\Results_533  
C:\Users\meep\Velma_Results\OR_ws1_30m\Results_1282
C:\Users\meep\Velma_Results\OR_ws1_30m\Results_1217
C:\Users\meep\Velma_Results\OR_ws1_30m\Results_1424

Regardless of how enableReachMapping is set, VelmaAlt always reports results using VelmPar's directory layout.
Suppose the simulation configuration .xml file had these parameter values:

[ . . . ]
calibration/VelmaInputs.properties/run_index, OR_ws1_30m
/calibration/VelmaInputs.properties/outx, 5			
/calibration/VelmaInputs.properties/outy, 8
/calibration/VelmaInputs.properties/enableReachMapping, SOLO_MODE
/calibration/VelmaInputs.properties/initialReachOutlets, 533
/calibration/VelmaInputs.properties/initializeOutputDataLocationRoot, C:\Users\meep\Velma_Results
[ . . . ]

Calling VelmaAlt for this simulation configuration (with 533 on the command line) will place simualtion results in:

C:\Users\meep\Velma_Results\OR_ws1_30m\Results_533

even though this is a SOLO_MODE run with no other outlets spedified for initialReachOutlets.

VelmaAlt results reporting behavior differs from VelmaPar in one important way.

When VelmaPar is (re-)run for a pre-existing results location, it will remove partial results and report new results in the existing directory.

When VelmaAlt is (re-)run for a pre-existing results location, it will leave the existing results as-is, and create a new "_"-suffixed results directory instead.
Using the last VelmaAlt example above, if VelmaAlt is re-run twice after the initial run, the 3 results will be reported in 3 separate directories, like this:

C:\Users\meep\Velma_Results\OR_ws1_30m\Results_533
C:\Users\meep\Velma_Results\OR_ws1_30m\Results_533_0
C:\Users\meep\Velma_Results\OR_ws1_30m\Results_533_1

Usage Message and Command Line Options

When you run VelmaAlt without specifying a VELMA simulation configuration .xml file, it displays a usage message to the console.
The message provides the VELMA version, reminds you that a VELMA simulation configuration .xml file is required, and lists optional command-line arguments that are available.

Here is an example:

java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar gov.epa.velmasimulator.VelmaSimulatorAltCmdLine
VELMA_2.1.0.39
Usage: VelmaSimulatorAltCmdLine configurationXmlFileFullName iOutlet_to_run [--kv="key,val"]
  or: VelmaSimulatorAltCmdLine configurationXmlFileFullName relocationFileFullName iOutlet_to_run [--kv="key,val"]
Where:
 
Required arguments are:
 
  configurationXmlFileFullName
    The fully-qualified path and name of a valid VELMA simulation configuration (.xml) file.
    Exactly ONE simulation configuration file fullName must appear in the command line.
 
  iOutlet_to_run
    The linear index of the reach outlet cell for this simulation run.
    The cell index must lie within watershed delineated in the configurationXmlFileFullName file,
    but it does not have to be the same value as the configurationXmlFileFullName file outlet.,
 
Optional arguments are:
 
  relocationFileFullName
    The fully-qualified path and name of a valid VELMA simulation relocation (.csv) file.
    If present, only ONE relocation file fullName may appear in the command line.
 
  --kv="key,val"
    key is the full (/group/item/name) text of a VELMA Simulation Configuration parameter.
    val is the value to set for that key.
  Multiple --kv arguments may occur in the command line.
  No two --kv arguments may specify the same key
  The --kv pairs are set or added to the Simulation Configuration at simulator initialization.
  (The original fullName_simulationConfiguration.xml file is NOT modified)

Command Line Options

The Optional relocationFileFullName

VelmaAlt allows an optional relocationFileFullName on the command line. The relocation file contains additional configuration information required for running multi-map, multi-scale simulations. As mentioned previously, these are beyond the scope of this document.

Be aware, however, that when a relocation file is specified, it does not have a double-dash (--) prefix, like other options, and it must appear on the command line between the simulation configuration .xml file and the watershed outlet.

Also be aware that if you accidentally specify two or more filenames on your VelmaAlt command line, one of them will be treated as the relocation file, and VelmaAlt will assume you are starting a multi-map, multi-scale simulation. Since you are not, the run will fail with possibly confusing errors. The specifics of the errors will depend on what the file mistook as a relocation file actually contains.

The --kv Option

VelmaAlt supports the --kv option in exactly the same way that VelmaSim does.
See VelmaSim's explanation for details.

Care and restraint should always be applied when using --kv options, but even more so with VelmaAlt.
VelmaAlt itself almost always overrides the settings of some of the parameter values from the specified simulation configuration. It does this to change the stated outlet location, and to rename the run-index.
In particular, avoid overriding the following parameters for VelmaAlt runs:

Special Cases:

  1. It is sometimes useful to override enableReachMapping, but if you do so, be aware of how the value its set to affects VelmaAlt's watershed delineation and outlet validation.

  2. There is one situation where you must override run_index, even though it is generally discouraged for VelmaAlt runs. If you are using VelmaAlt to re-run a sub-reach result of an existing VelmaPar run, and if you overrode the run_index on the orginal VelmaPar command line, then you must use a --kv option to override run_index to exactly the same value you used in the original VelmaPar run.

There is No --lint Option

VelmaAlt does not allow the --lint option supported by VelmaSim.
The only ways to "lint check" a VELMA simulation configuration .xml file are with VelmaSim, or in the VelmaGUI environment.

In VelmaGui, clicking the [Edit]->[Check the Current Configuration] menu item has the same effect as running VelmaSim with the --lint option.
Any --lint message output is displayed in VelmaGui's "Console" tab.