Configuring the report generator

The SKaMPI report generator version 3.0, normally named dorep3.pl, is a Perl script which can be made executable and then directly started. This is only possible if the first line of the script contains the correct path to the Perl executable. Please change it as needed. Otherwise the script's name has to be given as parameter to the Perl executable itself together with any parameters of the script (s. below).

Environment

Normally dorep3.pl searches for a file named .dorep in the current directory for information about options and suite comparisons. If the environment variable DOREP is set to an existing file this one is searched instead.

Command line options and options in the .dorep file

There are several options for the report generator. They can be specified in the .dorep file or at the command line. First the options in the .dorep file are read so that they possibly are overruled by the command line options.

CAUTION: The options -o and --overwrite of version 2.0 of the script are no longer valid. Temporary .tmd and .gpl files are overwritten by default since version 2.1. So, consequently, there are two new options -u respectively --use_temp (having the same meaning again) which tell the script to use existing files of the types .tmd and .gpl.

Here's a table which explains the possible options and their default values:

OptionParameterExplanationDefault value
-b or --barchart s. below tells the script to produce barcharts for node times for certain measurements min and max values for each known variation param.
-d or --dri_directory pathname path of directory where dorep information (.dri) files reside current directory
-h or --help   print a help text and quit  
-m or --minimum_data number number of data from which on charts are created instead of tables 4
-p or --output filename write messages in file (warnings and output of dvips are written on standard error) no file, but standard output
-q or --quiet   only print warnings print warnings and some informative messages
-Q or --very_quiet   don't even print warnings (only dvips output) s. -q
-t or --keep_temp   keep all temporary files the report generator has created all temporary files are deleted (only the resulting .ps file is kept) unless an error occurs
-T or --delete_temp_on_error   delete temporary files even when an error occurs s. -t
-u or --use_temp   use existing temporary files (only .gpl and .tmd files; others are still overwritten) existing files are overwritten
filename   name of SKaMPI output file skampi.out

The -m or --minimum_data option takes a number greater than or equal to 2, because graphical output for one data point doesn't make much sense.

If you configure the script to keep the temporary files, there will be a script called kill_temp in the current directory after the script has finished. Executing it will delete all the temporary files so that you can clean up when you don't need them any more.
NOTE: If an error occured, it's possible that some of the files to be deleted could not be included in kill_temp.

Parameters for the -b and --barchart options

With these options you can determine the values of the variation parameters for which bar charts for the respective node times should be created. The options are followed by a list of values for some or all variation parameters. The entries for the individual variation parameters have to be divided by a semicolon. Each entry consists of the variation parameter name (with underscores (_) instead of spaces) followed by a space and the list of values separated by commas.

The values can be numbers (integers for the known variation parameters) or the strings min, max or none. min and max stand for the minimum and maximum values of the variation parameter in a suite of measurements respectively. These are the first and last lines of a suite respectively. With the value none you can tell the report generator that you aren't interested in bar charts of the node times for the specified variation parameter. Of course, none only makes sense if it's the only value for the variation parameter.

Default values are min and max for all known variation parameters.

Here are some examples to make it clearer:

  1. Say, you only want bar charts for minimum, 4 and 8 bytes of message length and 5 and 10 nodes. Here's the appropriate line in the .dorep file:
    -b message_length min, 4, 8; number_of_nodes 5, 10; chunks none
  2. Say, you want bar charts for minimum and maximum bytes of message length and nodes and for 10 and 20 chunks. Here's the .dorep line:
    -b chunks 10, 20

If you specify one of these options at the command line you have to make sure that the parameters for the option must be one single parameter at the command line. So you have to enclose the parameters in quotes.

For example:
> dorep3.pl -b 'message_length min, 2, max; number_of_nodes 2, 4' skampi.out

Further options in the .dorep file

Empty lines and comments (lines starting with #) in the .dorep file are ignored.
Lines containing letters surrounded by square brackets [] (with the opening bracket being the very first character of this line) start a section.
The following sections exist:

Lines after any such line belong to the section specified by that line. A section ends with another section line or the end of the file.

The Options section contains (as you might have guessed) the options described above.

The Comparisons section contains description lines for SKaMPI suites to be compared. The report generator uses these lines to create comparisons of suites in the appropriate section of the output Postscript file.
The first part of the line is the name of the report section to be created. It must not contain any colon (:) because a colon marks the end of the section name.
The colon is followed by a comma-separated list of suites of measurements to be compared. The names of these suites consist of the abbreviation of the pattern of the suite, an underscore and the name of the MPI routine (see the sample .dorep file in the distribution).

The Suites section contains the suites to be shown in the non-comparison part of the report. The format of the suite names is the same as in the Comparisons section. Each name has to appear in one line.
If the section exists, only the specified suites (if found in the SKaMPI output file) will be shown. So if the section is there but it's empty, no suites will be shown in the non-comparison part.
If the section does not exist, all suites, that can be found in the SKaMPI output file, will be shown (if there's no Exclude section; s. below).
The suites given in this section have no effects on suites appearing in the Comparisons section. If a suite is given there, it will be shown in the comparison part of the report in any case (but not if the suite doesn't fit the other suites it shall be compared with or if it doesn't exist at all, of course).

The Exclude section contains suites not to be shown in the non-comparison part of the report. Other suites found in the SKaMPI output file are shown.
Again, suites in this section have no effects on suites in the Comparisons section.

Since it doesn't make sense in specifying both a Suites and an Exclude section, the last appearing in the `.dorep' file is decisive.
Apart from that, the order of the sections is irrelevant. Besides the case of the letters of the section names is also insignificant.

Exit value

The dorep script exits with 0 when there haven't been any errors and with 1 otherwise.


For further information about additional LaTeX modules, changing the look of the graphs and the dorep information (.dri) files see the user manual which can be found at http://wwwipd.ira.uka.de/~skampi/.

If you have any questions or discover any errors, please feel free sending an email to Gunnar Hunzelmann or Ralf Reussner.

Have fun.