orterun.1

MPI stands for the Message Passing Interface. Written by the MPI Forum (a large committee comprising

.\"
.\" Man page for ORTE's orterun command
.\" 
.\" .TH name     section center-footer   left-footer  center-header
.TH     MPIRUN  1       "March 2006" "Open MPI"   "OPEN MPI COMMANDS"
.\" **************************
.\"    Name Section
.\" **************************
.SH NAME
.
orterun, mpirun, mpiexec \- Execute serial and parallel jobs in Open MPI.

.B Note:
\fImpirun\fP, \fImpiexec\fP, and \fIorterun\fP are all exact synonyms for each
other.  Using any of the names will result in exactly identical behavior.
.
.\" **************************
.\"    Synopsis Section
.\" **************************
.SH SYNOPSIS
.
.PP
Single Process Multiple Data (SPMD) Model:

.B mpirun 
.R [ options ] 
.B <program>
.R [ <args> ]
.

Multiple Instruction Multiple Data (MIMD) Model:

.B mpirun
.R [ global_options ]
       [ local_options1 ]
.B <program1>
.R [ <args1> ] :
       [ local_options2 ]
.B <program2>
.R [ <args2> ] : 
       ... : 
       [ local_optionsN ]
.B <programN>
.R [ <argsN> ]
.P

Note that in both models, invoking \fImpirun\fR via an absolute path
name is equivalent to specifying the \fI--prefix\fR option with a
\fI<dir>\fR value equivalent to the directory where \fImpirun\fR
resides, minus its last subdirectory.  For example:

    \fBshell$\fP /usr/local/bin/mpirun ...

is equivalent to

    \fBshell$\fP mpirun --prefix /usr/local

.
.\" **************************
.\"    Quick Summary Section
.\" **************************
.SH QUICK SUMMARY
.
If you are simply looking for how to run an MPI application, you
probably want to use a command line of the following form:

    \fBshell$\fP mpirun [ -np X ] [ --hostfile <filename> ]  <program>

This will run X copies of \fI<program>\fR in your current run-time
environment (if running under a supported resource manager, Open MPI's
\fImpirun\fR will usually automatically use the corresponding resource manager
process starter, as opposed to, for example, \fIrsh\fR or \fIssh\fR,
which require the use of a hostfile, or will default to running all X
copies on the localhost), scheduling (by default) in a round-robin fashion by
CPU slot.  See the rest of this page for more details.
.
.\" **************************
.\"    Options Section
.\" **************************
.SH OPTIONS
.
.I mpirun
will send the name of the directory where it was invoked on the local
node to each of the remote nodes, and attempt to change to that
directory.  See the "Current Working Directory" section below for further
details.
.\"
.\" Start options listing
.\"    Indent 10 chacters from start of first column to start of second column
.TP 10
.B <args>
Pass these run-time arguments to every new process.  These must always
be the last arguments to \fImpirun\fP. If an app context file is used,
\fI<args>\fP will be ignored.
.
.
.TP
.B <program>
The program executable. This is identified as the first non-recognized argument
to mpirun.
.
.
.TP
.B -aborted\fR,\fP --aborted \fR<#>\fP
Set the maximum number of aborted processes to display.
.
.
.TP
.B --app \fR<appfile>\fP
Provide an appfile, ignoring all other command line options.
.
.
.TP
.B -bynode\fR,\fP --bynode
Allocate (map) the processes by node in a round-robin scheme.
.
.
.TP
.B -byslot\fR,\fP --byslot
Allocate (map) the processes by slot in a round-robin scheme. This is the
default.
.
.
.TP
.B -c \fR<#>\fP
Synonym for \fI-np\fP.
.
.
.TP
.B -debug\fR,\fP --debug
Invoke the user-level debugger indicated by the \fIorte_base_user_debugger\fP
MCA parameter.
.
.
.TP
.B -debugger\fR,\fP --debugger
Sequence of debuggers to search for when \fI--debug\fP is used (i.e.
a synonym for \fIorte_base_user_debugger\fP MCA parameter).
.
.
.TP
.B -gmca\fR,\fP --gmca \fR<key> <value>\fP
Pass global MCA parameters that are applicable to all contexts. \fI<key>\fP is
the parameter name; \fI<value>\fP is the parameter value.
.
.
.TP
.B -h\fR,\fP --help
Display help for this command
.
.
.TP
.B -H \fR<host1,host2,...,hostN>\fP
Synonym for \fI-host\fP.
.
.
.TP
.B -host\fR,\fP --host \fR<host1,host2,...,hostN>\fP
List of hosts on which to invoke processes.
.
.
.TP
.B -hostfile\fR,\fP --hostfile \fR<hostfile>\fP
Provide a hostfile to use. 
.\" JJH - Should have man page for how to format a hostfile properly.
.
.
.TP
.B -machinefile\fR,\fP --machinefile \fR<machinefile>\fP
Synonym for \fI-hostfile\fP.
.
.
.TP
.B -mca\fR,\fP --mca <key> <value>
Send arguments to various MCA modules.  See the "MCA" section, below.
.
.
.TP
.B -n\fR,\fP --n \fR<#>\fP
Synonym for \fI-np\fP.
.
.
.TP
.B -nolocal\fR,\fP --nolocal
Do not run any copies of the launched application on the same node as
orterun is running.  This option will override listing the localhost
with \fB--host\fR or any other host-specifying mechanism.
.
.
.TP
.B -nooversubscribe\fR,\fP --nooversubscribe
Do not oversubscribe any nodes; error (without starting any processes)
if the requested number of processes would cause oversubscription.
This option implicitly sets "max_slots" equal to the "slots" value for
each node.
.
.
.TP
.B -np \fR<#>\fP
Run this many copies of the program on the given nodes.  This option
indicates that the specified file is an executable program and not an
application context. If no value is provided for the number of copies to
execute (i.e., neither the "-np" nor its synonyms are provided on the command
line), Open MPI will automatically execute a copy of the program on
each process slot (see below for description of a "process slot"). This
feature, however, can only be used in the SPMD model and will return an
error (without beginning execution of the application) otherwise. 
.
.
.TP
.B -nw\fR,\fP --nw
Launch the processes and do not wait for their completion. mpirun will
complete as soon as successful launch occurs.
.
.
.TP
.B -path\fR,\fP --path \fR<path>\fP
<path> that will be used when attempting to locate requested executables.
.
.
.TP
.B --prefix \fR<dir>\fP
Prefix directory that will be used to set the \fIPATH\fR and
\fILD_LIBRARY_PATH\fR on the remote node before invoking Open MPI or
the target process.  See the "Remote Execution" section, below.
.
.
.TP
.B -q\fR,\fP --quiet
Suppress informative messages from orterun during application execution.
.
.
.TP
.B --tmpdir \fR<dir>\fP
Set the root for the session directory tree for mpirun only.
.
.
.TP
.B -tv\fR,\fP --tv
Launch processes under the TotalView debugger.
Deprecated backwards compatibility flag. Synonym for \fI--debug\fP.
.
.
.TP
.B --universe \fR<username@hostname:universe_name>\fP
For this application, set the universe name as:
     username@hostname:universe_name
.
.
.TP
.B -v\fR,\fP --verbose
Be verbose
.TP
.B -V\fR,\fP --version
Print version number.  If no other arguments are given, this will also
cause orterun to exit.
.
.
.TP
.B -wd \fR<dir>\fP
Synonym for \fI-wdir\fP.
.
.
.TP
.B -wdir \fR<dir>\fP
Change to the directory <dir> before the user's program executes.
See the "Current Working Directory" section for notes on relative paths.
.B Note:
If the \fI-wdir\fP option appears both on the command line and in an
application context, the context will take precedence over the command
line.
.
.
.TP
.B -x \fR<env>\fP
Export the specified environment variables to the remote nodes before
executing the program.  Existing environment variables can be
specified (see the Examples section, below), or new variable names
specified with corresponding values.  The parser for the \fI-x\fP
option is not very sophisticated; it does not even understand quoted
values.  Users are advised to set variables in the environment, and
then use \fI-x\fP to export (not define) them.
.
.
.P
The following options are useful for developers; they are not generally
useful to most ORTE and/or MPI users:
.
.TP
.B -d\fR,\fP --debug-devel
Enable debugging of the OpenRTE (the run-time layer in Open MPI).
This is not generally useful for most users.
.
.
.TP
.B --debug-daemons
Enable debugging of any OpenRTE daemons used by this application.
.
.
.TP
.B --debug-daemons-file
Enable debugging of any OpenRTE daemons used by this application, storing
output in files.
.
.
.TP
.B --no-daemonize
Do not detach OpenRTE daemons used by this application.
.
.
.\" **************************
.\"    Description Section
.\" **************************
.SH DESCRIPTION
.
One invocation of \fImpirun\fP starts an MPI application running under Open
MPI. If the application is single process multiple data (SPMD), the application
can be specified on the \fImpirun\fP command line.

If the application is multiple instruction multiple data (MIMD), comprising of
multiple programs, the set of programs and argument can be specified in one of
two ways: Extended Command Line Arguments, and Application Context.
.PP
An application context describes the MIMD program set including all arguments
in a separate file.
.\"See appcontext(5) for a description of the application context syntax.
This file essentially contains multiple \fImpirun\fP command lines, less the
command name itself.  The ability to specify different options for different
instantiations of a program is another reason to use an application context.
.PP
Extended command line arguments allow for the description of the application
layout on the command line using colons (\fI:\fP) to separate the specification
of programs and arguments. Some options are globally set across all specified
programs (e.g. --hostfile), while others are specific to a single program
(e.g. -np).
.
.
.
.SS Process Slots
.
Open MPI uses "slots" to represent a potential location for a process.
Hence, a node with 2 slots means that 2 processes can be launched on
that node. For performance, the community typically equates a "slot"
with a physical CPU, thus ensuring that any process assigned to that
slot has a dedicated processor. This is not, however, a requirement for
the operation of Open MPI.
.PP
Slots can be specified in hostfiles after the hostname.  For example:
.
.TP 4
host1.example.com slots=4
Indicates that there are 4 process slots on host1.
.
.PP
If no slots value is specified, then Open MPI will automatically assign
a default value of "slots=1" to that host.
.
.PP
When running under resource managers (e.g., SLURM, Torque, etc.), Open
MPI will obtain both the hostnames and the number of slots directly
from the resource manger.  For example, if running under a SLURM job,
Open MPI will automatically receive the hosts that SLURM has allocated
to the job as well as how many slots on each node that SLURM says
are usable - in most high-performance environments, the slots will
equate to the number of processors on the node.
.
.PP
When deciding where to launch processes, Open MPI will first fill up
all available slots before oversubscribing (see "Location
Nomenclature", below, for more details on the scheduling algorithms
available).  Unless told otherwise, Open MPI will arbitrarily
oversubscribe nodes.  For example, if the only node available is the
localhost, Open MPI will run as many processes as specified by the
-n (or one of its variants) command line option on the
localhost (although they may run quite slowly, since they'll all be
competing for CPU and other resources).
.
.PP
Limits can be placed on oversubscription with the "max_slots"
attribute in the hostfile.  For example:
.
.TP 4
host2.example.com slots=4 max_slots=6
Indicates that there are 4 process slots on host2.  Further, Open MPI
is limited to launching a maximum of 6 processes on host2.
.
.TP
host3.example.com slots=2 max_slots=2
Indicates that there are 2 process slots on host3 and that no
oversubscription is allowed (similar to the \fI--nooversubscribe\fR
option).
.
.TP
host4.example.com max_slots=2
Shorthand; same as listing "slots=2 max_slots=2".
.
.
.PP
Note that Open MPI's support for resource managers does not currently
set the "max_slots" values for hosts.  If you wish to prevent
oversubscription in such scenarios, use the \fI--nooversubscribe\fR
option.
.
.PP
In scenarios where the user wishes to launch an application across
all available slots by not providing a "-n" option on the mpirun
command line, Open MPI will launch a process on each process slot
for each host within the provided environment. For example, if a
hostfile has been provided, then Open MPI will spawn processes
on each identified host up to the "slots=x" limit if oversubscription
is not allowed. If oversubscription is allowed (the default), then
Open MPI will spawn processes on each host up to the "max_slots=y" limit
if that value is provided. In all cases, the "-bynode" and "-byslot"
mapping directives will be enforced to ensure proper placement of
process ranks.
.
.
.
.SS Location Nomenclature
.
As described above, \fImpirun\fP can specify arbitrary locations in
the current Open MPI universe.  Locations can be specified either by
CPU or by node.

.B Note:
This nomenclature does not force Open MPI to bind processes to CPUs --
specifying a location "by CPU" is really a convenience mechanism for
SMPs that ultimately maps down to a specific node.
.PP
Specifying locations by node will launch one copy of an executable per
specified node.