

				MPI Profiling

This directory contains both the upshot and nupshot tools, and tools for
building profiling libraries that exploit the MPI profiling interface.
This directory is distributed as part of MPICH, and is also available
separately.  If you have this as part of MPICH, use the MPICH build and
installation steps to build and install these tools; no separate steps are
required.

Building Nupshot
================
If you acquired this package separately (as profiling.tar.gz), you can build
nupshot with

    cd profiling/nupshot
    ./configure
    make

Building nupshot separately from the MPICH distribution has not been
extensively tested, but has been done on a few systems.  If you have problems,
please send the output from 

    ./configure -echo
    make

to mpi-bugs@mcs.anl.gov .  Note that you are working with the separate
profiling distribution.


Contents
========

The sample profiling wrappers for MPICH are distributed as wrapper
definition code.  The wrapper definition code is run through the
'wrappergen' utility to generate C code.  See the README in
mpich/profiling/wrappergen.  Any number of wrapper definitions
can be used together, so any level of profiling wrapper nesting
is possible when using wrappergen.

A few sample wrapper definitions are provided with mpich:

  timing - use MPI_Wtime() to keep track of the total # of
           calls to each MPI function, and the time spent
           within that function.  Note that this simply
           checks the timer before and after the function
           call.  It will not subtract time spent in calls to
	   other functions.
  logging - create logfile of all pt2pt function calls
  vismess - pop up an X window that gives a simple visualization of all
            messages that are passed
  allprof - all of the above

Note: these wrappers do not use any mpich-specific features, besides
the MPE graphics and logging used by 'vismess' and 'logging', respectively.
They should work on any MPI implementation.

They can be incorporated manually into your application.  This will
involve 3 changes to the building of your application:
   1. Generate the source code for the desired wrapper(s) with wrappergen.
      This can be a one-time task.

   2. Compile the code for the wrapper(s).  Be sure to supply the
      needed compile-line parameters.  'vismess' and 'logging'
      require the MPE library, and the 'vismess' wrapper definition
      requires MPE_GRAPHICS.

   3. Link the compiled wrapper code, the profiling version of the mpi
      library, and any other necessary libraries (vismess requires X)
      into your application.  There is a required order:

      $(CLINKER)   <application object files...> \
		   <wrapper object code> \
		   <other necessary libraries (-lmpe)> \
		   <profiling mpi library (-lpmpi)> \
		   <standard mpi library (-lmpi)>

To simplify it, some sample makefile sections have been created in
mpich/profiling/lib:

  Makefile.timing - timing wrappers
  Makefile.logging - logging wrappers
  Makefile.vismess - animated messages wrappers
  Makefile.allprof - timing, logging, and vismess

To use these Makefile fragments:
  1. (optional) Add $(PROF_OBJ) to your application's dependency list:
        myapp:  myapp.o $(PROF_OBJ)

  2. Define WGEN_DIR to 

  2. Add $(PROF_FLG) to your compile line (CFLAGS):
        CFLAGS = -O $(PROF_FLG)

  3. Add $(PROF_LIB) to your link line, after your application's object
     code, but before the main MPI library:
        $(CLINKER) myapp.o -L$(MPIR_HOME)/lib/$(ARCH)/$(COMM) $(PROF_LIB) -lmpi

  4. (optional) Add $(PROF_CLN) to your clean target:
        rm -f *.o *~ myapp $(PROF_CLN)

  5. Include the desired Makefile fragment in your makefile:
	include $(MPIR_HOME)/profiling/lib/Makefile.logging


