Running an Experiment

Once the lab environment has been set up, one needs to run the experiment and record the data necessary to be able to reproduce the experiment later. The tool labrun accomplishes this. There are three main tasks performed by labrun

• it assures that the source code has been ``fixed'';
• it records the context of the experiment;
• it runs the experiment.

In its simplest form, labrun is executed in a directory containing the source code for the experiment's executable. For example:

    labrun steiner -v closed 41 30

will cause the following two things to happen:

• a command cvs status is issued in the current directory to assure that the source code in the current directory (which presumably is the source code used to produce the program steiner) is up to date.
• if the source is up to date, the program steiner will be executed using the arguments -v closed 41 30.

The labrun tool will generally create at least two files: one that contains the output of the experiment (the .out file) and another that records the information about the environment in which the output was created (the .log file; see Section ). Additionally, a file with extension .err may be generated if the experiment program writes output to the error stream. The .out and .err files are generated only if the program writes output to the standard output and standard error streams, respectively. The .log file is always generated. The names of the generated files all have the same format: <exp_name>-<date and time>.<ext>, where <date and time> has the format YYYY-MM-DD-HHMMSS and <exp_name> is, by default, the name of the executable used by logrun. By default, these files are created in a subdirectory lab_log in the current directory. For the example above, the name of the log file would be something like ./lab_log/steiner-2002-05-21-093412.log. This file is also accessible as ./lab_log/current.log, which is a link to the most recent log file. Such a ``current'' link is created for each of the three possible files generated by labrun, thus making it easier to examine the results of the last experiment or to observe the progress of the current experiment as it is running.

Some of the options available for labrun allow one to specify

• the location of the CVS directories corresponding to this experiment,
• a different location for the .log, .out, and .err files,
• a name other than the executable to use for the experiment in the created output files,
• a tag other than the <date and time> to use in the files created.

For example, altering the above command as follows:

    labrun --cvs .:/home/hert/src --log ../lab --name example 
           --tag closed_41_30 steiner -v closed 41 30

will check if the code in the current directory as well as the directory /home/hert/src is up to date and, if so, will execute the program steiner in the current directory. It will place the created log and output files in a subdirectory lab in the current directory's parent directory, creating this subdirectory if it does not already exist. The files created will use example for <exp_name> and closed_41_30 instead of <date and time> in the name. Thus the name of the log file for this experiment would be ../lab/example-closed_41_30.log.

Other options for labrun allow one to indicate: that no CVS directories should be checked; that the program should be executed in a different directory; that a specific version of the source code should be used instead of the current one (particularly useful in conjunction with labmex); additional things to be recorded in the .log file; that all output from the experiment should be recorded in a single file (the .log file) instead of spread over possibly three files (the .log, .out, and .err files); and that the experiment should be run in the background and should notify the user upon completion.

Options may also be specified via a local or global resource file (Section ). Such resource files are searched for when processing the input for labrun and, if present, the information recorded there will be used to augment the input provided at the command line. In cases of conflict, command-line arguments take precedence over data provided in the local labrc file, which takes precedence over data provided in the global .labrc file.