Struct CsrMatrix

Source

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

Expand description

A Compressed Sparse Row Matrix.

Implementations§

Source §

impl<T> CsrMatrix<T>
where T: AbelianGroup + Copy + Default + PartialEq,

Source

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

Creates a zero matrix with the given shape.

§Arguments

rows - Number of rows
cols - Number of columns

§Returns

A sparse matrix with all elements zero (empty CSR structure).

Source

pub fn add(&self, rhs: &Self) -> Self

Element-wise matrix addition (panics on shape mismatch).

§Panics

Panics if self.shape != rhs.shape.

Source §

impl<T> CsrMatrix<T>
where T: AbelianGroup + Copy + Sub<Output = T> + Default + PartialEq,

Source

pub fn sub(&self, rhs: &Self) -> Self

Element-wise matrix subtraction (panics on shape mismatch).

§Panics

Panics if self.shape != rhs.shape.

Source §

impl<T> CsrMatrix<T>
where T: AbelianGroup + Copy + Neg<Output = T>,

Source

pub fn neg(&self) -> Self

Element-wise negation.

Source §

impl<T> CsrMatrix<T>

Source

pub fn scale<S>(&self, scalar: S) -> Self
where T: Module<S> + Copy, S: Ring + Copy,

Scalar multiplication.

§Arguments

scalar - The scalar to multiply by

§Returns

A new matrix where each element is multiplied by scalar.

Source §

impl<T> CsrMatrix<T>
where T: Ring + One + Copy + Default + PartialEq,

Source

pub fn one(size: usize) -> Self

Creates an identity matrix of size n × n.

§Arguments

size - The dimension of the square identity matrix

§Returns

An identity matrix where I[i,i] = 1 and I[i,j] = 0 for i != j.

Source

pub fn mul(&self, rhs: &Self) -> Self

Matrix multiplication (panics on dimension mismatch).

Computes self * rhs using sparse matrix multiplication.

§Panics

Panics if self.cols != rhs.rows.

Source §

impl<T> CsrMatrix<T>
where T: Copy + Zero + PartialEq + Default,

Source

pub fn add_matrix(&self, other: &Self) -> Result<Self, SparseMatrixError>

Performs matrix addition: ( C = A + B ).

Given two matrices ( A ) (self) and ( B ) (other) of the same shape ( m \times n ), their sum ( C ) is a matrix of the same shape where each element ( C_{ij} ) is the sum of the corresponding elements in ( A ) and ( B ): ( C_{ij} = A_{ij} + B_{ij} ).

Returns a new CsrMatrix representing the sum of the two matrices, or a SparseMatrixError::ShapeMismatch if their shapes are not compatible.

§Arguments

other - The matrix to add.

§Errors

Returns SparseMatrixError::ShapeMismatch if the matrices have different dimensions.

§Examples

use deep_causality_sparse::CsrMatrix;

let a = CsrMatrix::from_triplets(2, 2, &[(0, 0, 1.0), (1, 1, 2.0)]).unwrap();
// A = [[1.0, 0.0], [0.0, 2.0]]

let b = CsrMatrix::from_triplets(2, 2, &[(0, 1, 3.0), (1, 0, 4.0)]).unwrap();
// B = [[0.0, 3.0], [4.0, 0.0]]

let c = a.add_matrix(&b).unwrap();
// C = A + B = [[1.0, 3.0], [4.0, 2.0]]

assert_eq!(c.get_value_at(0, 0), 1.0);
assert_eq!(c.get_value_at(0, 1), 3.0);
assert_eq!(c.get_value_at(1, 0), 4.0);
assert_eq!(c.get_value_at(1, 1), 2.0);

Source

pub fn transpose(&self) -> Self

Computes the transpose of the matrix: ( B = A^T ).

Given a matrix ( A ) of shape ( m \times n ), its transpose ( B ) is a matrix of shape ( n \times m ), where the rows of ( A ) become the columns of ( B ) and the columns of ( A ) become the rows of ( B ). Formally, ( B_{ij} = A_{ji} ).

Returns a new CsrMatrix representing the transpose.

§Examples

use deep_causality_sparse::CsrMatrix;

let a = CsrMatrix::from_triplets(2, 3, &[(0, 0, 1.0), (0, 2, 2.0), (1, 1, 3.0)]).unwrap();
// A (2x3) = [[1.0, 0.0, 2.0], [0.0, 3.0, 0.0]]

let a_t = a.transpose();
// A^T (3x2) = [[1.0, 0.0], [0.0, 3.0], [2.0, 0.0]]

assert_eq!(a_t.shape(), (3, 2));
assert_eq!(a_t.get_value_at(0, 0), 1.0);
assert_eq!(a_t.get_value_at(1, 1), 3.0);
assert_eq!(a_t.get_value_at(2, 0), 2.0);

Source §

