Intel® MPI Library

Developer Reference for Windows* OS

Download PDF
ID 768734
Date 3/31/2025
Public
Document Table of Contents
Document Table of Contents x
Developer Reference for Windows* OS
Developer Reference for Windows* OS x
Introduction Command Reference Environment Variable Reference Notices and Disclaimers
Introduction x
Introducing Intel® MPI Library Notational Conventions Related Information User Authorization
Command Reference x
Compiler Commands mpiexec.hydra cpuinfo impi_info
Compiler Commands x
Compilation Command Options
mpiexec.hydra x
Global Hydra Options Local Hydra Options
Environment Variable Reference x
Compilation Environment Variables Hydra Environment Variables I_MPI_ADJUST Family Environment Variables Tuning Environment Variables Main Thread Pinning Environment Variables for Fabrics Control Environment Variables for Memory Policy Control Other Environment Variables
Tuning Environment Variables x
Autotuning
Autotuning x
I_MPI_TUNING_AUTO Family Environment Variables
Main Thread Pinning x
Environment Variables for Main Thread Pinning I_MPI_PIN I_MPI_PIN_PROCESSOR_LIST Interoperability with OpenMP* API
Environment Variables for Fabrics Control x
Communication Fabrics Control Shared Memory Control OFI*-capable Network Fabrics Control
Developer Reference for Windows* OS

Environment Variables for Main Thread Pinning

NOTE:
Starting with the 2021.12 release, Intel(R) MPI supports only I_MPI_PIN. To use the old pinning logic, set I_MPI_HYDRA_TOPOLIB=ipl.

I_MPI_PIN

Turn on/off main thread pinning.

Syntax

I_MPI_PIN=<arg>

Arguments

<arg> Binary indicator
enable | yes | on | 1 Enable main thread pinning. This is the default value.
disable | no | off | 0 Disable main thread pinning.

Description

Set this environment variable to control the main thread pinning feature of the Intel® MPI Library.

I_MPI_PIN_PROCESSOR_LIST

Define a processor subset and the mapping rules for MPI main threads within this subset.

This environment variable is available for both Intel and non-Intel microprocessors, but it may perform additional optimizations for Intel microprocessors than it performs for non-Intel microprocessors.

Syntax Forms

I_MPI_PIN_PROCESSOR_LIST=<value>

The environment variable value has two syntax forms:

  1. <proclist>
  2. allcores

Syntax 1: <proclist>

I_MPI_PIN_PROCESSOR_LIST=<proclist>

Arguments

<proclist> A comma-separated list of logical processor numbers and/or ranges of processors. The main thread with the i-th rank is pinned to the i-th processor in the list. The number should not exceed the number of processors on a node.
<l> Processor with logical number <l>.
<l>-<m> Range of processors with logical numbers from <l> to <m>.
<k>,<l>-<m> Processors <k>, as well as <l> through <m>.

Syntax 2: allcores

I_MPI_PIN_PROCESSOR_LIST=allcores

Arguments

allcores

All cores (physical CPUs). Specify this subset to define the number of cores on a node. This is the default value.

If Intel® Hyper-Threading Technology is disabled, allcores equals to all.

NOTE:
This environment variable is valid only with enabled I_MPI_PIN.

Examples

To pin the processes to CPU0 and CPU3 on each node globally, use the following command: 

$ mpirun -genv I_MPI_PIN_PROCESSOR_LIST=0,3 -n <number-of-processes> <executable>

To pin the processes to different CPUs on each node individually (CPU0 and CPU3 on host1 and CPU0, CPU1 and CPU3 on host2), use the following command: 

$ mpirun -host host1 -env I_MPI_PIN_PROCESSOR_LIST=0,3 -n <number-of-processes> <executable> : \
-host host2 -env I_MPI_PIN_PROCESSOR_LIST=1,2,3 -n <number-of-processes> <executable>

To print extra debugging information about process pinning, use the following command: 

$ mpirun -genv I_MPI_DEBUG=4 -m -host host1 \
-env I_MPI_PIN_PROCESSOR_LIST=0,3 -n <number-of-processes> <executable> :\
-host host2 -env I_MPI_PIN_PROCESSOR_LIST=1,2,3 -n <number-of-processes> <executable>
NOTE:
If the number of processes is greater than the number of CPUs used for pinning, the process list is wrapped around to the start of the processor list.

Examples

To pin the main thread to CPU0 and CPU3 on each node globally, use the following command: 

> mpiexec -genv I_MPI_PIN_PROCESSOR_LIST=0,3 -n <number-of-main-threads> <executable>

To pin the main thread to different CPUs on each node individually (CPU0 and CPU3 on host1 and CPU0, CPU1 and CPU3 on host2), use the following command: 

> mpiexec -host host1 -env I_MPI_PIN_PROCESSOR_LIST=0,3 -n <number-of-main-threads> <executable> :^
-host host2 -env I_MPI_PIN_PROCESSOR_LIST=1,2,3 -n <number-of-main-threads> <executable>

To print extra debug information about the main thread pinning, use the following command: 

> mpiexec -genv I_MPI_DEBUG=4 -m -host host1 -env I_MPI_PIN_PROCESSOR_LIST=0,3 -n <number-of-main-threads> <executable> :^
-host host2 -env I_MPI_PIN_PROCESSOR_LIST=1,2,3 -n <number-of-main-threads> <executable>
NOTE:
If the number of main threads is greater than the number of CPUs used for pinning, the thread list is wrapped around to the start of the processor list.
Parent topic: Main Thread Pinning
Level Two Title