Crate mdarray_linalg 

Linear algebra backends for mdarray

This crate defines a set of traits (MatVec, MatMul, Eig, SVD, …) that are implemented by different backends, allowing users to switch between them depending on their needs (performance, portability, or debugging).

Backends

• Blas: bindings to BLAS
• Lapack: bindings to LAPACK
• Faer: bindings to Faer
• Naive: simple demo backend, integrated into this crate

Note: Not all backends support all functionalities.

Functionality	BLAS	LAPACK	Naive	Faer
▶︎ Basic vector/matrix operations
Matrix/vector multiplications	✅	⬜	🔧	🔧
Operations on vectors	✅	⬜	🔧	🔧
Matrix multiplication	✅	⬜	✅	✅
Argmax	🔧	⬜	✅	⬜
▶︎ Linear algebra
Eigen decomposition	⬜	✅	⬜	✅
SVD decomposition	⬜	✅	⬜	✅
LU decomposition	⬜	✅	⬜	✅
Solve and inverse	⬜	✅	⬜	✅
QR decomposition	⬜	✅	⬜	✅
Cholesky decomposition	⬜	✅	⬜	🔧
Schur decomposition	⬜	✅	⬜	🔧
▶︎ Advanced
Tensor contraction	✅	⬜	✅	✅

✅ = implemented 🔧 = not implemented yet / partially implemented ⬜ = not applicable / not part of the backend’s scope

Example

Note: When running doctests with Blas or Lapack, linking issues may occur due to this Rust issue: rust-lang/rust#125657. In that case, run the doctests with: RUSTDOCFLAGS="-L native=/usr/lib -C link-arg=-lopenblas" cargo test --doc

See also the section Troubleshooting below.

The following example demonstrates basic functionality:

use mdarray::tensor;

// The prelude does not expose any names.  It only provides traits as _.
use mdarray_linalg::prelude::*;

// Backends are provided in partner crates (e.g. mdarray-linalg-blas or mdarray-linalg-faer),
// the naive backend exists mostly as a demonstration.
use mdarray_linalg::Naive;

fn main() {
    // Declare two vectors
    let x = tensor![1., 2.];
    let y = tensor![2., 4.];

    // Declare two matrices
    let a = tensor![[1., 2.], [3., 4.]];
    let b = tensor![[5., 6.], [7., 8.]];

    // ----- Scalar product -----
    let dot_result = Naive.dot(&x, &y);
    println!("dot(x, y) = {}", dot_result); // x · y

    // ----- Matrix multiplication -----
    let mut c = Naive.matmul(&a, &b).eval(); // C ← A ✕ B
    Naive.matmul(&b, &a).add_to(&mut c);     // C ← B ✕ A + C
    println!("A * B + B * A = {:?}", c);
}

Some notes:

• Memory usage: Each trait provides a method returning new matrices and an overwrite variant using user-allocated buffers. In that last case, output shapes must match exactly.

• Backend configuration: Some accept parameters; for example, SVD may choose an optimal algorithm by default, but the user can select a specific one if desired.

• Errors: Convergence issues return a Result; other problems (dimension mismatch) may panic.

Troubleshooting

If you encounter linking issues with BLAS or LAPACK on Linux, one solution is to add a build.rs file and configure it to link the libraries manually. In your Cargo.toml, add:

[package]
build = "build.rs"

Then, create a build.rs file with the following content:

fn main() {
    println!("cargo:rustc-link-lib=openblas");
    println!("cargo:rustc-link-search=native=/usr/lib");
}

Re-exports

pub use utils::*;

Modules

eig

Eigenvalue, eigenvector, and Schur decomposition utilities for general and Hermitian matrices

lu

LU, Cholesky, matrix inversion, and determinant computation utilities

matmul

Matrix multiplication and tensor contraction

matvec

Basic vector and matrix-vector operations, including Ax, Ax + βy, Givens rotations, argmax, and rank-1 updates

prelude

This module can be wildcard-imported to make the traits available without polluting the local namespace.

qr

QR decomposition

solve

Linear system solving utilities for equations of the form Ax = B

svd

Singular Value Decomposition (SVD)

testing

Generic (backend-agnosting) tests for mdarray-linalg

utils

Utility functions for matrix printing, shape retrieval, identity generation, Kronecker product, trace, transpose operations, …

Macros

assert_complex_matrix_eq

assert_matrix_eq

get_dims

Returns the dimensions of an arbitrary number of matrices (e.g., A, B, C → (ma, na), (mb, nb), (mc, nc))

trans_stride

Handles different stride layouts by selecting the correct memory order and stride for contiguous arrays

Structs

Naive

Simple backend, mostly for demonstratration purposes