Control File Syntax

 

This section describes the syntax of the control file. You can set Drone's parameters from the control file using the param command:

param parameter = value

If value is surrounded by double quotes ("value"), the quotes are stripped off. You can include whitespace in value by surrounding it with double quotes. You can set a parameter to an empty string simply by using the line

param parameter =

If a parameter is not set at all in the control file, Drone may set it to a default value, as noted in the parameter descriptions. Note that this is different from setting a parameter to an empty string. Any settings in the control file, including empty strings, override the default settings in the script. In general, you should explicitly set every parameter in the control file; the defaults are only meant to provide a safety net by setting the parameters to sane values initially. For some of the parameters, setting them to the empty string has a special meaning. For instance, if experimentSeed is set to the empty string in the control file, its value is generated by multiplying the current value of the system clock times Drone's process ID. An error is generated for certain parameters if they are not specified in the control file -- this is noted in the parameter descriptions. The parameters are described in Section 3.1.2. To get an online list of the parameters, along with full descriptions, type

% drone -h

or see the Drone source code. You shouldn't have to change most of these parameters, unless you are unhappy with their current values. The order of commands in the control file does not matter, but parameters must not be set more than once in the control file.

The Drone parameter rootDir should be set to the full path of the root directory for the experiment. You can then use the string $rootDir in any paths in the control file, and $rootDir will be replaced by the value of rootDir. Using $rootDir in path names is optional -- you can use full paths instead. Do not use ~ to stand for your home directory in any of the paths, since the Bourne shell sh will not understand this. You should also make sure that programDir and programFile point to the correct path, and that emailAddr is set to the correct value. If emailAddr is set to the empty string in the control file, it is set to the user's login ID on the computer that is running Drone.

If the Drone parameter makeInputFile is 1, Drone creates an input file for the target program and tells the target program where it is located using the command-line option specified by inputFileOption. You can specify the contents of this file by putting it between the lines begin input file and end input file in the control file. Drone doesn't parse this at all, so you can include any text that the target program will accept. This input file is then used for every run in the experiment.

You can also set program parameters from the control file using the set command:

set parameter = value

These parameters are dependent on the particular target program being used. They are set on the target program's command line, using the command-line option specified by the Drone parameter setParamOption, just like the sweep parameters (see below).

You can sweep a program parameter over a set of values, or a vector of parameters over a set of value vectors. Drone executes a case for each possible combination of the values and value vectors. To sweep a parameter over a set of values, use the form

sweep parameter value1 value2 ... valueN

To sweep a vector of parameters over a set of value vectors, use

sweep (p1 p2 ... pN) (v11 ... v1N) ... (vM1 ... vMN)

where the p's are program parameters and the v's are values. The parentheses are necessary. An arbitrary number of parameters and values may be swept.

For example, if param1, param2, and param3 are program parameters, then you could write:

sweep (param1 param2) (0.1 red) (0.2 green) (0.3 blue)
sweep param3 10 11 12

If you set the parameter numRuns to 10 in the control file, those two lines would cause Drone to run ten runs of the target program for each of the nine cases in Table 1. Each run would use a different run seed.

  
Table 1: Example of a set of cases produced by the sweep command.

The target program must allow these parameters to be set using the command-line option specified by Drone parameter setParamOption.

Comments may be added to the series log file and the output control file by using the comment command

comment text

Abbreviations for program parameters may be defined using the abbrev command

abbrev parameter = abbreviation

These abbreviations are optional and program-dependent. They are then used in place of the full parameter names when constructing case names. If no abbreviation is specified, the full parameter name is used. Abbreviations are currently not used by Drone for specifying command-line options.

Any line in the control file beginning with the character # is a comment. Lines containing only white space are ignored. Any other line causes an error.