Trait Matrix

pub trait Matrix<T: Send + Sync + Clone>: Send + Sync {
    // Required methods
    fn width(&self) -> usize;
    fn height(&self) -> usize;

    // Provided methods
    fn dimensions(&self) -> Dimensions { ... }
    fn get(&self, r: usize, c: usize) -> Option<T> { ... }
    unsafe fn get_unchecked(&self, r: usize, c: usize) -> T { ... }
    fn row(
        &self,
        r: usize,
    ) -> Option<impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>> { ... }
    unsafe fn row_unchecked(
        &self,
        r: usize,
    ) -> impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync> { ... }
    unsafe fn row_subseq_unchecked(
        &self,
        r: usize,
        start: usize,
        end: usize,
    ) -> impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync> { ... }
    fn row_slice(&self, r: usize) -> Option<impl Deref<Target = [T]>> { ... }
    unsafe fn row_slice_unchecked(&self, r: usize) -> impl Deref<Target = [T]> { ... }
    unsafe fn row_subslice_unchecked(
        &self,
        r: usize,
        start: usize,
        end: usize,
    ) -> impl Deref<Target = [T]> { ... }
    fn rows(
        &self,
    ) -> impl Iterator<Item = impl Iterator<Item = T>> + Send + Sync { ... }
    fn par_rows(
        &self,
    ) -> impl IndexedParallelIterator<Item = impl Iterator<Item = T>> + Send + Sync { ... }
    fn wrapping_row_slices(
        &self,
        r: usize,
        c: usize,
    ) -> Vec<impl Deref<Target = [T]>> { ... }
    fn first_row(
        &self,
    ) -> Option<impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>> { ... }
    fn last_row(
        &self,
    ) -> Option<impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>> { ... }
    fn to_row_major_matrix(self) -> RowMajorMatrix<T>
       where Self: Sized,
             T: Clone { ... }
    fn horizontally_packed_row<'a, P>(
        &'a self,
        r: usize,
    ) -> (impl Iterator<Item = P> + Send + Sync, impl Iterator<Item = T> + Send + Sync)
       where P: PackedValue<Value = T>,
             T: Clone + 'a { ... }
    fn padded_horizontally_packed_row<'a, P>(
        &'a self,
        r: usize,
    ) -> impl Iterator<Item = P> + Send + Sync
       where P: PackedValue<Value = T>,
             T: Clone + Default + 'a { ... }
    fn par_horizontally_packed_rows<'a, P>(
        &'a self,
    ) -> impl IndexedParallelIterator<Item = (impl Iterator<Item = P> + Send + Sync, impl Iterator<Item = T> + Send + Sync)>
       where P: PackedValue<Value = T>,
             T: Clone + 'a { ... }
    fn par_padded_horizontally_packed_rows<'a, P>(
        &'a self,
    ) -> impl IndexedParallelIterator<Item = impl Iterator<Item = P> + Send + Sync>
       where P: PackedValue<Value = T>,
             T: Clone + Default + 'a { ... }
    fn vertically_packed_row<P>(&self, r: usize) -> impl Iterator<Item = P>
       where T: Copy,
             P: PackedValue<Value = T> { ... }
    fn vertically_packed_row_pair<P>(&self, r: usize, step: usize) -> Vec<P>
       where T: Copy,
             P: PackedValue<Value = T> { ... }
    fn vertically_strided(
        self,
        stride: usize,
        offset: usize,
    ) -> VerticallyStridedMatrixView<Self>
       where Self: Sized { ... }
    fn columnwise_dot_product<EF>(&self, v: &[EF]) -> Vec<EF>
       where T: Field,
             EF: ExtensionField<T> { ... }
    fn rowwise_packed_dot_product<EF>(
        &self,
        vec: &[EF::ExtensionPacking],
    ) -> impl IndexedParallelIterator<Item = EF>
       where T: Field,
             EF: ExtensionField<T> { ... }
}

A generic trait for two-dimensional matrix-like data structures.

The Matrix trait provides a uniform interface for accessing rows, elements, and computing with matrices in both sequential and parallel contexts. It supports packing strategies for SIMD optimizations and interaction with extension fields.

