# 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 command-line options. The lines are of the form separated by the colons in the commandline form: mpiexec {<option arguments>} : {...} : {...} : ... : {...} Lines beginning with `#` are comments, and lines may be continued by terminating the partial line with `\`.

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/vc8XKeIJUJ/mpich-5.0.1/src/pm/hydra/mansrc/mpiexec.txt