| MPIEXEC(1) | LAM COMMANDS | MPIEXEC(1) |
mpiexec - Run MPI programs on LAM nodes.
mpiexec [global_args] local_args1 [: local_args2 [...]]
mpiexec [global_args] -configfile filename
Global arguments apply to all commands that will be launched by mpiexec. They come at the beginning of the command line.
One or more sets of local arguments must be specified (or a config file; see below). Local arguments essentially include everything allowed in an appschema(5) as well as the following options specified by the MPI-2 standard (note that the options listed below must be specified before appschema arguments):
mpiexec is loosely defined in the Miscellany chapter of the MPI-2 standard (see http://www.mpi-forum.org/). It is meant to be a portable mechanism for starting MPI processes. The MPI-2 standard recommends several command line options, but does not mandate any. LAM's mpiexec currently supports several of these options, but not all.
LAM's mpiexec is actually a perl script that is a wrapper around several underlying LAM commands, most notably lamboot, mpirun, and lamhalt. As such, the functionality provided by mpiexec can always be performed manually. Unless otherwise specified in arguments that are passed back to mpirun, mpiexec will use the per-CPU scheduling as described in mpirun(1) (i.e., the "cX" and "C" notation).
mpiexec can either use an already-existing LAM universe (i.e., a booted LAM run-time environment), similar to mpirun, or can be used for "one-shot" MPI executions where it boots the LAM run-time environment, runs the MPI executable(s), and then shuts down the LAM run-time environment.
mpiexec can also be used to launch MPMD MPI jobs from the command line. mpirun also supports launching MPMD MPI jobs, but the user must make a text file appschema(5) first.
Perhaps one of mpiexec's most useful features is the command-line ability to launch different executables on different architectures using the -arch flag (see EXAMPLES, below). Essentially, the string argument that is given to -arch is used as a pattern match against the output of the GNU config.guess utility on each node. If the user-provided architecture string matches any subset of the output of config.guess, it is ruled a match. Wildcards are not possible. The GNU config.guess utility is available both in the LAM/MPI source code distribution (in the config subdirectory) and at ftp://ftp.gnu.org/gnu/config/config.guess.
Some sample outputs from config.guess include:
You might want to run the laminfo command on your available platforms to see what string config.guess reported. See laminfo(1) for more details (e.g., the -arch flag to laminfo).
It is possible to specify any set of local parameters in a configuration file rather than on the command line using the -configfile option. This option is typically used when the number of command line options is too large for some shells, or when automated processes generate the command line arguments and it is simply more convenient to put them in a file for later processing by mpiexec.
The config file can contain both comments and one or more sets of local arguments. Lines beginning with "#" are considered comments and are ignored. Other lines are considered to be one or more groups of local arguments. Each group must be separated by either a newline or a colon (":"). For example:
# Sample mpiexec config file
# Launch foo on two nodes
-host node1.example.com foo : -host node2.example.com foo
# Launch two copies of bar on a third node
-host node3.example.com -np 2 bar
In the event of an error, mpiexec will do its best to shut everything down and return to the state before it was executed. For example, if mpiexec was used to boot a LAM run-time environment, mpiexec will do its best to take down whatever successfully booted of the run-time environment (to include invoking lamhalt and/or lamwipe).
The following are some examples of how to use mpiexec. Note that all examples assume the CPU-based scheduling (which does NOT map to physical CPUs) as described in mpirun(1).
| July, 2007 | LAM 7.1.4 |