Struct Matrix 

pub struct Matrix<T> { /* private fields */ }

A 2D matrix with row-major storage

Data is stored in row-major format (C-style), where consecutive elements in memory belong to the same row. This is compatible with NumPy’s default layout and optimal for cache locality when accessing rows.

Storage Layout

For a 2x3 matrix:

[[a, b, c],
 [d, e, f]]

Data is stored as: [a, b, c, d, e, f]

Example

use trueno::Matrix;

let m = Matrix::from_vec(2, 2, vec![1.0, 2.0, 3.0, 4.0]).unwrap();
assert_eq!(m.get(0, 0), Some(&1.0));
assert_eq!(m.get(0, 1), Some(&2.0));
assert_eq!(m.get(1, 0), Some(&3.0));
assert_eq!(m.get(1, 1), Some(&4.0));

Implementations

impl Matrix<f32>

pub fn matmul(&self, other: &Matrix<f32>) -> Result<Matrix<f32>, TruenoError>

Matrix multiplication (matmul)

Computes C = A × B where A is m×n, B is n×p, and C is m×p.

Arguments

• other - The matrix to multiply with (right operand)

Returns

A new matrix containing the result of matrix multiplication

Errors

Returns InvalidInput if matrix dimensions are incompatible (i.e., self.cols != other.rows)

Example

use trueno::Matrix;

let a = Matrix::from_vec(2, 2, vec![1.0, 2.0, 3.0, 4.0]).unwrap();
let b = Matrix::from_vec(2, 2, vec![5.0, 6.0, 7.0, 8.0]).unwrap();
let c = a.matmul(&b).unwrap();

// [[1, 2],   [[5, 6],   [[19, 22],
//  [3, 4]] ×  [7, 8]] =  [43, 50]]
assert_eq!(c.get(0, 0), Some(&19.0));
assert_eq!(c.get(0, 1), Some(&22.0));
assert_eq!(c.get(1, 0), Some(&43.0));
assert_eq!(c.get(1, 1), Some(&50.0));

pub fn batched_matmul( a_data: &[f32], b_data: &[f32], batch: usize, m: usize, k: usize, n: usize, ) -> Result<Vec<f32>, TruenoError>

Batched matrix multiplication for 3D tensors.

Computes [batch, m, k] @ [batch, k, n] -> [batch, m, n] using SIMD for each batch.

pub fn batched_matmul_4d( a_data: &[f32], b_data: &[f32], batch: usize, heads: usize, m: usize, k: usize, n: usize, ) -> Result<Vec<f32>, TruenoError>

Batched matrix multiplication for 4D tensors (attention pattern).

Computes [batch, heads, m, k] @ [batch, heads, k, n] -> [batch, heads, m, n]

impl Matrix<f32>

pub fn transpose(&self) -> Matrix<f32>

Transpose this matrix (swap rows and columns)

Returns a new matrix with dimensions swapped: self.rows → result.cols, self.cols → result.rows.

Performance

Uses cache-optimized block-wise transpose with 32x32 blocks. Sequential writes for output ensure good cache behavior.

Example

use trueno::Matrix;

let m = Matrix::from_vec(2, 3, vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]).unwrap();
let t = m.transpose();

// [[1, 2, 3],     [[1, 4],
//  [4, 5, 6]]  →   [2, 5],
//                  [3, 6]]
assert_eq!(t.rows(), 3);
assert_eq!(t.cols(), 2);
assert_eq!(t.get(0, 0), Some(&1.0));
assert_eq!(t.get(0, 1), Some(&4.0));
assert_eq!(t.get(1, 0), Some(&2.0));

pub fn matvec(&self, v: &Vector<f32>) -> Result<Vector<f32>, TruenoError>

Matrix-vector multiplication (column vector): A × v

Multiplies this matrix by a column vector, computing A × v where the result is a column vector with length equal to the number of rows in A.

Mathematical Definition

For an m×n matrix A and an n-dimensional vector v:

result[i] = Σ(j=0 to n-1) A[i,j] × v[j]

Arguments

• v - Column vector with length equal to self.cols()

Returns

