C Interface Conventions

The C interfaces are implemented for most of the Intel MKL LAPACK driver and computational routines.

The arguments of the C interfaces for the Intel MKL LAPACK functions comply with the following rules:

Scalar input arguments are passed by value.
Array arguments are passed by reference.
Array input arguments are declared with the const modifier.
Function arguments are passed by pointer.
An integer return value replaces the info output parameter. The return value equal to 0 means the function operation is completed successfully. See also special error codes below.
Most of the LAPACK C interfaces have an additional parameter matrix_order of the int type as their first argument. This parameter specifies whether the two-dimensional arrays are row-major (LAPACK_ROW_MAJOR) or column-major (LAPACK_COL_MAJOR).

The LAPACK C interface omits workspace parameters because workspace is allocated during runtime and released upon completion of the function operation.

For some functions, work arrays contain valuable information on exit. In such cases, the interface contains an additional argument or arguments, namely:

?gesvx and ?gbsvx contain rpivot
?gesvd contains superb
?gejsv and ?gesvj contain istat and stat, respectively.

Function Types

The function types are used in non-symmetric eigenproblem functions only.

typedef lapack_logical (*LAPACK_S_SELECT2) (const float*, const float*);
typedef lapack_logical (*LAPACK_S_SELECT3) (const float*, const float*, const float*);
typedef lapack_logical (*LAPACK_D_SELECT2) (const double*, const double*);
typedef lapack_logical (*LAPACK_D_SELECT3) (const double*, const double*, const double*);
			
typedef lapack_logical (*LAPACK_C_SELECT1) (const lapack_complex_float*);
typedef lapack_logical (*LAPACK_C_SELECT2) (const lapack_complex_float*, const lapack_complex_float*);
typedef lapack_logical (*LAPACK_Z_SELECT1) (const lapack_complex_double*);
typedef lapack_logical (*LAPACK_Z_SELECT2) (const lapack_complex_double*, const lapack_complex_double*);

Mapping FORTRAN Data Types against C Data Types

FORTRAN Data Types vs. C Data Types
FORTRAN	C
INTEGER	lapack_int
LOGICAL	lapack_logical
REAL	float
DOUBLE PRECISION	double
COMPLEX	lapack_complex_float
COMPLEX*16	lapack_complex_double
CHARACTER	char

C Types

#ifndef lapack_int
#define lapack_int MKL_INT
#endif

#ifndef lapack_logical
#define lapack_logical lapack_int
#endif

Complex Types

Complex type for single precision:

#ifndef lapack_complex_float
#define lapack_complex_float   MKL_Complex8
#endif

Complex type for double precision:

#ifndef lapack_complex_double
#define lapack_complex_double   MKL_Complex16
#endif

Matrix Ordering

#define LAPACK_ROW_MAJOR  101
#define LAPACK_COL_MAJOR  102

Error Codes

#define LAPACK_WORK_MEMORY_ERROR       -1010  /* Failed to allocate memory  
                                            for a working array */
#define LAPACK_TRANSPOSE_MEMORY_ERROR  -1011  /* Failed to allocate memory 
                                            for transposed matrix */

If the return value is -i, the -i-th parameter has an invalid value.

Function Prototypes

Some Intel MKL functions differ in data types they support and vary in the parameters they take.

Each function type has a unique prototype defined. Use this protype when you call the function from your application program. In most cases, Intel MKL supports four distinct floating-point precisions. Each corresponding prototype looks similar, usually differing only in the data type. To avoid listing all the prototypes in every supported precision, a generic prototype template is provided.

<?> denotes precision and is s, d, c, or z:

s for real, single precision
d for real, double precision
c for complex, single precision
z for complex, double precision

<datatype> stands for a respective data type: float, double, lapack_complex_float, or lapack_complex_double.

For example, the C prototype template for the ?pstrf function that computes the Cholesky factorization with complete pivoting of a positive semidefinite matrix looks as follows:

lapack_int LAPACKE_<?>pstrf(int matrix_order, char uplo, lapack_int n, <datatype>* a, lapack_int lda, lapack_int* piv, lapack_int* rank, <datatype> tol);

To obtain the function name and parameter list that corresponds to a specific precision, replace the <?> symbol with s, d, c, or z and the <datatype> field with the corresponding data type (float, double, lapack_complex_float, or lapack_complex_double respectively).

Note

For the select parameter, the respective values of the <datatype> field for s, d, c, or z are as follows: LAPACK_S_SELECT3, LAPACK_D_SELECT3, LAPACK_C_SELECT2, and LAPACK_Z_SELECT2.

A specific example follows. To compute the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix with single precision, use the following:

lapack_int LAPACKE_cpstrf(int matrix_order, char uplo, lapack_int n, lapack_complex_float* a, lapack_int lda, lapack_int* piv, lapack_int* rank, lapack_complex_float tol, lapack_complex_float* work);