impl<T> CsrMatrix<T>
where T: Copy + Sub<Output = T> + Zero + PartialEq + Default,

Source

pub fn sub_matrix(&self, other: &Self) -> Result<Self, SparseMatrixError>

Performs matrix subtraction: ( C = A - B ).

Given two matrices ( A ) (self) and ( B ) (other) of the same shape ( m \times n ), their difference ( C ) is a matrix of the same shape where each element ( C_{ij} ) is the difference of the corresponding elements in ( A ) and ( B ): ( C_{ij} = A_{ij} - B_{ij} ).

Returns a new CsrMatrix representing the difference of the two matrices, or a SparseMatrixError::ShapeMismatch if their shapes are not compatible.

§Arguments

other - The matrix to subtract.

§Errors

Returns SparseMatrixError::ShapeMismatch if the matrices have different dimensions.

§Examples

use deep_causality_sparse::CsrMatrix;

let a = CsrMatrix::from_triplets(2, 2, &[(0, 0, 5.0), (0, 1, 2.0), (1, 1, 3.0)]).unwrap();
// A = [[5.0, 2.0], [0.0, 3.0]]

let b = CsrMatrix::from_triplets(2, 2, &[(0, 0, 1.0), (1, 1, 1.0)]).unwrap();
// B = [[1.0, 0.0], [0.0, 1.0]]

let c = a.sub_matrix(&b).unwrap();
// C = A - B = [[4.0, 2.0], [0.0, 2.0]]

assert_eq!(c.get_value_at(0, 0), 4.0);
assert_eq!(c.get_value_at(0, 1), 2.0);
assert_eq!(c.get_value_at(1, 0), 0.0);
assert_eq!(c.get_value_at(1, 1), 2.0);

Source §

impl<T> CsrMatrix<T>
where T: Copy + Mul<Output = T> + Zero + PartialEq + Default + One,

Source

pub fn scalar_mult(&self, scalar: T) -> Self

Performs scalar multiplication: ( B = s \cdot A ).

Given a matrix ( A ) and a scalar ( s ), their product ( B ) is a matrix of the same shape as ( A ), where each element ( B_{ij} ) is the product of the scalar ( s ) and the corresponding element ( A_{ij} ): ( B_{ij} = s \cdot A_{ij} ).

Returns a new CsrMatrix where each element is multiplied by the scalar.

§Arguments

scalar - The scalar value to multiply by.

§Examples

use deep_causality_sparse::CsrMatrix;

let a = CsrMatrix::from_triplets(2, 2, &[(0, 0, 1.0), (1, 1, 2.0)]).unwrap();
// A = [[1.0, 0.0], [0.0, 2.0]]

let c = a.scalar_mult(3.0);
// C = 3 * A = [[3.0, 0.0], [0.0, 6.0]]

assert_eq!(c.get_value_at(0, 0), 3.0);
assert_eq!(c.get_value_at(1, 1), 6.0);

Source

pub fn vec_mult(&self, vector: &[T]) -> Result<Vec<T>, SparseMatrixError>

Performs matrix-vector multiplication: ( y = Ax ).

Given a matrix ( A ) of shape ( m \times n ) (self) and a vector ( x ) of length ( n ), their product ( y ) is a vector of length ( m ), where each element ( y_i ) is the dot product of the ( i )-th row of ( A ) and the vector ( x ): ( y_i = \sum_{j=0}^{n-1} A_{ij} x_j ).

§Arguments

x - The vector to multiply by. It is expected to have a length equal to the number of columns in the matrix.

§Returns

A Result<Vec<T>, SparseMatrixError> representing the resulting vector, or an error.

§Errors

Returns SparseMatrixError::DimensionMismatch if the length of x does not match the number of columns in the matrix (self.shape.1).

§Examples

use deep_causality_sparse::CsrMatrix;
use deep_causality_num::Zero;

let a = CsrMatrix::from_triplets(2, 3, &[(0, 0, 1.0), (0, 2, 2.0), (1, 1, 3.0)]).unwrap();
// A = [[1.0, 0.0, 2.0], [0.0, 3.0, 0.0]]

let x = vec![1.0, 2.0, 3.0];

let y = a.vec_mult(&x).unwrap();
// y = Ax = [(1.0*1.0 + 0.0*2.0 + 2.0*3.0), (0.0*1.0 + 3.0*2.0 + 0.0*3.0)] = [7.0, 6.0]

assert_eq!(y, vec![7.0, 6.0]);

Source

pub fn mat_mult(&self, other: &Self) -> Result<Self, SparseMatrixError>

Performs matrix multiplication: ( C = A \cdot B ).

Given two matrices ( A ) (self) of shape ( m \times k ) and ( B ) (other) of shape ( k \times n ), their product ( C ) is a matrix of shape ( m \times n ). Each element ( C_{ij} ) is the dot product of the ( i )-th row of ( A ) and the ( j )-th column of ( B ): ( C_{ij} = \sum_{p=0}^{k-1} A_{ip} B_{pj} ).

