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.
Matrix Order
Most of the LAPACK C interfaces have an additional parameter matrix_order of type int as their first argument. This parameter specifies whether the two-dimensional arrays are row-major (LAPACK_ROW_MAJOR) or column-major (LAPACK_COL_MAJOR).
In general the leading dimension lda is equal to the number of elements in the major dimension. It is also equal to the distance in elements between two neighboring elements in a line in the minor dimension. If there are no extra elements in a matrix with m rows and n columns, then
- For row-major ordering: the number of elements in a row is n, and row i is stored in memory right after row i-1. Therefore lda is n.
- For column-major ordering: the number of elements in a column is m, and column i is stored in memory right after column i-1. Therefore lda is m.
To refer to a submatrix with dimensions k by l, use the number of elements in the major dimension of the whole matrix (as above) as the leading dimension and k and l in the subroutine's input parameters to describe the size of the submatrix.
Workspace Arrays
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:
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 |
C |
|---|---|
INTEGER |
lapack_int |
LOGICAL |
lapack_logical |
REAL |
float |
DOUBLE PRECISION |
double |
COMPLEX |
lapack_complex_float |
COMPLEX*16/DOUBLE COMPLEX |
lapack_complex_double |
CHARACTER |
char |
C Type Definitions
#ifndef lapack_int
#define lapack_int MKL_INT
#endif
#ifndef lapack_logical
#define lapack_logical lapack_int
#endif
Complex Type Definitions
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 Order Definitions
#define LAPACK_ROW_MAJOR 101
#define LAPACK_COL_MAJOR 102
See Matrix Order for an explanation of row-major order and column-major order storage.
Error Code Definitions
#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 prototype 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 ?pptrs function that solves a system of linear equations with a packed Cholesky-factored symmetric (Hermitian) positive-definite matrix looks as follows:
lapack_int LAPACKE_<?>pptrs(int matrix_order, char uplo, lapack_int n, lapack_int nrhs, const <datatype>* ap, <datatype>* b, lapack_int ldb);
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).
A specific example follows. To solve a system of linear equations with a packed Cholesky-factored Hermitian positive-definite matrix with complex precision, use the following:
lapack_int LAPACKE_cpptrs(int matrix_order, char uplo, lapack_int n, lapack_int nrhs, const lapack_complex_float* ap, lapack_complex_float* b, lapack_int ldb);
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.