Struct DenseMatrix 

pub struct DenseMatrix<T, V = Vec<T>> {
    pub values: V,
    pub width: usize,
    /* private fields */
}

A dense matrix in row-major format, with customizable backing storage.

The data is stored as a flat buffer, where rows are laid out consecutively.

Fields

values: V

Flat buffer of matrix values in row-major order.

width: usize

Number of columns in the matrix.

The number of rows is implicitly determined as values.len() / width.

Implementations

impl<T: Clone + Send + Sync + Default> DenseMatrix<T>

pub fn default(width: usize, height: usize) -> Self

Create a new dense matrix of the given dimensions, backed by a Vec, and filled with default values.

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

pub fn new(values: S, width: usize) -> Self

Create a new dense matrix of the given dimensions, backed by the given storage.

Panics

Panics in debug builds if values.len() % width != 0. Release builds silently construct a matrix whose row/column indexing is inconsistent with the storage — callers must validate dimensions before calling.

pub fn new_row(values: S) -> Self

Create a new RowMajorMatrix containing a single row.

pub fn new_col(values: S) -> Self

Create a new RowMajorMatrix containing a single column.

pub fn as_view(&self) -> RowMajorMatrixView<'_, T>

Get a view of the matrix, i.e. a reference to the underlying data.

pub fn as_view_mut(&mut self) -> RowMajorMatrixViewMut<'_, T>

where S: BorrowMut<[T]>,

Get a mutable view of the matrix, i.e. a mutable reference to the underlying data.

pub fn copy_from<S2>(&mut self, source: &DenseMatrix<T, S2>)

where T: Copy, S: BorrowMut<[T]>, S2: DenseStorage<T>,

Copy the values from the given matrix into this matrix.

pub fn flatten_to_base<F: Field>(self) -> RowMajorMatrix<F>

where T: ExtensionField<F>,

Flatten an extension field matrix to a base field matrix.

pub fn row_slices(&self) -> impl DoubleEndedIterator<Item = &[T]>

Get an iterator over the rows of the matrix.

pub fn par_row_slices(&self) -> impl IndexedParallelIterator<Item = &[T]>

where T: Sync,

Get a parallel iterator over the rows of the matrix.

pub fn row_mut(&mut self, r: usize) -> &mut [T]

where S: BorrowMut<[T]>,

Returns a slice of the given row.

Panics

Panics if r larger than self.height().

pub fn rows_mut(&mut self) -> impl Iterator<Item = &mut [T]>

where S: BorrowMut<[T]>,

Get a mutable iterator over the rows of the matrix.

pub fn par_rows_mut<'a>( &'a mut self, ) -> impl IndexedParallelIterator<Item = &'a mut [T]>

where T: 'a + Send, S: BorrowMut<[T]>,

Get a mutable parallel iterator over the rows of the matrix.

pub fn horizontally_packed_row_mut<P>( &mut self, r: usize, ) -> (&mut [P], &mut [T])

where P: PackedValue<Value = T>, S: BorrowMut<[T]>,

Get a mutable iterator over the rows of the matrix which packs the rows into packed values.

If P::WIDTH does not divide self.width, the remainder of the row will be returned as a base slice.

pub fn scale_row(&mut self, r: usize, scale: T)

where T: Field, S: BorrowMut<[T]>,

Scale the given row by the given value.

Panics

Panics if r larger than self.height().

pub fn par_scale_row(&mut self, r: usize, scale: T)

where T: Field, S: BorrowMut<[T]>,

Scale the given row by the given value.

Performance

This function is parallelized, which may introduce some overhead compared to Self::scale_row when the width is small.

Panics

Panics if r larger than self.height().

pub fn scale(&mut self, scale: T)

where T: Field, S: BorrowMut<[T]>,

Scale the entire matrix by the given value.

pub fn split_rows( &self, r: usize, ) -> (RowMajorMatrixView<'_, T>, RowMajorMatrixView<'_, T>)

Split the matrix into two matrix views, one with the first r rows and one with the remaining rows.

Panics

Panics if r larger than self.height().

pub fn split_rows_mut( &mut self, r: usize, ) -> (RowMajorMatrixViewMut<'_, T>, RowMajorMatrixViewMut<'_, T>)

where S: BorrowMut<[T]>,

Split the matrix into two mutable matrix views, one with the first r rows and one with the remaining rows.

Panics

Panics if r larger than self.height().

pub fn par_row_chunks( &self, chunk_rows: usize, ) -> impl IndexedParallelIterator<Item = RowMajorMatrixView<'_, T>>

where T: Send,

Get an iterator over the rows of the matrix which takes chunk_rows rows at a time.

If chunk_rows does not divide the height of the matrix, the last chunk will be smaller.