Required Methods

fn width(&self) -> usize

Returns the number of columns in the matrix.

fn height(&self) -> usize

Returns the number of rows in the matrix.

Provided Methods

fn dimensions(&self) -> Dimensions

Returns the dimensions (width, height) of the matrix.

fn get(&self, r: usize, c: usize) -> Option<T>

Returns the element at the given row and column.

Returns None if either r >= height() or c >= width().

unsafe fn get_unchecked(&self, r: usize, c: usize) -> T

Returns the element at the given row and column.

For a safe alternative, see [get].

Safety

The caller must ensure that r < self.height() and c < self.width(). Breaking any of these assumptions is considered undefined behaviour.

fn row( &self, r: usize, ) -> Option<impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>>

Returns an iterator over the elements of the r-th row.

The iterator will have self.width() elements.

Returns None if r >= height().

unsafe fn row_unchecked( &self, r: usize, ) -> impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>

Returns an iterator over the elements of the r-th row.

The iterator will have self.width() elements.

For a safe alternative, see [row].

Safety

The caller must ensure that r < self.height(). Breaking this assumption is considered undefined behaviour.

unsafe fn row_subseq_unchecked( &self, r: usize, start: usize, end: usize, ) -> impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>

Returns an iterator over the elements of the r-th row from position start to end.

When start = 0 and end = width(), this is equivalent to [row_unchecked].

For a safe alternative, use [row], along with the skip and take iterator methods.

Safety

The caller must ensure that r < self.height() and start <= end <= self.width(). Breaking any of these assumptions is considered undefined behaviour.

fn row_slice(&self, r: usize) -> Option<impl Deref<Target = [T]>>

Returns the elements of the r-th row as something which can be coerced to a slice.

Returns None if r >= height().

unsafe fn row_slice_unchecked(&self, r: usize) -> impl Deref<Target = [T]>

Returns the elements of the r-th row as something which can be coerced to a slice.

For a safe alternative, see [row_slice].

Safety

The caller must ensure that r < self.height(). Breaking this assumption is considered undefined behaviour.

unsafe fn row_subslice_unchecked( &self, r: usize, start: usize, end: usize, ) -> impl Deref<Target = [T]>

Returns a subset of elements of the r-th row as something which can be coerced to a slice.

When start = 0 and end = width(), this is equivalent to [row_slice_unchecked].

For a safe alternative, see [row_slice].

Safety

The caller must ensure that r < self.height() and start <= end <= self.width(). Breaking any of these assumptions is considered undefined behaviour.

fn rows(&self) -> impl Iterator<Item = impl Iterator<Item = T>> + Send + Sync

Returns an iterator over all rows in the matrix.

fn par_rows( &self, ) -> impl IndexedParallelIterator<Item = impl Iterator<Item = T>> + Send + Sync

Returns a parallel iterator over all rows in the matrix.

fn wrapping_row_slices( &self, r: usize, c: usize, ) -> Vec<impl Deref<Target = [T]>>

Collect the elements of the rows r through r + c. If anything is larger than self.height() simply wrap around to the beginning of the matrix.

fn first_row( &self, ) -> Option<impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>>

Returns an iterator over the first row of the matrix.

Returns None if height() == 0.

fn last_row( &self, ) -> Option<impl IntoIterator<Item = T, IntoIter = impl Iterator<Item = T> + Send + Sync>>

Returns an iterator over the last row of the matrix.

Returns None if height() == 0.

fn to_row_major_matrix(self) -> RowMajorMatrix<T>

where Self: Sized, T: Clone,

Converts the matrix into a RowMajorMatrix by collecting all rows into a single vector.

fn horizontally_packed_row<'a, P>( &'a self, r: usize, ) -> (impl Iterator<Item = P> + Send + Sync, impl Iterator<Item = T> + Send + Sync)

where P: PackedValue<Value = T>, T: Clone + 'a,

Get a packed iterator over the r-th row.

If the row length is not divisible by the packing width, the final elements are returned as a base iterator with length <= P::WIDTH - 1.

Panics

Panics if r >= height().

