faer Linear Algebra Library

faer is a portable, high-performance dense linear algebra library written in Rust. It provides a high-level API for matrix decompositions and solving linear systems, built upon a lower-level API that allows fine-grained control over memory allocation and multithreading.

Key Features

• Matrix Types: Provides the Mat type for simple matrix construction and manipulation, alongside lightweight view types MatRef and MatMut for building memory views over existing data.
• Supported Scalars: Supports native floating-point types f32, f64, c32, and c64, as well as user-defined types (e.g., extended precision, complex numbers, dual/hyper-dual numbers) that satisfy the required interface.
• Decompositions: Implements state-of-the-art algorithms for:
  • Cholesky (LLT, LDLT, and Bunch-Kaufman LDLT)
  • QR (with and without column pivoting)
  • LU (with partial and full pivoting)
  • SVD (with or without singular vectors, thin or full)
  • Eigenvalue decomposition (with or without eigenvectors)
• Performance: Uses explicit SIMD instructions (x86-64 and Aarch64/NEON) and the Rayon library for high-performance parallelism.
• Platform Support: Supports all platforms supported by Rust.

The faer library provides three primary matrix abstractions depending on ownership and mutability:

1. Mat<T, Rows, Cols>: A heap-allocated, resizable, owned matrix. It is stored in column-major order. While individual columns are contiguous, the matrix as a whole may contain padding for alignment.
2. MatRef<'a, T, Rows, Cols, RStride, CStride>: An immutable view over a matrix (similar to a 2D strided slice). Note that data may be partially uninitialized; avoid reading uninitialized values.
3. MatMut<'a, T, Rows, Cols, RStride, CStride>: A mutable view over a matrix.

Important: Move Semantics and Reborrowing MatMut cannot be Copy because it mutably borrows data. If you pass a MatMut to a function by value or use a consuming method (like transpose_mut), the original variable becomes unusable. To use a MatMut multiple times, use the reborrow pattern via .rb() (for immutable reborrow) or .rb_mut() (for mutable reborrow).

use faer::{Mat, MatMut, MatRef};
use reborrow::ReborrowMut;

let mut matrix = Mat::<f64>::zeros(3, 4);
let mut view = matrix.as_mut();

// Use .rb_mut() to reborrow so 'view' remains usable
takes_matmut(view.rb_mut());
takes_matmut(view.rb_mut());

// Use .rb() to get an immutable view from a mutable one
takes_matref(view.rb());

use faer::{Mat, MatMut, MatRef};
use reborrow::ReborrowMut;

fn takes_matmut(view: MatMut<'_, f64>) {}
fn takes_matref(view: MatRef<'_, f64>) {}

let mut matrix = Mat::new();
let mut view = matrix.as_mut();
takes_matmut(view.rb_mut());
takes_matmut(view.rb_mut());
// view is still usable here
takes_matref(view.rb());
// view is still usable here

faer provides several matrix factorization methods via associated functions on Mat:

• $LL^\top$ decomposition: Mat::llt() decomposes a self-adjoint positive definite matrix $A$ into $A = LL^H$. Highly efficient and stable.
• $LBL^\top$ decomposition: Mat::lblt() decomposes a self-adjoint (possibly indefinite) matrix $A$ into $P A P^\top = LBL^H$, where $P$ is a permutation matrix, $L$ is lower triangular, and $B$ is block diagonal.
• $LU$ decomposition (Partial Pivoting): Mat::partial_piv_lu() decomposes a square invertible matrix $A$ into $PA = LU$. Recommended for solving square linear systems or computing determinants.
• $LU$ decomposition (Full Pivoting): Mat::full_piv_lu() decomposes a generic rectangular matrix $A$ into $PAQ^\top = LU$. More stable than partial pivoting but more expensive.
• $QR$ decomposition: Mat::qr() decomposes $A$ into $A = QR$ (unitary $Q$, upper trapezoidal $R$). Used for least squares problems.
• $QR$ decomposition (Column Pivoting): Mat::col_piv_qr() decomposes $AP^\top = QR$. More stable for rank-deficient matrices.
• Singular Value Decomposition (SVD):
  • Mat::svd(): Computes full matrices $U$, $S$, and $V$ such that $A = U S V^H$.
  • Mat::thin_svd(): Computes only the first $\min(m, n)$ columns of $U$ and $V$.
  • Mat::singular_values(): Returns only the singular values in nonincreasing order.
• Eigendecomposition:
  • Mat::self_adjoint_eigen(): For self-adjoint matrices (real or complex). Eigenvalues are sorted in nondecreasing order.
  • Mat::eigen(): For real or complex matrices; always produces complex values.

The faer library provides high-performance linear algebra operations. The primary way to interact with matrices is through the Mat, MatRef, and MatMut types.

• Mat<T>: A resizable matrix type with dynamic capacity.
• MatRef<'_, T>: A lightweight, copyable view of a matrix (created via Mat::as_ref).
• MatMut<'_, T>: A lightweight view of a matrix with move and reborrow semantics (created via Mat::as_mut).

Common creation methods for Mat include:

• Mat::new(): Creates an empty $0\times 0$ matrix.
• Mat::zeros(nrows, ncols): Creates a rectangular matrix filled with zeros.
• Mat::identity(n): Creates an identity matrix.
• Mat::from_fn(nrows, ncols, |i, j| ...): Creates a matrix using a generator function.
• mat![...]: A macro for convenient matrix initialization.

Matrix operations can be performed using standard math operators: + (addition), - (subtraction), and * (scalar or matrix multiplication).

use faer::{Mat, Scale, mat};
let a = mat![
	[1.0, 5.0, 9.0],
	[2.0, 6.0, 10.0],
	[3.0, 7.0, 11.0],
	[4.0, 8.0, 12.0f64],
];
let b = Mat::from_fn(4, 3, |i, j| (i + j) as f64);
let add = &a + &b;
let sub = &a - &b;
let scale = Scale(3.0) * &a;
let mul = &a * b.transpose();
let a00 = a[(0, 0)];