blas_lapack

CBLAS & LAPACKE API Reference

Complete C API documentation for BLAS (Basic Linear Algebra Subprograms) and LAPACK (Linear Algebra PACKage), version 3.12.1.

• 152 CBLAS functions - Level 1/2/3 vector and matrix operations
• 1,132 LAPACKE functions - Linear systems, eigenvalues, SVD, factorizations, and more
• Source of truth: cblas.h and lapacke.h from Reference-LAPACK v3.12.1

Quick Start

1. Include Headers

#include <cblas.h>      // BLAS operations
#include <lapacke.h>    // LAPACK operations

2. Compile and Link

# GCC/Clang
gcc myprogram.c -o myprogram -llapacke -llapack -lcblas -lblas -lm

# With pkg-config (if available)
gcc myprogram.c -o myprogram $(pkg-config --cflags --libs lapacke)

# With OpenBLAS (optimized)
gcc myprogram.c -o myprogram -lopenblas -lm

# With Intel MKL
gcc myprogram.c -o myprogram -lmkl_rt -lm

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:

Prefix	Type	C Type	Description
s	Single real	float	32-bit floating point
d	Double real	double	64-bit floating point
c	Single complex	void* (lapack_complex_float)	2x32-bit complex
z	Double complex	void* (lapack_complex_double)	2x64-bit complex

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:

Value	Meaning
0	Success
< 0	The -info-th argument had an illegal value
> 0	Routine-specific failure (e.g., singular matrix, no convergence)

Matrix Storage Schemes

Storage	Description	When to Use
Full (GE)	Dense M×N array	General matrices
Symmetric (SY/HE)	Only upper or lower triangle stored	Symmetric/Hermitian matrices
Triangular (TR)	Only upper or lower triangle	Triangular matrices
Banded (GB/SB/HB/TB)	Band storage, KL sub + KU super diagonals	Banded matrices
Packed (SP/HP/TP/PP)	Upper or lower triangle packed into 1D array	Memory-efficient symmetric/triangular
Tridiagonal (GT/PT/ST)	Three diagonals stored as vectors	Tridiagonal systems
RFP	Rectangular Full Packed	Cache-friendly packed format

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)

Reference	Functions	Description
blas-level1.md	~50	Vector operations: dot, nrm2, asum, axpy, swap, copy, rot, scal
blas-level2.md	~66	Matrix-vector: gemv, gbmv, trmv, trsv, symv, hemv, ger, syr, her
blas-level3.md	~36	Matrix-matrix: gemm, symm, hemm, syrk, herk, trmm, trsm

LAPACKE (1,132 functions)

Reference	Description
lapacke-linear-systems.md	Solve Ax=b: gesv, gbsv, posv, sysv, hesv + expert/refinement
lapacke-least-squares.md	Least squares: gels, gelsd + QR/LQ factorizations
lapacke-eigenvalues.md	Eigenvalues: syev, heev, geev, gees + generalized + Schur
lapacke-svd.md	SVD: gesvd, gesdd, gesvj + bidiagonal + CS decomposition
lapacke-factorizations.md	LU, Cholesky, LDL, triangular + storage conversions
lapacke-auxiliary.md	Norms, generators, orthogonal transforms, utilities

Complete Workflow Examples

Reference	Description
workflows.md	15 complete C examples with compile commands

Solver Selection Guide

"I need to solve Ax = b"

Matrix Type	Simple	Expert (with error bounds)
General	gesv	gesvx
General banded	gbsv	gbsvx
General tridiagonal	gtsv	gtsvx
Symmetric positive definite	posv	posvx
SPD banded	pbsv	pbsvx
SPD tridiagonal	ptsv	ptsvx
Symmetric indefinite	sysv	sysvx
Hermitian indefinite	hesv	hesvx

"I need eigenvalues/eigenvectors"

Matrix Type	Fastest	Most Accurate	Subset
Symmetric	syevd	syevr	syevx
Hermitian	heevd	heevr	heevx
General	geev	geevx	-
Generalized symmetric	sygvd	-	sygvx

"I need SVD"

Need	Routine	Notes
All singular values/vectors	gesdd	Fastest (divide & conquer)
Standard SVD	gesvd	Classic algorithm
Selected values/vectors	gesvdx	Subset by index or range
High accuracy	gesvj / gejsv	Jacobi methods

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