Provided by: mpi-doc_1.2.7-9ubuntu1_all bug

NAME

       MPE -  MultiProcessing Environment

DESCRIPTION

       The  Multi-Processing Environment (MPE) attempts to provide programmers
       with a complete suite of  performance  analysis  tools  for  their  MPI
       programs  based on post processing approach.  These tools include a set
       of profiling libraries, a  set  of  utility  programs,  and  a  set  of
       graphical visualization tools.

       The  first  set of tools to be used with user MPI programs is profiling
       libraries which provide a collection of routines that create log files.
       These  log  files can be created manually by inserting MPE calls in the
       MPI program, or automatically  by  linking  with  the  appropriate  MPE
       libraries,  or  by combining the above two methods.  Currently, the MPE
       offers the following 3 profiling libraries.

       Tracing Library
              - This traces all MPI calls.  Each MPI call  is  preceded  by  a
              line  that  contains  the  rank in MPI_COMM_WORLD of the calling
              process, and followed by another line indicating that  the  call
              has completed.  Most send and receive routines also indicate the
              values of count, tag, and partner (destination for sends, source
              for receives).  Output is to standard output.

       Animation Library
              -  This  is  a  simple  form  of real-time program animation and
              requires X window routines.

       Logging Library
              - This is the most useful and widely used profiling libraries in
              MPE.   They  form  the basis to generate log files from user MPI
              programs.  There are currently  3  different  log  file  formats
              allowed  in  MPE.   The  default log file format is CLOG.  It is
              basically a collection of events with  single  timestamps.   And
              there  is  ALOG  which  is  provided  for backward compatibility
              reason and it is not being developed.  And the most powerful one
              is  SLOG,  stands  for  Scalable  LOGfile  format,  which can be
              converted  from  CLOG  after  CLOG  file  has   been   generated
              (preferred  approach),  or  can  be  generated directly when MPI
              program is executed (through setting the environmental  variable
              MPE_LOG_FORMAT to SLOG).

              The set of utility programs in MPE includes log format converter
              (e.g.  clog2slog), logfile print (e.g. slog_print)  and  logfile
              viewer  wrappers, logviewer, which selects the correct graphical
              tool  to  display  the  logfile  based  on  the  logfile’s  file
              extension.

              Currently,  MPE’s  graphical  tools includes 3 display programs,
              upshot for ALOG, jumpshot-2 for CLOG and  jumpshot-3  for  SLOG.
              The  logviewer  script  eliminates the need for user to remember
              the relationship of logfile formats to display programs.

CONFIGURATION AND INSTALLATION

       MPE can be configured  and  installed  as  an  extension  to  most  MPI
       standard compliant MPI implementations, e.g. MPICH, LAM, SGI’s MPI, HP-
       UX’s MPI and IBM’s MPI.  It has been integrated seamlessly  into  MPICH
       distribution,  so  MPE  will  be installed automatically during MPICH’s
       installation process.

       For details of configuring and building of MPE,  please  refer  to  the
       README file in the MPE source directory.

EXAMPLE MPE PROGRAMS

       As  previously  noted,  the  mpe  library  is  composed  of 3 different
       profiling libraries.   Each  MPI  implementation  requires  a  slightly
       different way in which to link with these libraries.  During configure,
       the link path and appropriate libraries are determined and assigned  to
       variables.   These  variables  are first substituted in the Makefile in
       the directory mpe/contrib/test .  The Makefile is then  installed  into
       directory  share/examples  during  the final installation process.  The
       following is a list of these variables.

       LOG_LIBS   =  link path needed to link with the logging library

       TRACE_LIBS =  link path needed to link with the tracing library

       ANIM_LIBS  =  link path needed to link with the animation library

       The variable FLIB_PATH is the link path  needed  to  link  fortran  MPI
       programs with the logging library.

       During  make,  small  test programs cpi.c and fpi.f will be linked with
       each of the above libraries.  In the output from Make, a  message  will
       be  written  regarding  the  success  of each attempted link test.  The
       success of these linkage tests  will  also  be  included  in  the  Make
       output.   If  the linkage tests are successful, then these library link
       paths can be used for your programs as well.