A new vector with length self.rows()

Errors

Returns InvalidInput if v.len() != self.cols()

Example

use trueno::{Matrix, Vector};

let m = Matrix::from_vec(2, 3, vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]).unwrap();
let v = Vector::from_slice(&[1.0, 2.0, 3.0]);
let result = m.matvec(&v).unwrap();

// [[1, 2, 3]   [1]   [1×1 + 2×2 + 3×3]   [14]
//  [4, 5, 6]] × [2] = [4×1 + 5×2 + 6×3] = [32]
//               [3]
assert_eq!(result.as_slice(), &[14.0, 32.0]);

pub fn vecmat( v: &Vector<f32>, m: &Matrix<f32>, ) -> Result<Vector<f32>, TruenoError>

Vector-matrix multiplication (row vector): v^T × A

Multiplies a row vector by this matrix, computing v^T × A where the result is a row vector with length equal to the number of columns in A.

Mathematical Definition

For an m-dimensional vector v and an m×n matrix A:

result[j] = Σ(i=0 to m-1) v[i] × A[i,j]

Arguments

• v - Row vector with length equal to m.rows()
• m - Matrix to multiply

Returns

A new vector with length m.cols()

Errors

Returns InvalidInput if v.len() != m.rows()

Example

use trueno::{Matrix, Vector};

let m = Matrix::from_vec(2, 3, vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]).unwrap();
let v = Vector::from_slice(&[1.0, 2.0]);
let result = Matrix::vecmat(&v, &m).unwrap();

// [1, 2] × [[1, 2, 3]  = [1×1 + 2×4, 1×2 + 2×5, 1×3 + 2×6]
//           [4, 5, 6]]
//         = [9, 12, 15]
assert_eq!(result.as_slice(), &[9.0, 12.0, 15.0]);

impl Matrix<f32>

pub fn convolve2d( &self, kernel: &Matrix<f32>, ) -> Result<Matrix<f32>, TruenoError>

Perform 2D convolution with a kernel

Applies a 2D convolution operation using “valid” padding (no padding), resulting in an output smaller than the input.

Arguments

• kernel - Convolution kernel (filter) to apply

Returns

Convolved matrix with dimensions:

• rows: input.rows - kernel.rows + 1
• cols: input.cols - kernel.cols + 1

Errors

Returns InvalidInput if:

• Kernel is larger than input in any dimension

Example

use trueno::Matrix;

// 5x5 input image
let input = Matrix::from_vec(
    5, 5,
    vec![
        0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 9.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0,
    ]
)?;

// 3x3 averaging kernel
let kernel_val = 1.0 / 9.0;
let kernel = Matrix::from_vec(
    3, 3,
    vec![kernel_val; 9]
)?;

let result = input.convolve2d(&kernel)?;
assert_eq!(result.rows(), 3); // 5 - 3 + 1
assert_eq!(result.cols(), 3);

impl Matrix<f32>

pub fn max_pool2d( &self, kernel: (usize, usize), stride: (usize, usize), ) -> Result<Matrix<f32>, TruenoError>

2D Max Pooling operation for CNN downsampling

Applies max pooling over a 2D input tensor with specified kernel size and stride.

Arguments

• kernel - (kernel_height, kernel_width) pooling window size
• stride - (stride_height, stride_width) step size

Examples

use trueno::matrix::Matrix;
let input = Matrix::from_vec(4, 4, vec![
    1.0, 2.0, 3.0, 4.0,
    5.0, 6.0, 7.0, 8.0,
    9.0, 10.0, 11.0, 12.0,
    13.0, 14.0, 15.0, 16.0,
])?;
let pooled = input.max_pool2d((2, 2), (2, 2))?;
assert_eq!(pooled.shape(), (2, 2));
assert_eq!(pooled.get(0, 0), Some(&6.0));  // max of [1,2,5,6]
assert_eq!(pooled.get(1, 1), Some(&16.0)); // max of [11,12,15,16]

pub fn avg_pool2d( &self, kernel: (usize, usize), stride: (usize, usize), ) -> Result<Matrix<f32>, TruenoError>

2D Average Pooling operation for CNN downsampling