Returns a new CsrMatrix representing the product of the two matrices, or a SparseMatrixError::DimensionMismatch if their dimensions are not compatible.

§Arguments

other - The matrix to multiply by.

§Errors

Returns SparseMatrixError::DimensionMismatch if the matrices have incompatible dimensions for multiplication (self.cols != other.rows).

§Examples

use deep_causality_sparse::CsrMatrix;
use deep_causality_num::Zero;

let a = CsrMatrix::from_triplets(2, 3, &[(0, 0, 1.0), (0, 2, 2.0), (1, 1, 3.0)]).unwrap();
// A (2x3) = [[1.0, 0.0, 2.0], [0.0, 3.0, 0.0]]

let b = CsrMatrix::from_triplets(3, 2, &[(0, 0, 4.0), (1, 1, 5.0), (2, 0, 6.0)]).unwrap();
// B (3x2) = [[4.0, 0.0], [0.0, 5.0], [6.0, 0.0]]

let c = a.mat_mult(&b).unwrap();
// C = A * B (2x2) = [[(1*4+0*0+2*6), (1*0+0*5+2*0)], [(0*4+3*0+0*6), (0*0+3*5+0*0)]]
//                 = [[16.0, 0.0], [0.0, 15.0]]

assert_eq!(c.get_value_at(0, 0), 16.0);
assert_eq!(c.get_value_at(0, 1), 0.0);
assert_eq!(c.get_value_at(1, 0), 0.0);
assert_eq!(c.get_value_at(1, 1), 15.0);

Source §

impl<T> CsrMatrix<T>

Source

pub fn row_indices(&self) -> &Vec<usize>

Returns a reference to the internal row_indices vector.

This vector stores the starting index in col_indices and values for each row of the matrix, plus one extra element at the end indicating the total number of non-zero elements.

§Returns

A reference to a Vec<usize> representing the row pointers.

§Examples

use deep_causality_sparse::CsrMatrix;

let matrix: CsrMatrix<f64> = CsrMatrix::from_triplets(
    2, 3, &[(0, 0, 1.0), (0, 2, 2.0), (1, 1, 3.0)]
).unwrap();
assert_eq!(matrix.row_indices(), &vec![0, 2, 3]);

Source

pub fn col_indices(&self) -> &Vec<usize>

Returns a reference to the internal col_indices vector.

This vector stores the column index for each non-zero element in the matrix, ordered by row, then by column within each row.

§Returns

A reference to a Vec<usize> representing the column indices of non-zero elements.

§Examples

use deep_causality_sparse::CsrMatrix;

let matrix: CsrMatrix<f64> = CsrMatrix::from_triplets(
    2, 3, &[(0, 0, 1.0), (0, 2, 2.0), (1, 1, 3.0)]
).unwrap();
assert_eq!(matrix.col_indices(), &vec![0, 2, 1]);

Source

pub fn values(&self) -> &Vec<T>

Returns a reference to the internal values vector.

This vector stores the actual non-zero values of the matrix, corresponding to the column indices in col_indices.

§Returns

A reference to a Vec<T> representing the non-zero values.

§Examples

use deep_causality_sparse::CsrMatrix;

let matrix: CsrMatrix<f64> = CsrMatrix::from_triplets(
    2, 3, &[(0, 0, 1.0), (0, 2, 2.0), (1, 1, 3.0)]
).unwrap();
assert_eq!(matrix.values(), &vec![1.0, 2.0, 3.0]);

Source

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

Returns the shape (dimensions) of the matrix.

The shape is returned as a tuple (rows, cols).

§Returns

A tuple (usize, usize) representing the number of rows and columns.

§Examples

use deep_causality_sparse::CsrMatrix;

let matrix: CsrMatrix<f64> = CsrMatrix::with_capacity(5, 10, 0);
assert_eq!(matrix.shape(), (5, 10));

Source §

impl<T> CsrMatrix<T>

Source

pub fn get_value_at(&self, row_idx: usize, col_idx: usize) -> T
where T: Copy + Zero + PartialEq,

Retrieves the value at the specified row and column index. Returns T::zero() if the index is out of bounds or the element is zero.

§Arguments

row_idx - The row index.
col_idx - The column index.

§Returns

The value at (row_idx, col_idx) or T::zero() if not found or out of bounds.

Source §

impl<T> CsrMatrix<T>

Source

pub fn new() -> Self

Creates a new, empty CsrMatrix.

The matrix will have zero rows and columns and no stored elements. Its shape will be (0, 0).

§Returns

A new, empty CsrMatrix.

§Examples

use deep_causality_sparse::CsrMatrix;

