MPE

 MultiProcessing Environment

Description

The main benefit the MultiProcessing Environment library, mpe, offers is a set of routines that will create logfiles from MPI programs which can be examined by jumpshot or upshot. These logfiles can be created manually by inserting calls to mpe routines in your code, automatically by linking with the appropriate MPE libraries, or by combining the two methods. Currently, the mpe library offers 3 profiling libraries.

Tracing Library Trace 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 profiling library and is the most widely used. Logfiles (files of timestamped events) are generated and can be analyzed with graphical tools such as jumpshot (preferrably) or upshot.

Configuring the MPE library

The mpe library can be configured and installed as an extension of your current MPI implementation, or automatically during MPICH's configure and make process. The only requirement is that you configure with a specific MPI implementation switch. Currently, we have configured the mpe library to work with MPICH, SGI's MPI, IBM's MPI, and CRAY's MPI (not thoroughly tested). There are 3 types of configure options or switches.


MPI implementation switch (mandatory)


Generic configure flags (mandatory/optional)


User option switches/flags (optional)

Specific MPI Implementation Switches

--with-mpich=dir Specifies the top-level directory where MPICH (version 1.0.13 or later) was installed.
--with-mpichdev=subdir Specifies the subdirectory of which architecture\device you wish to use.
--with-sp Specifies use of the native IBM POE\MPI implementation.
--with-sgi Specifies use of the native SGI MPI implementation.
--with-sgi64 Specifies use of the native SGI MPI implementation, forcing it to compile in 64 bit mode.
--with-cray Specifies use of the native Cray MPI implementation.

Generic flags

-prefix=DIR Specifies the destination install directory for the mpeinstall script. If configuring with MPICH, it must be the same install directory as the one given as an option to mpich's configure or the mpiinstall script in the mpich/util directory. If omitted, and -prefix was given as an option to the mpich configure, then this directory will be automatically configured. The mpeinstall script installs into DIR only the required libraries and include files, and a small subset of the examples.
-libdir=DIR Specifies the top-level directory where the mpe libraries will be installed. If this directory does not exist, it will be created. This flag is mandatory when not using MPICH and irrelevant when using MPICH (-libdir is replaced by -mpichdev).
-bindir=DIR This flag is only relevant if you will be installing jumpshot along with the mpe library. This directory will be passed to jumpshot's configure and will be where jumpshot's executable will be installed. If configuring with MPICH, this is automatically configured for you. If not, and this flag is omitted, this directory will be $libdir/../bin. If this directory does not exist, it will be created.
--x-includes=DIR This is an optional flag which specifies that X include files are in DIR. If omitted, configure will attempt to locate them.
--x-libraries=DIR This is an optional flag which specifies that X library files are in DIR. If omitted, configure will attempt to locate them.

User Option Switches


Note: Because tcl and tk keep changing in incompatible ways, we will soon be dropping support for any tool that uses tcl/tk. The newest version of upshot, jumpshot, is written in Java.

--enable-echo This switch will turn on strong echoing. The default is enable=no.
--enable-mpe_graphics This switch will allow the mpe graphics routines to be built. If disabled, then the mpe routines that make use of X11 graphics will not be built. This is appropriate for systems that either do not have the X11 include files or that do not support X11 graphics. The default is enable=yes.
--enable-f77 This switch will allow the compilation of routines that require a Fortran compiler. If configuring with MPICH, the configure in the top-level mpich directory will choose the appropriate value for you. However, it can be overridden. The default is enable=yes.
--enable-jumpshot This switch will allow the configuration of the graphical tool jumpshot. The default for this option is enable=yes. If this option is enabled and you are not configuring with MPICH, then you will also need to supply the directory path where jumpshot has already been installed ( --with-jumpshot_home ).
--with-tcldir=TCL_DIR This switch specifies that tcl is located in TCL_DIR. This can only be version 7 and TCL_DIR must have lib/libtcl.a and include/tcl.h. These files are only used for nupshot. If this switch is omitted, configure will attempt to locate these files.
--with-tkdir=TK_DIR This switch specifies that tk is located in TK_DIR. This can only be version 3 if you want to use nupshot and TK_DIR must have lib/libtcl.a and include/tk.h. This may be the same as TCL_DIR. If this switch is omitted, configure will attempt to locate these files.
--with-wishloc=WISHLOC This switch specifies the name of tcl/tk wish executable. If this switch is omitted, configure will attempt to locate a version. This is used only for nupshot and upshot.
--with-jumpshot_home=JUMP_DIR This switch specifies the path of the top-level directory where jumpshot is installed. When configuring with MPICH, this option is automaticaly configured by default. However, it can be overridden If not configuring with MPICH, then you need to specify JUMP_DIR in order to configure jumpshot along with the mpe library.
--with-jumpshot_opts=JUMP_OPTS This switch allows you to pass specific options to jumpshot's configure. Unfortunately, because of the way autoconf 2.12 processes multiple arguments with AC_ARG_WITH, only 1 option may be passed to jumpshot's configure. If more options are required, then configure jumpshot separately.

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 substituted in the Makefile in the mpe/contrib/test directory. The following is a list of these variables.


LOG_LIB = link path needed to link with the logging library


TRACE_LIB = link path needed to link with the tracing library


ANIM_LIB = link path needed to link with the animation library

In the mpe/test directory there is a variable FLIB_PATH which is the link path needed to link fortran programs with the logging library.

During make, a small C program cpi (in the mpe/contrib/test directory) 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. Also, in the mpe/test directory a small Fortran program fpi will be linked with logging library using FLIB_PATH. The success of this link test will also be included in the Make output. If the link tests were successful, then these library paths should be used for your programs as well.

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