Developer Reference

Global Hydra Options

This section describes the global options of the Intel® MPI Library's Hydra process manager. Global options are applied to all arguments sets in the launch command. Argument sets are separated by a colon '
:
'.

-tune
<filename>

Use this option to specify the file name that contains the tuning data in a binary format.

-usize
<usize>

Use this option to set
MPI_UNIVERSE_SIZE
, which is available as an attribute of the
MPI_COMM_WORLD
.
<size>
Define the universe size
SYSTEM
Set the size equal to the number of cores passed to
mpiexec
through the hostfile or the resource manager.
INFINITE
Do not limit the size. This is the default value.
<value>
Set the size to a numeric value ≥ 0.

-hostfile
<hostfile>
or -f
<hostfile>

Use this option to specify host names on which to run the application. If a host name is repeated, this name is used only once.
See also the
I_MPI_HYDRA_HOST_FILE
environment variable for more details.
Use the following options to change the process placement on the cluster nodes:
  • Use the
    -perhost
    ,
    -ppn
    , and
    -grr
    options to place consecutive MPI processes on every host using the round robin scheduling.
  • Use the
    -rr
    option to place consecutive MPI processes on different hosts using the round robin scheduling.

-machinefile
<machine file>
or -machine
<machine file>

Use this option to control process placement through a machine file. To define the total number of processes to start, use the
-n
option. For example:
> type machinefile node0:2 node1:2 node0:1

-hosts-group

Use this option to set node ranges using brackets, commas, and dashes (like in Slurm* Workload Manager).
For more details, see the
I_MPI_HYDRA_HOST_FILE
environment variable in Hydra Environment Variables.  

-silent-abort

Use this option to disable abort warning messages.
For more details, see the
I_MPI_SILENT_ABORT
environment variable in Hydra Environment Variables.  

-nameserver

Use this option to specify the nameserver in the
hostname:port
format.
For more details, see the
I_MPI_HYDRA_NAMESERVER
environment variable in Hydra Environment Variables.  

-genv <ENVVAR> <value>

Use this option to set the
<ENVVAR>
environment variable to the specified
<value>
for all MPI processes.

-genvall

Use this option to enable propagation of all environment variables to all MPI processes.

-genvnone

Use this option to suppress propagation of any environment variables to any MPI processes.
The option does not work for localhost.

-genvexcl
<list of env var names>

Use this option to suppress propagation of the listed environment variables to any MPI processes.

-genvlist
<list>

Use this option to pass a list of environment variables with their current values.
<list>
is a comma separated list of environment variables to be sent to all MPI processes.

-pmi-connect
<mode>

Use this option to choose the caching mode of process management interface (PMI) message. Possible values for
<mode>
are:
<mode>
The caching mode to be used
nocache
Do not cache PMI messages.
cache
Cache PMI messages on the local
pmi_proxy
management processes to minimize the number of PMI requests. Cached information is automatically propagated to child management processes.
lazy-cache
cache
mode with on-request propagation of the PMI information.
alltoall
Information is automatically exchanged between all
pmi_proxy
before any get request can be done. This is the default mode.
See the environment variable for more details.

-perhost
<# of processes >
, -ppn
<# of processes >,
or -grr
<# of processes>

Use this option to place the specified number of consecutive MPI processes on every host in the group using round robin scheduling. See the environment variable for more details.
When running under a job scheduler, these options are ignored by default. To be able to control process placement with these options, disable the variable.

-rr

Use this option to place consecutive MPI processes on different hosts using the round robin scheduling. This option is equivalent to "
-perhost 1
". See the environment variable for more details.

-trace-pt2pt

Use this option to collect the information about point-to-point operations using Intel® Trace Analyzer and Collector. The option requires that
your application be linked against the Intel® Trace Collector profiling library.

-trace-collectives

Use this option to collect the information about collective operations using Intel® Trace Analyzer and Collector. The option requires that
your application be linked against the Intel® Trace Collector profiling library.
Use the
-trace-pt2pt
and
-trace-collectives
to reduce the size of the resulting trace file or the number of message checker reports. These options work with both statically and dynamically linked applications.

-configfile
<filename>

Use this option to specify the file
<filename>
that contains the command-line options with one executable per line. Blank lines and lines that start with '
#
' are ignored. Other options specified in the command line are treated as global.
You can specify global options in configuration files loaded by default (
mpiexec.conf
in
<installdir>/etc
,
~/.mpiexec.conf
, and
mpiexec.conf
in the working directory). The remaining options can be specified in the command line.

