Expand description
faer is a linear algebra library for Rust, with a focus on high performance for
medium/large matrices.
The core module contains the building blocks of linear algebra:
- Matrix structure definitions:
Mat,MatRef, andMatMut. - Coefficient-wise matrix operations, like addition and subtraction: either using the builtin
+and-operators or using the low level apizipped!. - Matrix multiplication: either using the builtin
*operator or the low levelmulmodule. - Triangular matrix solve: the
solvemodule. - Triangular matrix inverse: the
inversemodule. - Householder matrix multiplication: the
householdermodule.
Example
use faer_core::{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();Entity trait
Matrices are built on top of the Entity trait, which describes the prefered memory storage
layout for a given type E. An entity can be decomposed into a group of units: for a natively
supported type (f32, f64, c32, c64), the unit is simply the type itself, and a
group contains a single element. On the other hand, for a type with a more specific preferred
layout, like an extended precision floating point type, or a dual number type, the unit would
be one of the natively supported types, and the group would be a structure holding the
components that build up the full value.
To take a more specific example: num_complex::Complex<f64> has a storage memory layout that
differs from that of c64 (see complex_native for more details). Its real and complex
components are stored separately, so its unit type is f64, while its group type is Complex.
In practice, this means that for a Mat<f64>, methods such as Mat::col_ref will return a
&[f64]. Meanwhile, for a Mat<Complex<f64>>, Mat::col_ref will return Complex<&[f64]>,
which holds two slices, each pointing respectively to a view over the real and the imaginary
components.
While the design of the entity trait is unconventional, it helps us achieve much higher
performance when targetting non native types, due to the design matching the typical preffered
CPU layout for SIMD operations. And for native types, since Group<T> is just
T, the entity layer is a no-op, and the matrix layout is
compatible with the classic contiguous layout that’s commonly used by other libraries.
Memory allocation
Since most faer crates aim to expose a low level api for optimal performance, most algorithms
try to defer memory allocation to the user.
However, since a lot of algorithms need some form of temporary space for intermediate
computations, they may ask for a slice of memory for that purpose, by taking a stack: PodStack parameter. A PodStack is a thin wrapper over a slice of
memory bytes. This memory may come from any valid source (heap allocation, fixed-size array on
the stack, etc.). The functions taking a PodStack parameter have a corresponding function
with a similar name ending in _req that returns the memory requirements of the algorithm. For
example:
householder::apply_block_householder_on_the_left_in_place_with_conj and
householder::apply_block_householder_on_the_left_in_place_req.
The memory stack may be reused in user-code to avoid repeated allocations, and it is also
possible to compute the sum (dyn_stack::StackReq::all_of) or union
(dyn_stack::StackReq::any_of) of multiple requirements, in order to optimally combine them
into a single allocation.
After computing a dyn_stack::StackReq, one can query its size and alignment to allocate the
required memory. The simplest way to do so is through dyn_stack::GlobalMemBuffer::new.
Re-exports
pub use matrix_ops::scale;pub use complex_native::*;
Modules
- Native complex floating point types whose real and imaginary parts are stored contiguously.
- Advanced: Module for index and matrix types with compile time checks, instead of bound checking at runtime.
- Advanced: Helper types for working with
GroupForin generic contexts. - Block Householder transformations.
- Specialized containers that are used with
Matrix. - Triangular matrix inversion.
- addition and subtraction of matrices
- Matrix multiplication.
- Permutation matrices.
- Triangular solve module.
- Sparse matrix data structures.
- Matrix zipping module.
Macros
- Creates a
Matcontaining the arguments. - Zips together matrix of the same size, so that coefficient-wise operations can be performed on their elements.
Structs
- Generic matrix container.
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
- Trait for types that can be converted to a mutable matrix view.
- Trait for types that can be converted to a matrix view.
- 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.
- Represents a type that can be used to slice a matrix, such as an index or a range of indices.
- Unstable trait containing the operations that a real number type needs to implement.
Functions
- Causes functions that access global parallelism settings to panic.
- Gets the global parallelism settings.
- Sets the global parallelism settings.
- Creates a temporary matrix of constant values, from the given memory stack.
- Returns the stack requirements for creating a temporary matrix with the given dimensions.
- Creates a temporary matrix of untouched values, from the given memory stack.
- Creates a temporary matrix of zero values, from the given memory stack.