Crate faer_core

source ·
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, Mat, Scale};

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

Modules

  • complex_native
    Native complex floating point types whose real and imaginary parts are stored contiguously.
  • householder
    Block Householder transformations.
  • inverse
    Triangular matrix inversion.
  • mul
    Matrix multiplication.
  • permutation
    Permutation matrices.
  • solve
    Triangular solve module.
  • zip
    Matrix zipping module.

Macros

  • mat
    Creates a Mat containing the arguments.
  • zipped
    Zips together matrix of the same size, so that coefficient-wise operations can be performed on their elements.

Structs

  • IdentityGroup
  • 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.
  • Scale
    Thin wrapper used for scalar multiplication of a matrix by a scalar value. Wrapper around a scalar value that allows scalar multiplication by matrices.

Enums

  • Conj
  • Parallelism
    Parallelism strategy that can be passed to most of the routines in the library.

Traits

Functions

Type Aliases