Applies average pooling over a 2D input tensor with specified kernel size and stride.

Arguments

• kernel - (kernel_height, kernel_width) pooling window size
• stride - (stride_height, stride_width) step size

Examples

use trueno::matrix::Matrix;
let input = Matrix::from_vec(4, 4, vec![
    1.0, 2.0, 3.0, 4.0,
    5.0, 6.0, 7.0, 8.0,
    9.0, 10.0, 11.0, 12.0,
    13.0, 14.0, 15.0, 16.0,
])?;
let pooled = input.avg_pool2d((2, 2), (2, 2))?;
assert_eq!(pooled.shape(), (2, 2));
assert!((pooled.get(0, 0).unwrap_or(&0.0) - 3.5).abs() < 1e-5);  // avg of [1,2,5,6]

impl Matrix<f32>

pub fn embedding_lookup( &self, indices: &[usize], ) -> Result<Matrix<f32>, TruenoError>

Lookup embeddings by indices

Performs embedding lookup where self is the embedding table with shape [vocab_size, embed_dim] and indices specify which rows to select.

Arguments

• indices - Slice of indices into the embedding table

Returns

A matrix with shape [indices.len(), embed_dim] containing the selected rows

Errors

Returns InvalidInput if any index is out of bounds

Example

use trueno::Matrix;

// Create embedding table: 4 words, 3-dimensional embeddings
let embeddings = Matrix::from_vec(4, 3, vec![
    1.0, 2.0, 3.0,   // word 0
    4.0, 5.0, 6.0,   // word 1
    7.0, 8.0, 9.0,   // word 2
    10.0, 11.0, 12.0 // word 3
])?;

// Lookup embeddings for indices [1, 3, 0]
let result = embeddings.embedding_lookup(&[1, 3, 0])?;

assert_eq!(result.rows(), 3);
assert_eq!(result.cols(), 3);
assert_eq!(result.get(0, 0), Some(&4.0)); // word 1
assert_eq!(result.get(1, 0), Some(&10.0)); // word 3
assert_eq!(result.get(2, 0), Some(&1.0)); // word 0

pub fn embedding_lookup_sparse( &self, indices: &[usize], ) -> Result<(Matrix<f32>, Vec<usize>), TruenoError>

Lookup embeddings with gradient tracking support (for training)

Returns both the embeddings and a sparse gradient accumulator. This is useful for sparse gradient updates in training.

Arguments

• indices - Slice of indices into the embedding table

Returns

Tuple of (embeddings, unique_indices) where unique_indices can be used for sparse gradient updates

Errors

Returns InvalidInput if any index is out of bounds

pub fn topk(&self, k: usize) -> Result<(Vec<f32>, Vec<usize>), TruenoError>

Top-K selection: returns the k largest elements and their indices

Useful for beam search, sampling, and ranking operations. Searches row-major order and returns (values, indices) sorted descending.

Examples

use trueno::matrix::Matrix;
let m = Matrix::from_vec(2, 3, vec![1.0, 5.0, 3.0, 2.0, 6.0, 4.0])?;
let (values, indices) = m.topk(2)?;
assert_eq!(values, vec![6.0, 5.0]);
assert_eq!(indices, vec![4, 1]);  // flat indices

pub fn gather( &self, indices: &[usize], axis: usize, ) -> Result<Matrix<f32>, TruenoError>

Gather elements along axis using indices

For 2D matrix with axis=0: output[i] = self[indices[i], :] For 2D matrix with axis=1: output[:, i] = self[:, indices[i]]

Examples

use trueno::matrix::Matrix;
let m = Matrix::from_vec(3, 2, vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]).unwrap();
let gathered = m.gather(&[2, 0], 0).unwrap();  // Select rows 2 and 0
assert_eq!(gathered.shape(), (2, 2));
assert_eq!(gathered.get(0, 0), Some(&5.0));  // Row 2
assert_eq!(gathered.get(1, 0), Some(&1.0));  // Row 0

pub fn pad( &self, padding: ((usize, usize), (usize, usize)), value: f32, ) -> Result<Matrix<f32>, TruenoError>

