211. Portable MPI Process Startup

Up: Contents Next: The Info Object Previous: Determining Whether MPI Has Finished

A number of implementations of MPI provide a startup command for MPI programs that is of the form

    mpirun <mpirun arguments> <program> <program arguments>

Separating the command to start the program from the program itself provides flexibility, particularly for network and heterogeneous implementations. For example, the startup script need not run on one of the machines that will be executing the MPI program itself.

Having a standard startup mechanism also extends the portability of MPI programs one step further, to the command lines and scripts that manage them. For example, a validation suite script that runs hundreds of programs can be a portable script if it is written using such a standard starup mechanism. In order that the ``standard'' command not be confused with existing practice, which is not standard and not portable among implementations, instead of mpirun MPI specifies mpiexec.

While a standardized startup mechanism improves the usability of MPI, the range of environments is so diverse (e.g., there may not even be a command line interface) that MPI cannot mandate such a mechanism. Instead, MPI specifies an mpiexec startup command and recommends but does not require it, as advice to implementors. However, if an implementation does provide a command called mpiexec, it must be of the form described below.

It is suggested that

    mpiexec -n <numprocs> <program>

be at least one way to start <program> with an initial MPI_COMM_WORLD whose group contains <numprocs> processes. Other arguments to mpiexec may be implementation-dependent.

Advice to implementors.

Implementors, if they do provide a special startup command for MPI programs, are advised to give it the following form. The syntax is chosen in order that mpiexec be able to be viewed as a command-line version of MPI_COMM_SPAWN (See Section Reserved Keys ).

Analogous to MPI_COMM_SPAWN, we have

    mpiexec -n    <maxprocs> 
           -soft  <        > 
           -host  <        > 
           -arch  <        > 
           -wdir  <        > 
           -path  <        > 
           -file  <        > 
            ... 
           <command line>

for the case where a single command line for the application program and its arguments will suffice. See Section Reserved Keys for the meanings of these arguments. For the case corresponding to MPI_COMM_SPAWN_MULTIPLE there are two possible formats:

Form A:

    mpiexec { <above arguments> } : { ... } : { ... } : ... : { ... }

As with MPI_COMM_SPAWN, all the arguments are optional. (Even the -n x argument is optional; the default is implementation dependent. It might be 1, it might be taken from an environment variable, or it might be specified at compile time.) The names and meanings of the arguments are taken from the keys in the info argument to MPI_COMM_SPAWN. There may be other, implementation-dependent arguments as well.

Note that Form A, though convenient to type, prevents colons from being program arguments. Therefore an alternate, file-based form is allowed:

Form B:

    mpiexec -configfile <filename>

where the lines of $<$filename$>$ are of the form separated by the colons in Form A. Lines beginning with `#' are comments, and lines may be continued by terminating the partial line with `'.
Example Start 16 instances of myprog on the current or default machine:

    mpiexec -n 16 myprog

Example Start 10 processes on the machine called ferrari:

    mpiexec -n 10 -host ferrari myprog

Example Start three copies of the same program with different command-line arguments:

    mpiexec myprog infile1 : myprog infile2 : myprog infile3

Example Start the ocean program on five Suns and the atmos program on 10 RS/6000's:

    mpiexec -n 5 -arch sun ocean : -n 10 -arch rs6000 atmos

It is assumed that the implementation in this case has a method for choosing hosts of the appropriate type. Their ranks are in the order specified.
Example Start the ocean program on five Suns and the atmos program on 10 RS/6000's (Form B):

    mpiexec -configfile myfile

where myfile contains

    -n 5  -arch sun    ocean  
    -n 10 -arch rs6000 atmos

( End of advice to implementors.)

Up: Contents Next: The Info Object Previous: Determining Whether MPI Has Finished

Return to MPI-3.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-3.1 of June 4, 2015
HTML Generated on June 4, 2015