Global arguments apply to all commands that will be launched by
mpiexec.
They come at the beginning of the command line.
-boot
Boot the LAM run-time environment before running the MPI program. If
-machinefile
is not specified, use the default boot schema. When the MPI processes
finish, the LAM run-time environment will be shut down.
-boot-args <args>
Pass arguments to the back-end
lamboot
command when booting the LAM run-time environment. Implies
-boot.
-d
Enable lots of debugging output. Implies
-v.
-machinefile <hostfile>
Enable "one shot" MPI executions; boot the LAM run-time environment
with the boot schema specified by <hostfile> (see bhost(5)), run the
MPI program, and then shut down the LAM run-time environment. Implies
-boot.
-prefix <lam/install/path>
Use the LAM installation specified in
</lam/install/path/>. Not compatible with LAM/MPI versions prior to 7.1.
-ssi <key> <value>
Set the SSI parameter <key> to the value <value>.
-tv
Launch the MPI processes under the TotalView debugger.
-v
Be verbose
One or more sets of local arguments must be specified (or a config
file; see below). Local arguments essentially include everything
allowed in an appschema(5) as well as the following options specified
by the MPI-2 standard (note that the options listed below must be
specified
before
appschema arguments):
-n <numprocs>
Number of copies of the process to start.
-host <hostname>
Specify the hostname to start the MPI process on. The hostname must
be resolvable by the
lamnodes
command after the LAM run-time environment is booted (see
lamnodes(1)).
-arch <architecture>
Specify the architecture to start the MPI process on.
mpiexec
essentially uses the provided <architecture> as a pattern match
against the output of the GNU
config.guess
utility on each machine in the LAM run-time environment. Any subset
will match. See EXAMPLES, below.
-wdir <directory>
Set the working directory of the executable.
-soft
Not yet supported.
-path
Not yet supported.
-file
Not yet supported.
<other_arguments>
When
mpiexec
first encounters an argument that it doesn't recognize (such as an
appschema(5) argument, or the MPI executable name), the remainder of
the arguments will be passed back to
mpirun
to actually start the process. As such, all of
mpiexec's
arguments that are described above must come
before
appschema arguments and/or the MPI executable name. Similarly, all
arguments after the MPI executable name will be transparently passed
as command line argument to the MPI process and will be will be
effectively ignored by
mpirun.
DESCRIPTION
mpiexec
is loosely defined in the Miscellany chapter of the MPI-2 standard
(see http://www.mpi-forum.org/). It is meant to be a portable
mechanism for starting MPI processes. The MPI-2 standard recommends
several command line options, but does not mandate any. LAM's
mpiexec
currently supports several of these options, but not all.
LAM's
mpiexec
is actually a perl script that is a wrapper around several underlying
LAM commands, most notably
lamboot,
mpirun,
and
lamhalt.
As such, the functionality provided by
mpiexec
can always be performed manually. Unless otherwise specified in
arguments that are passed back to
mpirun,
mpiexec
will use the per-CPU scheduling as described in mpirun(1) (i.e.,
the "cX" and "C" notation).
mpiexec
can either use an already-existing LAM universe (i.e., a booted LAM
run-time environment), similar to
mpirun,
or can be used for "one-shot" MPI executions where it boots the LAM
run-time environment, runs the MPI executable(s), and then shuts down
the LAM run-time environment.
mpiexec
can also be used to launch MPMD MPI jobs from the command line.
mpirun
also supports launching MPMD MPI jobs, but the user must make a text
file appschema(5) first.
Perhaps one of
1mpiexec's
most useful features is the command-line ability to launch different
executables on different architectures using the
-arch
flag (see EXAMPLES, below). Essentially, the string argument that is
given to
-arch
is used as a pattern match against the output of the GNU
config.guess
utility on each node. If the user-provided <architecture> string
matches any subset of the output of
config.guess,
it is ruled a match. Wildcards are not possible. The GNU
config.guess
utility is available both in the LAM/MPI source code distribution (in
the config subdirectory) and at
ftp://ftp.gnu.org/gnu/config/config.guess.
Some sample outputs from
config.guess include:
sparc-sun-solaris2.8
Solaris 2.8 running on a SPARC platform.
i686-pc-linux-gnu
Linux running on an i686 architecture.
mips-sgi-irix6.5
IRIX 6.5 running on an SGI/MIPS architecture.
You might want to run the
laminfo
command on your available platforms to see what string
config.guess
reported. See laminfo(1) for more details (e.g., the
-arch
flag to
laminfo).
Configfile option
It is possible to specify any set of local parameters in a
configuration file rather than on the command line using the
-configfile
option. This option is typically used when the number of command line
options is too large for some shells, or when automated processes
generate the command line arguments and it is simply more convenient
to put them in a file for later processing by
mpiexec.
The config file can contain both comments and one or more sets of
local arguments. Lines beginning with "#" are considered comments and
are ignored. Other lines are considered to be one or more groups of
local arguments. Each group must be separated by either a newline or
a colon (":"). For example:
# Sample mpiexec config file
# Launch foo on two nodes
-host node1.example.com foo : -host node2.example.com foo
# Launch two copies of bar on a third node
-host node3.example.com -np 2 bar
ERRORS
In the event of an error,
mpiexec
will do its best to shut everything down and return to the state
before it was executed. For example, if
mpiexec
was used to boot a LAM run-time environment,
mpiexec
will do its best to take down whatever successfully booted of the
run-time environment (to include invoking
lamhalt
and/or
lamwipe).
EXAMPLES
The following are some examples of how to use
mpiexec.
Note that all examples assume the CPU-based scheduling (which does
NOT
map to physical CPUs) as described in mpirun(1).
mpiexec -n 4 my_mpi_program
Launch 4 copies of
my_mpi_program
in an already-existing LAM universe.
mpiexec -n 4 my_mpi_program arg1 arg2
Similar to the previous example, but pass "arg1" and "arg2" as command
line arguments to each copy of my_mpi_program.
mpiexec -ssi rpi gm -n 4 my_mpi_program
Similar to the previous example, but pass "-ssi rpi gm" back to
mpirun
to tell the MPI processes to use the Myrinet (gm) RPI for MPI message
passing.
mpiexec -n 4 program1 : -n 4 program2
Launch 4 copies of
program1
and 4 copies of
program2
in an already-existing LAM universe. All 8 resulting processes will
share a common MPI_COMM_WORLD.
mpiexec -machinefile hostfile -n 4 my_mpi_program
Boot the LAM run-time environment with the nodes listed in the
hostfile, run 4 copies of my_mpi_program in the resulting LAM
universe, and then shut down the LAM universe.
mpiexec -machinefile hostfile my_mpi_program
Similar to above, but run my_mpi_program on all available CPUs in the
LAM universe.
mpiexec -arch solaris2.8 sol_program : -arch linux linux_program
Run as many copies of sol_program as there are CPUs on Solaris
machines in the current LAM universe, and as many copies of
linux_program as there are CPUs on linux machines in the current LAM
universe. All resulting processes will share a common
MPI_COMM_WORLD.