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