Crate faer

faer is a general-purpose linear algebra library for rust, with a focus on high performance for algebraic operations on medium/large matrices, as well as matrix decompositions

most of the high-level functionality in this library is provided through associated functions in its vocabulary types: Mat/MatRef/MatMut

faer is recommended for applications that handle medium to large dense matrices, and its design is not well suited for applications that operate mostly on low dimensional vectors and matrices such as computer graphics or game development. for such applications, nalgebra and cgmath may be better suited

basic usage

Mat is a resizable matrix type with dynamic capacity, which can be created using Mat::new to produce an empty $0\times 0$ matrix, Mat::zeros to create a rectangular matrix filled with zeros, Mat::identity to create an identity matrix, or Mat::from_fn for the more general case

Given a &Mat<T> (resp. &mut Mat<T>), a MatRef<'_, T> (resp. MatMut<'_, T>) can be created by calling Mat::as_ref (resp. Mat::as_mut), which allow for more flexibility than Mat in that they allow slicing (MatRef::get) and splitting (MatRef::split_at)

MatRef and MatMut are lightweight view objects. the former can be copied freely while the latter has move and reborrow semantics, as described in its documentation

most of the matrix operations can be used through the corresponding math operators: + for matrix addition, - for subtraction, * for either scalar or matrix multiplication depending on the types of the operands.

example

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)];

matrix decompositions

faer provides a variety of matrix factorizations, each with its own advantages and drawbacks:

$LL^\top$ decomposition

Mat::llt decomposes a self-adjoint positive definite matrix $A$ such that $$A = LL^H,$$ where $L$ is a lower triangular matrix. this decomposition is highly efficient and has good stability properties

an implementation for sparse matrices is also available

$LBL^\top$ decomposition

Mat::lblt decomposes a self-adjoint (possibly indefinite) matrix $A$ such that $$P A P^\top = LBL^H,$$ where $P$ is a permutation matrix, $L$ is a lower triangular matrix, and $B$ is a block diagonal matrix, with $1 \times 1$ or $2 \times 2$ diagonal blocks. this decomposition is efficient and has good stability properties

$LU$ decomposition with partial pivoting

Mat::partial_piv_lu decomposes a square invertible matrix $A$ into a lower triangular matrix $L$, a unit upper triangular matrix $U$, and a permutation matrix $P$, such that $$PA = LU$$ it is used by default for computing the determinant, and is generally the recommended method for solving a square linear system or computing the inverse of a matrix (although we generally recommend using a faer::linalg::solvers::Solve instead of computing the inverse explicitly)

an implementation for sparse matrices is also available

$LU$ decomposition with full pivoting

Mat::full_piv_lu decomposes a generic rectangular matrix $A$ into a lower triangular matrix $L$, a unit upper triangular matrix $U$, and permutation matrices $P$ and $Q$, such that $$PAQ^\top = LU$$ it can be more stable than the LU decomposition with partial pivoting, in exchange for being more computationally expensive

$QR$ decomposition

Mat::qr decomposes a matrix $A$ into the product $$A = QR,$$ where $Q$ is a unitary matrix, and $R$ is an upper trapezoidal matrix. it is often used for solving least squares problems

an implementation for sparse matrices is also available

$QR$ decomposition with column pivoting

(Mat::col_piv_qr) decomposes a matrix $A$ into the product $$AP^\top = QR,$$ where $P$ is a permutation matrix, $Q$ is a unitary matrix, and $R$ is an upper trapezoidal matrix

it is slower than the version with no pivoting, in exchange for being more numerically stable for rank-deficient matrices

singular value decomposition

the SVD of a matrix $A$ of shape $(m, n)$ is a decomposition into three components $U$, $S$, and $V$, such that:

• $U$ has shape $(m, m)$ and is a unitary matrix,
• $V$ has shape $(n, n)$ and is a unitary matrix,
• $S$ has shape $(m, n)$ and is zero everywhere except the main diagonal, with nonnegative diagonal values in nonincreasing order,
• and finally:

$$A = U S V^H$$

the SVD is provided in two forms: either the full matrices $U$ and $V$ are computed, using Mat::svd, or only their first $\min(m, n)$ columns are computed, using Mat::thin_svd

