Standard Mode

Normally, Drone is invoked using the line

drone controlFile

Drone is configured by setting a number of parameters in a control file. An example control file is given in Section 3.1.3 and in the file examples/stublet/stublet.ctrl. Do not run Drone in the background using bg or &; set the background parameter to 1 in the control file instead.

Drone is a tool for automatically executing batch runs of a target program. A run is defined as a single execution of the target program. If useLocalHost is 1, the runs are executed on the single computer that is running the Drone script; otherwise, Drone also needs a host file, which lists the names of a set of usable hosts on the Internet. A sample host file is given in Section 3.2.2 and in the file examples/stublet/stublet.hosts. Only one run is executed on a host at a time, and runs are assigned to free hosts in the order in which they appear in the host file. The user must have an account on each host, with the same login ID and password for all of them. Furthermore, the target program must be installed at the same path on all of the hosts.

The target program is configured by giving it a set of command-line options, as well as an optional input file, if the makeInputFile parameter is 1. The input file is specified by the user as part of the control file.

A case or parameter set is a set of runs that are executed using the same set of target program parameters. Each run in a case has a unique run seed. The run seeds are generated by Drone using an internal random number generator; this generator is initialized using an experiment seed specified in the control file. If the experiment seed is set to an empty string in the control file, it is generated by multiplying the system clock's current value times Drone's process ID. Multiple runs with the same parameters but using different seeds are useful for collecting statistics about a stochastic target program's behavior under those settings. Each case has a case log file, which lists the actual Bourne shell (sh) commands that Drone used to start the runs, including the run seeds.

An experiment is a set of one or more cases, defined by a single control file. Experiments may include a sweep over a set of sweep parameters; each set of sweep parameter values defines a separate case. Drone writes an output control file for every experiment; this file is identical to the original control file, but it contains the parameters that were actually used in the experiment, including the experiment seed. It is located at the path

outputControlDir/outputControlFile

where outputControlDir and outputControlFile are parameters specified in the control file.

Each case is stored in a separate case directory at the end of the experiment. This directory contains the results from each run in the case, along with the case log file. The case directory's name is formed by concatenating the sweep parameters' names together with their values for that particular case. If no parameters are being swept, there is only a single case, and its directory is named caseDir.

The directory in which a run is executed is called the output directory for that run. This is where the target program stores the output files that it creates during the run. If useTmp is 1, the output directory is contained on a local disk in the directory named by tmpPath (normally /tmp), at the path

tmpPath/experimentName-processID/caseName

where processID is Drone's process ID, the parameter experimentName is set in the control file, and caseName is the name of that case. Not all runs from a single case will execute on the same machine if useLocalHosts is 0, so they will not all run in the same output directory. After all of the runs have finished, the results for each case are then collated together on the computer that is running Drone, at the path

experimentDir/experimentName/caseName

where the parameters experimentDir and experimentName are set in the control file.

If useTmp is 0, then a run's output directory is the same as its case directory:

experimentDir/experimentName/caseName

This path is assumed to be on a shared disk or remote file system such as AFS. It is the same directory where the results for that case will be stored at the end of the experiment.

The input file used for the experiment is stored in the directory

experimentDir/experimentName

If the runs were executed on remote hosts, copies of this file also exist in each of the case directories.

If compressExperiment is 1, the results in the directory

experimentDir/experimentName

are tared and compressed at the end of the experiment; if compressExperiment and removeExperiment are both 1, the original, un-tared copy of the results is then deleted. If the Drone parameter mailUser is set to 1, Drone sends email to the address specified by emailAddr at the end of the experiment, or if an error occurs.

A series is a set of experiments that share a common series log file. This log file is located at the path

seriesLogDir/seriesLogFile

where seriesLogDir and seriesLogFile are parameters that are set in the control file. The series log file is updated at the beginning of every experiment and gives a summary of how each experiment was configured, including some of the parameter settings, the input file, who ran it and when, the comments of the experimenter, and the location of the output control file. Note that this log is updated even if the experiment ends prematurely due to an error.