+

Running a VELMA Simulation From a Command Line

Overview

Most VELMA simulation results (excluding Parallel runs) are generated via the JVelma GUI environment (henceforth referred to as "VelmaGUI"). However, you can also start a VELMA simulation directly from a command-line console prompt via VelmaSimulatorCmdLine (henceforth referred to as "VelmaSim").

You may be thinking, "JVelma starts from a command-line console prompt". While that it true, what is starting is VELMA's GUI environment (VelmaGUI). After VelmaGUI starts, you load a simulation configuration .xml file, possibly edit it, and then click the "Run" button to start it running all within VELMA GUI.
In contrast, when you start VelmaSimulatorCmdLine (VelmaSim) from a command-line console prompt, it immediately loads and starts running the simulation configuration .xml file that you specify. Tracing/log statements that would have appeared in VelmaGUI's Console tab instead appear directly in the command-line console's window.

Both VelmaGUI and VelmaSim use the same simulation engine, and generate the same results for a given simulation configuration, but they provide different benefits:

VelmaGUI:

VelmaSim:

Use whichever suits your need for a given simulation run.

Quickstart Guide

Requirements

To run a Velma simulation configuration using VelmaSimulatorCmdLine, you must have the following installed and available:

You must also know the following information:

Running a Simulation via VelmaSimulatorCmdLine in PowerShell

Open a PowerShell Console

If you are familiar with Windows Powershell, open a console window as you normally do.
If you are unfamiliar with Windows Powershell, you can open a Powershell window via the following steps:

  1. Press the Windows Start Key + the R key to open the "Run" dialog box.
  2. Type "powershell" in the Run dialog's textbox.
  3. Click the Run dialog's OK button.

Verify the Java JRE

If this is the first time you are running a VELMA simulation on a particular computer, verify that it has a suitable Java JRE available.
In the PowerShell console, type the command java --version, then press the Enter key.
Here is an example:

PS C:\Users\meep> java -version
java version "1.8.0_291"
Java(TM) SE Runtime Environment (build 1.8.0_291-b10)
Java HotSpot(TM) 64-Bit Server VM (build 25.291-b10, mixed mode)
PS C:\Users\meep>

In the example above PS C:\Users\meep> is PowerShell's command prompt (yours may look different).
If your java -version command result reports a version number lower than 1.8, or does not report "64-bit", your VELMA simulations may not start or run successfully (for either VelmaSim or VelmaGUI).
If your java -version command result is an error message that begins like this ...

java : The term 'java' is not recognized as the name of a cmdlet, function, script file, or operable program.

... your computer does not have a Java JRE installed, or PowerShell does not know where to find it.

Start a Simulation With VelmaSimulatorCmdLine

This is the format for the PowerShell command line required to run a VELMA simulation.

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

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.VelmaSimulatorCmdLine C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml

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 that would have appeared in the VelmaGUI's "Console" tab panel will instead appear in the console.

Usage Message and Command Line Options

When you run VelmaSim without specifying a VELMA simulation configuration .xml file, VelmaSim 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:

PS C:\Users\meep> java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar gov.epa.velmasimulator.VelmaSimulatorCmdLine
VELMA_2.1.0.39
Usage: VelmaSimulatorCmdLine  [--lint] [--kv=","]
Where:
 
Required arguments are:
 
  
    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.
 
Optional arguments are:
 
  --lint
    Performs the initialization step, but does not actually run the simulation.
    Warnings or errors encountered during initialization are reported to console.
    No results folder or files are created.
 
  --kv=","
     is the full (/group/item/name) text of a VELMA Simulation Configuration parameter.
     is the value to set for that .
    Multiple --kv arguments may occur in the command line.
    No two --kv arguments may specify the same 
    The --kv pairs are set or added to the Simulation Configuration at simulator initialization.
    (The original fullName_simulationConfiguration.xml file is NOT modified)

