Call LAPACK and BLAS Functions

You can call a LAPACK or BLAS function using a MEX file. To create a MEX file, you need C/C++ or Fortran programming experience and the software resources (compilers and linkers) to build an executable file. It also is helpful to understand how to use Fortran subroutines. MATLAB^® provides the mwlapack and mwblas libraries in matlabroot/extern/lib. To help you get started, there are source code examples in matlabroot/extern/examples/refbook.

To call LAPACK or BLAS functions:

Create a source MEX file containing the mexFunction gateway routine.
Make sure that you have a supported compiler for your platform. For an up-to-date list of supported compilers, see Supported and Compatible Compilers.
Build a binary MEX file using the mex command and the separate complex build flag -R2017b.
- Link your source file to one or both of the libraries, mwlapack and mwblas.
- The mwlapack and mwblas libraries only support 64-bit integers for matrix dimensions. Do not use the -compatibleArrayDims option.
- To build a MEX file with functions that use complex numbers, see Pass Separate Complex Numbers to Fortran Functions.
For information about BLAS or LAPACK functions, see https://netlib.org/blas/ or https://netlib.org/lapack/.

Build `matrixMultiply` MEX Function Using BLAS Functions

This example shows how to build the example MEX file matrixMultiply.c, which uses functions from the BLAS library. To work with this file, copy it to a local folder. For example:

copyfile(fullfile(matlabroot,'extern','examples','refbook','matrixMultiply.c'),'.')

The example files are read-only files. To modify an example, ensure that the file is writable by typing:

fileattrib('matrixMultiply.c','+w')

To build the MEX file, type:

mex -v -R2017b matrixMultiply.c -lmwblas

To run the MEX file, type:

A = [1 3 5; 2 4 7];
B = [-5 8 11; 3 9 21; 4 0 8];
X = matrixMultiply(A,B)

X =
    24    35   114
    30    52   162

Preserve Input Values from Modification

Many LAPACK and BLAS functions modify the values of arguments passed to them. It is good practice to make a copy of arguments you can modify before passing them to these functions. For information about how MATLAB handles arguments to the mexFunction, see Managing Input and Output Parameters.

`matrixDivide` Example

This example calls the LAPACK function dgesv that modifies its input arguments. The code in this example makes copies of prhs[0] and prhs[1], and passes the copies to dgesv to preserve the contents of the input arguments.

To see the example, open matrixDivide.c in the MATLAB Editor. To create the MEX file, copy the source file to a writable folder.

copyfile(fullfile(matlabroot,'extern','examples','refbook','matrixDivide.c'),'.')

To build the file, type:

mex -v -R2017b matrixDivide.c -lmwlapack

To test, type:

A = [1 2; 3 4];
B = [5; 6];
X = matrixDivide(A,B)

X =
   -4.0000
    4.5000

Pass Arguments to Fortran Functions from C/C++ Programs

The LAPACK and BLAS functions are written in Fortran. C/C++ and Fortran use different conventions for passing arguments to and from functions. Fortran functions pass arguments by reference, while C/C++ functions pass arguments by value. When you pass by value, you pass a copy of the value. When you pass by reference, you pass a pointer to the value. A reference is also the address of the value.

When you call a Fortran subroutine, like a function from LAPACK or BLAS, from a C/C++ program, be sure to pass the arguments by reference. To pass by reference, precede the argument with an ampersand (&), unless that argument is already a reference. For example, when you create a matrix using the mxGetDoubles function, you create a reference to the matrix and do not need the ampersand before the argument.

In the following code snippet, variables m, n, p, one, and zero need the & character to make them a reference. Variables A, B, C, and chn are pointers, which are references.

/* pointers to input & output matrices*/
double *A, *B, *C;
/* matrix dimensions */
mwSignedIndex m,n,p;
/* other inputs to dgemm */
char *chn = "N";
double one = 1.0, zero = 0.0;

/* call BLAS function */
dgemm(chn, chn, &m, &n, &p, &one, A, &m, B, &p, &zero, C, &m);

`matrixMultiply` Example

The matrixMultiply.c example calls dgemm, passing all arguments by reference. To see the source code, open matrixMultiply.c in the MATLAB Editor. To build and run this example, see Build matrixMultiply MEX Function Using BLAS Functions.

Pass Arguments to Fortran Functions from Fortran Programs

You can call LAPACK and BLAS functions from Fortran MEX files. The following example takes two matrices and multiplies them by calling the BLAS routine dgemm. To run the example, copy the code into the editor and name the file calldgemm.F.

#include "fintrf.h"

      subroutine mexFunction(nlhs, plhs, nrhs, prhs)
      mwPointer plhs(*), prhs(*)
      integer nlhs, nrhs
      mwPointer mxcreatedoublematrix
      mwPointer mxgetpr
      mwPointer A, B, C
      mwSize mxgetm, mxgetn
      mwSignedIndex m, n, p
      mwSize numel
      double precision one, zero, ar, br
      character ch1, ch2
      
      ch1 = 'N'
      ch2 = 'N'
      one = 1.0
      zero = 0.0
      
      A = mxgetpr(prhs(1))
      B = mxgetpr(prhs(2))
      m = mxgetm(prhs(1))
      p = mxgetn(prhs(1))
      n = mxgetn(prhs(2))
      
      plhs(1) = mxcreatedoublematrix(m, n, 0.0)
      C = mxgetpr(plhs(1))
      numel = 1
      call mxcopyptrtoreal8(A, ar, numel)
      call mxcopyptrtoreal8(B, br, numel)
      
      call dgemm(ch1, ch2, m, n, p, one, %val(A), m,
     +           %val(B), p, zero, %val(C), m)
      
      return
      end

Link to the BLAS library, which contains the dgemm function.

mex -v -R2017b calldgemm.F -lmwblas

Modify Function Name on UNIX Systems

Add an underscore character following the function name when calling LAPACK or BLAS functions on a UNIX^® system. For example, to call dgemm, use:

dgemm_(arg1, arg2, ..., argn);

Or add these lines to your source code:

#if !defined(_WIN32)
#define dgemm dgemm_
#endif