Pad matrix with a constant value

Arguments

• padding - ((top, bottom), (left, right)) padding amounts
• value - constant value to pad with (usually 0.0)

Examples

use trueno::matrix::Matrix;
let m = Matrix::from_vec(2, 2, vec![1.0, 2.0, 3.0, 4.0]).unwrap();
let padded = m.pad(((1, 1), (1, 1)), 0.0).unwrap();
assert_eq!(padded.shape(), (4, 4));
assert_eq!(padded.get(0, 0), Some(&0.0));  // top-left padding
assert_eq!(padded.get(1, 1), Some(&1.0));  // original (0,0)

impl Matrix<f32>

pub fn new(rows: usize, cols: usize) -> Self

Creates a new matrix with uninitialized values

Arguments

• rows - Number of rows
• cols - Number of columns

Returns

A new matrix with dimensions rows x cols containing uninitialized values

Example

use trueno::Matrix;

let m = Matrix::new(3, 4);
assert_eq!(m.rows(), 3);
assert_eq!(m.cols(), 4);

pub fn from_vec( rows: usize, cols: usize, data: Vec<f32>, ) -> Result<Self, TruenoError>

Creates a matrix from a vector of data

Arguments

• rows - Number of rows
• cols - Number of columns
• data - Vector containing matrix elements in row-major order

Errors

Returns InvalidInput if data.len() != rows * cols

Example

use trueno::Matrix;

let m = Matrix::from_vec(2, 2, vec![1.0, 2.0, 3.0, 4.0]).unwrap();
assert_eq!(m.rows(), 2);
assert_eq!(m.cols(), 2);

pub fn from_vec_with_backend( rows: usize, cols: usize, data: Vec<f32>, backend: Backend, ) -> Self

Creates a matrix from a vector with a specific backend

This is useful for testing specific SIMD code paths.

pub fn from_slice( rows: usize, cols: usize, data: &[f32], ) -> Result<Self, TruenoError>

Creates a matrix from a slice by copying the data

This is a convenience method that copies the slice into an owned vector. For zero-copy scenarios, consider using the data directly with from_vec if you already have an owned Vec.

Arguments

• rows - Number of rows
• cols - Number of columns
• data - Slice containing matrix elements in row-major order

Errors

Returns InvalidInput if data.len() != rows * cols

Example

use trueno::Matrix;

let data = [1.0, 2.0, 3.0, 4.0];
let m = Matrix::from_slice(2, 2, &data).unwrap();
assert_eq!(m.get(0, 0), Some(&1.0));

pub fn zeros(rows: usize, cols: usize) -> Self

Creates a matrix filled with zeros

Example

use trueno::Matrix;

let m = Matrix::zeros(3, 3);
assert_eq!(m.get(1, 1), Some(&0.0));

pub fn identity(n: usize) -> Self

Creates an identity matrix (square matrix with 1s on diagonal)

Example

use trueno::Matrix;

let m = Matrix::identity(3);
assert_eq!(m.get(0, 0), Some(&1.0));
assert_eq!(m.get(0, 1), Some(&0.0));
assert_eq!(m.get(1, 1), Some(&1.0));

pub fn rows(&self) -> usize

Returns the number of rows

pub fn cols(&self) -> usize

Returns the number of columns

pub fn shape(&self) -> (usize, usize)

Returns the shape as (rows, cols)

pub fn get(&self, row: usize, col: usize) -> Option<&f32>

Gets a reference to an element at (row, col)

Returns None if indices are out of bounds

pub fn get_mut(&mut self, row: usize, col: usize) -> Option<&mut f32>

Gets a mutable reference to an element at (row, col)

Returns None if indices are out of bounds

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

Returns a reference to the underlying data

pub fn backend(&self) -> Backend

Returns the backend used by this matrix

Trait Implementations

impl<T: Clone> Clone for Matrix<T>

fn clone(&self) -> Matrix<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Matrix<T>

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

Formats the value using the given formatter.

impl Index<(usize, usize)> for Matrix<f32>

type Output = f32

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T: PartialEq> PartialEq for Matrix<T>

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