Crate faer_core

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, and MatMut.
Coefficient-wise matrix operations, like addition and subtraction: either using the builtin + and - operators or using the low level api zipped!.
Matrix multiplication: either using the builtin * operator or the low level mul module.
Triangular matrix solve: the solve module.
Triangular matrix inverse: the inverse module.
Householder matrix multiplication: the householder module.

§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_as_slice will return a &[f64]. Meanwhile, for a Mat<Complex<f64>>, Mat::col_as_slice 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 dyn_stack;
pub use reborrow;
pub use faer_entity::pulp;
pub use complex_native::*;

Modules§

col: Column view creation module.
complex_native: Native complex floating point types whose real and imaginary parts are stored contiguously.
constrained: Advanced: Module for index and matrix types with compile time checks, instead of bound checking at runtime.
group_helpers: Advanced: Helper types for working with GroupFor in generic contexts.
householder: Block Householder transformations.
inner: Specialized containers that are used with Matrix.
inverse: Triangular matrix inversion.
mat: Matrix view creation module.
matrix_ops: addition and subtraction of matrices
mul: Matrix multiplication.
permutation: Permutation matrices.
row: Row view creation module.
serde_impl: Serde implementations for Mat
solve: Triangular solve module.
sparse: Sparse matrix data structures.
zip: Implementation of zipped! structures.

Macros§

col: Creates a Col containing the arguments.
concat: Concatenates the matrices in each row horizontally, then concatenates the results vertically. concat![[a0, a1, a2], [b1, b2]] results in the matrix
mat: Creates a Mat containing the arguments.
row: Creates a Row containing the arguments.
unzipped: Used to undo the zipping by the zipped! macro.
zipped: Zips together matrix of the same size, so that coefficient-wise operations can be performed on their elements.

Structs§

IdentityGroup
Matrix: Generic matrix container.

Enums§

Conj: Whether a matrix should be implicitly conjugated when read or not.
FaerError: Errors that can occur in sparse algorithms.
Parallelism: Parallelism strategy that can be passed to most of the routines in the library.
Side: Specifies whether the triangular lower or upper part of a matrix should be accessed.

Traits§

As2D: Trait for types that can be converted to a 2D matrix view.
As2DMut: Trait for types that can be converted to a mutable 2D matrix view.
AsColMut: Trait for types that can be converted to a mutable col view.
AsColRef: Trait for types that can be converted to a column view.
AsMatMut: Trait for types that can be converted to a mutable matrix view.
AsMatRef: Trait for types that can be converted to a matrix view.
AsRowMut: Trait for types that can be converted to a mutable row view.
AsRowRef: Trait for types that can be converted to a row view.
ColIndex: Represents a type that can be used to slice a column, such as an index or a range of indices.
ComplexField: Unstable trait containing the operations that a number type needs to implement.
Conjugate: Trait for types that may be implicitly conjugated.
Entity: Unstable core trait for describing how a scalar value may be split up into individual component.
MatIndex: Represents a type that can be used to slice a matrix, such as an index or a range of indices.
RealField: Unstable trait containing the operations that a real number type needs to implement.
RowIndex: Represents a type that can be used to slice a row, such as an index or a range of indices.
SimdCtx
SimpleEntity

Functions§

disable_global_parallelism: Causes functions that access global parallelism settings to panic.
get_global_parallelism: Gets the global parallelism settings.
kron: Kronecker product of two matrices.
set_global_parallelism: Sets the global parallelism settings.
temp_mat_constant: Creates a temporary matrix of constant values, from the given memory stack.
temp_mat_req: Returns the stack requirements for creating a temporary matrix with the given dimensions.
temp_mat_uninit: Creates a temporary matrix of untouched values, from the given memory stack.
temp_mat_zeroed: Creates a temporary matrix of zero values, from the given memory stack.

Type Aliases§

Col: Heap allocated resizable column vector.
ColMut: Mutable view over a column vector, similar to a mutable reference to a strided slice.
ColRef: Immutable view over a column vector, similar to an immutable reference to a strided slice.
GroupFor
Mat: Heap allocated resizable matrix, similar to a 2D Vec.
MatMut: Mutable view over a matrix, similar to a mutable reference to a 2D strided slice.
MatRef: Immutable view over a matrix, similar to an immutable reference to a 2D strided slice.
MatScale: Wrapper around a scalar value that allows scalar multiplication by matrices.
Row: Heap allocated resizable row vector.
RowMut: Mutable view over a row vector, similar to a mutable reference to a strided slice.
RowRef: Immutable view over a row vector, similar to an immutable reference to a strided slice.

Crate faer_coreCopy item path