Type Alias faer_core::Mat

pub type Mat<E> = Matrix<DenseOwn<E>>;

Heap allocated resizable matrix, similar to a 2D Vec.

Note

The memory layout of Mat is guaranteed to be column-major, meaning that it has a row stride of 1, and an unspecified column stride that can be queried with Mat::col_stride.

This implies that while each individual column is stored contiguously in memory, the matrix as a whole may not necessarily be contiguous. The implementation may add padding at the end of each column when overaligning each column can provide a performance gain.

Let us consider a 3×4 matrix

 0 │ 3 │ 6 │  9
───┼───┼───┼───
 1 │ 4 │ 7 │ 10
───┼───┼───┼───
 2 │ 5 │ 8 │ 11

The memory representation of the data held by such a matrix could look like the following:

0 1 2 X 3 4 5 X 6 7 8 X 9 10 11 X

where X represents padding elements.

Aliased Type

struct Mat<E> { /* private fields */ }

Implementations

impl<E: Entity> Mat<E>

pub fn new() -> Self

Returns an empty matrix of dimension 0×0.

pub fn with_capacity(row_capacity: usize, col_capacity: usize) -> Self

Returns a new matrix with dimensions (0, 0), with enough capacity to hold a maximum of row_capacity rows and col_capacity columns without reallocating. If either is 0, the matrix will not allocate.

Panics

The function panics if the total capacity in bytes exceeds isize::MAX.

pub fn from_fn( nrows: usize, ncols: usize, f: impl FnMut(usize, usize) -> E ) -> Self

Returns a new matrix with dimensions (nrows, ncols), filled with the provided function.

Panics

The function panics if the total capacity in bytes exceeds isize::MAX.

pub fn zeros(nrows: usize, ncols: usize) -> Self

where E: ComplexField,

Returns a new matrix with dimensions (nrows, ncols), filled with zeros.

Panics

The function panics if the total capacity in bytes exceeds isize::MAX.

pub fn identity(nrows: usize, ncols: usize) -> Self

where E: ComplexField,

Returns a new matrix with dimensions (nrows, ncols), filled with zeros, except the main diagonal which is filled with ones.

Panics

The function panics if the total capacity in bytes exceeds isize::MAX.

pub fn nrows(&self) -> usize

Returns the number of rows of the matrix.

pub fn ncols(&self) -> usize

Returns the number of columns of the matrix.

pub unsafe fn set_dims(&mut self, nrows: usize, ncols: usize)

Set the dimensions of the matrix.

Safety

The behavior is undefined if any of the following conditions are violated:

• nrows < self.row_capacity().
• ncols < self.col_capacity().
• The elements that were previously out of bounds but are now in bounds must be initialized.

pub fn as_ptr(&self) -> GroupFor<E, *const E::Unit>

Returns a pointer to the data of the matrix.

pub fn as_ptr_mut(&mut self) -> GroupFor<E, *mut E::Unit>

Returns a mutable pointer to the data of the matrix.

pub fn row_capacity(&self) -> usize

Returns the row capacity, that is, the number of rows that the matrix is able to hold without needing to reallocate, excluding column insertions.

pub fn col_capacity(&self) -> usize

Returns the column capacity, that is, the number of columns that the matrix is able to hold without needing to reallocate, excluding row insertions.

pub fn row_stride(&self) -> isize

Returns the offset between the first elements of two successive rows in the matrix. Always returns 1 since the matrix is column major.

pub fn col_stride(&self) -> isize

Returns the offset between the first elements of two successive columns in the matrix.

pub fn reserve_exact(&mut self, row_capacity: usize, col_capacity: usize)

Reserves the minimum capacity for row_capacity rows and col_capacity columns without reallocating. Does nothing if the capacity is already sufficient.

Panics

The function panics if the new total capacity in bytes exceeds isize::MAX.

pub fn resize_with( &mut self, new_nrows: usize, new_ncols: usize, f: impl FnMut(usize, usize) -> E )

Resizes the matrix in-place so that the new dimensions are (new_nrows, new_ncols). New elements are created with the given function f, so that elements at indices (i, j) are created by calling f(i, j).

pub fn col_as_slice(&self, col: usize) -> GroupFor<E, &[E::Unit]>

