# mpiexec

Run an MPI program

## Synopsis

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

where `args` are command line arguments for `mpiexec` (see below), `executable` is the name of an executable MPI program, and `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 `a.out` on 4 processes:

        mpiexec -n 4 a.out

The MPI standard specifies the following arguments and their meanings:

-n <np>
  Specify the number of processes to use
-host <hostname>
  Name of host on which to run processes
-arch <architecture name>
  Pick hosts with this architecture type
-wdir <working directory>
  cd to this one before running executable
-path <pathlist>
  use this to find the executable
-soft <triplets>
  comma separated triplets that specify requested numbers of processes (see the MPI-2 specification for more details)
-file <name>
  implementation-defined specification file
-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.

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 `gforker` version of `mpiexec` creates all processes on the same system on which it is running; in that case, the `\-arch` and `\-host` options are ignored.

The colon character (`:`) may be used to separate different executables for MPMD (multiple program multiple data) programming. For example, to run the program `ocean` on 4 processes and `air` on 8 processes, use:

        mpiexec -n 4 ocean : -n 8 air

## MPICH-Specific Arguments

MPICH implements a few process managers. Here we list a general set of arguments that many of the implementations support. More detailed options that are supported by a particular implementation, e.g. hydra, are available via:

        mpiexec -h

Many of the implementations of process managers in MPICH support the following arguments to `mpiexec`:

-np <num>
  A synonym for the standard `\-n` argument
-env <name> <value>
  Set the environment variable `<name>` to `<value>` for the processes being run by `mpiexec`
-envnone
  Pass no environment variables (other than ones specified with other `\-env` or `\-genv` arguments) to the processes being run by `mpiexec`. By default, all environment variables are provided to each MPI process (rationale: principle of least surprise for the user)
-envlist <list>
  Pass the listed environment variables (names separated by commas), with their current values, to the processes being run by `mpiexec`.
-genv <name> <value>
  The `\-genv` options have the same meaning as their corresponding `\-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 executables).
-genvnone
  Like `\-envnone`, but for all executables
-genvlist <list>
  Like `\-envlist`, but for all executables
-usize <n>
  Specify the value returned for the value of the attribute `MPI_UNIVERSE_SIZE`.
-l
  Label standard out and standard error (`stdout` and `stderr`) with the rank of the process
-maxtime <n>
  Set a timelimit of `<n>` seconds.
-exitinfo
  Provide more information on the reason each process exited if there is an abnormal exit

## Environment variables for mpiexec

The following environment variables are understood by some versions of `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.

MPIEXEC_TIMEOUT
  Maximum running time in seconds. `mpiexec` will terminate MPI programs that take longer than the value specified by `MPIEXEC_TIMEOUT`.
MPIEXEC_UNIVERSE_SIZE
  Set the universe size
MPIEXEC_PORT_RANGE
  Set the range of ports that `mpiexec` will use in communicating with the processes that it starts. The format of this is `<low>:<high>`. For example, to specify any port between 10000 and 10100, use `10000:10100`.
MPICH_PORT_RANGE
  Has the same meaning as `MPIEXEC_PORT_RANGE` and is used if `MPIEXEC_PORT_RANGE` is not set.

  ## Return Status

  `mpiexec` returns the maximum of the exit status values of all of the processes created by `mpiexec`.

  Location:/var/tmp/D6Fh70cM3H/mpich-4.1/src/pm/hydra/mansrc/mpiexec.txt