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).
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.
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:
| Option | Parameter | Explanation | Default 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.
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:
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
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:
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.
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.