Note: the text of the usage message varies between different VELMA versions. If you are using an older-version JVelma.jar, some or most of the usage message text shown above may be missing. Options that are not displayed are unavailable.

Command Line Options

Command line options are exactly that: optional. If you choose to use them, we recommend placing them at the end of your command line. That way, you can recall the command (via the up-arrow key in Windows PowerShell) and easily backspace over them to run the same command with the optional argurments removed or changed.

The --lint Option

When the --lint option is added to a command line, VelmaSim starts the simulator engine and performs initialization, but then stops and does not actually run the simulation. No results folder or output files are created. Additionally, console output is filtered down to only WARNING and SEVERE messages.

Running VelmaSim with --lint allows you to confirm that your simulation configuration .xml file will initialize properly. The console filtering emphasizes any WARNING or SEVERE log messagese that occur. Without --lint they can be missed amongst the many CONFIG and INFO messages that normally echo to the console.

A peculiarity regarding warnings is that a VelmaSim started with --lint always echoes at least two warnings to the console. This is because --lint suppresses all results folder and file output, and in punctilious fashion, issues warnings to call attention to that suppression.
The two warnings look like this:

WARNING VelmaSimulatorEngine runLinter: VELMA Lint Mode Enabled: startups parameter suppressAllOutputFiles overridden and set == true
WARNING GlobalState setOutputDataLocationDir: All File Output is suppressed: ignoring Output Data Location

Even if you simulation configuration .xml initializes correctly and has no "real" warnings, you will see the two messages listed above when you add the --lint option to your VelmaSim command line.

If you see other, additional warnings, pay attention to them. Your simulation may run to completion even if WARNING messages appear during initialization, but it may not produce trustworthy results.
For example, the following WARNING message ...

WARNING GlobalState initializeCoverSpeciesForRun: CoverSpecies uniqueId=10 uniqueName="LowShrub" referenced in: dem=NO sid=NO inSidCount=0

... indicates that your simulation configuration .xml contains a CoverSpecies parameterization that is not referenced anywhere in the specified cover id map. This might be fine -- there's no harm (apart from using some memory) in specifying but not referencing CoverSpecies that you wish to ignore. However, if "LowShrub" is a CoverSpecies that you definitely expected to be part of your simulation run, this warning indicates that your should check the CoverSpecies parameterization for typos or the correctness of your cover id map.

If you see a SEVERE error message, it indicates that VelmaSim was unable to successfully complete initializing. You will need to correct the error message's cause before your simulation will successfully initialize and run.

An aside: the --lint option name is due to historical precendent, although --lint's capabilities are minimal compared to "real" linter tools.

The --kv Option

The --kv option allows you to override the value of a parameter in the simulation configuration .xml file, replacing it with a value specified on the VelmaSim command line.

Multiple --kv arguments may be specified for a single command line, to change multiple parameters (one parameter per --kv argument) for a given VelmaSim run.

The --kv option cannot add or remove a parameter, it can only change an existing parameter's value, but it can change any parameter with no validation of the new value, so employ it with considerable caution and care.

A --kv option must indicate what parameter it will override, and the new value for that parameter.
The --kv option is informally called the "kv-override", because it provides a key (the parameter) and a value (to -- i.e. override -- the existing value) to the VELMA simulator engine.

The syntax for a --kv option, used to indicate the parameter and assocated value is:

--kv=","

A fully-qualified parameter name is VELMA's internal identifier for a given configuration parameter.
VELMA parameters are commonly referred to via their "short" name (e.g. run_index), but every "short" parameter name actually corresponds to a longer fully-qualified name.
Fully-qualified parameter names have this form:

///

The portion of the fully-qualified name corresponds to what is colloquially the "short" parameter name.
For example, the fully qualified parameter name corresponding to the "short" parameter name run_index is:

/calibration/VelmaInputs.properties/run_index

The forward-slash (/) characters are required as separators, but are not themselves part of the key names.

