Seth Woolley's Man Viewer

MPE(4) - MPE - MultiProcessing Environment - man 4 MPE

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

MPE(4)                                MPE                               MPE(4)



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  pro-
       grams  based on post processing approach.  These tools include a set(7,n,1 builtins) of
       profiling libraries, a set(7,n,1 builtins) of utility programs, and a set(7,n,1 builtins) of  graphical
       visualization tools.

       The  first  set(7,n,1 builtins) 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(1,8) 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(1,8) MPI_COMM_WORLD of the calling
              process, and followed by another line indicating that  the  call
              has completed.  Most send(2,n) 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(1,8)
              MPE.   They  form  the basis to generate log files from user MPI
              programs.  There are currently  3  different  log  file(1,n)  formats
              allowed  in(1,8)  MPE.   The  default log file(1,n) format is CLOG.  It is
              basically a collection of events with  single  timestamps.   And
              there  is ALOG which is provided for backward compatibility rea-
              son 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(1,n)  has  been  generated   (preferred
              approach), or can be generated directly when MPI program is exe-
              cuted (through setting the environmental variable MPE_LOG_FORMAT
              to SLOG).

              The set(7,n,1 builtins) of utility programs in(1,8) 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(1,n)  exten-
              sion.

              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  stan-
       dard 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  dis-
       tribution,  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(1,n) in(1,8) the MPE source directory.




EXAMPLE MPE PROGRAMS
       As previously noted, the mpe library is composed of 3 different profil-
       ing libraries.  Each MPI implementation requires a  slightly  different
       way  in(1,8) which to link(1,2) with these libraries.  During configure, the link(1,2)
       path and appropriate libraries are determined  and  assigned  to  vari-
       ables.   These  variables  are first substituted in(1,8) the Makefile in(1,8) 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(1,2) path needed to link(1,2) with the logging library

       TRACE_LIBS =  link(1,2) path needed to link(1,2) with the tracing library

       ANIM_LIBS  =  link(1,2) path needed to link(1,2) with the animation library

       The variable FLIB_PATH is the link(1,2) path needed to link(1,2) fortran MPI pro-
       grams 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(1,2) test.  The suc-
       cess of these linkage tests will also be included in(1,8) the  Make  output.
       If  the linkage tests are successful, then these library link(1,2) 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(3,n) 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(1,n) 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(1,8) MPE source directory contrib/test or the installed direc-
       tory 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 execu-
              tion 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(7,n,1 builtins), CLOG is assumed.

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


              Note : The final merged logfile will be written back to the file(1,n)
              system where process 0 is.




UTILITY PROGRAMS
       In  bin/, user can find several useful utility programs when manipulat-
       ing logfiles.  These includes log format  converters,  e.g.  clog2slog,
       log format print programs, e.g. slog_print, and a script to launch dis-
       play program, logviewer.




LOG FORMAT CONVERTERS
       clog2slog
              - a CLOG to SLOG logfile converter.  Since the automatic genera-
              tion  of  SLOG  file(1,n)  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(1,2,n) 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(1,n) 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(3,n) the SLOG file(1,n) 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(1,n)
              extension of logfile.  For instance, if(3,n) the logfile is foo.slog,
              logviewer  will invoke jumpshot-3 to display the logfile.  Jump-
              shot-3 resides in(1,8) 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(1,8) 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(1,8) the top-level mpe directory.

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

       The man(1,5,7) pages included in(1,8) the distribution  has  information  regarding
       the  MPE  routines.  The command mpich/bin/mpiman is a script that runs
       xman on these man(1,5,7) pages.


LOCATION
       /home/MPI/mansrc/mpepage



                                   9/2/2000                             MPE(4)

References for this manual (incoming links)