Running Origin

This chapter describes how to run Origin programs and set Origin program parameters. The easiest way to run an Origin program is to use the origin shell script or origin.bat Windows batch file to start Origin from the command line. These scripts are documented in The Origin Command Line Program.

Almost all of Origin's behavior is controlled by parameters read from parameter files or set on the command line. Parameters and the parameter file hierarchy are discussed in Parameters and Parameter Files.

Finally, Origin provides a checkpointing mechanism to save and restart an evolutionary run, described in Checkpoints.

The Origin Command Line Program

The origin shell script and origin.bat batch file in origin/bin run the main Origin program, setting the classpath and system environment variables to the correct values for your Origin installation. You must set your path to include the location of the java executable before running these scripts. The following command line options are supported:

-remote: Runs Origin Frontier tasks remotely on a Frontier® Grid Platform. Ignored if this program does not use one of the Origin grid models.
-local: Runs Origin Frontier tasks on the local machine. This is the default.
-classpath java-classpath: Appends classpath to the Origin classpath. Can be abbreviated -cp.
-Dproperty=value: Sets a system property.
-p parameter=value: Sets a parameter (compatible with ECJ).
-file parameterfile: Reads parameter-file. If the file does not exist and is a relative path Origin first looks in origin/conf/params for the file, and then searches the classpath for a resource of the same name (this means that parameter files can be contained in jar files). Parameter files are documented in Parameters and Parameter Files.
-checkpoint checkpointfile: Restarts an evolutionary run from checkpointfile. If this option is specified all other command line options except -classpath and JVM options are ignored. Checkpointing is described under Checkpoints.
-JVMoption: All other option flags are assumed to be JVM options and are passed through to the JVM used to run Origin.

Most Origin programs write a brief summary of their progress to standard output, with more detailed logging information written to the file origin.log in the current directory. You can change both the location and the level of logging by editing the Log4J configuration file origin/conf/origin.log4j.properties, or use a different Log4J configuration file by adding this file to the classpath and specifying -Dlog4j.configuration=configfile on the Origin command line. The Log4J configuration file format is documented on the Apache Log4J web site.

Parameters and Parameter Files

Almost all of Origin's behavior is controlled by parameters read from parameter files. Origin parameter files are similar to Java property files and are almost identical to ECJ parameter files. Parameters are specified one per line in the form:

name = value

(the deprecated ECJ form name value is not supported). Blank lines and lines starting with # are ignored. The parameter value consists of all characters following the = sign up to the line terminator, with leading and trailing whitespace removed. Parameter file values are overridden by values specified on the Origin command line using the -D or -p options.

Parameter Values and Interpolation

Parameter values may interpolate other parameter values, Java system properties, and field values from Java classes. The syntax for interpolating values is the same as that used in Ant build files: strings of the form ${parametername} are replaced by that parameter's value. If the named parameter does not exist the ${parameter} string is left unchanged. This example shows the different forms of parameter interpolation:

foo = 2
bar = 4${foo}
program_banner = This is ${java.vm.version} for ${os.name}
problem_type = ${const:ec.app.ecsuite.ECSuite.PROB_ROSENBROK}

The parameter bar has the value "42", while the value of program_banner includes the JVM version and and OS name from the Java system properties. In the last case the const: prefix in the interpolation name indicates that this is a reference to a Java field rather than a parameter value; in this case PROB_ROSENBROK in the Java class ec.app.ecsuite.ECSuite. Interpolated Java fields must be declared static final.

Parameter values are interpreted as one of the following data types:

Strings.: Leading and trailing whitespace is removed, and Unicode escape sequences (\uXXXX) are converted to their corresponding characters.
Class names.: Processed as strings, must specify a fully-qualified Java class name.
Integers.: Parsed according to the rules in the Java Language Specification: if the value begins with 0x or 0X it's parsed as a hexadecimal integer, while if it starts with a leading zero it's treated as an octal number. Anything else is considered a decimal integer. For compatibility with existing ECJ parameter files a value starting with a leading x or X not preceded by a zero is parsed as hexadecimal.
Floating-point Numbers.: Parsed according to the rules for floating-point numbers in the Java Language Specification: both decimal fractions and "scientific notation" are permitted.
Booleans.: Value must be either the true or false.
File and directory pathnames.: Parsed as strings. Relative pathnames are interpreted relative to the directory of the parameter file containing the parameter. For compatibility with ECJ a relative pathname that starts with a $ is interpreted relative to the current directory.

The Parameter File Hierarchy

Origin parameter files can use the parent property to include additional parameter files:

parent.n = pathname

where n is an integer starting at 0 and increasing by 1 for each parent parameter file. If a parameter is not found in a parameter file its parent parameter files (including any of their parents) are searched in depth-first sequence. This makes parent parameter files useful for setting default values and common parameters used by more than one program.

pathname is treated like any other pathname parameter- relative pathnames are interpreted relative to the directory containing the parameter file, and parameters may be interpolated into the pathname value. This allows a couple of common idioms:

parent.0 = ../common.params

myprogram.dir = /home/program/default/parameters
parent.1 = ${myprogram.dir}/program.params

In the first example a common parameter file is read from the parent directory of the containing parameter file. The second example is a more complex: first myprogram.dir is set to the path of a directory containing parameter files, and then program.params is read from this directory. If we wanted to load a different version of program.params we could use the -D command line option to point myprogram.dir to the directory containing our alternate version:

origin -Dmyprogram.dir=/home/mystuff/parameters ...

and /home/mystuff/parameters/program.params would be read instead of /home/program/default/parameters/program.params. Note that using -p parameter=value flag instead of -D won't work, because -p parameter settings aren't applied until after all parameter files are read. Origin sets the parameter origin.parameter.dir to the path of the origin/conf/params directory in the Origin installation.

Checkpoints

Some Origin evolutionary runs may take hours or days to complete. Origin provides a checkpointing mechanism that periodically saves the current state of the run to a file, and permits Origin to be restarted from an earlier checkpoint if the program is killed before the evolutionary run completes.

Checkpointing is enabled by setting the parameter checkpoint to true and checkpoint-modulo to the interval in generations between checkpoints. For example, invoking Origin with these flags:

origin -Dcheckpoint=true -Dcheckpoint-modulo=10 ...

will save a checkpoint every 10 generations. Checkpoints files are saved in the current directory of the Origin program and have names of the form ec.generation.gz. To restart a run from a checkpoint start Origin with:

origin -checkpoint checkpointfile

The evolutionary run will restart from the generation saved to that checkpoint. Origin will continue to checkpoint after being restarted, so an evolutionary run may be killed and resumed multiple times. Checkpoint files can be large, so you may want to periodically delete all but the most recent checkpoint.