Returns a reference to a slice over the column at the given index.

pub fn col_as_slice_mut(&mut self, col: usize) -> GroupFor<E, &mut [E::Unit]>

Returns a mutable reference to a slice over the column at the given index.

pub fn col_ref(&self, col: usize) -> GroupFor<E, &[E::Unit]>

👎Deprecated: replaced by Mat::col_as_slice

Returns a reference to a slice over the column at the given index.

pub fn col_mut(&mut self, col: usize) -> GroupFor<E, &mut [E::Unit]>

👎Deprecated: replaced by Mat::col_as_slice_mut

Returns a mutable reference to a slice over the column at the given index.

pub fn as_ref(&self) -> MatRef<'_, E>

Returns a view over the matrix.

pub fn as_mut(&mut self) -> MatMut<'_, E>

Returns a mutable view over the matrix.

pub unsafe fn get_unchecked<RowRange, ColRange>( &self, row: RowRange, col: ColRange ) -> <MatRef<'_, E> as MatIndex<RowRange, ColRange>>::Target

where for<'a> MatRef<'a, E>: MatIndex<RowRange, ColRange>,

Returns references to the element at the given indices, or submatrices if either row or col is a range.

Note

The values pointed to by the references are expected to be initialized, even if the pointed-to value is not read, otherwise the behavior is undefined.

Safety

The behavior is undefined if any of the following conditions are violated:

• row must be contained in [0, self.nrows()).
• col must be contained in [0, self.ncols()).

pub fn get<RowRange, ColRange>( &self, row: RowRange, col: ColRange ) -> <MatRef<'_, E> as MatIndex<RowRange, ColRange>>::Target

where for<'a> MatRef<'a, E>: MatIndex<RowRange, ColRange>,

Returns references to the element at the given indices, or submatrices if either row or col is a range, with bound checks.

Note

The values pointed to by the references are expected to be initialized, even if the pointed-to value is not read, otherwise the behavior is undefined.

Panics

The function panics if any of the following conditions are violated:

• row must be contained in [0, self.nrows()).
• col must be contained in [0, self.ncols()).

pub unsafe fn get_mut_unchecked<RowRange, ColRange>( &mut self, row: RowRange, col: ColRange ) -> <MatMut<'_, E> as MatIndex<RowRange, ColRange>>::Target

where for<'a> MatMut<'a, E>: MatIndex<RowRange, ColRange>,

Returns mutable references to the element at the given indices, or submatrices if either row or col is a range.

Note

The values pointed to by the references are expected to be initialized, even if the pointed-to value is not read, otherwise the behavior is undefined.

Safety

The behavior is undefined if any of the following conditions are violated:

• row must be contained in [0, self.nrows()).
• col must be contained in [0, self.ncols()).

pub fn get_mut<RowRange, ColRange>( &mut self, row: RowRange, col: ColRange ) -> <MatMut<'_, E> as MatIndex<RowRange, ColRange>>::Target

where for<'a> MatMut<'a, E>: MatIndex<RowRange, ColRange>,

Returns mutable references to the element at the given indices, or submatrices if either row or col is a range, with bound checks.

Note

The values pointed to by the references are expected to be initialized, even if the pointed-to value is not read, otherwise the behavior is undefined.

Panics

The function panics if any of the following conditions are violated:

• row must be contained in [0, self.nrows()).
• col must be contained in [0, self.ncols()).

pub unsafe fn read_unchecked(&self, row: usize, col: usize) -> E

Reads the value of the element at the given indices.

Safety

The behavior is undefined if any of the following conditions are violated:

• row < self.nrows().
• col < self.ncols().

pub fn read(&self, row: usize, col: usize) -> E

Reads the value of the element at the given indices, with bound checks.

Panics

The function panics if any of the following conditions are violated:

• row < self.nrows().
• col < self.ncols().

pub unsafe fn write_unchecked(&mut self, row: usize, col: usize, value: E)

Writes the value to the element at the given indices.

Safety

The behavior is undefined if any of the following conditions are violated:

• row < self.nrows().
• col < self.ncols().

pub fn write(&mut self, row: usize, col: usize, value: E)

