# 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 suggests 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
-wdir <working directory>
  cd to this one before running executable
-configfile <name>
  file containing specifications of host/program, one per line, with # as a comment indicator, e.g., the usual mpiexec input. The lines excluding comments are concatenated with newlines replaced with spaces, and are then parsed as command line options.

The following options are reserved by the MPI standard, but they are not supported by MPICH (hydra):

-arch <architecture name>
  Pick hosts with this architecture type
-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

Additional arguments that are specific to the MPICH implementation are discussed below.

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/edNwVKBAwA/mpich-4.3.0rc1/src/pm/hydra/mansrc/mpiexec.txt