Scroll to navigation

mpiexec(1) MPI mpiexec(1)

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:





  

  
- Specify the number of processes to use

  

  
- Name of host on which to run processes

  

  
- Pick hosts with this architecture type

  

  
- cd to this one before running executable

  

  
- use this to find the executable

  

  
- comma separated triplets that specify requested numbers of processes
      (see the MPI-2 specification for more details)

  

  
- implementation-defined specification file

  

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





  

  
- A synonym for the standard -n argument

  

  
- Set the environment variable <name> to <value>
      for the processes being run by mpiexec
    

  

  

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

  

  

  
- Pass the listed environment variables (names separated by commas), with
      their current values, to the processes being run by mpiexec .
    

  

  

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

  

  
- Like -envnone , but for all executables

  

  
- Like -envlist , but for all executables

  

  
- Specify the value returned for the value of the attribute
      MPI_UNIVERSE_SIZE .
    

  

  

  
- Label standard out and standard error ( stdout and stderr
      ) with the rank of the process

  

  
- Set a timelimit of <n> seconds.

  

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





  

  
- Maximum running time in seconds. mpiexec will terminate MPI
      programs that take longer than the value specified by
      MPIEXEC_TIMEOUT .
    

  

  

  
- Set the universe size

  

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

  

  

  
- Has the same meaning as MPIEXEC_PORT_RANGE and is used if
      MPIEXEC_PORT_RANGE is not set.

  

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

  

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

  

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











  

    2/21/2022