Crate faer

Expand description

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 those purposes, nalgebra and cgmath may provide better tools.

§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 most generic case.

Given a &Mat<E> (resp. &mut Mat<E>), a MatRef<'_, E> (resp. MatMut<'_, E>) 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.

More details about the vocabulary types can be found in each one’s module’s documentation. See also: faer_entity::Entity and complex_native.

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::<f64>::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:

§Cholesky decomposition

Mat::cholesky 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.

§Bunch-Kaufman 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::Solver 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

The 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

The 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 $M$ 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:

$$M = 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 eigendecomposition of a square matrix $M$ 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:

$$M = U S U^{-1}.$$

If $M$ is hermitian, then $U$ can be made unitary ($U^{-1} = U^H$), and $S$ is real valued.

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

If only the eigenvalues (elements of $S$) are desired, they can be obtained in nonincreasing order using Mat::selfadjoint_eigenvalues, Mat::eigenvalues, or Mat::complex_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 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;
• pub use dyn_stack;
• pub use reborrow;

Modules§

• Column vector type.
• Native complex floating point types whose real and imaginary parts are stored contiguously.
• Diagonal matrix type.
• iostd
De-serialization from common matrix file formats.
• Iterators and related utilities.
• Linear algebra module.
• linopunstable
Matrix-free linear operator traits and algorithms.
• Matrix type.
• modulesDeprecated
Re-exports.
• Permutation matrices.
• faer prelude. Includes useful types and traits for solving linear systems.
• Row vector type.
• solversDeprecated
Matrix solvers and decompositions.
• Sparse data structures and algorithms. Sparse matrix data structures.
• statsrand
Statistics-related utilities.
• Various utilities for low level implementations in generic code.

Structs§

• Factor for matrix-scalar multiplication.

Enums§

• Whether a matrix should be implicitly conjugated when read or not.
• Parallelism strategy that can be passed to most of the routines in the library.
• Specifies whether the triangular lower or upper part of a matrix should be accessed.

Traits§

• Unstable trait containing the operations that a number type needs to implement.
• Trait for types that may be implicitly conjugated.
• Unstable core trait for describing how a scalar value may be split up into individual component.
• Trait for unsigned integers that can be indexed with.
• Unstable trait containing the operations that a real number type needs to implement.
• Trait for signed integers corresponding to the ones satisfying Index.