Module gemm 

Column-major GEMM with a pluggable BLAS backend.

All matrices are column-major (Fortran/BLAS convention) and every call is expressed in BLAS terms: C <- alpha * op(A) * op(B) + beta * C with explicit leading dimensions, so strided sub-blocks are addressed without copies.

Design

• Default: pure Rust faer backend (sequential), or system BLAS when the system-blas feature is enabled.
• Optional: external LP64/ILP64 BLAS injected through function pointers (used by the C API).
• Thread-safe: the process-wide default is protected by an RwLock; per-call backends are passed as GemmBackendHandle.

The safe entry point is gemm, which validates buffer lengths and leading dimensions before dispatching; matmul multiplies two Matrix values.

Example

use sparse_ir::Matrix;
use sparse_ir::gemm::{GemmBackendHandle, matmul};

// Column-major data: [[1, 2], [3, 4]] and [[5, 6], [7, 8]]
let a = Matrix::<f64>::from_vec_col_major([2, 2], vec![1.0, 3.0, 2.0, 4.0]).unwrap();
let b = Matrix::<f64>::from_vec_col_major([2, 2], vec![5.0, 7.0, 6.0, 8.0]).unwrap();

// `None` uses the global dispatcher: the Faer backend by default (system
// BLAS with the `system-blas` feature, or a BLAS injected at runtime)
let c = matmul(None, &a, &b).unwrap();
assert_eq!(c.host_data().unwrap(), &[19.0, 43.0, 22.0, 50.0]); // [[19, 22], [43, 50]]

// Or pass an explicit backend handle instead of relying on global state
let faer = GemmBackendHandle::default();
assert_eq!(
    matmul(Some(&faer), &a, &b).unwrap().host_data().unwrap(),
    c.host_data().unwrap()
);

A custom BLAS (e.g. from the C API) is injected at runtime with set_blas_backend (LP64) or set_ilp64_backend (ILP64); see their examples. clear_blas_backend restores the Faer backend.

Structs

ExternalBlas64Backend

External BLAS backend (ILP64: 64-bit integers).

ExternalBlasBackend

External BLAS backend (LP64: 32-bit integers).

GemmBackendHandle

Shared, cloneable GEMM backend selection.

Enums

GemmError

Errors reported by GEMM dispatch.

Transpose

Operation applied to a GEMM operand.

Traits

GemmBackend

GEMM backend trait for runtime dispatch.

GemmScalar

Scalars supported by gemm: f64 and Complex<f64>.

Functions

clear_blas_backend

Reset the process-wide default to the pure Rust faer backend.

gemm

Safe column-major GEMM: C <- alpha * op(A) * op(B) + beta * C.

get_backend_info

Returns (name, is_external, is_ilp64) of the process-wide default.

matmul

Matrix product A * B of two contiguous column-major matrices.

set_blas_backend^⚠

Set the process-wide default to an LP64 BLAS.

set_ilp64_backend^⚠

Set the process-wide default to an ILP64 BLAS.

Type Aliases

Dgemm64FnPtr

BLAS dgemm function pointer type (ILP64: 64-bit integers)

DgemmFnPtr

BLAS dgemm function pointer type (LP64: 32-bit integers)

Zgemm64FnPtr

BLAS zgemm function pointer type (ILP64: 64-bit integers)

ZgemmFnPtr

BLAS zgemm function pointer type (LP64: 32-bit integers)