teshsuite/smpi/mpich3-test/README

   1 MPICH Test Suite
   2
   3 This test suite is a *supplement* to other test suites, including the
   4 original MPICH testsuite, the Intel testsuite, and the IBM MPI test suite
   5 (or test suites derived from that test, including the MPI C++ tests).
   6
   7 Building the Test Suite
   8 =======================
   9 In many cases, configure will find the MPI implementation
  10 automatically.  In some cases, it will need some help.  For example:
  11
  12 For IBM MPI, where the compilation commands are not mpicc and mpif77 etc.:
  13
  14 ./configure CC=xlc MPICC=mpcc F77=xlf MPIF77=mpxlf CXX=xlC \
  15                        MPICXX="mpCC -cpp" F90=xlf90 MPIF90=mpxlf90 \
  16                        --disable-spawn \
  17                        --enable-strictmpi
  18
  19 (or the _r versions of the compilers)
  20
  21 If mpicc and friends are not in your default path (and you do not want to
  22 add them), you can specify the path with --with-mpi=<path>.  For example,
  23 if they are in /usr/local/mympi/bin, use
  24
  25 ./configure --with-mpi=/usr/local/mympi
  26
  27 (configure will append the bin to the path that you give).
  28
  29 You may need to add MPI_SIZEOF_OFFSET=8 .
  30
  31 The option "-cpp" is needed for at least some versions of mpCC to define the
  32 C++ bindings of the MPI routines.
  33
  34 For implementations that do not implement all of MPI-2, there are --disable
  35 options, including --disable-spawn and --disable-cxx.  To restrict tests to
  36 just what is defined in the MPI specification, use --enable-strictmpi .
  37
  38 The script that runs the tests assumes that the MPI implementation
  39 supports mpiexec; you should consider this the first test of the implementation.
  40
  41 Setting Options
  42 ===============
  43 The following environment variables will modify the behavior of the tests
  44
  45 MPITEST_DEBUG - if set, output information for debugging the test suite
  46 MPITEST_VERBOSE - if set to an integer value, output messages whose
  47                   level is at least that value (0 is a good choice here)
  48 MPITEST_RETURN_WITH_CODE - Set the return code from the test programs based on
  49                          success or failure, with a zero for success and one
  50                          for failure (value must be yes, YES, true, or TRUE to
  51                          turn this on)
  52 MPITEST_THREADLEVEL_DEFAULT - Set the default thread level.  Values are
  53                               multiple, serialized, funneled, and single.
  54
  55 Batch Systems
  56 =============
  57 For systems that run applications through a batch system, the option "-batch"
  58 to the runtests script will create a script file that can be edited and
  59 submitted to the batch system.  The script checktests can be run to
  60 summarize the results.
  61
  62 Specifically, (assuming the bash shell, and that the directory "btest", a
  63 subdirectory of the test suite directory, is used for running the tests):
  64
  65 export MPITEST_BATCHDIR=`pwd`/btest
  66 runtests -batch -tests=testlist
  67 ... edit btest/runtests.batch to make it a value batch submissions script
  68 ... run that script and wait for the batch job to complete
  69 cd btest && ../checktests
  70
  71 If a program other than mpiexec is used in the batch form to run programs, then
  72 specify that to runtests:
  73
  74     runtests -batch -mpiexec=aprun -tests=testlist
  75
  76 (Here, aprun is the command used on Cray XE6 systems.)
  77
  78 Note that some programs that are used to run MPI programs add extra output,
  79 which can confuse any tool that depends on clean output in STDOUT.  Since
  80 such unfortunate behavior is common, the option -ignorebogus can be given
  81 to checktests:
  82
  83 cd btest && ../checktests --ignorebogus
  84
  85 Controlling the Tests that are Run
  86 ==================================
  87 The tests are actually built and run by the script "runtests".  This script
  88 can be given a file that contains a list of the tests to run.  This file has
  89 two primary types of entries:
  90
  91     directories:  Enter directory and look for the file "testlist".
  92                   Recursively run the contents of that file
  93     program names: Build and run that program
  94
  95 Lines may also be commented out with "#".
  96
  97 The simplest program line contains the name of the program and the number of
  98 MPI processes to use.  For example, the following will build the
  99 program sendrecv1 and run it with 4 processes:
 100
 101 sendrecv1 4
 102
 103 In addition, the program line can contain key=value pairs that provide
 104 special information about running the test.  For example,
 105
 106 sendflood 8 timeLimit=600
 107
 108 says to build and run the program sendflood with 8 MPI processes and
 109 permit the test to run for 600 seconds (by default, at least for
 110 MPICH, the default timelimit is 180 seconds).  Other key=value pairs
 111 can be used to select whether a program should be run at all,
 112 depending on the abilities of the MPI implementation (this is
 113 particularly important for Fortran programs, since preprocessor
 114 support for Fortran is a non-standard extension to the Fortran
 115 language, and there are some compilers that would not accept Fortran
 116 programs that used the preprocessor).
 117
 118 The most important key=value pairs are:
 119
 120
 121 timeLimit=n : Use a timelimit of n seconds
 122
 123 arg=string  : Run the program with string as an argument to the program
 124
 125 mpiexecarg=string  : Run the program with string as an argument to mpiexec
 126
 127 env=name=value : Run the program with environment variable "name" given the
 128                  value "value"
 129
 130 mpiversion=x.y : Build and run the program only if the MPI version is at
 131                  least x.y.  For example,
 132
 133                 distgraph1 4 mpiversion=2.2
 134
 135                 will build and run distgraph1 with 4 MPI processes only
 136                 if the MPI version is at least 2.2.
 137
 138 strict=bool : If bool is false, only build and run the program if
 139               --enable-strictmpi was not used in configuring the test suite.
 140               That is, a line such as
 141
 142               neighb_coll 4 strict=false
 143
 144               Says that this test is not valid for a strict MPI implementation;
 145               it contains extensions to the standard, or in the case of some
 146               MPICH development, MPIX routines
 147
 148 resultTest=proc : This is used to change the way in which the success or
 149                   failure of a test is evaluated.  proc is one of several
 150                   Perl subroutines defined within the runtest program.  These
 151                   are primarily used within the testsuite for tests programs
 152                   exit with expected status values or that timeouts are
 153                   in fact handled.
 154
 155