CBLAS & LAPACKE API Reference

3. Typical Workflow

1. Allocate matrices/vectors as flat arrays (row-major or column-major)
2. Call CBLAS for basic operations (multiply, solve triangular, etc.)
3. Call LAPACKE for advanced operations (factorize, solve systems, eigenvalues, SVD)
4. Check info return value (0 = success, <0 = bad argument, >0 = numerical issue)
5. Free allocated memory

When to Use This Skill

• API Lookup: Find the right CBLAS/LAPACKE function for a specific operation
• Code Generation: Write correct C code using BLAS/LAPACK with proper parameters
• Linking Help: Resolve compilation/linking issues with BLAS/LAPACK libraries
• Solver Selection: Choose the right solver for your matrix type and problem
• Performance: Select optimized routines for specific matrix structures

Core Concepts

Precision Prefixes

Every routine comes in up to 4 precision types:

Example: cblas_sgemm (float), cblas_dgemm (double), cblas_cgemm (complex float), cblas_zgemm (complex double)

CBLAS Enums

typedef enum CBLAS_LAYOUT    { CblasRowMajor=101, CblasColMajor=102 } CBLAS_LAYOUT;
typedef enum CBLAS_TRANSPOSE { CblasNoTrans=111,  CblasTrans=112, CblasConjTrans=113 } CBLAS_TRANSPOSE;
typedef enum CBLAS_UPLO      { CblasUpper=121,    CblasLower=122 } CBLAS_UPLO;
typedef enum CBLAS_DIAG      { CblasNonUnit=131,  CblasUnit=132 } CBLAS_DIAG;
typedef enum CBLAS_SIDE      { CblasLeft=141,     CblasRight=142 } CBLAS_SIDE;

LAPACKE Layout Constants

#define LAPACK_ROW_MAJOR  101
#define LAPACK_COL_MAJOR  102

Leading Dimension (lda, ldb, ldc)

The leading dimension specifies the stride between consecutive columns (column-major) or rows (row-major) in memory:

• Row-major: lda = number of columns allocated (>= N for an M×N matrix)
• Column-major: lda = number of rows allocated (>= M for an M×N matrix)

LAPACKE Info Return Values

All LAPACKE driver routines return lapack_int info:

Matrix Storage Schemes

LAPACK Naming Convention

LAPACKE_<precision><operation>
         ^          ^
         s/d/c/z    2-6 char code describing the operation

Common operation codes:

• gesv = GEneral SolVe
• posv = POsitive definite SolVe
• syev = SYmmetric EigenValues
• gesvd = GEneral Singular Value Decomposition
• getrf = GEneral TRiangular Factorization (LU)
• potrf = POsitive definite TRiangular Factorization (Cholesky)

API Reference

CBLAS (152 functions)

LAPACKE (1,132 functions)

Complete Workflow Examples

Solver Selection Guide

"I need to solve Ax = b"

"I need eigenvalues/eigenvectors"

"I need SVD"

Best Practices

• Choose the right solver: Use specialized routines for structured matrices (symmetric, banded, triangular) - they are faster and more accurate
• Check info: Always check the return value of LAPACKE functions
• Row vs column major: CBLAS and LAPACKE support both via the layout parameter; be consistent throughout your code
• Leading dimension: Must be >= the actual dimension; can be larger for submatrix operations
• Workspace: LAPACKE high-level functions handle workspace allocation automatically (unlike raw LAPACK Fortran calls)
• Complex types: Use lapack_complex_float / lapack_complex_double or pass void* to C arrays of float[2]/double[2]

Troubleshooting

Linking errors: undefined reference to cblas_dgemm

# Make sure you link in the right order (dependent libs first)
gcc prog.c -llapacke -llapack -lcblas -lblas -lm -lgfortran

# Or use OpenBLAS which bundles everything
gcc prog.c -lopenblas -lm

Wrong results with row-major layout

LAPACK is natively column-major (Fortran). When using LAPACK_ROW_MAJOR, LAPACKE transposes internally. For maximum performance, use LAPACK_COL_MAJOR and store matrices in column-major order.

LAPACKE_dgesv returns info > 0

The matrix is singular (or nearly singular). info = i means U(i,i) is exactly zero in the LU factorization. Use gesvx for condition number estimation.

"Illegal value" error (info < 0)

Parameter -info has an illegal value. Common causes:

• Wrong matrix_layout constant
• lda too small (must be >= N for row-major, >= M for column-major)
• Invalid uplo, trans, or diag character

Segmentation fault in LAPACKE calls

• Ensure arrays are large enough: A[lda * N] not A[M * N] when lda > M
• For ipiv arrays, allocate at least min(M, N) elements
• For eigenvalue arrays, allocate at least N elements

Performance is poor

• Use an optimized BLAS implementation (OpenBLAS, Intel MKL, BLIS) instead of reference BLAS
• Ensure proper memory alignment (64-byte for AVX-512)
• Use column-major storage to avoid LAPACKE's internal transposition

What's New in LAPACK 3.12.1

• gemmtr - Triangular matrix-matrix multiply (new BLAS Level 3 extension)
• gesvdq - SVD with QR preconditioning for high accuracy
• getsqrhrt - Tall-skinny QR with Householder reconstruction
• trsyl3 - Level 3 Sylvester equation solver
• *_64 variants - 64-bit integer API for large matrices
• Improved gelq/geqr - Tall-skinny and short-wide QR/LQ