Environment variables for OpenMP

If you use OpenMP constructs for parallelization, you can specify runtime options using the OMP environment variables.

OpenMP runtime options affecting parallel processing are set by specifying OMP environment variables. These environment variables use syntax of the form:


>>-env_variable--=--option_and_args----------------------------><

If an OMP environment variable is not explicitly set, its default setting is used.

For information about the OpenMP specification, see http://www.openmp.org.

OMP_DYNAMIC

The OMP_DYNAMIC environment variable enables or disables dynamic adjustment of the number of threads available for running parallel regions.

If it is set to TRUE, the number of threads available for executing parallel regions can be adjusted at run time to make the best use of system resources.

If it is set to FALSE, dynamic adjustment is disabled.

The default setting is TRUE.

OMP_MAX_ACTIVE_LEVELS

Use OMP_MAX_ACTIVE_LEVELS to set the max-active-levels-var internal control variable. This controls the maximum number of active nested parallel regions. The syntax is as follows:


>>-OMP_MAX_ACTIVE_LEVELS=n-------------------------------------><

where n is the maximum number of nested active parallel regions. It must be a positive scalar integer. The maximum number that you can specify is 5.

In programs where nested parallelism is disabled, the initial value is 1. In programs where nested parallelism is enabled, the initial value is greater than 1. The function omp_get_max_active_levels can be used to retrieve this value at run time.

OMP_NUM_THREADS

The OMP_NUM_THREADS environment variable specifies the number of threads to use for parallel regions.

The syntax of the environment variable is as follows:


>>-OMP_NUM_THREADS=--num_list----------------------------------><

num_list: A list of one or more positive integer values separated by commas.

If you do not set OMP_NUM_THREADS, the number of processors available is the default value to form a new team for the first encountered parallel construct. If nested parallelism is disabled, any nested parallel constructs are run by one thread by default.

If num_list contains a single value, dynamic adjustment of the number of threads is enabled (OMP_DYNAMIC is set to true), and a parallel construct without a num_threads clause is encountered, the value is the maximum number of threads that can be used to form a new team for the encountered parallel construct.

If num_list contains a single value, dynamic adjustment of the number of threads is not enabled (OMP_DYNAMIC is set to false), and a parallel construct without a num_threads clause is encountered, the value is the exact number of threads that can be used to form a new team for the encountered parallel construct.

If num_list contains multiple values, dynamic adjustment of the number of threads is enabled (OMP_DYNAMIC is set to true), and a parallel construct without a num_threads clause is encountered, the first value is the maximum number of threads that can be used to form a new team for the encountered parallel construct. After the encountered construct is entered, the first value is removed and the remaining values form a new num_list. The new num_list is in turn used in the same way for any closely nested parallel constructs inside the encountered parallel construct.

If num_list contains multiple values, dynamic adjustment of the number of threads is not enabled (OMP_DYNAMIC is set to false), and a parallel construct without a num_threads clause is encountered, the first value is the exact number of threads that can be used to form a new team for the encountered parallel construct. After the encountered construct is entered, the first value is removed and the remaining values form a new num_list. The new num_list is in turn used in the same way for any closely nested parallel constructs inside the encountered parallel construct.

Note: If the number of parallel regions is equal to or greater than the number of values in num_list, the omp_get_max_threads function returns the last value of num_list in the parallel region.

If the number of threads requested exceeds the system resources available, the program stops.

The omp_set_num_threads function sets the first value of num_list. The omp_get_max_threads function returns the first value of num_list.

If you specify the number of threads for a given parallel region more than once with different settings, the compiler uses the following precedence order to determine which setting takes effect:

The number of threads set using the num_threads clause takes precedence over that set using the omp_set_num_threads function.
The number of threads set using the omp_set_num_threads function takes precedence over that set using the OMP_NUM_THREADS environment variable.

See the following example:

export OMP_NUM_THREADS=3,4,5
export OMP_DYNAMIC=false

// omp_get_max_threads() returns 3

#pragma omp parallel
{  
// Three threads running the parallel region  
// omp_get_max_threads() returns 4
  
  #pragma omp parallel if(0)
  {
  // One thread running the parallel region 
  // omp_get_max_threads() returns 5

    #pragma omp parallel
    {  
    // Five threads running the parallel region   
    // omp_get_max_threads() returns 5 
    } 
  }
}