Writes the value to the element at the given indices, with bound checks.

Panics

The function panics if any of the following conditions are violated:

• row < self.nrows().
• col < self.ncols().

pub fn copy_from(&mut self, other: impl AsMatRef<E>)

Copies the values from other into self.

pub fn fill_zero(&mut self)

where E: ComplexField,

Fills the elements of self with zeros.

pub fn fill(&mut self, constant: E)

Fills the elements of self with copies of constant.

pub fn transpose(&self) -> MatRef<'_, E>

Returns a view over the transpose of self.

pub fn conjugate(&self) -> MatRef<'_, E::Conj>

where E: Conjugate,

Returns a view over the conjugate of self.

pub fn adjoint(&self) -> MatRef<'_, E::Conj>

where E: Conjugate,

Returns a view over the conjugate transpose of self.

pub fn diagonal(&self) -> Matrix<DiagRef<'_, E>>

Returns a view over the diagonal of the matrix.

pub fn to_owned(&self) -> Mat<E::Canonical>

where E: Conjugate,

Returns an owning Mat of the data

pub fn has_nan(&self) -> bool

where E: ComplexField,

Returns true if any of the elements is NaN, otherwise returns false.

pub fn is_all_finite(&self) -> bool

where E: ComplexField,

Returns true if all of the elements are finite, otherwise returns false.

pub fn norm_max(&self) -> E::Real

where E: ComplexField,

Returns the maximum norm of self.

pub fn norm_l2(&self) -> E::Real

where E: ComplexField,

Returns the L2 norm of self.

pub fn sum(&self) -> E

where E: ComplexField,

Returns the sum of self.

pub fn kron(&self, rhs: impl As2D<E>) -> Mat<E>

where E: ComplexField,

Kroneckor product of self and rhs.

This is an allocating operation; see kron for the allocation-free version or more info in general.

pub fn col_chunks( &self, chunk_size: usize ) -> impl '_ + DoubleEndedIterator<Item = MatRef<'_, E>>

Returns an iterator that provides successive chunks of the columns of a view over this matrix, with each having at most chunk_size columns.

If the number of columns is a multiple of chunk_size, then all chunks have chunk_size columns.

pub fn col_chunks_mut( &mut self, chunk_size: usize ) -> impl '_ + DoubleEndedIterator<Item = MatMut<'_, E>>

Returns an iterator that provides successive chunks of the columns of a mutable view over this matrix, with each having at most chunk_size columns.

If the number of columns is a multiple of chunk_size, then all chunks have chunk_size columns.

pub fn par_col_chunks( &self, chunk_size: usize ) -> impl '_ + IndexedParallelIterator<Item = MatRef<'_, E>>

Available on crate feature rayon only.

Returns a parallel iterator that provides successive chunks of the columns of a view over this matrix, with each having at most chunk_size columns.

If the number of columns is a multiple of chunk_size, then all chunks have chunk_size columns.

Only available with the rayon feature.

pub fn par_col_chunks_mut( &mut self, chunk_size: usize ) -> impl '_ + IndexedParallelIterator<Item = MatMut<'_, E>>

Available on crate feature rayon only.

Returns a parallel iterator that provides successive chunks of the columns of a mutable view over this matrix, with each having at most chunk_size columns.

If the number of columns is a multiple of chunk_size, then all chunks have chunk_size columns.

Only available with the rayon feature.

pub fn row_chunks( &self, chunk_size: usize ) -> impl '_ + DoubleEndedIterator<Item = MatRef<'_, E>>

Returns an iterator that provides successive chunks of the rows of a view over this matrix, with each having at most chunk_size rows.

If the number of rows is a multiple of chunk_size, then all chunks have chunk_size rows.

pub fn row_chunks_mut( &mut self, chunk_size: usize ) -> impl '_ + DoubleEndedIterator<Item = MatMut<'_, E>>

Returns an iterator that provides successive chunks of the rows of a mutable view over this matrix, with each having at most chunk_size rows.

If the number of rows is a multiple of chunk_size, then all chunks have chunk_size rows.

pub fn par_row_chunks( &self, chunk_size: usize ) -> impl '_ + IndexedParallelIterator<Item = MatRef<'_, E>>

