External Interfaces/API

Using LAPACK and BLAS Functions

LAPACK is a large, multiauthor Fortran subroutine library that MATLAB uses for numerical linear algebra. BLAS, which stands for Basic Linear Algebra Subroutines, is used by MATLAB to speed up matrix multiplication and the LAPACK routines themselves. The functions provided by LAPACK and BLAS can also be called directly from within your C MEX-files.

This section explains how to write and build MEX-files that call LAPACK and BLAS functions. It provides information on

• Specifying the Function Name
• Passing Arguments to Fortran from C
• Handling Complex Numbers
• Building the MEX-File

It also provides a symmetric indefinite factorization example that uses functions from LAPACK.

Specifying the Function Name

When calling an LAPACK or BLAS function, some platforms require an underscore character following the function name in the call statement.

On the PC, IBM_RS, and HP platforms, use the function name alone, with no trailing underscore. For example, to call the LAPACK dgemm function, use

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

On the SGI, LINUX, Solaris, and Alpha platforms, add the underscore after the function name. For example, to call dgemm on any of these platforms, use

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

Passing Arguments to Fortran from C

Since the LAPACK and BLAS functions are written in Fortran, arguments passed to and from these functions must be passed by reference. The following example calls dgemm, passing all arguments by reference. An ampersand (&) precedes each argument unless that argument is already a reference.

#include "mex.h"

void mexFunction( int nlhs, mxArray *plhs[], int nrhs, mxArray 
*prhs[] )
{
double *A, *B, *C, one=1.0, zero=0.0;
int m,n,p; 
char *chn="N";

A = mxGetPr( prhs[0] );
B = mxGetPr( prhs[1] );
m = mxGetM( prhs[0] );
p = mxGetN( prhs[0] );
n = mxGetN( prhs[1] );

if ( p != mxGetM( prhs[1] ) ) {
mexErrMsgTxt("Inner dimensions of matrix multiply do not match");
}

plhs[0] = mxCreateDoubleMatrix( m, n, mxREAL );
C = mxGetPr( plhs[0] );

/* Pass all arguments to Fortran by reference */
dgemm (chn, chn, &m, &n, &p, &one, A, &m, B, &p, &zero, C, &m);
}

Handling Complex Numbers

MATLAB stores complex numbers differently than FORTRAN. MATLAB stores the real and imaginary parts of a complex number in separate, equal length vectors, pr and pi. FORTRAN stores the same number in one location with the real and imaginary parts interleaved.

As a result, complex variables exchanged between MATLAB and the FORTRAN functions in LAPACK and BLAS are incompatible. MATLAB provides conversion routines that change the storage format of complex numbers to address this incompatibility.

Input Arguments.   For all complex variables passed as input arguments to a FORTRAN function, you need to convert the storage of the MATLAB variable to be compatible with the FORTRAN function. Use the mat2fort function for this. See the example that follows.

Output Arguments.   For all complex variables passed as output arguments to a FORTRAN function, you need to do the following.

1. When allocating storage for the complex variable, allocate a real variable with twice as much space as you would for a MATLAB variable of the same size. You need to do this because the returned variable uses the FORTRAN format, which takes twice the space. See the allocation of zout in the example that follows.
2. Once the variable is returned to MATLAB, convert its storage so that it is compatible with MATLAB. Use the fort2mat function for this.

Example - Passing Complex Variables.   The example below shows how to call an LAPACK function from MATLAB, passing complex prhs[0] as input and receiving complex plhs[0] as output. Temporary variables zin and zout are used to hold prhs[0] and plhs[0] in FORTRAN format.

#include "mex.h" 
#include "fort.h"      /* defines mat2fort and fort2mat */

void mexFunction( int nlhs, mxArray *plhs[], int nrhs, mxArray 
*prhs[] ) 
{ 
int lda, n; 
double *zin, *zout;
lda = mxGetM( prhs[0] ); 
n = mxGetN( prhs[0] ); 

/* Convert input to FORTRAN format */
zin = mat2fort( prhs[0], lda, n );

/* Allocate a real, complex, lda-by-n variable to store output */
zout = (double *)mxCalloc( 2*lda*n );

/* Call complex LAPACK function */ 
zlapack_function( zin, &lda, &n, zout );

/* Convert output to MATLAB format */ 
plhs[0] = fort2mat( zout, lda, lda, n );

/* Free intermediate FORTRAN format arrays */ 
mxFree( zin );
mxFree( zout ); 
}

Building the MEX-File

The examples in this section show how to compile and link a C MEX file, myCmexFile.c, on the platforms supported by MATLAB. In each example, the term <matlab> stands for the MATLAB root directory.

If you build your C MEX-file on a PC or IBM_RS platform, you need to explicitly specify a library file to link with.

On the PC, use either one of the following.

mex myCmexFile.c <matlab>/extern/lib/win32/digital/df60/
libmwlapack.lib
mex myCmexFile.c <matlab>/extern/lib/win32/microsoft/msvc60/
libmwlapack.lib

For IBM_RS, use the following syntax.

mex myCmexFile.c -L<matlab>/bin/ibm_rs -lmwlapack

On all other platforms, you can build your MEX-file as you would any other C MEX-file. For example,

mex myCmexFile.c

Example - Symmetric Indefinite Factorization Using LAPACK

You will find an example C MEX-file that calls two LAPACK functions in the directory <matlab>/extern/examples/refbook, where <matlab> stands for the MATLAB root directory. There are two versions of this file.

• utdu_slv.c - calls functions zhesvx and dsysvx, and thus is compatible with the PC, HP, and IBM platforms.
• utdu_slv_.c - calls functions zhesvx_ and dsysvx_, and thus is compatible with the SGI, LINUX, Solaris, and Alpha platforms.

The output files can be found in the same directory and have the filename xc_utdu_slv with the usual MEX-file extensions.

An M-file wrapper, utdusolve.m, provides help and allows you to call

X = xc_utdu_slv(A,B);

Memory Management

Debugging C Language MEX-Files