You can determine the fully-qualified prefix for a "short" parameter name in a number of ways, but the two simplest and most common methods are to look in the VelmaGUI ("JVelma") Parameter's tab, or look in the SimulationConfiguration.csv file of an existing simulation result generated with the same simulation configuration .xml file you're planning to modify via a --kv option.

Finding a fully-qualified parameter name using VelmaGUI

  1. Start the VelmaGUI ("JVelma") running
  2. Load your simulation configuration .xml file
  3. Click to the "Parameters" tab.
  4. Scroll through the table's rows until you find the parameter "short" name in the "Parameter" column of the table
    OR Enter the "short" name in the middle of the 3 filter text-entry-boxes above the table and press Enter or Tab to filter down to the appropriate row.

The column names of the Parameters tab's table of parameters indicate column values that match components of a fully-qualified parameter name.
Here is our run_index example again, to make the correspondence explicit:

Parameter name component
VelmaGUI Parameters Column Name Group Item Parameter
run_index example calibration VelmaInputs.properties run_index

Finding a fully-qualified parameter name in a SimulationConfiguration.csv file

When a VELMA simulation run generates results, one of the files written to the results folder is the SimulationConfiguration.csv file. The file lists every fully-qualified parameter name specified for the simulation run in column A, and the value specified for the parameter in column B (SimulationConfiguration.csv files have no header row). The rows are in asscending order, sorted alphabetically by fully-qualified name.
Here are a few rows at the top of a SimulationConfiguration.csv file, as and example:

/calibration/VelmaCalibration.properties/DDs, 3.0
/calibration/VelmaCalibration.properties/Tmlt, 2.0
/calibration/VelmaCalibration.properties/Tsn, 0.0
/calibration/VelmaCalibration.properties/avgAT, 13.0
/calibration/VelmaCalibration.properties/avgGST, 12.4
/calibration/VelmaCalibration.properties/be, 6.33974
/calibration/VelmaCalibration.properties/co2RespirationFraction, 0.98
/calibration/VelmaCalibration.properties/deg_lat, 38.867914
[ ... ]

The easiest way to search a SimulationConfiguration.csv file is with the find or search feature of Excel or a text editor:

  1. Open the SimulationConfiguration.csv file in an editor or in Excel.
  2. Using the editor or Excel's search function, search for the parameter's short name. Doing so should locate the row of the SimulationConfiguration.csv file containing the fully-qualified name (since the short name is always part of the fully-qualified name).
  3. Use the fully-qualified name in place of the short name when you specify your --kv option.

You can also search a SimulationConfiguration.csv file directly from a PowerShell console, using the Select-String cmdlet.
Here is an example:

PS C:\Users\meep> Select-String -Pattern "/be," C:\Users\meep\Velma_Results\MD_ws109\SimulationConfiguration.csv

The above command line searches the SimulationCongfiguration.csv file partially display above, for the fully-qualified name of the be parameter.
Always include the leading forward-slash (/) and trailing comma (,) with the parameter short name you're looking for -- e.g. search for "/be,", not "be".
Select-String is a general-purpose text search tool, and it may return many lines that you don't care about if you omit the / and ,, or add space between them and the parameter name. Adding space before the / or after the , will also throw off the search results. As just two examples among many, neither "/ be," nor "/be, " would return any result if we tried them on our SimulationConfiguration.csv file.

Select-String outputs its results to the console.
The output for the example search above looks like this:

C:\Users\meep\Velma_Results\MD_ws109\SimulationConfiguration.csv:6:/calibration/VelmaCalibration.properties/be, 6.33974

This is Select-String's default results format. for line in the file containing /be,, it reports the file's path/name, the line number, and the line itself, using : as a separator.
The following example repeats the search with a bit of syntax that forces Select-String to report the lines it finds without the file or line number information:

PS C:\Users\meep> (Select-String -Pattern "/be," C:\Users\meep\Velma_Results\MD_ws109\SimulationConfiguration.csv).Line

