# 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

| --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.`
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.

| --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