Visible to Intel only — GUID: GUID-DD80A46E-800F-4245-9374-AAF7915DB910
Compilation Environment Variables
Hydra Environment Variables
I_MPI_ADJUST Family Environment Variables
Tuning Environment Variables
Process Pinning
GPU Support
Environment Variables for Fabrics Control
Environment Variables for Memory Policy Control
Environment Variables for Asynchronous Progress Control
Environment Variables for Multi-EP
Other Environment Variables
Visible to Intel only — GUID: GUID-DD80A46E-800F-4245-9374-AAF7915DB910
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:
|
| -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.
NOTE:
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 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 I_MPI_TUNING 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:
$ mpitune -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.
Parent topic: Command Reference