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

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

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

Calling LAPACK and BLAS Functions 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.

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.

Preserving Input Values from Modification

Many LAPACK and BLAS functions modify the values of arguments passed in to them. It is advisable to make a copy of arguments that can be modified prior to passing them to the function. For complex inputs, this point is moot since the mat2fort version of the input is a new piece of memory, but for real data this is not the case.

The following example calls an LAPACK function that modifies the first input argument. The code in this example makes a copy of prhs[0], and then passes the copy to the LAPACK function to preserve the contents of prhs[0].

Building the C 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.

Building on the PC.   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 this command if you are using the Lcc compiler that ships with MATLAB:

Or, use this command if you are using Microsoft Visual C++ as your C compiler:

Building on IBM_RS.   For IBM_RS, use the following syntax.

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

MEX-Files That Perform Complex Number Conversion.   MATLAB supplies the files fort.c and fort.h, which provide routines for conversion between MATLAB and FORTRAN complex data structures. These files define the mat2fort and fort2mat routines mentioned previously under Handling Complex Numbers.

If your program uses these routines, then you need to:

  1. Include the fort.h file in your program, using, #include "fort.h". See the example above.
  2. Build the fort.c file with your program. Specify the pathname, <matlab>/extern/examples/refbook for both fort.c and fort.h in the build command, (where <matlab> stands for the MATLAB root directory).

On the PC, use either one of the following.

For IBM_RS, use

For all other platforms, use

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:

Calling LAPACK and BLAS Functions from Fortran

You can make calls to the LAPACK and BLAS functions used by MATLAB from your Fortran MEX files. The following is an example program that takes two matrices and multiplies them by calling the LAPACK routine, dgemm:

Building the Fortran MEX-File

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

Building on the PC.   On the PC, using Visual Fortran, you will have to link against a library called libdflapack.lib:

Building on IBM_RS.   On the IBM_RS, invoke

Building on Other UNIX Platforms.   On the UNIX platforms (except IBM_RS), you create the MEX file as follows:

  Memory Management Debugging C Language MEX-Files