CUSTOMIZING LOGFILES

       In addition to using the predefined MPE logging libraries  to  log  all
       MPI calls, MPE logging calls can be inserted into user’s MPI program to
       define and log states.  These states are  called  User-Defined  states.
       States  may be nested, allowing one to define a state describing a user
       routine that contains several MPI calls, and  display  both  the  user-
       defined state and the MPI operations contained within it.

       The  routine  MPE_Log_get_event_number()  has  to be used to get unique
       event numbers (this is important if you are writing a library that uses
       the   MPE   logging  routines)  from  the  MPE  system.   The  routines
       MPE_Describe_state() and MPE_Log_event()  are  then  used  to  describe
       user-defined states.

       int eventID_begin, eventID_end;
       .
       .
       .
       eventID_begin = MPE_Log_get_event_number();
       eventID_end   = MPE_Log_get_event_number();
       .
       .
       .
       MPE_Describe_state( eventID_begin, eventID_end, "Amult", "bluegreen" );
       .
       .
       .
       MyAmult( Matrix m, Vector v )
       {
       /* Log the start event along with the size of the matrix */
       MPE_Log_event( eventID_begin, m->n, (char *)0 );
       .
       .
       .
       Amult code, including MPI calls ...
       MPE_Log_event( eventID_end, 0, (char *)0 );
       }

       The  log  file generated by this code will have the MPI routines within
       the routine MyAmult() indicated by a containing bluegreen rectangle.

       If the MPE logging library, liblmpe.a, are NOT  linked  with  the  user
       program, MPE_Init_log() and MPE_Finish_log() need to be used before and
       after all the MPE calls.    Sample  programs  cpilog.c  and  fpi.f  are
       available  in  MPE  source  directory  contrib/test  or  the  installed
       directory share/examples to illustrate the use of these MPE routines.

ENVIRONMENTAL VARIABLES

       There are 2 environmental variables, TMPDIR and MPE_LOG_FORMAT  ,  that
       user

MAY NEED TO SET BEFORE THE GENERATION OF LOGFILES

       MPE_LOG_FORMAT
              -  determines  the  format  of  the  logfile  generated from the
              execution of application linked with MPE logging libraries.  The
              allowed  value  for MPE_LOG_FORMAT are CLOG, SLOG and ALOG. When
              MPE_LOG_FORMAT is NOT set, CLOG is assumed.

       TMPDIR - specifies a directory to be used as temporary storage for each
              process.  By default, when TMPDIR is NOT set, /tmp will be used.
              When user needs to generate  a  very  large  logfile  for  long-
              running  MPI  job,  user  needs  to make sure that TMPDIR is big
              enough to hold the temporary logfile which will  be  deleted  if
              the  merged  logfile  can  be created successfully.  In order to
              minimize the overhead of the logging to the MPI program,  it  is
              highly  recommended user to use a *local* file system for TMPDIR
              .

              Note : The final merged logfile will be written back to the file
              system where process 0 is.

UTILITY PROGRAMS

       In   bin/,   user   can  find  several  useful  utility  programs  when
       manipulating logfiles.  These  includes  log  format  converters,  e.g.
       clog2slog,  log format print programs, e.g. slog_print, and a script to
       launch display program, logviewer.

LOG FORMAT CONVERTERS

       clog2slog
              - a  CLOG  to  SLOG  logfile  converter.   Since  the  automatic
              generation   of  SLOG  file  through  setting  of  environmental
              variable MPE_LOG_FORMAT to SLOG may NOT work for some non  well-
              behaved  MPI  programs,  using  the logfile format converter can
              generate extra diagnostic information about the condition of the
              logfile.   Also  the  converter  allows  one  to  adjust certain
              parameters of the logfile, like frame size which is the  segment
              of the logfile to be displayed by Jumpshot-3’s time line window.
              For non well behaved MPI program, one may need to  increase  the
              frame  size  from  the default 64KB to a bigger value.  For more
              information about the converter, do "clog2slog -h"

       clog2alog
              - a CLOG to ALOG logfile converter.  It is not being  developed.
              It is provided here for backward compatibility purpose.

LOG FORMAT PRINT PROGRAMS

       slog_print
              -  a stdout print program for SLOG file.  It serves to check the
              content of the logfile.  If the SLOG file is too big, it may NOT
              be  useful  to use slog_print.  Also, when slog is NOT complete,
              slog_print won’t work.  So it serves as a simple test  to  check
              if the SLOG file is generated completely.

       clog_print
              - stdout print program for CLOG file.

DISPLAY PROGRAM SELECTOR

       logviewer
              - the script which involves appropriate viewer based on the file
              extension of logfile.  For instance, if the logfile is foo.slog,
              logviewer   will  invoke  jumpshot-3  to  display  the  logfile.
              Jumpshot-3  resides  in  share/.   For   more   information   of
              logviewer, do "logviewer -help" to list all available options.

ADDITIONAL INFORMATION

       To view a list of configure options, type ./configure--help in the top-
       level mpe directory.

       In the Installation Manual, there is  a  section  on  MPE  which  gives
       instructions and examples for each type of installation.

       The README in the top-level mpe directory.

       In  the Users Guide, there is additional information describing the MPE
       routines and the profiling libraries.

       The man pages included in the distribution  has  information  regarding
       the  MPE  routines.  The command mpich/bin/mpiman is a script that runs
       xman on these man pages.

LOCATION

       /home/MPI/mansrc/mpepage

                                   9/2/2000                             MPE(4)