pub fn par_row_chunks_exact( &self, chunk_rows: usize, ) -> impl IndexedParallelIterator<Item = RowMajorMatrixView<'_, T>>

where T: Send,

Get a parallel iterator over the rows of the matrix which takes chunk_rows rows at a time.

If chunk_rows does not divide the height of the matrix, the last chunk will be smaller.

pub fn par_row_chunks_mut( &mut self, chunk_rows: usize, ) -> impl IndexedParallelIterator<Item = RowMajorMatrixViewMut<'_, T>>

where T: Send, S: BorrowMut<[T]>,

Get a mutable iterator over the rows of the matrix which takes chunk_rows rows at a time.

If chunk_rows does not divide the height of the matrix, the last chunk will be smaller.

pub fn row_chunks_exact_mut( &mut self, chunk_rows: usize, ) -> impl Iterator<Item = RowMajorMatrixViewMut<'_, T>>

where T: Send, S: BorrowMut<[T]>,

Get a mutable iterator over the rows of the matrix which takes chunk_rows rows at a time.

If chunk_rows does not divide the height of the matrix, the last up to chunk_rows - 1 rows of the matrix will be omitted.

pub fn par_row_chunks_exact_mut( &mut self, chunk_rows: usize, ) -> impl IndexedParallelIterator<Item = RowMajorMatrixViewMut<'_, T>>

where T: Send, S: BorrowMut<[T]>,

Get a parallel mutable iterator over the rows of the matrix which takes chunk_rows rows at a time.

If chunk_rows does not divide the height of the matrix, the last up to chunk_rows - 1 rows of the matrix will be omitted.

pub fn row_pair_mut( &mut self, row_1: usize, row_2: usize, ) -> (&mut [T], &mut [T])

where S: BorrowMut<[T]>,

Get a pair of mutable slices of the given rows.

Panics

Panics if row_1 or row_2 are out of bounds or if row_1 >= row_2.

pub fn packed_row_pair_mut<P>( &mut self, row_1: usize, row_2: usize, ) -> ((&mut [P], &mut [T]), (&mut [P], &mut [T]))

where S: BorrowMut<[T]>, P: PackedValue<Value = T>,

Get a pair of mutable slices of the given rows, both packed into packed field elements.

If P:WIDTH does not divide self.width, the remainder of the row will be returned as a base slice.

Panics

Panics if row_1 or row_2 are out of bounds or if row_1 >= row_2.

pub fn bit_reversed_zero_pad(self, added_bits: usize) -> RowMajorMatrix<T>

where T: Field,

Append zeros to the “end” of the given matrix, except that the matrix is in bit-reversed order, so in actuality we’re interleaving zero rows.

impl<T: Clone + Default + Send + Sync> DenseMatrix<T>

pub fn as_cow<'a>(self) -> RowMajorMatrixCow<'a, T>

pub fn rand<R: Rng>(rng: &mut R, rows: usize, cols: usize) -> Self

where StandardUniform: Distribution<T>,

pub fn rand_nonzero<R: Rng>(rng: &mut R, rows: usize, cols: usize) -> Self

where T: Field, StandardUniform: Distribution<T>,

pub fn with_random_cols<R>(&self, num_cols: usize, rng: R) -> Self

where T: Field, R: Rng + Send + Sync, StandardUniform: Distribution<T>,

Return a copy of this matrix with additional columns filled with random values appended on the right.

The original columns are preserved unchanged and the new trailing columns in each row are populated independently from the provided random number generator.

Memory Layout

    Original (h × w):          Result (h × (w + num_cols)):
    [ a00  a01  …  a0w ]  →    [ a00  a01  …  a0w | r0  r1  …  rN ]
    [ a10  a11  …  a1w ]       [ a10  a11  …  a1w | r0  r1  …  rN ]
    …                          …

Arguments

• num_cols: number of random columns to append.
• rng: random number generator used to sample each new element.

Returns

A new matrix with width equal to self.width() + num_cols.

pub fn with_zero_cols(&self, num_cols: usize) -> Self

where T: Field,

Return a copy of this matrix with additional zero-filled columns appended on the right.

Delegates to cloning the matrix and calling the in-place widening method with a zero fill value.

Memory Layout

    Original (h × w):          Result (h × (w + num_cols)):
    [ a00  a01  …  a0w ]  →    [ a00  a01  …  a0w | 0  0  …  0 ]
    [ a10  a11  …  a1w ]       [ a10  a11  …  a1w | 0  0  …  0 ]
    …                          …

Arguments

• num_cols: number of zero columns to append.

Returns

A new matrix with width equal to self.width() + num_cols.

