Speed Up Linear Algebra in Generated Standalone Code by Using LAPACK Calls

To improve the execution speed of code generated for certain linear algebra functions in standalone (library or executable program) code, specify that you want MATLAB^® Coder™ to generate LAPACK calls. LAPACK is a software library for numerical linear algebra. MATLAB Coder uses the LAPACKE C interface to LAPACK. If you specify that you want to generate LAPACK calls, and the input arrays for the linear algebra functions meet certain criteria, the code generator produces the LAPACK calls. Otherwise, the code generator produces code for the linear algebra functions.

For LAPACK calls in standalone code, MATLAB Coder uses the LAPACK library that you specify. Specify a LAPACK library that is optimized for your execution environment. See www.netlib.org/lapack/faq.html#_what_and_where_are_the_lapack_vendors_implementations.

Specify LAPACK Library

To generate LAPACK calls in standalone code, you must have access to a LAPACK callback class. A LAPACK callback class specifies the LAPACK library and LAPACKE header file for the LAPACK calls. To indicate that you want to generate LAPACK calls and that you want to use a specific LAPACK library, specify the name of the LAPACK callback class.

At the command line, set the code configuration object property CustomLAPACKCallback to the name of the callback class.
In the MATLAB Coder app, set Custom LAPACK library callback to the name of the callback class.

Write LAPACK Callback Class

To specify the locations of a particular LAPACK library and LAPACKE header file, write a LAPACK callback class. Share the callback class with others who want to use this LAPACK library for LAPACK calls in standalone code.

The callback class must derive from the abstract class coder.LAPACKCallback. Use the following example callback class as a template.

classdef useMyLAPACK < coder.LAPACKCallback
    methods (Static)
        function hn = getHeaderFilename()
            hn = 'mylapacke_custom.h';
        end
        function updateBuildInfo(buildInfo, buildctx)
            buildInfo.addIncludePaths(fullfile(pwd,'include'));
            libName = 'mylapack';
            libPath = fullfile(pwd,'lib');
            [~,linkLibExt] = buildctx.getStdLibInfo();
            buildInfo.addLinkObjects([libName linkLibExt], libPath, ...
                '', true, true);
            buildInfo.addDefines('HAVE_LAPACK_CONFIG_H');
            buildInfo.addDefines('LAPACK_COMPLEX_STRUCTURE');
            buildInfo.addDefines('LAPACK_ILP64'); 
        end
    end
end

You must provide the getHeaderFilename and updateBuildInfo methods. The getHeaderFilename method returns the LAPACKE header file name. In the example callback class, replace mylapacke_custom.h with the name of your LAPACKE header file. The updateBuildInfo method provides the information required for the build process to link to the LAPACK library. Use code like the code in the template to specify the location of header files and the full path name of the LAPACK library. In the example callback class, replace mylapack with the name of your LAPACK library.

If your compiler supports only complex data types that are represented as structures, include these lines in the updateBuildInfo method.

buildInfo.addDefines('HAVE_LAPACK_CONFIG_H');
buildInfo.addDefines('LAPACK_COMPLEX_STRUCTURE');

You must specify the integer type that your LAPACK library uses. Not specifying this integer type can result in incorrect behaviors or crashes. Do one of the following:

Include these lines in the updateBuildInfo method.

buildInfo.addDefines('HAVE_LAPACK_CONFIG_H');
buildInfo.addDefines('LAPACK_ILP64');

Alternatively, you can directly specify the integer type that your LAPACK library uses. For example, if the integer type is long long, include this line in the updateBuildInfo method.
```
buildInfo.addDefines('lapack_int=long long');
```

Generate LAPACK Calls by Specifying a LAPACK Callback Class

This example shows how to generate code that calls LAPACK functions in a specific LAPACK library. For this example, assume that the LAPACK callback class useMyLAPACK specifies the LAPACK library that you want to use.

Write a MATLAB function that calls a linear algebra function. For example, write a function mysvd that calls the MATLAB function svd.
```
function s = mysvd(A)
    %#codegen
    s = svd(A);
end
```
Define a code configuration object for a static library, dynamically linked library, or executable program. For example, define a configuration object for a dynamically linked library on a Windows^® platform.
```
cfg = coder.config('dll');
```
Specify the LAPACK callback class useMyLAPACK.
```
cfg.CustomLAPACKCallback = 'useMyLAPACK';
```
The callback class must be on the MATLAB path.
Generate code. Specify that the input A is a 500-by-500 array of doubles.
```
codegen mysvd -args {zeros(500)} -config cfg -report
```

If A is large enough, the code generator produces a LAPACK call for svd. Here is an example of a call to the LAPACK library function for svd.

info_t = LAPACKE_dgesvd(LAPACK_COL_MAJOR, 'N', 'N', (lapack_int)500,
    (lapack_int)500, &A[0], (lapack_int)500, &S[0], NULL, (lapack_int)1, NULL,
    (lapack_int)1, &superb[0]);

Locate LAPACK Library in Execution Environment

The LAPACK library must be available in your execution environment. If your LAPACK library is shared, use environment variables or linker options to specify the location of the LAPACK library.

On a Windows platform, modify the PATH environment variable.
On a Linux^® platform, modify the LD_LIBRARY_PATH environment variable or use the rpath linker option.
On a macOS platform, modify the DYLD_LIBRARY_PATH environment variable or use the rpath linker option.

To specify the rpath linker option, you can use the build information addLinkFlags method in the updateBuildInfo method of your coder.LAPACKCallback class. For example, for a GCC compiler:

buildInfo.addLinkFlags(sprintf('-Wl,-rpath,"%s"',libPath));

Documentation