## 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§

- Column view creation module.
- 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
`GroupFor`

in generic contexts. - Block Householder transformations.
- Specialized containers that are used with
`Matrix`

. - Triangular matrix inversion.
- Matrix view creation module.
- addition and subtraction of matrices
- Matrix multiplication.
- Permutation matrices.
- Row view creation module.
- Serde implementations for Mat
- Triangular solve module.
- Sparse matrix data structures.
- Implementation of
`zipped!`

structures.

## Macros§

- Creates a
`Col`

containing the arguments. - Concatenates the matrices in each row horizontally, then concatenates the results vertically.
`concat![[a0, a1, a2], [b1, b2]]`

results in the matrix - Creates a
`Mat`

containing the arguments. - Creates a
`Row`

containing the arguments. - Used to undo the zipping by the
`zipped!`

macro. - 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.
- Errors that can occur in sparse algorithms.
- 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 2D matrix view.
- Trait for types that can be converted to a mutable 2D matrix view.
- Trait for types that can be converted to a mutable col view.
- Trait for types that can be converted to a column view.
- Trait for types that can be converted to a mutable matrix view.
- Trait for types that can be converted to a matrix view.
- Trait for types that can be converted to a mutable row view.
- Trait for types that can be converted to a row view.
- Represents a type that can be used to slice a column, such as an index or a range of indices.
- 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.
- Represents a type that can be used to slice a row, such as an index or a range of indices.

## Functions§

- Causes functions that access global parallelism settings to panic.
- Gets the global parallelism settings.
- Kronecker product of two matrices.
- 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.

## Type Aliases§

- Heap allocated resizable column vector.
- Mutable view over a column vector, similar to a mutable reference to a strided slice.
- Immutable view over a column vector, similar to an immutable reference to a strided slice.
- Heap allocated resizable matrix, similar to a 2D
`Vec`

. - Mutable view over a matrix, similar to a mutable reference to a 2D strided slice.
- Immutable view over a matrix, similar to an immutable reference to a 2D strided slice.
- Wrapper around a scalar value that allows scalar multiplication by matrices.
- Heap allocated resizable row vector.
- Mutable view over a row vector, similar to a mutable reference to a strided slice.
- Immutable view over a row vector, similar to an immutable reference to a strided slice.