Available on crate feature rayon only.

Returns a parallel iterator that provides successive chunks of the rows of a view over this matrix, with each having at most chunk_size rows.

If the number of rows is a multiple of chunk_size, then all chunks have chunk_size rows.

Only available with the rayon feature.

pub fn par_row_chunks_mut( &mut self, chunk_size: usize ) -> impl '_ + IndexedParallelIterator<Item = MatMut<'_, E>>

Available on crate feature rayon only.

Returns a parallel iterator that provides successive chunks of the rows of a mutable view over this matrix, with each having at most chunk_size rows.

If the number of rows is a multiple of chunk_size, then all chunks have chunk_size rows.

Only available with the rayon feature.

Trait Implementations

impl<E: Entity> As2D<E> for &Mat<E>

fn as_2d_ref(&self) -> MatRef<'_, E>

Convert to a 2D matrix view.

impl<E: Entity> As2D<E> for Mat<E>

fn as_2d_ref(&self) -> MatRef<'_, E>

Convert to a 2D matrix view.

impl<E: Entity> As2DMut<E> for &mut Mat<E>

fn as_2d_mut(&mut self) -> MatMut<'_, E>

Convert to a mutable 2D matrix view.

impl<E: Entity> As2DMut<E> for Mat<E>

fn as_2d_mut(&mut self) -> MatMut<'_, E>

Convert to a mutable 2D matrix view.

impl<E: Entity> AsMatMut<E> for &mut Mat<E>

fn as_mat_mut(&mut self) -> MatMut<'_, E>

Convert to a mutable matrix view.

impl<E: Entity> AsMatMut<E> for Mat<E>

fn as_mat_mut(&mut self) -> MatMut<'_, E>

Convert to a mutable matrix view.

impl<E: Entity> AsMatRef<E> for &Mat<E>

fn as_mat_ref(&self) -> MatRef<'_, E>

Convert to a matrix view.

impl<E: Entity> AsMatRef<E> for Mat<E>

fn as_mat_ref(&self) -> MatRef<'_, E>

Convert to a matrix view.

impl<E: Entity> Clone for Mat<E>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<E: Entity> Debug for Mat<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: Entity> Default for Mat<E>

fn default() -> Self

Returns the “default value” for a type.

impl<E: Entity> DenseAccess<E> for Mat<E>

Available on crate feature std only.

fn fetch_single(&self, row: usize, col: usize) -> E

impl<'a, E> Deserialize<'a> for Mat<E>

where E: Deserialize<'a> + Entity,

fn deserialize<D>(d: D) -> Result<Self, <D as Deserializer<'a>>::Error>

where D: Deserializer<'a>,

Deserialize this value from the given Serde deserializer.

impl<E: SimpleEntity> Index<(usize, usize)> for Mat<E>

type Output = E

The returned type after indexing.

fn index(&self, (row, col): (usize, usize)) -> &E

Performs the indexing (container[index]) operation.

impl<E: SimpleEntity> IndexMut<(usize, usize)> for Mat<E>

fn index_mut(&mut self, (row, col): (usize, usize)) -> &mut E

Performs the mutable indexing (container[index]) operation.

impl<E: Entity> Matrix<E> for Mat<E>

Available on crate feature std only.

fn rows(&self) -> usize

fn cols(&self) -> usize

fn access(&self) -> Access<'_, E>

Expose dense or sparse access to the matrix.

impl<E> Serialize for Mat<E>

where E: Serialize + Entity,

fn serialize<S>( &self, s: S ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<E: Entity> ViewMut for &Mat<E>

type Target<'a> = Matrix<DenseRef<'a, E>> where Self: 'a

View type.

fn view_mut(&mut self) -> Self::Target<'_>

Returns the view over self.

impl<E: Entity> ViewMut for &mut Mat<E>

type Target<'a> = Matrix<DenseMut<'a, E>> where Self: 'a

View type.

fn view_mut(&mut self) -> Self::Target<'_>

Returns the view over self.

impl<E: Entity> ViewMut for Mat<E>

type Target<'a> = Matrix<DenseRef<'a, E>> where Self: 'a

View type.

fn view_mut(&mut self) -> Self::Target<'_>

Returns the view over self.