let matrix: CsrMatrix<f64> = CsrMatrix::new();
assert_eq!(matrix.shape(), (0, 0));
assert!(matrix.values().is_empty());

Source

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

Creates a new CsrMatrix with pre-allocated capacity for its internal vectors.

This can improve performance by reducing reallocations when a large number of elements are expected to be added to the matrix after creation. The matrix is initially logically empty (all zeros) with the specified shape.

§Arguments

rows - The number of rows the matrix will have.
cols - The number of columns the matrix will have.
capacity - The estimated number of non-zero elements the matrix will store.

§Returns

A new CsrMatrix with the specified shape and allocated capacity.

§Examples

use deep_causality_sparse::CsrMatrix;

let matrix: CsrMatrix<f64> = CsrMatrix::with_capacity(5, 5, 10);
assert_eq!(matrix.shape(), (5, 5));
assert!(matrix.values().capacity() >= 10);
assert_eq!(matrix.row_indices().len(), 6); // rows + 1
assert!(matrix.col_indices().is_empty());

Source §

impl<T> CsrMatrix<T>
where T: Copy + Zero + PartialEq,

Source

pub fn from_triplets( rows: usize, cols: usize, triplets: &[(usize, usize, T)], ) -> Result<Self, SparseMatrixError>

Creates a new CsrMatrix from a list of (row, col, value) triplets.

The from_triplets function constructs a sparse matrix ( A ) of size ( m \times n ) (where ( m ) is rows and ( n ) is cols) from a list of ( (r, c, v) ) triplets. Each triplet represents a non-zero element ( A_{rc} = v ). If multiple triplets specify the same ( (r, c) ) position, their values are summed: ( A_{rc} = \sum v_i ) for all ( v_i ) at ( (r, c) ). Triplets whose summed value is zero are discarded.

The triplets are sorted, and duplicate (row, col) entries have their values summed.

§Arguments

rows - The number of rows in the matrix.
cols - The number of columns in the matrix.
triplets - A slice of (row_idx, col_idx, value) tuples.

§Errors

Returns SparseMatrixError::IndexOutOfBounds if any triplet’s indices are outside the specified matrix dimensions.

§Examples

use deep_causality_sparse::CsrMatrix;
use deep_causality_num::Zero;

// Example 1: Basic construction
let triplets1 = vec![(0, 0, 1.0), (0, 2, 2.0), (1, 1, 3.0)];
let matrix1 = CsrMatrix::from_triplets(2, 3, &triplets1).unwrap();
// matrix1 will represent:
// [1.0, 0.0, 2.0]
// [0.0, 3.0, 0.0]
assert_eq!(matrix1.values(), &vec![1.0, 2.0, 3.0]);
assert_eq!(matrix1.col_indices(), &vec![0, 2, 1]);
assert_eq!(matrix1.row_indices(), &vec![0, 2, 3]);
assert_eq!(matrix1.shape(), (2, 3));

// Example 2: With duplicate entries
let triplets2 = vec![(0, 0, 1.0), (0, 0, 0.5), (1, 1, 3.0)];
let matrix2 = CsrMatrix::from_triplets(2, 2, &triplets2).unwrap();
// matrix2 will represent:
// [1.5, 0.0]
// [0.0, 3.0]
assert_eq!(matrix2.values(), &vec![1.5, 3.0]);
assert_eq!(matrix2.col_indices(), &vec![0, 1]);
assert_eq!(matrix2.row_indices(), &vec![0, 1, 2]);
assert_eq!(matrix2.shape(), (2, 2));

// Example 3: With zero-valued entries after summation
let triplets3 = vec![(0, 0, 1.0), (0, 0, -1.0), (1, 1, 3.0)];
let matrix3 = CsrMatrix::from_triplets(2, 2, &triplets3).unwrap();
// matrix3 will represent:
// [0.0, 0.0]
// [0.0, 3.0]
assert_eq!(matrix3.values(), &vec![3.0]);
assert_eq!(matrix3.col_indices(), &vec![1]);
assert_eq!(matrix3.row_indices(), &vec![0, 0, 1]); // Note: row_indices[0]=0, row_indices[1]=0 as row 0 has no non-zeros
assert_eq!(matrix3.shape(), (2, 2));

Source §

impl<T> CsrMatrix<T>
where T: Copy + PartialEq + Add<Output = T>,

Source

pub fn from_triplets_with_zero( rows: usize, cols: usize, triplets: &[(usize, usize, T)], zero: T, ) -> Result<Self, SparseMatrixError>

Creates a new CsrMatrix from a list of (row, col, value) triplets, using an explicit zero value.

This method is similar to from_triplets, but instead of using T::zero(), it uses the provided zero value to determine which elements should be considered “zero” (and thus excluded from the sparse structure). This is useful for types that do not implement the Zero trait or when a different “zero” context is needed.