1MPICH2 Test Suite
2
3This test suite is a *supplement* to other test suites, including the
4original 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
7Building the Test Suite
8=======================
9In many cases, configure will find the MPI implementation
10automatically. In some cases, it will need some help. For example:
11
12For 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
21If mpicc and friends are not in your default path (and you do not want to
22add them), you can specify the path with --with-mpi=<path>. For example,
23if 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
29You may need to add MPI_SIZEOF_OFFSET=8 .
30
31The option "-cpp" is needed for at least some versions of mpCC to define the
32C++ bindings of the MPI routines.
33
34For implementations that do not implement all of MPI-2, there are --disable
35options, including --disable-spawn and --disable-cxx. To restrict tests to
36just what is defined in the MPI specification, use --enable-strictmpi .
37
38The script that runs the tests assumes that the MPI implementation
39supports mpiexec; you should consider this the first test of the implementation.
40
41Setting Options
42===============
43The following environment variables will modify the behavior of the tests
44
45MPITEST_DEBUG - if set, output information for debugging the test suite
46MPITEST_VERBOSE - if set to an integer value, output messages whose
47 level is at least that value (0 is a good choice here)
48MPITEST_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)
52MPITEST_THREADLEVEL_DEFAULT - Set the default thread level. Values are
53 multiple, serialized, funneled, and single.
54
55Batch Systems
56=============
57For systems that run applications through a batch system, the option "-batch"
58to the runtests script will create a script file that can be edited and
59submitted to the batch system. The script checktests can be run to
60summarize the results.
61
62Specifically, (assuming the bash shell, and that the directory "btest", a
63subdirectory of the test suite directory, is used for running the tests):
64
65export MPITEST_BATCHDIR=`pwd`/btest
66runtests -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
69cd btest && ../checktests
70
71If a program other than mpiexec is used in the batch form to run programs, then
72specify that to runtests:
73
74 runtests -batch -mpiexec=aprun -tests=testlist
75
76(Here, aprun is the command used on Cray XE6 systems.)
77
78Note that some programs that are used to run MPI programs add extra output,
79which can confuse any tool that depends on clean output in STDOUT. Since
80such unfortunate behavior is common, the option -ignorebogus can be given
81to checktests:
82
83cd btest && ../checktests --ignorebogus
84
85Controlling the Tests that are Run
86==================================
87The tests are actually built and run by the script "runtests". This script
88can be given a file that contains a list of the tests to run. This file has
89two 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
95Lines may also be commented out with "#".
96
97The simplest program line contains the name of the program and the number of
98MPI processes to use. For example, the following will build the
99program sendrecv1 and run it with 4 processes:
100
101sendrecv1 4
102
103In addition, the program line can contain key=value pairs that provide
104special information about running the test. For example,
105
106sendflood 8 timeLimit=600
107
108says to build and run the program sendflood with 8 MPI processes and
109permit the test to run for 600 seconds (by default, at least for
110MPICH2, the default timelimit is 180 seconds). Other key=value pairs
111can be used to select whether a program should be run at all,
112depending on the abilities of the MPI implementation (this is
113particularly important for Fortran programs, since preprocessor
114support for Fortran is a non-standard extension to the Fortran
115language, and there are some compilers that would not accept Fortran
116programs that used the preprocessor).
117
118The most important key=value pairs are:
119
120
121timeLimit=n : Use a timelimit of n seconds
122
123arg=string : Run the program with string as an argument to the program
124
125mpiexecarg=string : Run the program with string as an argument to mpiexec
126
127env=name=value : Run the program with environment variable "name" given the
128 value "value"
129
130mpiversion=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
138strict=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 MPICH2 development, MPIX routines
147
148resultTest=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
156