This variation of the search command returns the following result to the console:

/calibration/VelmaCalibration.properties/be, 6.33974

Notice that this is almost exactly what the --kv switch requires to specify its , pair.
You could ...

  1. Copy the above search result.
  2. Enclose it in double-quotes (").
  3. Remove the whitespace after the comma.
  4. Change the old value to a new, different value.
  5. Prefix it with --kv=

... and you'd have a correctly-specified --kv option item:

--kv="/calibration/VelmaCalibration.properties/be,3.125"

As a final example, the full command line below invokes VelmaSim and includes two --kv options.
The first --kv option sets a new be value, and the second changes the run_index name. In this example when VelmaSim initializes and runs, it will set be=3.125 regardless of its value in OR_BlueRiver_ws10.xml, and will write the results to a results folder named "new_be-OR_BlueRiver_ws10" (at the output location specified in OR_BlueRiver_ws10.xml -- the output root directory path has not been overridden in this example).
This example also illustrates a useful feature of the PowerShell command line: using the backtick (`) character to split a long command across multiple lines:

PS C:\Users\meep> java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar `
>> gov.epa.velmasimulator.VelmaSimulatorCmdLine `
>> C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml `
>> --kv="/calibration/VelmaCalibration.properties/be,3.125" `
>> --kv="/calibration/VelmaInputs.properties/run_index,new_be-OR_BlueRiver_ws10"

When you type a command into the PowerShell console at the command prompt (>), if you end the line with a backtick character (`), then instead of running your (incomplete) command, PowerShell opens a new line, displays the prompt (>>) and waits for you to type more of the command. PowerShell will continue to do this until you end a line without a backtick character. It will then run your command.

Using the backtick character for command-line continuation makes it easier review long commands before running them, however, it can be tricky to get right. Remember the following rules:

Appendix A: Common Command-Line Errors

The VelmaSim command line is easily broken by mistyped commands, and because commands can easily become long, they can be easy to mistype.
Moreover, VelmaSim is terse and abrupt when it encounters a command line that it does not understand, which can make it difficult to determine the cause of an error.

This appendix contains an ad-hoc collection of common command line error descriptions as a cautionary quick-reference.

Java Errors

The arguments on the command line after java and before gov.epa.velmasimulator.VelmaSimulatorCmdLine are used by the Java runtime engine, not by VelmaSim.

Ommiting the -Xmx size suffix

The -Xmx argument allows you to specify a memory amount. Typically, VelmaSim likes at least a Gigabyte of memory, and that is specified as -Xmx1g -- "1" with "g" indicating "Gigabyte". If the "g" is ommitted, the following is likely to happen:

PS C:\Users\meep> java -Xmx1 -cp C:\Users\meep\VELMA\JVelma.jar gov.epa.velmasimulator.VelmaSimulatorCmdLine
Error occurred during initialization of VM
Too small initial heap
PS C:\Users\kdjang\Velma_GitHub>

Misspelling VelmaSim's fully-qualified name

In this example, VelmaSim's fully-qualified name is misspelled:

PS C:\Users\meep> java -Xmx1 -cp C:\Users\meep\VELMA\JVelma.jar gov.epa.velmasimulator.VelmaSimulatorCmdLine
Error: Could not find or load main class gov.epa.velmasimualtor.VelmaSimulatorCmdLine
PS C:\Users\kdjang\Velma_GitHub>

This is self-explanatory, but very easy to do, and surprisingly difficult to catch before Java complains about it.

Specifying a missing or inaccessible .jar file

The following example misspells the .jar file name:

PS C:\Users\meep> java -Xmx1 -cp C:\Users\meep\VELMA\JVelm.jar gov.epa.velmasimulator.VelmaSimulatorCmdLine
Error: Could not find or load main class gov.epa.velmasimualtor.VelmaSimulatorCmdLine

The error message is the same as for the previous error, but in this case, VelmaSim's fully-qualified name is spelled correctly.

Omitting -cp

An example is the clearest way to describe this situation:

PS C:\Users\meep> java -Xmx1 -cp C:\Users\meep\VELMA\JVelm.jar gov.epa.velmasimulator.VelmaSimulatorCmdLine
Error: Could not find or load main class C:\Users\meep\VELMA\JVelm.jar

This looks a lot like the two previous error messages, but notice that the "main class" is specified as the name of the JVelma.jar file. Without the -cp argument, Java has assumed that the fully-qualified "class" we want to run is the .jar file itself, which is incorrect, we want to run the gov.epa.velmasimulator.VelmaSimulatorCmdLine code contained inside the .jar file. (In effect, the -cp argument indicates to Java, "look in what follows me to run what follows it: -cp .)

VelmaSim Errors

Everything on the command line after gov.epa.velmasimulator.VelmaSimulatorCmdLine is used by VelmaSim.

Specifying a missing or inaccessible simulation configuration.xml file

When VelmaSim cannot find or open the simulation configuration .xml file you specify, it stops abruptly.

Omitting the simulation configuration .xml file, but including options

When you provide no arguments after gov.epa.velmasimulator.VelmaSimulatorCmdLine , VelmaSim displays the usage message.
However, if you provide any arguments, exactly one of them must be a valid simulation configuration .xml file.
Here's an example that specifies the --lint option, but does not specify an .xml file:

PS C:\Users\meep> java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar gov.epa.velmasimulator.VelmaSimulatorCmdLine --lint
FAIL! exception="java.lang.IllegalArgumentException: No simulation configuration .xml file specified."
FAIL! message="No simulation configuration .xml file specified."
FAIL! VELMA simulation run halted, configuration="null"
java.lang.IllegalArgumentException: No simulation configuration .xml file specified.
        at gov.epa.velmasimulator.VelmaSimulatorCmdLine.main(VelmaSimulatorCmdLine.java:93)

Misspelling an option name

Understandably, VelmaSim will not run if you specify an option and misspell its name.
However, the error message it reports for this situation may be surprising and confusing.
Here is an (PowerShell multi-cmdline) example with --kv misspelled as kc:

>> PS C:\Users\meep> java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar `
>> gov.epa.velmasimulator.VelmaSimulatorCmdLine `
>> C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml `
>> --kc="/calibration/VelmaInputs.properties/run_index,new_be-OR_BlueRiver_ws10" `
>> --lint
>>
FAIL! exception="java.lang.IllegalArgumentException: Multiple simulation configuration .xml files specified."
FAIL! message="Multiple simulation configuration .xml files specified."
FAIL! VELMA simulation run halted, configuration="C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml"
java.lang.IllegalArgumentException: Multiple simulation configuration .xml files specified.
        at gov.epa.velmasimulator.VelmaSimulatorCmdLine.main(VelmaSimulatorCmdLine.java:86)

VelmaSim catches the misspelling, but identifies it as a second simulation configuration .xml file. This happens because VelmaSim assumes everything on the command line (after gov.velmasimulator.VelmaSimulatorCmdLine ) that isn't identified as an option is a simulation configuration .xml file (even if it doesn't end in ".xml") The same error message occurs (less confusingly) for a command line with no options but two or more simulation configuration .xml files. So, when you see the "Multiple simulation configuration .xml files specified." failure message, but your command line only contains one .xml file, check any options for spelling errors.

Providing an invalid parameter key for a --kv option

VelmaSim also will not run when a --kv option's fully-qualified parameter name is mispelled, or when that name does not exist in the specified simulation configuration.xml.
Here is an example with a slight misspelling ("propertie" instead of "properties"):

>> PS C:\Users\meep> java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar `
>> gov.epa.velmasimulator.VelmaSimulatorCmdLine `
>> C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml `
>> --kv="/calibration/VelmaInputs.propertie/run_index,new_be-OR_BlueRiver_ws10" `
>> --lint
>>
Applying: key=|/calibration/VelmaInputs.propertie/run_index| val=|new_be-OR_BlueRiver_ws10|
FAIL! exception="java.lang.NullPointerException"
FAIL! VELMA simulation run halted, configuration="C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml"
java.lang.NullPointerException
        at gov.epa.velmasimulator.SimulationConfiguration.setProperty(SimulationConfiguration.java:864)
        at gov.epa.velmasimulator.VelmaSimulatorCmdLine.main(VelmaSimulatorCmdLine.java:102)

Unhelpfully, VelmaSim does not explicitly identify the problem as a misspelled parameter name, and a "java.lang.NullPointerException" can be caused by other errors.
However, when you see a FAIL! exception="java.lang.NullPointerException" message shortly after an "Applying: key=..." message, carefully check the spelling of that key name, and verify that it exists in the simulation configuration .xml file.

Omitting part of the full syntax for a --kv option

If you omit part of a --kv option's syntax, VelmaSim may or may not fail to run: what happens depends on what you omit.
Here is an example that is only missing the portion:

>> PS C:\Users\meep> java -Xmx1g -cp C:\Users\meep\VELMA\JVelma.jar `
>> gov.epa.velmasimulator.VelmaSimulatorCmdLine `
>> C:Users\meep\VelmaConfigs\OR_BlueRiver_ws10.xml `
>> --kv="/calibration/VelmaCalibration.properties/be," `
>> --lint
Applying: key=|/calibration/VelmaCalibration.properties/be| val=||
VELMA LINTER: started at 2021-10-29 15:23:57
WARNING VelmaSimulatorEngine runLinter: VELMA Lint Mode Enabled: startups parameter suppressAllOutputFiles overridden and set == true
SEVERE GlobalState initializeCalibration: Model Calibration Initialization FAILED
SEVERE GlobalState initializeCalibration: Please check the status of the VelmaCalibration.properties file.
SEVERE GlobalState initializeCalibration: Exception was:
SEVERE GlobalState initializeCalibration: empty String
SEVERE VelmaSimulatorEngine initForSetup: FAIL! Cannot initialize Global State Object.
SEVERE VelmaSimulatorEngine runLinter: FAIL! The linter itself experienced an error: exception=java.lang.RuntimeException: FAIL! Cannot initialize Global State Object.
VELMA LINTER: done at 2021-10-29 15:23:57

In this case, VelmaSim got to the comma separator after the (valid) and found an empty string which it accepts as a parameter value. But, when VelmaSim initialization code starts, it rejects the empty string as a value for the be parameter, and at that point, and error occurs.

In contrast, suppose the comma between the and is omitted:

--kv="/calibration/VelmaCalibration.properties/be 2.5"

You might expect that substituting this into the comand line above would produce a similar sort of error. In fact, it produces no error at all. Instead, VelmaSim takes this to mean you want to set a parameter with the short name "be 2.5" equal to "". The attempt fails, but VelmaSim does not mention it.

Finally, suppose you forgot one of the paired double-quotes (typically, the right-side d-quote gets dropped). This situation is usually caught by PowerShell itself: it will won't consider your command line input complete until you add the missing double-quote. Pressing the Enter key in the meantime simply returns a new (>>) prompt.

Providing an invalid value for a --kv option

VelmaSim does not provide any special validation for the values specified in --kv options. If you provide a valid parameter name, VelmaSim will replace that parameter's value with the value you specify regardless of how valid or appropriate it is for that parameter. Many invalid values are still caught just after the command line is processed, during initialization. (See the "Omitting part of the full syntax for a --kv option above for an example.) Some of these will cause initialization to fail, but some will only incur a WARNING log message -- your simulation will still start, and will either crash or run to completion with invalid results.
Using the --lint option to check for this sort of situation is highly encouraged.