Developer Guide

Developer Guide for Intel® oneAPI Math Kernel Library Windows*

Download PDF
ID 766692
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
Document Table of Contents x
Developer Guide for Intel® oneAPI Math Kernel Library for Windows*
Developer Guide for Intel® oneAPI Math Kernel Library for Windows* x
Getting Help and Support What's New Notational Conventions Related Information Getting Started Structure of the Intel® oneAPI Math Kernel Library Linking Your Application with the Intel® oneAPI Math Kernel Library Managing Performance and Memory Language-specific Usage Options Obtaining Numerically Reproducible Results Coding Tips Managing Output Working with the Intel® oneAPI Math Kernel Library Cluster Software Managing Behavior of the Intel® oneAPI Math Kernel Library with Environment Variables Programming with Intel® Math Kernel Library in Integrated Development Environments (IDE) Intel® oneAPI Math Kernel Library Benchmarks Appendix A: Intel® oneAPI Math Kernel Library Language Interfaces Support Appendix B: Support for Third-Party Interfaces Appendix C: Directory Structure in Detail Notices and Disclaimers
Getting Started x
Shared Library Versioning CMake Config for oneMKL Checking Your Installation Setting Environment Variables Compiler Support Using Code Examples What You Need to Know Before You Begin Using the Intel® oneAPI Math Kernel Library
Structure of the Intel® oneAPI Math Kernel Library x
Architecture Support High-level Directory Structure Layered Model Concept
Linking Your Application with the Intel® oneAPI Math Kernel Library x
Linking Quick Start Linking Examples Linking in Detail Building Custom Dynamic-link Libraries Building a Universal Windows Driver
Linking Quick Start x
Using the /Qmkl Compiler Option Automatically Linking a Project in the Visual Studio* Integrated Development Environment with Intel® oneAPI Math Kernel Library Using the Single Dynamic Library Selecting Libraries to Link with Using the Link-line Advisor Using the Command-Line Link Tool
Automatically Linking a Project in the Visual Studio* Integrated Development Environment with Intel® oneAPI Math Kernel Library x
Automatically Linking Your Microsoft Visual C/C++* Project with oneMKL Automatically Linking Your Intel® Visual Fortran Project with oneMKL
Linking Examples x
Linking on IA-32 Architecture Systems Linking on Intel(R) 64 Architecture Systems
Linking in Detail x
Dynamically Selecting the Interface and Threading Layer Linking with Interface Libraries Linking with Threading Libraries Linking with Computational Libraries Linking with Compiler Run-time Libraries Linking with System Libraries
Linking with Interface Libraries x
Using the ILP64 Interface vs. LP64 Interface Linking with Fortran 95 Interface Libraries
Building Custom Dynamic-link Libraries x
Using the Custom Dynamic-link Library Builder in the Command-line Mode Composing a List of Functions Specifying Function Names Building a Custom Dynamic-link Library in the Visual Studio* Development System Distributing Your Custom Dynamic-link Library
Managing Performance and Memory x
Improving Performance with Threading Improving Performance for Small Size Problems Other Tips and Techniques to Improve Performance Using Memory Functions
Improving Performance with Threading x
OpenMP* Threaded Functions and Problems Functions Threaded with Intel® Threading Building Blocks Avoiding Conflicts in the Execution Environment Techniques to Set the Number of Threads Setting the Number of Threads Using an OpenMP* Environment Variable Changing the Number of OpenMP* Threads at Run Time Using Additional Threading Control Calling oneMKL Functions from Multi-threaded Applications Using Intel® Hyper-Threading Technology Managing Multi-core Performance Managing Performance with Heterogeneous Cores
Using Additional Threading Control x
oneMKL-specific Environment Variables for OpenMP Threading Control MKL_DYNAMIC MKL_DOMAIN_NUM_THREADS MKL_NUM_STRIPES Setting the Environment Variables for Threading Control
Improving Performance for Small Size Problems x
Using MKL_DIRECT_CALL in C Applications Using MKL_DIRECT_CALL in Fortran Applications Limitations of the Direct Call
Other Tips and Techniques to Improve Performance x
Coding Techniques Improving oneMKL Performance on Specific Processors Operating on Denormals
Using Memory Functions x
Avoiding Memory Leaks in oneMKL Redefining Memory Functions
Language-specific Usage Options x
Using Language-Specific Interfaces with Intel® oneAPI Math Kernel Library Mixed-language Programming with the Intel Math Kernel Library
Using Language-Specific Interfaces with Intel® oneAPI Math Kernel Library x
Interface Libraries and Modules Fortran 95 Interfaces to LAPACK and BLAS Compiler-dependent Functions and Fortran 90 Modules
Mixed-language Programming with the Intel Math Kernel Library x
Calling LAPACK, BLAS, and CBLAS Routines from C/C++ Language Environments Using Complex Types in C/C++ Calling BLAS Functions that Return the Complex Values in C/C++ Code
Obtaining Numerically Reproducible Results x
Getting Started with Conditional Numerical Reproducibility Specifying Code Branches Reproducibility Conditions Setting the Environment Variable for Conditional Numerical Reproducibility Code Examples C Example of CNR Fortran Example of CNR Use of CNR with Unaligned Data in C Use of CNR with Unaligned Data in Fortran
Coding Tips x
Example of Data Alignment Using Predefined Preprocessor Symbols for Intel® MKL Version-Dependent Compilation
Managing Output x
Using oneMKL Verbose Mode
Using oneMKL Verbose Mode x
Version Information Line Call Description Line
Working with the Intel® oneAPI Math Kernel Library Cluster Software x
Message-Passing Interface Support Linking with oneMKL Cluster Software Determining the Number of OpenMP* Threads Using DLLs Setting Environment Variables on a Cluster Interaction with the Message-passing Interface Using a Custom Message-Passing Interface Examples of Linking for Clusters
Examples of Linking for Clusters x
Examples for Linking a C Application Examples for Linking a Fortran Application
Managing Behavior of the Intel® oneAPI Math Kernel Library with Environment Variables x
Managing Behavior of Function Domains with Environment Variables Instruction Set Specific Dispatching on Intel® Architectures
Managing Behavior of Function Domains with Environment Variables x
Setting the Default Mode of Vector Math with an Environment Variable Managing Performance of the Cluster Fourier Transform Functions Managing Invalid Input Checking in LAPACKE Functions
Programming with Intel® Math Kernel Library in Integrated Development Environments (IDE) x
Configuring Your Integrated Development Environment to Link with Intel® oneAPI Math Kernel Library Getting Assistance for Programming in the Microsoft Visual Studio* IDE
Configuring Your Integrated Development Environment to Link with Intel® oneAPI Math Kernel Library x
Configuring the Microsoft Visual C/C++* Development System to Link with Intel® MKL Configuring Intel® Visual Fortran to Link with Intel MKL
Getting Assistance for Programming in the Microsoft Visual Studio* IDE x
Using Context-Sensitive Help Using the IntelliSense* Capability
Intel® oneAPI Math Kernel Library Benchmarks x
Intel Optimized LINPACK Benchmark for Windows* Intel® Distribution for LINPACK* Benchmark and Intel® Optimized HPL-AI* Benchmark
Intel Optimized LINPACK Benchmark for Windows* x
Contents of the Intel® Optimized LINPACK Benchmark Running the Software Known Limitations of the Intel® Optimized LINPACK Benchmark
Intel® Distribution for LINPACK* Benchmark and Intel® Optimized HPL-AI* Benchmark x
Overview of the Intel® Distribution for LINPACK* Benchmark Overview of the Intel® Optimized HPL-AI* Benchmark Contents of the Intel® Distribution for LINPACK* Benchmark and the Intel® Optimized HPL-AI* Benchmark Building the Intel® Distribution for LINPACK* Benchmark and the Intel® Optimized HPL-AI* Benchmark for a Customized MPI Implementation Building the Netlib HPL from Source Code Configuring Parameters Ease-of-use Command-line Parameters Running the Intel® Distribution for LINPACK* Benchmark and the Intel® Optimized HPL-AI* Benchmark Heterogeneous Support in the Intel® Distribution for LINPACK* Benchmark Environment Variables Improving Performance of Your Cluster
Appendix A: Intel® oneAPI Math Kernel Library Language Interfaces Support x
Language Interfaces Support, by Function Domain Include Files
Appendix B: Support for Third-Party Interfaces x
FFTW Interface Support
Appendix C: Directory Structure in Detail x
Detailed Structure of the IA-32 Architecture Directories Detailed Structure of the Intel® 64 Architecture Directories
Detailed Structure of the IA-32 Architecture Directories x
Static Libraries in the lib\\ia32 Directory Dynamic Libraries in the lib\\ia32 Directory Contents of the redist\\ia32 Directory
Detailed Structure of the Intel® 64 Architecture Directories x
Static Libraries in the lib\\intel64 Directory Dynamic Libraries in the lib\\intel64 Directory Contents of the redist\\intel64 Directory
Developer Guide for Intel® oneAPI Math Kernel Library for Windows*

