NAME

       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

       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 execuables).
       -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.
       MPIEXEC_PREFIX_DEFAULT
              - If this environment variable is set, output to standard output is prefixed by the
              rank in MPI_COMM_WORLD of the process and output to standard error is  prefixed  by
              the rank and the text (err) ; both are followed by an angle bracket ( > ).  If this
              variable is not set, there is no prefix.
       MPIEXEC_PREFIX_STDOUT
              - Set the prefix used for lines sent to standard output.  A %d is replaced with the
              rank   in   MPI_COMM_WORLD  ;  a  %w  is  replaced  with  an  indication  of  which
              MPI_COMM_WORLD in MPI jobs that involve multiple MPI_COMM_WORLD s (e.g., ones  that
              use MPI_Comm_spawn or MPI_Comm_connect ).
       MPIEXEC_PREFIX_STDERR
              - Like MPIEXEC_PREFIX_STDOUT , but for standard error.

RETURN STATUS

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

LOCATION

       src/env/mpiexec.txt

                                            4/24/2013                                  mpiexec(1)