This directory contains programs that are part of the mpptest performance
test suite.  By default, they generate output for the C.It graphics program;
the -gnuplot option will generate data for Gnuplot.  Because of limitations
of Gnuplot, the full generality of these commands is not supported when
gnuplot output is selected.

To build the programs, use configure.  In many cases, all you need to do is
invoke configure.  If that doesn't work, use the following:

MPICH:

	./configure --with-mpich

SGI MPI:

	./configure --with-sgimpi

IBM MPI

	./configure --with-ibmmpi

Others (assuming that your shell is csh or tcsh):
	setenv CC name-of-C-compiler for MPI programs
	setenv F77 name-of-Fortran-compiler for MPI programs
	setenv MPILIB name-of-mpi-library 
	./configure

If you are cross-compiling, but you can run programs locally using a different
compiler, add the following environment variables
	setenv TESTCC name-of-C-compiler-for-local-programs
	setenv TESTF77 name-of-Fortran-compiler-for-local-programs

The programs that you want to run are mpptest and goptest.  You can run
these as you would any MPI program, or you can use the following scripts 
that will generate data automatically.  To use these, you will also need 
to create a script that runs an MPI program with some arguments;
samples are provided for IBM's MPI in mpirun.ibm .  For MPICH, you may use
the mpirun provided by MPICH.

For a quick overview of the performance of your system, try

   mpirun -np 2 mpptest -logscale
   mpirun -np 16 mpptest -bisect -logscale

(the latter assumes that you have 16 processors).

Several scripts have been provided to generate data.  The following two 
run mpptest and goptest with common options.

runmpptest - point-to-point tests and collective as a function of data length
rungoptest - collective as a function of the number of processes

To get an idea about your system, do (assuming a 32 processor system)

./runmpptest -short -pair -blocking -givedy -gnuplot -fname pt2pt.mpl
./runmpptest -np 32 -bisect -short -blocking -gnuplot -fname bisect.mpl
./rungoptest -maxnp 32 -add -bcast -gnuplot -fname bcast.mpl

(use 
    -mpirunpgm ./mpirun.ibm 
 to select an alternate mpirun program (mpirun.ibm in this case)
)
Then

gnuplot pt2pt.mpl
gnuplot bisect.mpl
gnuplot bcast.mpl

will generate plots of the performance of MPI_Send/MPI_Recv, (point to point
and bisection bandwidth) and MPI_Bcast.  These routines may be used for 
additional testing.  For example,

./runmpptest -long -pair -nonblocking -givedy -gnuplot -fname nbpt2pt.mpl

will give the performance of the nonblocking MPI routines with long messages.

The script basetest can be used to get common information about your 
system for both point-to-point and collective calls.  It 

In addition, mpptest and goptest may be used alone.  Both take -help and give
a summary of options.  For example, 

./mpptest -sz 2 -cachesize 1000000

causes the messages to be taken from a buffer of size 1000000, reducing the 
reuse of memory locations.

The copytest program gives a rough estimate of how fast memcpy works in a
single address space.  To use

mpirun -np 1 copytest

This copies data from one place to another three times; the first copy
may take longer because of the need to page in (and possibly initialize to
zero) data.  If the data cache is large enough, the second and third copies
may be faster than expected.

(You need to use mpirun because copytest uses MPI_Wtime to get times)

Finally, the program buflimit is a simple program that estimates the size
of message that you can send with an MPI_Send without having a matching 
receive.  Just run

mpirun -np 2 buflimit

The following uses of runmpptest and rungoptest will produce a basic survey 
of your system.  This script can be placed in a file and executed.

-- cut here --
#! /bin/sh
./runmpptest -short -pair -blocking -givedy -gnuplot -fname pt2ptshort.mpl
./runmpptest -long -pair -blocking -givedy -gnuplot -fname pt2ptlong.mpl
./runmpptest -long -pair -nonblocking -givedy -gnuplot -fname nbpt2ptlong.mpl
./runmpptest -np 32 -bisect -short -blocking -gnuplot -fname bisectshort.mpl
./runmpptest -np 32 -bisect -long -blocking -gnuplot -fname bisectlong.mpl
./rungoptest -maxnp 32 -add -bcast -gnuplot -fname bcast.mpl
temp=`which $gnuplot | head -1`
if [ ! -x "$temp" ] ; then
   echo "Creating tar file of plot data"
   tar cf data.tar *.mpl *.???
else 
    for file in *.mpl ; do
        filebase=`basename $file`
        # Use set terminal postscript eps 
        # to get encapsulated Postscript for including in documents
        gnuplot <<EOF >>${filebase}.ps
set terminal postscript
load $file
EOF
        echo "Created file ${filebase}.ps"
    end
fi
-- cut here --

If you have access to the graphics program C.It (very few of you will), 
you can get slightly nicer output, as well as more easily getting "rate"
graphs.

To do this, do the following:

Use -cit instead of -gnuplot as the option to mpptest.  Add the -rate 
option to mpptest.

For example, the basic performance plots for latency and bandwidth, 
using C.It output form, can be generated with

mpirun -np 2 mpptest -cit -auto -autodx 4 > short.cit
mpirun -np 2 mpptest -cit -rate -size 16000 1600000 16000 > long.cit 

Nonblocking versions are

mpirun -np 2 mpptest -cit -async -auto -autodx 4 > short.cit
mpirun -np 2 mpptest -cit -async -rate -size 16000 1600000 16000 > long.cit 