Code Examples

The following simple programs show how to obtain reproducible results from run to run of Intel® oneAPI Math Kernel Library (oneMKL) functions. See the Intel® oneAPI Math Kernel Library (oneMKL) Developer Reference for more examples.

C Example of CNR

#include <mkl.h>
int main(void) {
    int my_cbwr_branch;
    /* Align all input/output data on 64-byte boundaries */
    /* "for best performance of Intel® oneAPI Math Kernel Library (oneMKL) */
    void *darray;
    int darray_size=1000;
    /* Set alignment value in bytes */
    int alignment=64;
    /* Allocate aligned array */
    darray = mkl_malloc (sizeof(double)*darray_size, alignment);
    /* Find the available MKL_CBWR_BRANCH automatically */
    my_cbwr_branch = mkl_cbwr_get_auto_branch();
    /* User code without oneMKL calls */
    /* Piece of the code where CNR of oneMKL is needed */
    /* The performance of oneMKL functions might be reduced for CNR mode */
/* If the "IF" statement below is commented out, Intel® oneAPI Math Kernel Library (oneMKL) will run in a regular mode, */
    /* and data alignment will allow you to get best performance */
    if (mkl_cbwr_set(my_cbwr_branch)) {
        printf("Error in setting MKL_CBWR_BRANCH! Aborting…\n”);
        return;
    }
    /* CNR calls to oneMKL + any other code */
    /* Free the allocated aligned array */
    mkl_free(darray);
}

Fortran Example of CNR

PROGRAM MAIN
    INCLUDE 'mkl.fi'
    INTEGER*4 MY_CBWR_BRANCH
! Align all input/output data on 64-byte boundaries
! for best performance of Intel® oneAPI Math Kernel Library (oneMKL)
! Declare oneMKL memory allocation routine
    DOUBLE PRECISION DARRAY
    POINTER (P_DARRAY,DARRAY(1))
    INTEGER DARRAY_SIZE
    PARAMETER (DARRAY_SIZE=1000)
! Set alignment value in bytes
    INTEGER ALIGNMENT
    PARAMETER (ALIGNMENT=64)
! Allocate aligned array
    INTEGER*8 ALLOC_SIZE
    ALLOC_SIZE = 8*DARRAY_SIZE
    P_DARRAY = MKL_MALLOC (ALLOC_SIZE, ALIGNMENT);
! Find the available MKL_CBWR_BRANCH automatically
    MY_CBWR_BRANCH = MKL_CBWR_GET_AUTO_BRANCH()
! User code without oneMKL calls
! Piece of the code where CNR of oneMKL is needed
! The performance of oneMKL functions may be reduced for CNR mode
! If the "IF" statement below is commented out,
! Intel® oneAPI Math Kernel Library (oneMKL) will run in a
! regular mode, and data alignment will enable you to get the best performance
    IF (MKL_CBWR_SET (MY_CBWR_BRANCH) .NE. MKL_CBWR_SUCCESS) THEN
        PRINT *, 'Error in setting MKL_CBWR_BRANCH! Aborting…'
        STOP 0
    ENDIF
! CNR calls to oneMKL + any other code
! Free the allocated aligned array
    CALL MKL_FREE(P_DARRAY)
END

Use of CNR with Unaligned Data in C

#include <mkl.h>
int main(void) {
     int my_cbwr_branch;
     /* If it is not possible to align all input/output data on 64-byte boundaries */
     /* to achieve performance, use unaligned IO data with possible performance */ 
     /* penalty */
     /* Using unaligned IO data */
     double *darray;
     int darray_size=1000;
     /* Allocate array, malloc aligns data on 8/16-byte boundary only */
     darray = (double *)malloc (sizeof(double)*darray_size);
     /* Find the available MKL_CBWR_BRANCH automatically */
     my_cbwr_branch = mkl_cbwr_get_auto_branch();
     /* User code without oneMKL calls */
     /* Piece of the code where CNR of oneMKL is needed */
     /* The performance of oneMKL functions might be reduced for CNR mode */
     /* If the "IF" statement below is commented out, oneMKL will run in a regular mode, */ 
     /* and you will NOT get best performance without data alignment */
     if (mkl_cbwr_set(my_cbwr_branch)) {
          printf("Error in setting MKL_CBWR_BRANCH! Aborting…\n");
          return;
}
     /* CNR calls to oneMKL + any other code */
     /* Free the allocated array */
     free(darray);

Use of CNR with Unaligned Data in Fortran

     PROGRAM MAIN
     INCLUDE 'mkl.fi'
     INTEGER*4 MY_CBWR_BRANCH
! If it is not possible to align all input/output data on 64-byte boundaries 
! to achieve performance, use unaligned IO data with possible performance 
! penalty 
     DOUBLE PRECISION, DIMENSION(:), ALLOCATABLE :: DARRAY
     INTEGER DARRAY_SIZE, STATUS
     PARAMETER (DARRAY_SIZE=1000)
! Allocate array with undefined alignment
     ALLOCATE(DARRAY(DARRAY_SIZE));
! Find the available MKL_CBWR_BRANCH automatically
     MY_CBWR_BRANCH = MKL_CBWR_GET_AUTO_BRANCH()
! User code without oneMKL calls
! Piece of the code where CNR of oneMKL is needed
! The performance of oneMKL functions might be reduced for CNR mode
! If the "IF" statement below is commented out, oneMKL will run in a regular mode, 
! and you will NOT get best performance without data alignment 
     IF (MKL_CBWR_SET(MY_CBWR_BRANCH) .NE. MKL_CBWR_SUCCESS) THEN
          PRINT *, 'Error in setting MKL_CBWR_BRANCH! Aborting…'
          RETURN
     ENDIF
! CNR calls to oneMKL + any other code
! Free the allocated array
     DEALLOCATE(DARRAY)
     END
Parent topic: Obtaining Numerically Reproducible Results
Level Two Title