Developer Reference

mpitune

Tunes the Intel® MPI Library parameters for the given MPI application.
Syntax
mpitune <
options
>
Arguments
mpitune Options
Options
-c | --config-file <
file
>
Specify a configuration file to run a tuning session.
-d | --dump-file <
file
>
Specify a file that stores the collected results. The option is used in the
analyze
mode.
-m | --mode {collect | analyze}
Specify the
mpitune
mode. The supported modes are
collect
and  
analyze
:
  • the  
    collect
    mode runs the tuning process and saves results in temporary files;
  • the  
    analyze
    mode transforms temporary files into a JSON-tree, which is used by the Intel MPI Library, and generates a table that represents algorithm values in a human-readable format.
-h | --help
Display the help message.
-v | --version
Display the product version.
Description
The
mpitune
utility allows you to automatically adjust Intel MPI Library parameters, such as collective operation algorithms, to your cluster configuration or application.
The tuner iteratively launches a benchmarking application with different configurations to measure performance and stores the results of each launch. Based on these results, the tuner generates optimal values for the parameters being tuned.
Starting with the Intel MPI Library 2019 Update 4 release, you must specify two
mpitune
configuration files, which differ in their
mode
and
dump-file
fields. A simpler alternative may be to use one of the single configuration file templates shipped with the Intel MPI Library. In this case, you must use the command line to define the
mode
and
dump-file
fields.
  • The
    -mode
    option defines one of two possible MPI tune modes:
    collect
    or
    analyze
    .
  • The
    -dump-file
    option defines the path to the temporary files when in
    analyze
    mode. This path is returned by mpitune after the first iteration.
The configuration files should specify all tuner parameters, which are passed to the tuner with the
--config-file
option. A typical configuration file consists of the main section, specifying generic options, and search space sections for specific library parameters (for example, for specific collective operations). To comment a line, use the hash symbol
#
.  All configuration file examples are available at
<installdir>/etc/tune_cfg
. Please note that configuration files for Intel® MPI Benchmarks are already created.
The tuning process consists of two steps: data collection (the
collect
mode) and data analysis (the
analyze
mode):
> mpitune -m collect -c <path-to-config-file2> > mpitune -m analyze -c <path-to-config-file1>
Another variant of the launch is:
> mpitune -m collect -c <path-to-config-file1> -d <path-to-dump-file> > mpitune -m analyze -c <path-to-config-file1>
where the path to the dump-file received in the first step is used in the config file with templates inside.
The tuning results are presented as a JSON tree and can be added to the library with the environment variable.

MPI Options Support

The following MPI options are available within the utility:
MPI Options
Description
-f
<filename>
Specify a file containing host names.
-hosts
<hostlist>
Specify a comma-separated list of hosts.
-np
<value>
Specify the number of processes.

Examples

> mpitune -np 2 -ppn 1 -hosts HOST1,HOST2 -m collect -c <path-to-config-file2> > mpitune -np 2 -ppn 1 -hosts HOST1,HOST2 -m analyze -c <path-to-config-file1>

Configuration File Format

All tuner parameters should be specified in two configuration files, passed to the tuner with the
--config-file
option. A typical configuration file consists of the main section, specifying generic options, and search space sections for specific library parameters (for example, for specific collective operations). Configuration files differ in mode and dump-file fields only. To comment a line, use the hash symbol #.
You can also specify MPI options to simplify
mpitune
usage. MPI options are useful for Intel® MPI Benchmarks that have special templates for
mpitune
located at
<
install-dir
>/etc/tune_cfg
. The templates require no changes in configuration files to be made.
For example, to tune the
Bcast
collective algorithm, use the following option:
> mpiexec -np 2 -ppn 2 -hosts HOST1 -m analyze -c <path-to-Bcast.cfg>
Experienced users can change configuration files to use this option for other applications.

Output Format

The tuner presents results in a JSON tree view (since the 2019 release), where the
comm_id=-1
layer is added automatically for each tree:
{ "coll=Reduce": { "ppn=2": { "comm_size=2": { "comm_id=-1": { "msg_size=243": { "REDUCE=8": {} }, "msg_size=319": { "REDUCE=11": {} }, "msg_size=8192": { "REDUCE=8": {} }, "msg_size=28383": { "REDUCE=9": {} }, "msg_size=-1": { "REDUCE=1": {} } } } } } }
To add the resulting JSON tree to the library, use the
I_MPI_TUNING
environment variable.

Old Output Format

The old output format is only valid for Intel MPI Library 2018 and prior versions:
I_MPI_ADJUST_BCAST=2:0-0;1:1-64;2:65-509;1:510-8832;3:8833-0
Use the resulting variable value with the application launch to achieve performance gain.
See Also
MPI Tuning in the Developer Guide.
For available configuration options, refer to mpitune Configuration Options.

Product and Performance Information

1

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