OMP_PROC_BIND

The OMP_PROC_BIND environment variable controls whether OpenMP threads can be moved between processors. The syntax is as follows:


>>-OMP_PROC_BIND=--+-TRUE--+-----------------------------------><
                   '-FALSE-'

By default, the OMP_PROC_BIND environment variable is not set. If you set OMP_PROC_BIND to TRUE, the threads are bound to processors. If you set OMP_PROC_BIND to FALSE, the threads may be moved between processors.

Note: The OMP_PROC_BIND environment variable provides a portable way to control whether OpenMP threads can be migrated.

OMP_SCHEDULE

The OMP_SCHEDULE environment variable specifies the scheduling algorithm used for loops with the omp schedule(runtime) clause.

For example:

OMP_SCHEDULE=“guided, 4”

Valid options for algorithm are:

auto
dynamic[, n]
guided[, n]
runtime
static[, n]

If specifying a chunk size with n, the value of n must be a positive integer.

The default scheduling algorithm is auto.

OMP_STACKSIZE

The OMP_STACKSIZE environment variable indicates the stack size of threads created by the OpenMP run time. OMP_STACKSIZE sets the value of the stacksize-var internal control variable. OMP_STACKSIZE does not control the stack size of the master thread. The syntax is as follows:


>>-OMP_STACKSIZE=----size--------------------------------------><

By default, the size value is represented in Kilobytes. You can also use the suffixes B, K, M, or G if you want to indicate the size in Bytes, Kilobytes, Megabytes, or Gigabytes respectively. White space is allowed between and around the size value and the suffix. For example, the following examples both indicate a stack size of 10 Megabytes.

setenv OMP_STACKSIZE 10M

setenv OMP_STACKSIZE " 10 M "

If OMP_STACKSIZE is not set, the initial value of the stacksize-var internal control variable is set to the default value. The default value for 32-bit mode is 256M. For 64-bit mode, the default is up to the limit imposed by system resources.

If the compiler cannot use the stack size specified or if OMP_STACKSIZE does not conform to the correct format, the compiler sets the environment variable to the default value.

OMP_THREAD_LIMIT

The OMP_THREAD_LIMIT environment variable sets the number of OpenMP threads to use for the whole program. The syntax is as follows:


>>-OMP_THREAD_LIMIT=--n----------------------------------------><

n: The number of OpenMP threads to use for the whole program. It must be a positive scalar integer.

The value for OMP_THREAD_LIMIT is a positive integer. When nested parallelism is enabled, the value you specify for OMP_THREAD_LIMIT can affect the behavior of a parallel region. For example, if the value of OMP_THREAD_LIMIT is much smaller than the number of threads required in the program, say OMP_THREAD_LIMIT=1, the parallel region is run sequentially rather than in parallel.

If the OMP_THREAD_LIMIT environment variable is not set and the OMP_NUM_THREADS environment variable is set to a single value, the default value for OMP_THREAD_LIMIT is the value of OMP_NUM_THREADS or the number of available processors, whichever is greater.

If the OMP_THREAD_LIMIT environment variable is not set and the OMP_NUM_THREADS environment variable is set to a list, the default value for OMP_THREAD_LIMIT is the multiplication of all the numbers in the list or the number of available processors, whichever is greater.

If the OMP_THREAD_LIMIT and OMP_NUM_THREADS environment variables are both not set, the default value for OMP_THREAD_LIMIT is the number of available processors.

OMP_WAIT_POLICY

The OMP_WAIT_POLICY environment variable gives hints to the compiler about the preferred behavior of waiting threads during program run time. The OMP_WAIT_POLICY environment variable sets the wait-policy-var internal control variable value.

The syntax is as follows:


                     .-PASSIVE-.   
>>-OMP_WAIT_POLICY=--+-ACTIVE--+-------------------------------><

The default value for OMP_WAIT_POLICY is PASSIVE.

Use ACTIVE if you want waiting threads to be mostly active. With ACTIVE, the thread consumes processor cycles while waiting, if possible.

Use PASSIVE if you want waiting threads to be mostly passive. That is, the preference is for the thread to not consume processor cycles while waiting. For example, you prefer waiting threads to sleep or to yield the processor to other threads.