<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>mpiexec</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<A NAME="mpiexec"><H1>mpiexec</H1></A>
Run an MPI program
<H2>Synopsis</H2>
<PRE>
</PRE>
<PRE>
mpiexec args executable pgmargs [ : args executable pgmargs ... ]
</PRE>
where <TT>args</TT> are command line arguments for <TT>mpiexec</TT> (see below),
<TT>executable</TT> is the name of an executable MPI program, and <TT>pgmargs
</TT>are command line arguments for the executable. Multiple executables
can be specified by using the colon notation (for MPMD - Multiple Program
Multiple Data applications). For example, the following command will run
the MPI program <TT>a.out</TT> on 4 processes:
<PRE>
mpiexec -n 4 a.out
</PRE>
<P>
The MPI standard specifies the following arguments and their meanings:
<P>
<DL>
<DT><B>-n <np> </B><DD>Specify the number of processes to use
<DT><B>-host <hostname> </B><DD>Name of host on which to run processes
<DT><B>-arch <architecture name> </B><DD>Pick hosts with this architecture type
<DT><B>-wdir <working directory> </B><DD>cd to this one <EM>before</EM> running executable
<DT><B>-path <pathlist> </B><DD>use this to find the executable
<DT><B>-soft <triplets> </B><DD>comma separated triplets that specify requested numbers
of processes (see the MPI-2 specification for more details)
<DT><B>-file <name> </B><DD>implementation-defined specification file
<DT><B>-configfile <name> </B><DD>file containing specifications of host/program,
one per line, with # as a comment indicator, e.g., the usual
mpiexec input, but with ":" replaced with a newline. That is,
the configfile contains lines with -soft, -n etc.
</DL>
<P>
Additional arguments that are specific to the MPICH2 implementation
are discussed below.
<P>
Note that not all of these parameters are meaningful for all
systems. For example, the <TT>gforker</TT> version of <TT>mpiexec</TT> creates all
processes on the same system on which it is running; in that case, the
<TT>-arch</TT> and <TT>-host</TT> options are ignored.
<P>
The colon character (<TT>:</TT>) may be used to separate different executables
for MPMD (multiple program multiple data) programming. For example,
to run the program <TT>ocean</TT> on 4 processes and <TT>air</TT> on 8 processes, use:
<P>
<PRE>
mpiexec -n 4 ocean : -n 8 air
</PRE>
<P>
<P>
<H2>MPICH2-Specific Arguments</H2>
<P>
Many of the implementations of process managers in MPICH2 support the
following arguments to <TT>mpiexec</TT>:
<P>
<DL>
<DT><B>-np <num> </B><DD>A synonym for the standard <TT>-n</TT> argument
<DT><B>-env <name> <value> </B><DD>Set the environment variable <TT><name></TT> to <TT><value></TT> for
the processes being run by <TT>mpiexec
</TT>
<DT><B>-envnone </B><DD>Pass no environment variables (other than ones specified with
other <TT>-env</TT> or <TT>-genv</TT> arguments) to the processes being run by <TT>mpiexec</TT>.
By default, all environment
variables are provided to each MPI process (rationale: principle of
least surprise for the user)
<DT><B>-envlist <list> </B><DD>Pass the listed environment variables (names separated
by commas), with their current values, to the processes being run by
<TT>mpiexec</TT>.
<DT><B>-genv <name> <value> </B><DD>The <TT>-genv</TT> options have the same meaning as their
corresponding <TT>-env</TT> version, except they apply to all executables, not just
the current executable (in the case that the colon syntax is used to specify
multiple execuables).
<DT><B>-genvnone </B><DD>Like <TT>-envnone</TT>, but for all executables
<DT><B>-genvlist <list> </B><DD>Like <TT>-envlist</TT>, but for all executables
<DT><B>-usize <n> </B><DD>Specify the value returned for the value of the attribute
<TT>MPI_UNIVERSE_SIZE</TT>.
<DT><B>-l </B><DD>Label standard out and standard error (<TT>stdout</TT> and <TT>stderr</TT>) with
the rank of the process
<DT><B>-maxtime <n> </B><DD>Set a timelimit of <TT><n></TT> seconds.
<DT><B>-exitinfo </B><DD>Provide more information on the reason each process exited if
there is an abnormal exit
</DL>
<P>
<H2>Environment variables for mpiexec</H2>
The following environment variables are understood by some versions of
<TT>mpiexec</TT>. The command line arguments have priority over these; that is,
if both the environment variable and command line argument are used, the
value specified by the command line argument is used.
<P>
<DL>
<DT><B>MPIEXEC_TIMEOUT </B><DD>Maximum running time in seconds. <TT>mpiexec</TT> will
terminate MPI programs that take longer than the value specified by
<TT>MPIEXEC_TIMEOUT</TT>.
<DT><B>MPIEXEC_UNIVERSE_SIZE </B><DD>Set the universe size
<DT><B>MPIEXEC_PORT_RANGE </B><DD>Set the range of ports that <TT>mpiexec</TT> will use
in communicating with the processes that it starts. The format of
this is <TT><low>:<high></TT>. For example, to specify any port between
10000 and 10100, use <TT>10000:10100</TT>.
<DT><B>MPICH_PORT_RANGE </B><DD>Has the same meaning as <TT>MPIEXEC_PORT_RANGE</TT> and
is used if <TT>MPIEXEC_PORT_RANGE</TT> is not set.
<DT><B>MPIEXEC_PREFIX_DEFAULT </B><DD>If this environment variable is set, output
to standard output is prefixed by the rank in <TT>MPI_COMM_WORLD</TT> of the
process and output to standard error is prefixed by the rank and the
text <TT>(err)</TT>; both are followed by an angle bracket (<TT>></TT>). If
this variable is not set, there is no prefix.
<DT><B>MPIEXEC_PREFIX_STDOUT </B><DD>Set the prefix used for lines sent to standard
output. A <TT>%d</TT> is replaced with the rank in <TT>MPI_COMM_WORLD</TT>; a <TT>%w</TT> is
replaced with an indication of which <TT>MPI_COMM_WORLD</TT> in MPI jobs that
involve multiple <TT>MPI_COMM_WORLD</TT>s (e.g., ones that use <TT>MPI_Comm_spawn</TT> or
<TT>MPI_Comm_connect</TT>).
<DT><B>MPIEXEC_PREFIX_STDERR </B><DD>Like <TT>MPIEXEC_PREFIX_STDOUT</TT>, but for standard error.
</DL>
<P>
<H2>Return Status</H2>
<TT>mpiexec</TT> returns the maximum of the exit status values of all of the
processes created by <TT>mpiexec</TT>.
<P>
<P><B>Location:</B>mpiexec.txt<P>
</BODY></HTML>
