Struct Matrix 

#[repr(C, align(64))]
pub struct Matrix {
    pub n_rows: usize,
    pub n_cols: usize,
    pub stride: usize,
    pub data: Buffer<f64>,
    pub name: Option<String>,
}

Matrix

Column-major dense matrix.

Description

This struct is compatible with Arrow, LAPACK, BLAS, and all column-major numeric routines.

This is an optional extra enabled by the matrix feature, and is not part of the Apache Arrow framework.

Properties

• n_rows: Logical number of rows.
• n_cols: Number of columns.
• stride: Physical elements per column in the buffer. Padded to 8-element (64-byte) boundaries so every column starts SIMD-aligned. This is the BLAS leading dimension (lda). Always >= n_rows.
• data: Flat buffer in column-major order with stride padding.
• name: Optional matrix name for diagnostics.

Null handling

• It is dense - nulls can be represented through f64::NAN
• However this is not always reliable, as a single NaN can affect vectorised calculations when integrating with various frameworks.

Layout trade-offs vs standard Arrow tables

Matrix is shaped for OLAP-style batch compute, designed to hand memory to LAPACK without repacking. For streaming or append-heavy workloads, stay in a Table and promote to Matrix only at the boundary where LAPACK access is needed (see TableV::try_as_matrix_zc).

Operation	Matrix	Arrow Table
Cross-column scan at a shared row index (e.g. dot product across columns)	Strided access across the flat buffer; recovering spatial locality requires a transpose	Each column lives in its own allocation, so cross-column access spans distinct arenas
Hand the buffer to BLAS/LAPACK expecting (ptr, lda)	Native - pass (as_slice(), stride) directly to dgemm, dsyev, and their peers	Requires a repack into a contiguous stride-aligned buffer before dispatch
Grow the row count	Bounded by the pre-allocated stride budget; exceeding it triggers a full reallocation and re-layout of every column	Amortised O(1) per column via Buffer::push
Drop or reorder columns	Metadata-only while callers track which columns are live; a physical reorder rebuilds the flat buffer	Metadata change on the FieldArray list

Both layouts deliver fast per-column SIMD scans. They differ on row-append flexibility and on how cheaply the buffer can be handed to LAPACK.

Fields

n_rows: usize

n_cols: usize

stride: usize

Physical column stride in elements, padded so each column is 64-byte aligned.

data: Buffer<f64>

Backing storage. Buffer<f64> carries either an owned Vec64<f64> or a shared view into an existing allocation. The shared variant enables zero-copy construction from upstream TableV arenas via TableV::try_as_matrix_zc without sacrificing the dense column-major stride layout that BLAS/LAPACK expects.

name: Option<String>

Implementations

impl Matrix

pub fn new(n_rows: usize, n_cols: usize, name: Option<String>) -> Self

Constructs a new dense Matrix with shape and optional name. Data buffer is zeroed. Columns are padded to 64-byte alignment.

pub fn from_f64_aligned( data: Vec64<f64>, n_rows: usize, n_cols: usize, name: Option<String>, ) -> Self

Constructs a Matrix from a pre-padded Vec64 buffer. The buffer must already have stride * n_cols elements with the correct stride layout. Use from_f64_unaligned if your data is unpadded.

pub fn from_f64_unaligned( src: &[f64], n_rows: usize, n_cols: usize, name: Option<String>, ) -> Self

Constructs a Matrix from a flat column-major buffer without stride padding. The data is re-laid out with 64-byte aligned column padding.

pub fn try_from_cols( cols: impl AsRef<[FloatArray<f64>]>, name: Option<String>, ) -> Result<Self, MinarrowError>

Constructs a Matrix from a slice of FloatArray<f64> columns. Each column becomes one Matrix column; null masks are rejected so Matrix stays dense.

impl AsRef<[FloatArray<f64>]> accepts any contiguous layout at the call-site: &[FloatArray<f64>], &Vec<FloatArray<f64>>, [FloatArray<f64>; N], etc.

All columns must have the same length. Columns are copied into a 64-byte-aligned column-major buffer with stride padding.

For existing Table / TableV containers prefer Matrix::try_from. This constructor targets direct construction from already-built column arrays.

pub fn get(&self, row: usize, col: usize) -> f64

Returns the value at (row, col) (0-based). Panics if out of bounds.

pub fn set(&mut self, row: usize, col: usize, value: f64)

Sets the value at (row, col) (0-based). Panics if out of bounds. Triggers copy-on-write if the backing buffer is currently shared.

pub fn is_empty(&self) -> bool

Returns true if the matrix is empty.

pub fn len(&self) -> usize

Returns the logical number of elements (n_rows * n_cols), not including padding.

pub fn as_slice(&self) -> &[f64]

Returns an immutable reference to the full flat buffer including padding.

pub fn as_mut_slice(&mut self) -> &mut [f64]

Returns a mutable reference to the full flat buffer including padding. Triggers copy-on-write if the backing buffer is currently shared.

pub fn columns(&self) -> Vec<&[f64]>

Returns a view of the matrix as a slice of columns (logical rows only, no padding).

pub fn columns_mut(&mut self) -> Vec<&mut [f64]>

Returns a vector of mutable slices, each corresponding to a column. Triggers copy-on-write if the backing buffer is currently shared.

pub fn col(&self, col: usize) -> &[f64]

Returns a single column as a slice, panics if col out of bounds.

pub fn col_mut(&mut self, col: usize) -> &mut [f64]

Returns a single column as a mutable slice, panics if col out of bounds. Triggers copy-on-write if the backing buffer is currently shared.

pub fn row(&self, row: usize) -> Vec<f64>

Returns a single row as an owned Vec.

pub fn transpose(&self) -> Self

