Developer Guide

Developer Guide for Intel® oneAPI Math Kernel Library macOS*

ID 766688
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

MKL_DOMAIN_NUM_THREADS

The MKL_DOMAIN_NUM_THREADS environment variable suggests the number of OpenMP threads for a particular function domain.

MKL_DOMAIN_NUM_THREADS accepts a string value <MKL-env-string>, which must have the following format:

<MKL-env-string> ::= <MKL-domain-env-string> { <delimiter><MKL-domain-env-string> }

<delimiter> ::= [ <space-symbol>* ] ( <space-symbol> | <comma-symbol> | <semicolon-symbol> | <colon-symbol>) [ <space-symbol>* ]

<MKL-domain-env-string> ::= <MKL-domain-env-name><uses><number-of-threads>

<MKL-domain-env-name> ::= MKL_DOMAIN_ALL | MKL_DOMAIN_BLAS | MKL_DOMAIN_FFT | MKL_DOMAIN_VML | MKL_DOMAIN_PARDISO

<uses> ::= [ <space-symbol>* ] ( <space-symbol> | <equality-sign> | <comma-symbol>) [ <space-symbol>* ]

<number-of-threads> ::= <positive-number>

<positive-number> ::= <decimal-positive-number> | <octal-number> | <hexadecimal-number>

In the syntax above, values of <MKL-domain-env-name> indicate function domains as follows:

MKL_DOMAIN_ALL

All function domains

MKL_DOMAIN_BLAS

BLAS Routines

MKL_DOMAIN_FFT

Fourier Transform Functions

MKL_DOMAIN_LAPACK

LAPACK Routines

MKL_DOMAIN_VML

Vector Mathematics (VM)

MKL_DOMAIN_PARDISO

Intel® oneAPI Math Kernel Library (oneMKL) PARDISO, a direct sparse solver based on Parallel Direct Sparse Solver (PARDISO*)

For example, you could set the MKL_DOMAIN_NUM_THREADSenvironment variable to any of the following string variants, in this case, defining three specific domain variables internal to Intel® oneAPI Math Kernel Library (oneMKL):

MKL_DOMAIN_NUM_THREADS="MKL_DOMAIN_ALL=2, MKL_DOMAIN_BLAS=1, MKL_DOMAIN_FFT=4"

MKL_DOMAIN_NUM_THREADS="MKL_DOMAIN_ALL 2 : MKL_DOMAIN_BLAS 1 : MKL_DOMAIN_FFT 4"

MKL_DOMAIN_NUM_THREADS="MKL_DOMAIN_ALL=2 : MKL_DOMAIN_BLAS=1 : MKL_DOMAIN_FFT=4"

MKL_DOMAIN_NUM_THREADS="MKL_DOMAIN_ALL=2; MKL_DOMAIN_BLAS=1; MKL_DOMAIN_FFT=4"

MKL_DOMAIN_NUM_THREADS="MKL_DOMAIN_ALL=2 MKL_DOMAIN_BLAS 1, MKL_DOMAIN_FFT 4"

MKL_DOMAIN_NUM_THREADS="MKL_DOMAIN_ALL,2: MKL_DOMAIN_BLAS 1, MKL_DOMAIN_FFT,4"

NOTE:
Prepend the appropriate set/export/setenv command for your command shell and operating system. Refer to Setting the Environment Variables for Threading Control for more details.

The global variables MKL_DOMAIN_ALL, MKL_DOMAIN_BLAS, MKL_DOMAIN_FFT, MKL_DOMAIN_VML, and MKL_DOMAIN_PARDISO, as well as the interface for the Intel® oneAPI Math Kernel Library (oneMKL) threading control functions, can be found in themkl.h header file.

NOTE:
You can retrieve the values of the specific domain variables that you have set in your code with a call to the mkl_get_domain_max_threads(domain_name) function per the Fortran and C interface with the desired domain variable name.

This table illustrates how values of MKL_DOMAIN_NUM_THREADS are interpreted.

Value of MKL_DOMAIN_NUM_THREADS

Interpretation

MKL_DOMAIN_ALL=4

All parts of Intel® oneAPI Math Kernel Library (oneMKL) should try four OpenMP threads. The actual number of threads may be still different because of theMKL_DYNAMIC setting or system resource issues. The setting is equivalent to MKL_NUM_THREADS = 4.

MKL_DOMAIN_ALL=1, MKL_DOMAIN_BLAS=4

All parts of Intel® oneAPI Math Kernel Library (oneMKL) should try one OpenMP thread, except for BLAS, which is suggested to try four threads.

MKL_DOMAIN_VML=2

VM should try two OpenMP threads. The setting affects no other part of Intel® oneAPI Math Kernel Library (oneMKL).

Be aware that the domain-specific settings take precedence over the overall ones. For example, the "MKL_DOMAIN_BLAS=4" value of MKL_DOMAIN_NUM_THREADS suggests trying four OpenMP threads for BLAS, regardless of later setting MKL_NUM_THREADS, and a function call "mkl_domain_set_num_threads ( 4, MKL_DOMAIN_BLAS );" suggests the same, regardless of later calls to mkl_set_num_threads().
However, a function call with input "MKL_DOMAIN_ALL", such as "mkl_domain_set_num_threads (4, MKL_DOMAIN_ALL);" is equivalent to "mkl_set_num_threads(4)", and thus it will be overwritten by later calls to mkl_set_num_threads. Similarly, the environment setting of MKL_DOMAIN_NUM_THREADS with "MKL_DOMAIN_ALL=4" will be overwritten with MKL_NUM_THREADS = 2.

Whereas the MKL_DOMAIN_NUM_THREADS environment variable enables you set several variables at once, for example, "MKL_DOMAIN_BLAS=4,MKL_DOMAIN_FFT=2", the corresponding function does not take string syntax. So, to do the same with the function calls, you may need to make several calls, which in this example are as follows:

mkl_domain_set_num_threads ( 4, MKL_DOMAIN_BLAS );

mkl_domain_set_num_threads ( 2, MKL_DOMAIN_FFT );