fn padded_horizontally_packed_row<'a, P>( &'a self, r: usize, ) -> impl Iterator<Item = P> + Send + Sync

where P: PackedValue<Value = T>, T: Clone + Default + 'a,

Get a packed iterator over the r-th row.

If the row length is not divisible by the packing width, the final entry will be zero-padded.

Panics

Panics if r >= height().

fn par_horizontally_packed_rows<'a, P>( &'a self, ) -> impl IndexedParallelIterator<Item = (impl Iterator<Item = P> + Send + Sync, impl Iterator<Item = T> + Send + Sync)>

where P: PackedValue<Value = T>, T: Clone + 'a,

Get a parallel iterator over all packed rows of the matrix.

If the matrix width is not divisible by the packing width, the final elements of each row are returned as a base iterator with length <= P::WIDTH - 1.

fn par_padded_horizontally_packed_rows<'a, P>( &'a self, ) -> impl IndexedParallelIterator<Item = impl Iterator<Item = P> + Send + Sync>

where P: PackedValue<Value = T>, T: Clone + Default + 'a,

Get a parallel iterator over all packed rows of the matrix.

If the matrix width is not divisible by the packing width, the final entry of each row will be zero-padded.

fn vertically_packed_row<P>(&self, r: usize) -> impl Iterator<Item = P>

where T: Copy, P: PackedValue<Value = T>,

Pack together a collection of adjacent rows from the matrix.

Returns an iterator whose i’th element is packing of the i’th element of the rows r through r + P::WIDTH - 1. If we exceed the height of the matrix, wrap around and include initial rows.

fn vertically_packed_row_pair<P>(&self, r: usize, step: usize) -> Vec<P>

where T: Copy, P: PackedValue<Value = T>,

Pack together a collection of rows and “next” rows from the matrix.

Returns a vector corresponding to 2 packed rows. The i’th element of the first row contains the packing of the i’th element of the rows r through r + P::WIDTH - 1. The i’th element of the second row contains the packing of the i’th element of the rows r + step through r + step + P::WIDTH - 1. If at some point we exceed the height of the matrix, wrap around and include initial rows.

fn vertically_strided( self, stride: usize, offset: usize, ) -> VerticallyStridedMatrixView<Self>

where Self: Sized,

Returns a view over a vertically strided submatrix.

The view selects rows using r = offset + i * stride for each i.

fn columnwise_dot_product<EF>(&self, v: &[EF]) -> Vec<EF>

where T: Field, EF: ExtensionField<T>,

Compute Mᵀv, aka premultiply this matrix by the given vector, aka scale each row by the corresponding entry in v and take the sum across rows. v can be a vector of extension elements.

fn rowwise_packed_dot_product<EF>( &self, vec: &[EF::ExtensionPacking], ) -> impl IndexedParallelIterator<Item = EF>

where T: Field, EF: ExtensionField<T>,

Compute the matrix vector product M . vec, aka take the dot product of each row of M by vec. If the length of vec is longer than the width of M, vec is truncated to the first width() elements.

We make use of PackedFieldExtension to speed up computations. Thus vec is passed in as a slice of PackedFieldExtension elements.

Panics

This function panics if the length of vec is less than self.width().div_ceil(T::Packing::WIDTH).

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<F, EF, Inner> Matrix<F> for FlatMatrixView<F, EF, Inner>

where F: Field, EF: ExtensionField<F>, Inner: Matrix<EF>,

impl<T, Inner> Matrix<T> for HorizontallyTruncated<T, Inner>

where T: Send + Sync + Clone, Inner: Matrix<T>,

impl<T: Clone + Send + Sync, S: DenseStorage<T>> Matrix<T> for DenseMatrix<T, S>

impl<T: Send + Sync + Clone, IndexMap: RowIndexMap, Inner: Matrix<T>> Matrix<T> for RowIndexMappedView<IndexMap, Inner>

impl<T: Send + Sync + Clone, Left: Matrix<T>, Right: Matrix<T>> Matrix<T> for HorizontalPair<Left, Right>

impl<T: Send + Sync + Clone, Top: Matrix<T>, Bottom: Matrix<T>> Matrix<T> for VerticalPair<Top, Bottom>