.TH mpiexec 1 "11/12/2019" " " "MPI"

.SH NAME

mpiexec \-  Run an MPI program 

.SH SYNOPSIS

.nf

.fi

.nf

mpiexec args executable pgmargs [ : args executable pgmargs ... ]

.fi

where 

.I args

are command line arguments for 

.I mpiexec

(see below),

.I executable

is the name of an executable MPI program, and 

.I pgmargs

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 

.I a.out

on 4 processes:

.nf

mpiexec -n 4 a.out

.fi

The MPI standard specifies the following arguments and their meanings:

.PD 0

.TP

.B -n <np> 

- Specify the number of processes to use

.PD 1

.PD 0

.TP

.B -host <hostname> 

- Name of host on which to run processes

.PD 1

.PD 0

.TP

.B -arch <architecture name> 

- Pick hosts with this architecture type

.PD 1

.PD 0

.TP

.B -wdir <working directory> 

- cd to this one 

.B before

running executable

.PD 1

.PD 0

.TP

.B -path <pathlist> 

- use this to find the executable

.PD 1

.PD 0

.TP

.B -soft <triplets> 

- comma separated triplets that specify requested numbers

of processes (see the MPI-2 specification for more details)

.PD 1

.PD 0

.TP

.B -file <name> 

- implementation-defined specification file

.PD 1

.PD 0

.TP

.B -configfile <name> 

- 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.

.PD 1

Additional arguments that are specific to the MPICH implementation

are discussed below.

Note that not all of these parameters are meaningful for all

systems.  For example, the 

.I gforker

version of 

.I mpiexec

creates all

processes on the same system on which it is running; in that case, the

.I \\-arch

and 

.I \\-host

options are ignored.

The colon character (

.I :

) may be used to separate different executables

for MPMD (multiple program multiple data) programming.  For example,

to run the program 

.I ocean

on 4 processes and 

.I air

on 8 processes, use:

.nf

mpiexec -n 4 ocean : -n 8 air

.fi

.SH MPICH-SPECIFIC ARGUMENTS

Many of the implementations of process managers in MPICH support the

following arguments to 

.I mpiexec

:

.PD 0

.TP

.B -np <num> 

- A synonym for the standard 

.I \\-n

argument

.PD 1

.PD 0

.TP

.B -env <name> <value> 

- Set the environment variable 

.I <name>

to 

.I <value>

for

the processes being run by 

.I mpiexec

.PD 1

.PD 0

.TP

.B -envnone 

- Pass no environment variables (other than ones specified with

other 

.I \\-env

or 

.I \\-genv

arguments) to the processes being run by 

.I mpiexec

\&.

By default, all environment

variables are provided to each MPI process (rationale: principle of

least surprise for the user)

.PD 1

.PD 0

.TP

.B -envlist <list> 

- Pass the listed environment variables (names separated

by commas), with their current values, to the processes being run by

.I mpiexec

\&.

.PD 1

.PD 0

.TP

.B -genv <name> <value> 

- The 

.I \\-genv

options have the same meaning as their

corresponding 

.I \\-env

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).

.PD 1

.PD 0

.TP

.B -genvnone 

- Like 

.I \\-envnone

, but for all executables

.PD 1

.PD 0

.TP

.B -genvlist <list> 

- Like 

.I \\-envlist

, but for all executables

.PD 1

.PD 0

.TP

.B -usize <n> 

- Specify the value returned for the value of the attribute

.I MPI_UNIVERSE_SIZE

\&.

.PD 1

.PD 0

.TP

.B -l 

- Label standard out and standard error (

.I stdout

and 

.I stderr

) with

the rank of the process

.PD 1

.PD 0

.TP

.B -maxtime <n> 

- Set a timelimit of 

.I <n>

seconds.

.PD 1

.PD 0

.TP

.B -exitinfo 

- Provide more information on the reason each process exited if

there is an abnormal exit

.PD 1

.SH ENVIRONMENT VARIABLES FOR MPIEXEC

The following environment variables are understood by some versions of

.I mpiexec

\&.

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.

.PD 0

.TP

.B MPIEXEC_TIMEOUT  

- Maximum running time in seconds.  

.I mpiexec

will

terminate MPI programs that take longer than the value specified by

.I MPIEXEC_TIMEOUT

\&.

.PD 1

.PD 0

.TP

.B MPIEXEC_UNIVERSE_SIZE 

- Set the universe size

.PD 1

.PD 0

.TP

.B MPIEXEC_PORT_RANGE 

- Set the range of ports that 

.I mpiexec

will use 

in communicating with the processes that it starts.  The format of 

this is 

.I <low>:<high>

\&.

For example, to specify any port between

10000 and 10100, use 

.I 10000:10100

\&.

.PD 1

.PD 0

.TP

.B MPICH_PORT_RANGE 

- Has the same meaning as 

.I MPIEXEC_PORT_RANGE

and 

is used if 

.I MPIEXEC_PORT_RANGE

is not set.

.PD 1

.PD 0

.TP

.B MPIEXEC_PREFIX_DEFAULT 

- If this environment variable is set, output

to standard output is prefixed by the rank in 

.I MPI_COMM_WORLD

of the 

process and output to standard error is prefixed by the rank and the 

text 

.I (err)

; both are followed by an angle bracket (

.I >

).  If

this variable is not set, there is no prefix.

.PD 1

.PD 0

.TP

.B MPIEXEC_PREFIX_STDOUT 

- Set the prefix used for lines sent to standard

output.  A 

.I %d

is replaced with the rank in 

.I MPI_COMM_WORLD

; a 

.I %w

is 

replaced with an indication of which 

.I MPI_COMM_WORLD

in MPI jobs that

involve multiple 

.I MPI_COMM_WORLD

s (e.g., ones that use 

.I MPI_Comm_spawn

or

.I MPI_Comm_connect

).

.PD 1

.PD 0

.TP

.B MPIEXEC_PREFIX_STDERR 

- Like 

.I MPIEXEC_PREFIX_STDOUT

, but for standard error.

.PD 1

.SH RETURN STATUS

.I mpiexec

returns the maximum of the exit status values of all of the

processes created by 

.I mpiexec

\&.