-branch-count
<num>

Use this option to restrict the number of child management processes launched by the Hydra process manager, or by each
pmi_proxy
management process.
See the
I_MPI_HYDRA_BRANCH_COUNT
environment variable for more details.

-pmi-aggregate or -pmi-noaggregate

Use this option to switch on or off, respectively, the aggregation of the PMI requests. The default value is
-pmi-aggregate
, which means the aggregation is enabled by default.
See the
I_MPI_HYDRA_PMI_AGGREGATE
environment variable for more details.

-nolocal

Use this option to avoid running the
<executable>
on the host where
mpiexec
is launched. You can use this option on clusters that deploy a dedicated main node for starting the MPI jobs and a set of dedicated compute nodes for running the actual MPI processes.

-hosts
<nodelist>

Use this option to specify a particular
<nodelist>
on which the MPI processes should be run. For example, the following command runs the executable
a.out
on the hosts
host1
and
host2
:
> mpiexec -n 2 -ppn 1 -hosts host1,host2 test.exe
If
<nodelist>
contains only one node, this option is interpreted as a local option. See Local Options for details.

-iface
<interface>

Use this option to choose the appropriate network interface. For example, if the IP emulation of your InfiniBand* network is configured to
ib0
, you can use the following command.
> mpiexec -n 2 -iface ib0 test.exe
See the
I_MPI_HYDRA_IFACE
environment variable for more details.
Arguments

-l, -prepend-rank

Use this option to insert the MPI process rank at the beginning of all lines written to the standard output.

-s
<spec>

Use this option to direct standard input to the specified MPI processes.
Arguments
<spec>
Define MPI process ranks
all
Use all processes.
none
Do not direct standard output to any processes.
<l>,<m>,<n>
Specify an exact list and use processes
<l>
,
<m>
and
<n>
only. The default value is zero.
<k>,<l>-<m>,<n>
Specify a range and use processes
<k>
,
<l>
through
<m>
, and
<n>
.

-noconf

Use this option to disable processing of the
mpiexec.hydra
configuration files.

-ordered-output

Use this option to avoid intermingling of data outut from the MPI processes. This option affects both the standard output and the standard error streams.
When using this option, end the last output line of each process with the end-of-line '
\n
' character. Otherwise the application may stop responding.

-path
<directory>

Use this option to specify the path to the executable file.

-version or -V

Use this option to display the version of the Intel® MPI Library.

-info

Use this option to display build information of the Intel® MPI Library. When this option is used, the other command line arguments are ignored.

-delegate

Use this option to enable the domain-based authorization with the delegation ability. See User Authorization for details.

-impersonate

Use this option to enable the limited domain-based authorization. You will not be able to open files on remote machines or access mapped network drives. See User Authorization for details.

-localhost

Use this option to explicitly specify the local host name for the launching node.

-localroot

Use this option to launch the root process directly from
mpiexec
if the host is local. You can use this option to launch GUI applications. The interactive process should be launched before any other process in a job. For example:
> mpiexec -n 1 -host <host2> -localroot interactive.exe : -n 1 -host <host1> background.exe

-localonly

Use this option to run an application on the local node only. If you use this option only for the local node, the Hydra service is not required.

-register [-username <
user
> -password <
password
>]

You can specify the user name and password using the
-username
and
-password
options after the
-register
option. Otherwise you will be prompted to enter your credentials.

-remove

Use this option to delete the encrypted credentials from the registry.

-validate [-host <
hostname
>]

Validate the encrypted credentials for the current user.

-whoami

Use this option to print the current user name.

-map
<drive:\\host\share>

Use this option to create network mapped drive on nodes before starting executable
. Network drive will be automatically removed after the job completion.

-mapall

Use this option to request creation of all user created network mapped drives on nodes before starting executable. Network drives will be automatically removed after the job completion.

-logon

Use this option to force the prompt for user credentials.

-noprompt

Use this option to suppress the prompt for user credentials.

-port/-p

Use this option to specify the port that the service is listening on. See the
I_MPI_HYDRA_SERVICE_PORT
environment variable for more details.

-verbose or -v

Use this option to print debug information from
mpiexec
, such as:
  • Service processes arguments
  • Environment variables and arguments passed to start an application
  • PMI requests/responses during a job life cycle
See the
I_MPI_HYDRA_DEBUG
environment variable for more details.

-print-rank-map

Use this option to print out the MPI rank mapping.

-print-all-exitcodes

Use this option to print the exit codes of all processes.
Arguments

-v6

Use this option to force using the IPv6 protocol.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.