Transpose this matrix, returning a new Matrix with rows and columns swapped. The result has stride-aligned columns for SIMD access.

pub fn extract_rows(&self, indices: &[usize]) -> Self

Extract rows by index into a new Matrix. Column stride alignment is maintained in the result.

pub fn set_name(&mut self, name: impl Into<String>)

Sets the matrix name.

pub fn n_cols(&self) -> usize

Returns the number of columns.

pub fn n_rows(&self) -> usize

Returns the number of rows.

pub fn m(&self) -> i32

Number of rows as i32 for BLAS parameter passing.

pub fn n(&self) -> i32

Number of columns as i32 for BLAS parameter passing.

pub fn lda(&self) -> i32

Leading dimension for BLAS - equals stride, which is n_rows padded to 64-byte alignment. Pass this as the lda parameter to all BLAS/LAPACK calls.

pub fn as_strided(&self) -> (&[f64], i32)

Borrow the matrix as a (data, lda) pair suitable for BLAS/LAPACK routines. The leading dimension travels with the slice because the two are meaningless apart - both describe the same stride-aligned column-major layout.

Packaging them together also avoids a borrow-checker conflict when handing a matrix to a function that wants both values: reading self.stride produces a Copy i32, so no outstanding borrow of the matrix lingers once the tuple is returned.

pub fn as_mut_strided(&mut self) -> (&mut [f64], i32)

Mutable counterpart to [as_strided]. Returns (data, lda) where data is a &mut [f64] view of the backing buffer (triggering copy-on-write if the buffer is currently shared). The leading dimension is read as a Copy value before the mutable borrow is created, so the returned i32 carries no borrow of self.

pub fn to_table(self, fields: Vec<Field>) -> Result<Table, MinarrowError>

Convert this Matrix into a Table with zero-copy column sharing.

The matrix data buffer is frozen into a SharedBuffer (or reused, if it was already shared), and each column becomes a FloatArray backed by a window into that shared allocation. No data is copied.

fields must have exactly n_cols entries, providing the name and metadata for each column.

pub fn to_table_gen(self) -> Table

Convert this Matrix into a Table using auto-generated column names (col_0, col_1, …).

Trait Implementations

impl ByteSize for Matrix

Available on crate feature matrix only.

fn est_bytes(&self) -> usize

Returns the estimated byte size of this object in memory.

impl Clone for Matrix

fn clone(&self) -> Matrix

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Concatenate for Matrix

fn concat(self, other: Self) -> Result<Self, MinarrowError>

Concatenates two matrices vertically (i.e., row-wise stacking).

Requirements

• Both matrices must have the same number of columns

Returns

A new Matrix with rows from self followed by rows from other

Errors

• IncompatibleTypeError if column counts don’t match

impl Debug for Matrix

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

Formats the value using the given formatter.

impl From<&[FloatArray<f64>]> for Matrix

fn from(columns: &[FloatArray<f64>]) -> Self

Converts to this type from the input type.

impl From<&[Vec<f64>]> for Matrix

fn from(columns: &[Vec<f64>]) -> Self

Converts to this type from the input type.

impl<'a> From<(&'a [f64], usize, usize, Option<String>)> for Matrix

fn from( (slice, n_rows, n_cols, name): (&'a [f64], usize, usize, Option<String>), ) -> Self

Converts to this type from the input type.

impl From<(Vec<FloatArray<f64>>, String)> for Matrix

fn from((columns, name): (Vec<FloatArray<f64>>, String)) -> Self

Converts to this type from the input type.

impl From<Matrix> for Value

Available on crate feature matrix only.

fn from(v: Matrix) -> Self

Converts to this type from the input type.

impl From<Vec<FloatArray<f64>>> for Matrix

fn from(columns: Vec<FloatArray<f64>>) -> Self

Converts to this type from the input type.

impl<'a> IntoIterator for &'a Matrix

type Item = &'a f64

The type of the elements being iterated over.

type IntoIter = Iter<'a, f64>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Matrix

type Item = &'a mut f64

The type of the elements being iterated over.

type IntoIter = IterMut<'a, f64>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Matrix

type Item = f64

The type of the elements being iterated over.

type IntoIter = <Vec64<f64> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Matrix

fn eq(&self, other: &Matrix) -> 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 Shape for Matrix

fn shape(&self) -> ShapeDim

Returns arbitrary Shape dimension for any data shape

fn shape_1d(&self) -> usize

Returns the first dimension shape

fn shape_2d(&self) -> (usize, usize)

Returns the first and second dimension shapes

fn shape_3d(&self) -> (usize, usize, usize)

Returns the first, second and third dimension shapes

fn shape_4d(&self) -> (usize, usize, usize, usize)

Returns the first, second, third and fourth dimension shapes

impl StructuralPartialEq for Matrix

impl TryFrom<&Table> for Matrix

type Error = MinarrowError

The type returned in the event of a conversion error.

fn try_from(table: &Table) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&TableV> for Matrix

Available on crate feature views only.

fn try_from(view: &TableV) -> Result<Self, Self::Error>

Materialise a TableV window into a column-major Matrix. Honours active_col_selection and slices each column at the view’s offset, so only the windowed rows are copied. Columns must be FloatArray<f64>; callers needing other numeric types should convert before constructing the view.

type Error = MinarrowError

The type returned in the event of a conversion error.

impl TryFrom<Table> for Matrix

type Error = MinarrowError

The type returned in the event of a conversion error.

fn try_from(table: Table) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Value> for Matrix

Available on crate feature matrix only.

type Error = MinarrowError

The type returned in the event of a conversion error.

fn try_from(v: Value) -> Result<Self, Self::Error>

Performs the conversion.