Drone 1.01 README file by Theodore C. Belding The CAR Group (Michael Cohen, Robert Axelrod, and Rick Riolo) University of Michigan Program for the Study of Complex Systems November 13, 1996 Drone homepage: Drone email list: To subscribe or unsubscribe to the list: INTRODUCTION This document gives a quick introduction on how to install and use Drone. Everything in this README file is also in the Drone User's Guide. If you read that, you don't need to read what follows. See the User's Guide for full information on using Drone. WHAT IS DRONE? Drone is a tool for automatically running batch jobs of a simulation program. It allows sweeps over arbitrary sets of parameters, as well as multiple runs for each parameter set, with a separate random seed for each run. The runs may be executed either on a single computer or over the Internet on a set of remote hosts. Drone is written in Expect (an extension to the Tcl scripting language) and runs under Unix. It was originally designed for use with the Swarm agent-based simulation framework, but Drone can be used with any simulation program that reads parameters from the command line or from an input file. COPYRIGHT INFORMATION Drone is copyright (C) 1996 by the Regents of the University of Michigan. This is free software; you can redistribute and modify it under the terms of the GNU General Public License. This software comes with absolutely no warranty. See the file COPYING for details and terms of copying. INSTALLING DRONE You can download the current version of Drone from the Drone homepage: Drone is written in Expect, a Tcl extension, and requires that Expect be installed. You don't need to install Tcl or Tk to use Drone, and Expect only needs to be installed on the machines that you will use to run the Drone script itself. Drone has been tested under Expect versions 5.17.7 and 5.20.13, on Sun workstations running Solaris and on HP workstations running HP-UX. It should work under any version of Expect covered in Exploring Expect. Expect is currently available only for Unix. You can find Expect on the Web at the Expect homepage: You also need an ANSI C compiler, such as gcc, in order to compile the example application Stublet. gcc is available at: Once you have installed Expect, you must change the first line of the file drone to: #! where is the full path where Expect is located on your system. Now type % make install CC= in the top-level directory of the Drone distribution, where is the name of the ANSI C compiler on your system (for instance, gcc). That's it! Drone is now installed. To test your installation, type % drone -v and you should get Drone's current version number. Type % drone -h and you should get usage information. GETTING THE DOCUMENTATION The Drone User's Guide is contained in the doc directory of the Drone distribution, in LaTeX 2e, PostScript (for both US Letter and A4 paper), and HTML formats. The LaTeX 2e version will not work with LaTeX 2.09. To produce a version in DVI format, for US Letter paper, type % make dvi This will produce the file doc/latex/drone.dvi The PostScript version of the User's Guide, for both US Letter and A4 paper, is included in the Drone distribution. To remake the US Letter version from the LaTeX 2e source, type % make ps which will produce the file doc/postscript/drone.ps To read the HTML version of the User's Guide, point your browser at the file doc/html/drone.html The User's Guide is also available on the Drone homepage in LaTeX 2e, PostScript (for both US Letter and A4 paper), and HTML formats: A CONCRETE EXAMPLE If you would like to see how to use Drone, or if you would like to test your installation, there is a simple stub application named Stublet that is designed to exercise Drone. All Stublet does is parse its command-line options, read an input file, sleep for an interval specified by the parameter sleepInt, and then output two files named report. and popdump., where is the current run. Stublet is written in ANSI C. When you install Drone, you also compile Stublet. If you need to install Stublet on other hosts, you can type % make install CC= in the examples/stublet directory, where is the name of the ANSI C compiler on your system (for instance, gcc). To see how Stublet operates, type the following lines: % cd examples/stublet % stublet -Istublet.in -batchmode -Nrun1 -S123456789 -Dparam1=7 \ -Dparam2=orange -Dparam3=0.5 -Dparam4=1 This tells Stublet to run in batch mode (actually Stublet's only mode), to read the input file stublet.in, that the current run is run1, and that the run seed is 123456789 (the seed has no effect on Stublet's operation). Then the parameters param1, param2, param3, and param4 are set to dummy values; these parameters also have no effect on Stublet's execution. The sample input file stublet.in contains the line # set sleepInt = 10 which causes Stublet to sleep for 10 seconds. Stublet reads in stublet.in, sleeps for 10 seconds, and then produces the files report.run1 and popdump.run1. You can get usage information for Stublet by typing % stublet -h and version information by typing % stublet -batchmode -v Now that you've seen how Stublet works, let's use Drone to do an experiment using Stublet. Go back to the top-level Drone directory. % cd ../.. Next, edit the control file examples/stublet/stublet.ctrl. You will need to change the line param rootDir = so that is the full path where you would like the results and other directories to be stored. For now, you can simply set rootDir to be the full path where you have installed Drone. You can then use the string $rootDir in any of the paths in the control file, and $rootDir will be replaced by the value of rootDir. If necessary, change the line param programDir = $rootDir/examples/stublet to param programDir = where is the absolute path of the directory that contains Stublet on your system. Initially, programDir is defined relative to rootDir, but there is no need for this. You may also have to change the line param emailAddr = in the same control file to param emailAddr = Drone will notify you by email when the experiment has finished, or if an error occurs. By default, if emailAddr is set to an empty string, as in the first line, the email address that Drone uses to send you email is set to your login ID on the computer that is running Drone. After you have edited and saved the control file, type % drone examples/stublet/stublet.ctrl You should see something like the following: galilei% drone examples/stublet/stublet.ctrl Drone version 1.01 Started on Wed Nov 6 05:10:11 1996 Reading control file... Initializing... Running... Going into the background... galilei% After several minutes you should get an email notifying you that the experiment has finished. If you haven't changed any of the paths in the control file, the results should be stored in the directory examples/stublet/experimentDir/experiment-1. See the User's Guide for full details on what Drone does during an experiment, and on the files that are produced. To test Drone on a set of remote hosts, change the line param useLocalhost = 1 in the control file examples/stublet/stublet.ctrl to read param useLocalhost = 0 You also need to edit the host file examples/stublet/stublet.hosts so that it contains a list of available hosts on the Internet, one per line. You must have an account on each host, with the same login ID and password for all of them. Make sure that Stublet is installed on each of the hosts, and that it is located at the same path on all of them. If necessary, change the line param programDir = $rootDir/examples/stublet in the control file to param programDir = where is the absolute path where you have installed Stublet on the remote hosts. Then type % drone examples/stublet/stublet.ctrl in the top-level directory. You should see something like the following: galilei% drone examples/stublet/stublet.ctrl Drone version 1.01 Started on Wed Nov 6 05:18:53 1996 Reading control file... Initializing... login: Type your login ID for the remote hosts. Then you will get prompted twice for your password: login: streak Password: Re-enter password: After entering your password, you will see: Running... Going into the background... galilei% Again, you should get an email after several minutes telling you that the experiment has finished. The results should be stored in examples/stublet/experimentDir/experiment-2 If you get any error messages, see the User's Guide. Make sure that you have installed Expect and Drone correctly, that you have correctly modified the files examples/stublet/stublet.ctrl and examples/stublet/stublet.hosts, and that you have installed the Stublet application at the same path on each host. Congratulations! You've successfully used Drone on a single computer and on a set of remote hosts. For more information on how to use and configure Drone, see the Drone User's Guide. USAGE REFERENCE To run Drone: drone To do a dry run without running the target program: drone -d To collate incomplete results: drone -c To get usage instructions and descriptions of the control file parameters: drone -h To get version information: drone -v Do not run Drone in the background using "bg" or "&"! Set the background parameter to 1 in the control file instead. See the Drone User's Guide for full details.