1. Start Options
JAMS offers two main graphical user interfaces:
- JAMS Launcher: providing functions to load, run and save models, to edit model parameters and to analyse model results.
- JAMS Builder: allowing to modify the structure of JAMS models (components used, spatio-temporal iteration and general control flow) and offering the functionality of the launcher.
In addition, a command line interface offers functionality for loading and running JAMS models.
These interfaces can be accessed by executing one of the starter scripts or executables in the root of the JAMS installation directory. Depending on the operating system used, the following options are available:
| Windows | Linux / OS X | |
|---|---|---|
| JAMS Launcher | jams.exe; jams.bat | jams.sh; jams.command |
| JAMS Builder | juice.exe; juice.bat | juice.sh, juice.command |
| Command line without GUI | java <JAVA_OPTIONS> -splash: -jar jams-starter.jar -n -m <MODEL_FILE> | |
If the starter scripts (.bat, .sh, or .command files) are used, Java start options have to be set by editing these script files and by inserting/changing the required option. If the Windows executables (.exe files) are used, Java options are provieded in the related parameter files jams.l4j.ini or juice.l4j.ini. The most important options are described below and are related to the amount of available memory and the location of platform-related dynamic libraries.
- For starter scripts, edit the script and update the -Xms and -Xmx options of the Java call to define initial and maximum Java heap space. The following example would set them to 100MB and 500MB, respectively:
java -Xms100m -Xmx500m -jar jams-starter.jar
To only set the upper limit of memory available for modelling, the -Xmx switch can be used standalone. To define MB and GB units, the “m” and “g” characters can be used.
- For executables, edit the jams.l4j.ini or juice.l4j.ini files stored next to the jams.exe and juice.exe files and enter desired values (one line per option), e.g.
-Xms100m -Xmx500m
- When running JAMS direcly from the command line, change it accordingly, e.g.
java -Xms100m -Xmx500m -splash: -jar jams-starter.jar -n -m <MODEL_FILE>
Use the -Djava.library.path option to define the location of platform-dependent dynamic libraries.
- For starter scripts, add the option to the Java call, e.g.
java -Djava.library.path=bin/linux64 -jar jams-starter.jar
- For executables, edit the jams.l4j.ini or juice.l4j.ini files stored next to the jams.exe and juice.exe and enter desired values, e.g.
-Djava.library.path=bin/linux64
2. JAMS Command Line Arguments
When starting JAMS the following command line arguments can be used:
| Short code | Long code | Function |
|---|---|---|
| -h | --help | Print help |
| -c | --config <config file name> | Load configuration from file |
| -m | --model <model definition file name> | Load model from file |
| -s | --snapshot <snapshot file name> | Load model from snapshot file |
| -n | --nogui | Suppress all graphical output |
| -p | --parametervalue <list of parameter values> | Provide parameter values divided by semicolons |
| -j | --parameterfile <parameter file name> | Load parameters from file |
2.1. JAMS without graphical output
In order to load and run a JAMS model from the command line, either use the available starter scripts or start JAVA directly:
./jams.sh -n -m data/j2k_gehlberg/j2k_gehlberg.jam
or
java -splash: -jar c:/jams/jams-starter.jar -n -m c:/jams/data/j2k_gehlberg/j2k_gehlberg.jam
2.2. Transferring Model Parameters during JAMS start
The command line argument -p/--parametervalue allows to easily set parameter values from command line by providing them as a semicolon-separated list (e.g. "0.1;7;1996-11-01 7:30 2000-10-31 7:30 6 1"). The assignment of these values to parameters of the JAMS model is done via their positioning in the list. For this purpose, wildcards have to be inserted in the model configuration file at those positions where the transferred parameter values are to be inserted. Those wildcards have the form "%x%", where x is a consecutive number starting at 0. In the example
./jams.sh -n -m data/j2k_gehlberg/j2k_gehlberg.jam -p "0.1;7;1996-11-01 7:30 2000-10-31 7:30 6 1"
the wildcard "%0%" in "data/j2k_gehlberg/j2k_gehlberg.jam" would be replaced by "0.1", then "%1%" by "7", and "%2%" by "1996-11-01 7:30 2000-10-31 7:30 6 1". In this way it is easily possible to assign given values to model parameters when starting JAMS, such as required in the batch processing of simulation runs.
A second option to achieve the same is via the -j/--parameterfile switch that allows to load a set of parameters from a file. Such a parameter file can be exported from JAMS Launcher or JAMS Builder and contains key/value pairs in the form "parametername=parametervalue", one of them in each line. These files have the standard file name ending "jmp" and can also be found in the output folder of a model's workspace after the model has been run. An example command line could look like this:
./jams.sh -n -m data/j2k_gehlberg/j2k_gehlberg.jam -j model.jmp