NAME
ParaGraph - performance visualization for MPI programs
SYNOPSIS
PG [-c | -g | -m] [-d hostname:0.0] [-e envfile] [-f trace-
file] [-o orderfile] [-r rgbfile]
DESCRIPTION
ParaGraph is a graphical display tool for visualizing the
behavior and performance of parallel programs that use MPI
(Message-Passing Interface). The visual animation of a
parallel program is based on execution trace information
gathered during an actual run of the program on a message-
passing parallel computer system. The resulting trace data
are replayed pictorially to provide a dynamic depiction of
the behavior of the parallel program, as well as graphical
summaries of its overall performance. The same performance
data can be viewed from many different visual perspectives
to gain insights that might be missed by any single view.
The necessary execution trace data are produced by MPICL
(available from http://www.epm.ornl.gov/picl), which uses
the profiling interface of MPI.
ParaGraph runs on any workstation supporting the X Window
System. It uses no X toolkit and requires only Xlib.
Although most effective in color, it also works on mono-
chrome and grayscale monitors. It has a graphical, menu-
oriented user interface that accepts user input via mouse
clicks and keystrokes. The execution of ParaGraph is event
driven, including both user-generated X Window events and
trace events in the input data file provided by MPICL.
Thus, ParaGraph displays a dynamic depiction of the parallel
program while also providing responsive interaction with the
user. Menu selections determine the execution behavior of
ParaGraph both statically (e.g., initial selection of param-
eter values) and dynamically (e.g., pause/resume, single-
step mode). ParaGraph preprocesses the input tracefile to
determine relevant parameters (e.g., time scale, number of
processors) automatically before the graphical simulation
begins, but these values can be overridden by the user, if
desired.
ParaGraph provides about 30 different displays or views, all
based on the same underlying trace data, but each giving a
distinct perspective. Some of these displays change dynami-
cally in place, with execution time in the original run
represented by simulation time in the replay. Other
displays represent execution time in the original run by one
space dimension on the screen. The latter displays scroll
as necessary (by a user-controllable amount) as visual simu-
lation time progresses. The user can view as many of the
displays simultaneously as will fit on the screen, and all
visible windows are updated appropriately as the tracefile
is read. The displays can be resized within reasonable
bounds. Most of the displays depict up to 512 processors in
the current implementation, although a few are limited to
128 processors and one is limited to 16.
ParaGraph is extensible so that users can add new displays
of their own design that can be viewed along with those
views already provided. This capability is intended pri-
marily to support application-specific displays that augment
the insight that can be gained from the generic views pro-
vided by ParaGraph. Sample application-specific displays
are supplied with the source code. If no user-supplied
display is desired, then dummy "stub" routines are linked
with ParaGraph instead.
The ParaGraph source code comes with several sample trace-
files for use in demonstrating the package and verifying its
correct installation. To create your own tracefiles for
viewing with ParaGraph, you will need MPICL, which is avail-
able from http://www.epm.ornl.gov/picl. The tracing option
of MPICL produces a tracefile with records in node order.
For graphical animation with ParaGraph, the tracefile must
be sorted into time order, which can be accomplished with
the Unix sort command:
% sort +2n -3 +1rn -2 +0rn -1 tracefile.raw > tracefile.trf
When using MPICL to produce tracefiles for viewing with
ParaGraph, set tracelevel(1,1,0) to produce the trace events
required by ParaGraph. You may also want to define tasks
using the traceevent command of MPICL to delimit sections of
code and assign them task numbers to be depicted by Para-
Graph in some of its displays as an aid in correlating the
visual simulation with your parallel program. ParaGraph
does not depict a distinguished HOST processor graphically
and ignores all trace events involving such a HOST, if any.
OPTIONS
The following command-line options are supported by Para-
Graph.
-c to force color display mode.
-d to specify a hostname and screen (e.g., hostname:0.0)
for remote display across a network.
-e to specify an initialization file (default: .pgrc).
-f (or no switch) to specify a tracefile name.
-g to force grayscale display mode.
-m to force monochrome display mode.
-o to specify an order file (default: .pgorder).
-r to specify a file containing RGB values of task colors
(default: .pgcolors).
By default, ParaGraph automatically detects the appropriate
display mode (color, grayscale, or monochrome), but a par-
ticular display mode can be forced, if desired, by the
corresponding command-line option. This facility is useful,
for example, in making black-and-white hardcopies from a
color monitor.
FILES
The following environment files can optionally be supplied
by the user to customize ParaGraph's appearance and
behavior. The default filenames given below can be changed
by the appropriate command-line options.
.pgrc defines the initial state of ParaGraph upon
invocation, including which menus and
displays are open and various options.
.pgorder allows the user to define an optional order
or alternative names for the processors.
.pgcolors allows the user to define the color scheme to
be used for identifying tasks.
The following files are provided in the ParaGraph distribu-
tion.
*.c several C source files.
*.h several include files.
Makefile.* sample makefiles for several machine
configurations, which should be modified to
incorporate the local location for Xlib, etc.
manual.ps a user guide in postscript format.
pg.man a Unix man page.
tracefiles a directory containing several sample
tracefiles.
u_* several directories containing example
application-specific displays.
SEE ALSO
A user manual for ParaGraph is provided in postscript form
along with the source code. Additional information is con-
tained in the article "Visualizing Performance of Parallel
Programs" in the September 1991 issue of IEEE Software,
pages 29-39, and in the technical report ORNL/TM-11813.
Documentation for MPICL is available in the technical
reports ORNL/TM-11130 and ORNL/TM-11616 as well as from
http://www.epm.ornl.gov/picl.
BUGS
Some of the displays are not restored when re-exposed after
having been partially obscured. Changing parameters dynami-
cally while the visual animation is active may give erratic
results. The apparent speed of visual animation is deter-
mined primarily by the drawing speed of the workstation and
is not necessarily uniformly proportional to the original
execution speed of the parallel program.
AUTHORS
Michael T. Heath and Jennifer E. Finger