pub fn pad_to_height(&mut self, new_height: usize, fill: T)

pub fn pad_to_power_of_two_height(&mut self, fill: T)

Pad the matrix height to the next power of two by appending rows filled with fill.

This is commonly used in proof systems where trace matrices must have power-of-two heights.

Behavior

• If the matrix is empty (height = 0), it is padded to have exactly one row of fill values.
• If the height is already a power of two, the matrix is unchanged.
• Otherwise, the matrix is padded to the next power of two height.

pub fn pad_to_min_power_of_two_height(&mut self, min_height: usize, fill: T)

Pad the matrix height to at least a given minimum, rounded up to the next power of two.

Appends rows filled with the provided fill value. Useful in batch proving where multiple trace matrices must share a minimum height while still satisfying the power-of-two requirement.

Logic

• Round both the current height and the minimum up to the next power of two.
• Take the maximum of those two values as the target.
• Append fill rows until the target is reached.

Behavior

• If the matrix already meets or exceeds the target, it is unchanged.
• If the minimum is 0, this reduces to padding to the next power of two.
• If the matrix is empty (height = 0), it is padded entirely with fill values.

pub fn from_flat_padded(values: Vec<T>, width: usize, fill: T) -> Self

Build a matrix from a flat buffer whose length may not be a multiple of the requested width.

Useful when constructing trace matrices from a stream of values where the final row may be incomplete.

Arguments

• values: flat row-major data, ownership transferred to avoid a copy.
• width: number of columns (must be > 0).
• fill: value used to complete the last row or to create an empty row.

Returns

A dense matrix with ceil(values.len() / width) rows (at least 1).

Panics

Panics if width is zero.

pub fn widen_right(&mut self, extra_cols: usize, fill: T)

where T: Copy,

Return a new matrix with additional columns appended to the right of every row, filled with a constant value.

Useful when a trace matrix needs extra selector or flag columns that are initialised to a default.

Memory Layout

 Before (width = W):          After (width = W + extra):
 [ d0  d1 ... d_{W-1} ]       [ d0  d1 ... d_{W-1}  fill ... fill ]
 [ ..                 ]       [ ..                                ]

Algorithm

Rows are relocated back-to-front so that earlier (lower-address) source data is never overwritten before it is read.

• Grow the backing buffer to height * new_width.
• Walk rows from the last to the first.
• For each row, move its elements to the new position and fill the trailing gap with the provided value.

Arguments

• extra_cols: number of columns to append (0 is a no-op).
• fill: value written into every new column.

impl<T: Copy + Default + Send + Sync, V: DenseStorage<T>> DenseMatrix<T, V>

pub fn transpose(&self) -> RowMajorMatrix<T>

Return the transpose of this matrix.

pub fn transpose_into<W: DenseStorage<T> + BorrowMut<[T]>>( &self, other: &mut DenseMatrix<T, W>, )

Transpose the matrix returning the result in other without intermediate allocation.

impl<'a, T: Clone + Default + Send + Sync> DenseMatrix<T, &'a [T]>

pub fn as_cow(self) -> RowMajorMatrixCow<'a, T>

Trait Implementations

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

type BitRev = RowIndexMappedView<BitReversalPerm, DenseMatrix<T, S>>

The type returned when this matrix is viewed in bit-reversed order.

fn bit_reverse_rows(self) -> Self::BitRev

Return a version of the matrix with its row order reversed by bit index.

impl<T: Clone, V: Clone> Clone for DenseMatrix<T, V>

fn clone(&self) -> DenseMatrix<T, V>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Copy, V: Copy> Copy for DenseMatrix<T, V>

impl<T: Debug, V: Debug> Debug for DenseMatrix<T, V>

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

Formats the value using the given formatter.

impl<'de, T, V> Deserialize<'de> for DenseMatrix<T, V>

where V: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Eq, V: Eq> Eq for DenseMatrix<T, V>

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

fn width(&self) -> usize

Returns the number of columns in the matrix.

fn height(&self) -> usize

Returns the number of rows in the matrix.

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

Returns the element at the given row and column.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

where Self: Sized,

Returns a view over a vertically strided submatrix.

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 columnwise_dot_product_batched<EF, const N: usize>( &self, vs: &[FieldArray<EF, N>], ) -> Vec<FieldArray<EF, N>>

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

Compute Mᵀ · [v₀, v₁, …, vₙ₋₁] for N weight vectors simultaneously.

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.

impl<T: PartialEq, V: PartialEq> PartialEq for DenseMatrix<T, V>

fn eq(&self, other: &DenseMatrix<T, V>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, V> Serialize for DenseMatrix<T, V>

where V: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T, V> StructuralPartialEq for DenseMatrix<T, V>