# 4.1. Portable MPI Process Startup

Up: Miscellany Next: Passing NULL to MPI_Init Previous: Miscellany

A number of implementations of MPI-1 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.

This is advice to implementors, rather than a required part of MPI-2. It is not suggested that this be the only way to start MPI programs. If an implementation does provide a command called `mpiexec`, however, it must be of the form described here.

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: Miscellany Next: Passing NULL to MPI_Init Previous: Miscellany

Return to MPI-2 Standard Index
Return to MPI 1.1 Standard Index
Return to MPI Forum Home Page

MPI-2.0 of July 18, 1997
HTML Generated on September 10, 2001