if only the singular values (elements of $S$) are desired, they can be obtained in nonincreasing order using Mat::singular_values

eigendecomposition

note: the order of the eigenvalues is currently unspecified and may be changed in a future release

the eigenvalue decomposition of a square matrix $A$ of shape $(n, n)$ is a decomposition into two components $U$, $S$:

• $U$ has shape $(n, n)$ and is invertible,
• $S$ has shape $(n, n)$ and is a diagonal matrix,
• and finally:

$$A = U S U^{-1}$$

if $A$ is self-adjoint, then $U$ can be made unitary ($U^{-1} = U^H$), and $S$ is real valued. additionally, the eigenvalues are sorted in nondecreasing order

Depending on the domain of the input matrix and whether it is self-adjoint, multiple methods are provided to compute the eigendecomposition:

• Mat::self_adjoint_eigen can be used with either real or complex matrices, producing an eigendecomposition of the same type,
• Mat::eigen can be used with real or complex matrices, but always produces complex values.

if only the eigenvalues (elements of $S$) are desired, they can be obtained using Mat::self_adjoint_eigenvalues (nondecreasing order), Mat::eigenvalues with the same conditions described above.

crate features

• std: enabled by default. links with the standard library to enable additional features such as cpu feature detection at runtime
• rayon: enabled by default. enables the rayon parallel backend and enables global parallelism by default
• serde: Enables serialization and deserialization of Mat
• npy: enables conversions to/from numpy’s matrix file format
• perf-warn: produces performance warnings when matrix operations are called with suboptimal data layout
• nightly: requires the nightly compiler. enables experimental simd features such as avx512

Re-exports

pub extern crate dyn_stack;

pub extern crate reborrow;

pub extern crate faer_traits as traits;

pub use col::Col;

pub use col::ColMut;

pub use col::ColRef;

pub use mat::Mat;

pub use mat::MatMut;

pub use mat::MatRef;

pub use row::Row;

pub use row::RowMut;

pub use row::RowRef;

Modules

col

column vector

diag

diagonal matrix

io

de-serialization from common matrix file formats

linalg

linear algebra module

mat

rectangular matrix

matrix_free

matrix-free linear operator traits and algorithms

perm

permutation matrix

prelude

useful imports for general usage of the library

row

row vector

sparse

sparse matrix data structures

stats

statistics and randomness functionality

utils

helper utilities

Macros

col

creates a col::Col containing the arguments

concat

concatenates the matrices in each row horizontally, then concatenates the results vertically

make_guard

see: generativity::make_guard

mat

creates a Mat containing the arguments.

row

creates a row::Row containing the arguments

unzip

used to undo the zipping by the zip! macro.

zip

zips together matrix of the same size, so that coefficient-wise operations can be performed on their elements.

Structs

ContiguousBwd

contiguous stride equal to -1

ContiguousFwd

contiguous stride equal to +1

Scale

scaling factor for multiplying matrices.

Spec

implements Default based on Config’s Auto implementation for the type T.

Enums

Accum

determines whether to replace or add to the result of a matmul operatio

Conj

determines whether the input should be implicitly conjugated or not

Par

determines the parallelization configuration

Side

determines which side of a self-adjoint matrix should be accessed

TryReserveError

memory allocation error

Traits

Auto

like Default, but with an extra type parameter so that algorithm hyperparameters can be tuned per scalar type.

Index

native unsigned integer type

Shape

matrix dimension

ShapeIdx

base trait for Shape

Stride

stride distance between two consecutive elements along a given dimension

Unbind

sealed trait for types that can be created from “unbound” values, as long as their struct preconditions are upheld

Functions

disable_global_parallelism

causes functions that access global parallelism settings to panic.

get_global_parallelism

gets the global parallelism settings.

set_global_parallelism

sets the global parallelism settings.

Type Aliases

Idx

type that can be used to index into a range

IdxInc

type that can be used to partition a range

MaybeIdx

either an index or a negative value

c32

Complex<f32>

c64

Complex<f64>

cx128

Complex<f64>

fx128

Complex<f64>