Using Intel® MKL in MATLAB Executable (MEX) Files

Note: This document applies to Intel® MKL 10.3.x and MATLAB R2008a running on Windows*.


How can I configure MATLAB to run the Intel MKL 10.3.x at start-up?
By default, MATLAB R2008a uses Intel MKL 9.1 BLAS. To upgrade to the Intel MKL 10.3.x BLAS, follow the instructions in the document Using Intel MKL with MATLAB.


How do I link to Intel MKL with my MATLAB executable (mex) file?
To avoid conflicts with Intel MKL 9.1 BLAS used by MATLAB R2008a, please follow the instructions in the document Using Intel MKL with MATLAB when calling Intel MKL 10.3 BLAS functions from the mex file. Then link the mex file to the custom DLL

When linking to Intel MKL 10.3.x LAPACK and other functions (non-BLAS), we recommend linking Intel MKL 10.3.x to the mex file using either static linking or custom dynamic library linking. We expect to provide a more flexible and capable solution to resolve these compatibility issues in a future Intel MKL release.

The instructions below refer to an example C-language mex file, mex_dgemm.c, which calls the Intel MKL BLAS dgemm function. Intel MKL is installed to the default location.

Choosing a Compiler

MATLAB provides a command which searches for supported compilers installed on your system.

>> mex -setup

The above command also allows you to select the compiler you wish to use. Click here to view a list of MATLAB supported compilers. For more information, visit the MATLAB support web site.

Static Linking

Use the following command to statically link the mex file to the Intel MKL static libraries:

 

>> mex -v mex_dgemm.c ${MKL}\lib\ia32\mkl_intel_c.lib  ${MKL}\lib\ia32\mkl_intel_thread.lib

${MKL}\lib\ia32\mkl_core.lib ${MKL}\lib\ia32\libiomp5md.lib

where ${MKL}=C:\APPS\Intel\ComposerXE-2011\mkl

Refer to Intel MKL User's Guide, Chapter "Linking with Threading Libraries" for detailed instructions on statically linking to Intel MKL.

Note: It is important to always dynamically link to the Intel MKL threading library, libiomp5md.lib, to the mex file.

Custom Library Builder

For applications which use only a few Intel MKL functions or are limited by code size, we provide a tool to create a smaller, customized dynamic library for distribution. Follow the instructions contained in the Intel MKL User's Guide, Chapter "Linking with Threading Libraries" to create a new dynamic library, containing the functions you selected, with the Custom Library Builder. Use the following command line to link the mex file to the your custom dynamic library:

>> mex -v dgemm.c ${MKL}\tools\builder\mkl_custom.lib


MATLAB error message: "??? Error using ==> mex at 207 Unable to complete successfully."
When trying to build a mex file with Intel MKL, the MATLAB error message may be given:

??? Error using ==> mex at 207
Unable to complete successfully.

This error message occurs when MATLAB cannot find the Intel MKL libraries during the link step. Full paths to the location of the Intel MKL installation on the build system are required for the compiler to find the libraries and link to them. The default location for the latest version of MKL bundled with ComposerXE-2011 package: C:\Program Files\Intel\ComposerXE-2011\mkl\lib\ia32\

MATLAB error message: "??? Invalid MEX-file 'filename.mexw32': The specified module could not be found."
When trying to run a mex file linked with an Intel MKL Custom Dynamic Library, the MATLAB error message is given:

??? Invalid MEX-file 'filename.mexw32': The specified module could not be found.

This error occurs when the Intel MKL runtime libraries are not found by MATLAB. To resolve the error, either copy your custom dynamic library to the same directory as the mex file or make sure the location of your custom dynamic library is listed in the system path.


MATLAB crashes when running my mex file built with Intel MKL.
There can be two reasons for this:

  1. The mex file is linked to the static threading library, libiomp5mt.lib or libguide.lib. When the mex file is invoked, MATLAB crashes with one of the following error message printed in a command-line window:
    • OMP: Error #15: Initializing libiomp5mt.lib, but found libguide40.dll already intialized
    • OMP: Error #15: Initializing libguide.lib, but found libguide40.dll already intialized
    • OMP: Error #15: Initializing libiomp5md.dll, but found libguide40.dll already intialized

    This occurs when the threading library used by the mex file is conflicting with the threading library used by MATLAB. To resolve the problem, link the mex file to the dynamic threading library, libiomp5md.lib.

  2. The mex file is linked to the Intel MKL 10.3.x (or later) dynamic libraries. When the mex file is invoked, MATLAB crashes. This occurs when the Intel MKL dynamic libraries used by the mex file are conflicting with those used by MATLAB. To resolve the problem, use static linking or link to a custom dynamic library and link to the dynamic threading library. For more information see the document Intel MKL Version Compatibility.

We expect to provide a more flexible and capable solution to resolve these compatibility issues in a future Intel MKL release.

For more complete information about compiler optimizations, see our Optimization Notice.
Tags: