Type Alias Mat 

pub type Mat<T, Rows = usize, Cols = usize> = Mat<Own<T, Rows, Cols>>;

heap allocated resizable matrix, similar to a 2d alloc::vec::Vec

note

the memory layout of Own 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

#[repr(transparent)]
pub struct Mat<T, Rows = usize, Cols = usize>(pub Own<T, Rows, Cols>);

Tuple Fields

0: Own<T, Rows, Cols>

Implementations

impl<T> Mat<T>

pub const fn new() -> Self

returns an empty matrix of dimension 0×0.

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

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

impl<T, Rows: Shape, Cols: Shape> Mat<T, Rows, Cols>

pub fn from_fn( nrows: Rows, ncols: Cols, f: impl FnMut(Idx<Rows>, Idx<Cols>) -> T, ) -> Self

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

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

where T: ComplexField,

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

pub fn ones(nrows: Rows, ncols: Cols) -> Self

where T: ComplexField,

returns a new matrix with dimensions (nrows, ncols), filled with ones

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

where T: ComplexField,

returns a new identity matrix, with ones on the diagonal and zeros everywhere else

pub fn full(nrows: Rows, ncols: Cols, value: T) -> Self

where T: Clone,

returns a new matrix with dimensions (nrows, ncols), filled with value

pub fn try_reserve( &mut self, new_row_capacity: usize, new_col_capacity: usize, ) -> Result<(), TryReserveError>

reserves the minimum capacity for new_row_capacity rows and new_col_capacity columns without reallocating, or returns an error in case of failure. does nothing if the capacity is already sufficient

pub fn reserve(&mut self, new_row_capacity: usize, new_col_capacity: usize)

reserves the minimum capacity for new_row_capacity rows and new_col_capacity columns without reallocating. does nothing if the capacity is already sufficient

pub fn resize_with( &mut self, new_nrows: Rows, new_ncols: Cols, f: impl FnMut(Idx<Rows>, Idx<Cols>) -> T, )

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 index (i, j) are created by calling f(i, j).

pub fn truncate(&mut self, new_nrows: Rows, new_ncols: Cols)

truncates the matrix so that its new dimensions are new_nrows and new_ncols.
both of the new dimensions must be smaller than or equal to the current dimensions

panics

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

• new_nrows > self.nrows()
• new_ncols > self.ncols()

pub fn into_shape<V: Shape, H: Shape>(self, nrows: V, ncols: H) -> Mat<T, V, H>

see MatRef::as_shape

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

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 col_as_slice(&self, j: Idx<Cols>) -> &[T]

returns a reference to a slice over the column at the given index

pub fn col_as_slice_mut(&mut self, j: Idx<Cols>) -> &mut [T]

returns a reference to a slice over the column at the given index

impl<T, Rows: Shape, Cols: Shape> Mat<T, Rows, Cols>

pub fn nrows(&self) -> Rows

returns the number of rows of the matrix

pub fn ncols(&self) -> Cols

returns the number of columns of the matrix

impl<T, Rows: Shape, Cols: Shape> Mat<T, Rows, Cols>

pub fn as_ptr(&self) -> *const T

returns a pointer to the matrix data

pub fn shape(&self) -> (Rows, Cols)

returns the number of rows and columns of the matrix

pub fn row_stride(&self) -> isize

returns the row stride of the matrix, specified in number of elements, not in bytes

pub fn col_stride(&self) -> isize

returns the column stride of the matrix, specified in number of elements, not in bytes

pub fn ptr_at(&self, row: IdxInc<Rows>, col: IdxInc<Cols>) -> *const T

returns a raw pointer to the element at the given index

pub unsafe fn ptr_inbounds_at(&self, row: Idx<Rows>, col: Idx<Cols>) -> *const T

returns a raw pointer to the element at the given index, assuming the provided index is within the matrix bounds

safety

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

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

pub fn split_at( &self, row: IdxInc<Rows>, col: IdxInc<Cols>, ) -> (MatRef<'_, T, usize, usize>, MatRef<'_, T, usize, usize>, MatRef<'_, T, usize, usize>, MatRef<'_, T, usize, usize>)

see MatRef::split_at

pub fn split_at_row( &self, row: IdxInc<Rows>, ) -> (MatRef<'_, T, usize, Cols>, MatRef<'_, T, usize, Cols>)

see MatRef::split_at_row

pub fn split_at_col( &self, col: IdxInc<Cols>, ) -> (MatRef<'_, T, Rows, usize>, MatRef<'_, T, Rows, usize>)

see MatRef::split_at_col

pub fn transpose(&self) -> MatRef<'_, T, Cols, Rows>

see MatRef::transpose

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

where T: Conjugate,

see MatRef::conjugate

pub fn canonical(&self) -> MatRef<'_, T::Canonical, Rows, Cols>

where T: Conjugate,

see MatRef::canonical

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

where T: Conjugate,

see MatRef::adjoint

pub fn reverse_rows(&self) -> MatRef<'_, T, Rows, Cols>

see MatRef::reverse_rows

pub fn reverse_cols(&self) -> MatRef<'_, T, Rows, Cols>

see MatRef::reverse_cols

pub fn reverse_rows_and_cols(&self) -> MatRef<'_, T, Rows, Cols>

see MatRef::reverse_rows_and_cols

pub fn submatrix<V: Shape, H: Shape>( &self, row_start: IdxInc<Rows>, col_start: IdxInc<Cols>, nrows: V, ncols: H, ) -> MatRef<'_, T, V, H>

see MatRef::submatrix

pub fn subrows<V: Shape>( &self, row_start: IdxInc<Rows>, nrows: V, ) -> MatRef<'_, T, V, Cols>

see MatRef::subrows

pub fn subcols<H: Shape>( &self, col_start: IdxInc<Cols>, ncols: H, ) -> MatRef<'_, T, Rows, H>

see MatRef::subcols

pub fn as_shape<V: Shape, H: Shape>( &self, nrows: V, ncols: H, ) -> MatRef<'_, T, V, H>

see MatRef::as_shape

pub fn as_row_shape<V: Shape>(&self, nrows: V) -> MatRef<'_, T, V, Cols>

see MatRef::as_row_shape

pub fn as_col_shape<H: Shape>(&self, ncols: H) -> MatRef<'_, T, Rows, H>

see MatRef::as_col_shape

pub fn as_dyn_stride(&self) -> MatRef<'_, T, Rows, Cols, isize, isize>

see MatRef::as_dyn_stride

pub fn as_dyn(&self) -> MatRef<'_, T, usize, usize>

see MatRef::as_dyn

pub fn as_dyn_rows(&self) -> MatRef<'_, T, usize, Cols>

see MatRef::as_dyn_rows

pub fn as_dyn_cols(&self) -> MatRef<'_, T, Rows, usize>

see MatRef::as_dyn_cols

pub fn row(&self, i: Idx<Rows>) -> RowRef<'_, T, Cols>

see MatRef::row

pub fn col(&self, j: Idx<Cols>) -> ColRef<'_, T, Rows>

see MatRef::col

pub fn col_iter( &self, ) -> impl '_ + ExactSizeIterator + DoubleEndedIterator<Item = ColRef<'_, T, Rows>>

see MatRef::col_iter

pub fn row_iter( &self, ) -> impl '_ + ExactSizeIterator + DoubleEndedIterator<Item = RowRef<'_, T, Cols>>

see MatRef::row_iter

pub fn par_col_iter( &self, ) -> impl '_ + IndexedParallelIterator<Item = ColRef<'_, T, Rows>>

where T: Sync,

see MatRef::par_col_iter

pub fn par_row_iter( &self, ) -> impl '_ + IndexedParallelIterator<Item = RowRef<'_, T, Cols>>

where T: Sync,

see MatRef::par_row_iter

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

where T: Sync,

see MatRef::par_col_chunks

pub fn par_col_partition( &self, count: usize, ) -> impl '_ + IndexedParallelIterator<Item = MatRef<'_, T, Rows, usize>>

where T: Sync,

see MatRef::par_col_partition

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

where T: Sync,

see MatRef::par_row_chunks

pub fn par_row_partition( &self, count: usize, ) -> impl '_ + IndexedParallelIterator<Item = MatRef<'_, T, usize, Cols>>

where T: Sync,

see MatRef::par_row_partition

pub fn try_as_col_major( &self, ) -> Option<MatRef<'_, T, Rows, Cols, ContiguousFwd>>

see MatRef::try_as_col_major

pub fn try_as_row_major( &self, ) -> Option<MatRef<'_, T, Rows, Cols, isize, ContiguousFwd>>

see MatRef::try_as_row_major

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

where for<'a> MatRef<'a, T, Rows, Cols>: MatIndex<RowRange, ColRange>,

see MatRef::get

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

where for<'a> MatRef<'a, T, Rows, Cols>: MatIndex<RowRange, ColRange>,

see MatRef::get_unchecked

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

where for<'a> MatMut<'a, T, Rows, Cols>: MatIndex<RowRange, ColRange>,

see MatMut::get_mut

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

where for<'a> MatMut<'a, T, Rows, Cols>: MatIndex<RowRange, ColRange>,

see MatMut::get_mut_unchecked

impl<T, Rows: Shape, Cols: Shape> Mat<T, Rows, Cols>

pub fn as_ptr_mut(&mut self) -> *mut T

returns a pointer to the matrix data

pub fn ptr_at_mut(&mut self, row: IdxInc<Rows>, col: IdxInc<Cols>) -> *mut T

returns a raw pointer to the element at the given index

pub unsafe fn ptr_inbounds_at_mut( &mut self, row: Idx<Rows>, col: Idx<Cols>, ) -> *mut T

returns a raw pointer to the element at the given index, assuming the provided index is within the matrix bounds

safety

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

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

pub fn split_at_mut( &mut self, row: IdxInc<Rows>, col: IdxInc<Cols>, ) -> (MatMut<'_, T, usize, usize>, MatMut<'_, T, usize, usize>, MatMut<'_, T, usize, usize>, MatMut<'_, T, usize, usize>)

see MatMut::split_at_mut

pub fn split_at_row_mut( &mut self, row: IdxInc<Rows>, ) -> (MatMut<'_, T, usize, Cols>, MatMut<'_, T, usize, Cols>)

see MatMut::split_at_row_mut

pub fn split_at_col_mut( &mut self, col: IdxInc<Cols>, ) -> (MatMut<'_, T, Rows, usize>, MatMut<'_, T, Rows, usize>)

see MatMut::split_at_col_mut

pub fn transpose_mut(&mut self) -> MatMut<'_, T, Cols, Rows>

see MatMut::transpose_mut

pub fn conjugate_mut(&mut self) -> MatMut<'_, T::Conj, Rows, Cols>

where T: Conjugate,

see MatMut::conjugate_mut

pub fn canonical_mut(&mut self) -> MatMut<'_, T::Canonical, Rows, Cols>

where T: Conjugate,

see MatMut::canonical_mut

pub fn adjoint_mut(&mut self) -> MatMut<'_, T::Conj, Cols, Rows>

where T: Conjugate,

see MatMut::adjoint_mut

pub fn reverse_rows_mut(&mut self) -> MatMut<'_, T, Rows, Cols>

see MatMut::reverse_rows_mut

pub fn reverse_cols_mut(&mut self) -> MatMut<'_, T, Rows, Cols>

see MatMut::reverse_cols_mut

pub fn reverse_rows_and_cols_mut(&mut self) -> MatMut<'_, T, Rows, Cols>

see MatMut::reverse_rows_and_cols_mut

pub fn submatrix_mut<V: Shape, H: Shape>( &mut self, row_start: IdxInc<Rows>, col_start: IdxInc<Cols>, nrows: V, ncols: H, ) -> MatMut<'_, T, V, H>

see MatMut::submatrix_mut

pub fn subrows_mut<V: Shape>( &mut self, row_start: IdxInc<Rows>, nrows: V, ) -> MatMut<'_, T, V, Cols>

see MatMut::subrows_mut

pub fn subcols_mut<H: Shape>( &mut self, col_start: IdxInc<Cols>, ncols: H, ) -> MatMut<'_, T, Rows, H>

see MatMut::subcols_mut

pub fn as_shape_mut<V: Shape, H: Shape>( &mut self, nrows: V, ncols: H, ) -> MatMut<'_, T, V, H>

see MatMut::as_shape_mut

pub fn as_row_shape_mut<V: Shape>(&mut self, nrows: V) -> MatMut<'_, T, V, Cols>

see MatMut::as_row_shape_mut

pub fn as_col_shape_mut<H: Shape>(&mut self, ncols: H) -> MatMut<'_, T, Rows, H>

see MatMut::as_col_shape_mut

pub fn as_dyn_stride_mut(&mut self) -> MatMut<'_, T, Rows, Cols, isize, isize>

see MatMut::as_dyn_stride_mut

pub fn as_dyn_mut(&mut self) -> MatMut<'_, T, usize, usize>

see MatMut::as_dyn_mut

pub fn as_dyn_rows_mut(&mut self) -> MatMut<'_, T, usize, Cols>

see MatMut::as_dyn_rows_mut

pub fn as_dyn_cols_mut(&mut self) -> MatMut<'_, T, Rows, usize>

see MatMut::as_dyn_cols_mut

pub fn row_mut(&mut self, i: Idx<Rows>) -> RowMut<'_, T, Cols>

see MatMut::row_mut

pub fn col_mut(&mut self, j: Idx<Cols>) -> ColMut<'_, T, Rows>

see MatMut::col_mut

pub fn col_iter_mut( &mut self, ) -> impl '_ + ExactSizeIterator + DoubleEndedIterator<Item = ColMut<'_, T, Rows>>

see MatMut::col_iter_mut

pub fn row_iter_mut( &mut self, ) -> impl '_ + ExactSizeIterator + DoubleEndedIterator<Item = RowMut<'_, T, Cols>>

see MatMut::row_iter_mut

pub fn par_col_iter_mut( &mut self, ) -> impl '_ + IndexedParallelIterator<Item = ColMut<'_, T, Rows>>

where T: Send,

see MatMut::par_col_iter_mut

pub fn par_row_iter_mut( &mut self, ) -> impl '_ + IndexedParallelIterator<Item = RowMut<'_, T, Cols>>

where T: Send,

see MatMut::par_row_iter_mut

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

where T: Send,

see MatMut::par_col_chunks_mut

pub fn par_col_partition_mut( &mut self, count: usize, ) -> impl '_ + IndexedParallelIterator<Item = MatMut<'_, T, Rows, usize>>

where T: Send,

see MatMut::par_col_partition_mut

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

where T: Send,

see MatMut::par_row_chunks_mut

pub fn par_row_partition_mut( &mut self, count: usize, ) -> impl '_ + IndexedParallelIterator<Item = MatMut<'_, T, usize, Cols>>

where T: Send,

see MatMut::par_row_partition_mut

pub fn split_first_row_mut( &mut self, ) -> Option<(RowMut<'_, T, Cols>, MatMut<'_, T, usize, Cols>)>

see MatMut::split_first_row_mut

pub fn try_as_col_major_mut( &mut self, ) -> Option<MatMut<'_, T, Rows, Cols, ContiguousFwd>>

see MatMut::try_as_col_major_mut

pub fn try_as_row_major_mut( &mut self, ) -> Option<MatMut<'_, T, Rows, Cols, isize, ContiguousFwd>>

see MatMut::try_as_row_major_mut

pub fn two_cols_mut( &mut self, i0: Idx<Cols>, i1: Idx<Cols>, ) -> (ColMut<'_, T, Rows>, ColMut<'_, T, Rows>)

see MatMut::two_cols_mut

pub fn two_rows_mut( &mut self, i0: Idx<Rows>, i1: Idx<Rows>, ) -> (RowMut<'_, T, Cols>, RowMut<'_, T, Cols>)

see MatMut::two_rows_mut

impl<T, Dim: Shape> Mat<T, Dim, Dim>

pub fn diagonal(&self) -> DiagRef<'_, T, Dim, isize>

see MatRef::diagonal

pub fn diagonal_mut(&mut self) -> DiagMut<'_, T, Dim, isize>

see MatMut::diagonal_mut

impl<T, Cols: Shape> Mat<T, usize, Cols>

pub fn push_row(&mut self, row: RowRef<'_, T, Cols>)

where T: Clone,

inserts a row at the end of the matrix

panics

The function panics if the number of columns in the row does not match the number of columns in the matrix

impl<T, Rows: Shape> Mat<T, Rows, usize>

pub fn push_col(&mut self, col: ColRef<'_, T, Rows>)

where T: Clone,

inserts a col at the end of the matrix

panics

The function panics if the number of rows in the col does not match the number of rows in the matrix

impl<T, Rows: Shape, Cols: Shape> Mat<T, Rows, Cols>

where T: RealField,

pub fn min(self) -> Option<T>

see MatRef::min

pub fn max(self) -> Option<T>

see MatRef::min

Trait Implementations

impl<T, Rows: Shape, Cols: Shape> AsMat<T> for Mat<T, Rows, Cols>

fn zeros(rows: Rows, cols: Cols) -> Self

where T: ComplexField,

returns a matrix with dimensions (rows, cols) filled with zeros

fn truncate(&mut self, rows: Self::Rows, cols: Self::Cols)

returns a matrix with dimensions (rows, cols) filled with zeros

impl<T, Rows: Shape, Cols: Shape> AsMatMut for Mat<T, Rows, Cols>

fn as_mat_mut(&mut self) -> MatMut<'_, T, Rows, Cols>

returns a view over self

impl<T, Rows: Shape, Cols: Shape> AsMatRef for Mat<T, Rows, Cols>

type Cols = Cols

column dimension type

type Owned = Mat<Own<T, Rows, Cols>>

owned matrix type

type Rows = Rows

row dimension type

type T = T

scalar type

fn as_mat_ref(&self) -> MatRef<'_, T, Rows, Cols>

returns a view over self

impl<T: ComplexField, ViewT: Conjugate<Canonical = T>> BiLinOp<T> for Mat<ViewT>

fn transpose_apply_scratch(&self, rhs_ncols: usize, par: Par) -> StackReq

computes the workspace size and alignment required to apply the transpose or adjoint o self to a matrix with rhs_ncols columns

fn transpose_apply( &self, out: MatMut<'_, T>, rhs: MatRef<'_, T>, par: Par, stack: &mut MemStack, )

applies the transpose of self to rhs, and stores the result in out

fn adjoint_apply( &self, out: MatMut<'_, T>, rhs: MatRef<'_, T>, par: Par, stack: &mut MemStack, )

applies the adjoint of self to rhs, and stores the result in out

impl<T: ComplexField, ViewT: Conjugate<Canonical = T>> BiPrecond<T> for Mat<ViewT>

fn transpose_apply_in_place_scratch( &self, rhs_ncols: usize, par: Par, ) -> StackReq

computes the workspace size and alignment required to apply the transpose or adjoint of self to a matrix with rhs_ncols columns in place

fn transpose_apply_in_place( &self, rhs: MatMut<'_, T>, par: Par, stack: &mut MemStack, )

applies the transpose of self to rhs, and stores the result in rhs

fn adjoint_apply_in_place( &self, rhs: MatMut<'_, T>, par: Par, stack: &mut MemStack, )

applies the adjoint of self to rhs, and stores the result in rhs

impl<'a, T, Rows: Shape, Cols: Shape> IntoView for &'a Mat<T, Rows, Cols>

type Target = Mat<Ref<'a, T, Rows, Cols, ContiguousFwd>>

fn into_view(self) -> Self::Target

impl<'a, T, Rows: Shape, Cols: Shape> IntoView for &'a mut Mat<T, Rows, Cols>

type Target = Mat<Mut<'a, T, Rows, Cols, ContiguousFwd>>

fn into_view(self) -> Self::Target

impl<T: ComplexField, ViewT: Conjugate<Canonical = T>> LinOp<T> for Mat<ViewT>

fn nrows(&self) -> usize

output dimension of the operator

fn ncols(&self) -> usize

input dimension of the operator

fn apply_scratch(&self, rhs_ncols: usize, par: Par) -> StackReq

computes the workspace size and alignment required to apply self or the conjugate o self to a matrix with rhs_ncols columns

fn apply( &self, out: MatMut<'_, T>, rhs: MatRef<'_, T>, par: Par, stack: &mut MemStack, )

applies self to rhs, and stores the result in out

fn conj_apply( &self, out: MatMut<'_, T>, rhs: MatRef<'_, T>, par: Par, stack: &mut MemStack, )

applies the conjugate of self to rhs, and stores the result in out

impl<T: ComplexField, ViewT: Conjugate<Canonical = T>> Precond<T> for Mat<ViewT>

fn apply_in_place_scratch(&self, rhs_ncols: usize, par: Par) -> StackReq

computes the workspace size and alignment required to apply self or the conjugate of self to a matrix with rhs_ncols columns in place

fn apply_in_place(&self, rhs: MatMut<'_, T>, par: Par, stack: &mut MemStack)

applies self to rhs, and stores the result in rhs

fn conj_apply_in_place( &self, rhs: MatMut<'_, T>, par: Par, stack: &mut MemStack, )

applies the conjugate of self to rhs, and stores the result in rhs