Target Program Requirements

 

All target programs must recognize at least three command-line options: one to specify the random seed, one to specify the run number (or a base filename or file suffix for the current run, that includes the run number), and one to set a program parameter to a specified value. In addition, if makeInputFile is 1, the target program must have an option to specify the input file's path. Finally, if getProgramVersion is 1, the program must also have a command-line option that makes it return the program version and then exit. The input file is guaranteed to be specified first, if there is one; the program must not make any other assumptions about the order of the command-line options. Drone invokes the target program from the output directory, so that the program will see the output directory as its current working directory. If an output directory must be specified in order to run the program, it can be set using the miscOptions parameter.

For example, if makeInputFile is 1, inputFileOption is -I, setParamOption is -D,
runNumOption is -N, runNumPrefix is run, runSeedOption is -S, and miscOptions is -batchmode, then Drone would invoke a target program named foo under the Bourne shell sh using a command something like

$ foo -Iexperiment1.in -Dpopsize=100 -Nrun1 -S123456789 \
-batchmode </dev/null >/dev/null 2>stderrlog.1 &

Drone uses the Bourne shell for compatibility across platforms, and to make redirecting output easier. The program foo should read the input file experiment.in, set the internal parameter popsize to 100, set the random seed to 123456789, and write all output to the current working directory. The program must include run1 as part of the filenames of all output files that it produces (this is necessary to avoid overwriting files from other runs in the same output directory). The text run1 could be used as a prefix, suffix, or any other part of the filename. The parameter runNumPrefix can be set to the empty string in the control file, in which case the target program is given just the run number, with no prefix. In the above example, the option -D is used to set the program's popsize parameter; Drone would use this option to specify the sweep parameters as well as any program parameters that are specified in the control file using the set command. Finally, the shell is told to redirect the stdin and stdout streams to /dev/null, and the stderr stream to a log file, stderrlog.1.

Note that it is not necessary for the target program to use a special syntax for the options specifying the input file, random seed, and run number parameters. For example, if setParamOption is -D, then you could set runSeedOption to -Dseed=, inputFileOption to -DinputFile=, and runNumPrefix to -Drun=, if the target program has parameters named seed, inputFile, and run, respectively. These parameters would then be set using the same syntax as any other program parameters, such as popsize. If a command-line option must be separated from its argument by whitespace or an equals sign, then this must be specified in the control file as part of the option string.

The target program must not exit with a non-zero return value or send output to stderr unless there really is an error. Anything printed to stderr will be put in the log file
stderrlog.runNumber and will cause Drone to abort the experiment. This log file is checked after the run is completed and deleted if it has nothing in it. A non-zero exit value will also cause Drone to abort. Output to stdout is not saved unless saveStdout is 1, in which case it is sent to a log file named stdoutlog.runNumber. The input file format is completely independent of Drone, except that it must be a text file; an input file is not used if makeInputFile is 0.

Continuing the example, if getProgramVersion is 1 and versionOptions is -v -batchmode then Drone would get the version of the target program foo at the start of an experiment with the command

$ foo -v -batchmode

The program must output a response to stdout that contains the word version or Version and the version number or string, separated by whitespace. A colon may follow the word version. For example, the following is a valid response

Foo version 3.14b27 by Wallace and Gromit, Ltd. Copyright (C) 1996.

Drone would then record the version as 3.14b27. If getProgramVersion is 0, the target program doesn't need to be able to provide version information.

If you then ran the output control file from the above example using foo version 4.2, Drone would generate an error, since foo version 3.14b27 is required. This is meant to guarantee that an experiment is replicated using exactly the same program that it was run with originally. To override this, simply set the programVersion parameter to an empty string in the control file.

You can run Drone in dry-run mode to see what command-line options your program must accept when using a particular control file; see Section 2.4.2 for details.