Struct CooMatrix

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

A COO representation of a sparse matrix.

A COO matrix stores entries in coordinate-form, that is triplets (i, j, v), where i and j correspond to row and column indices of the entry, and v to the value of the entry. The format is of limited use for standard matrix operations. Its main purpose is to facilitate easy construction of other, more efficient matrix formats (such as CSR/COO), and the conversion between different formats.

Format

For given dimensions nrows and ncols, the matrix is represented by three same-length arrays row_indices, col_indices and values that constitute the coordinate triplets of the matrix. The indices must be in bounds, but duplicate entries are explicitly allowed. Upon conversion to other formats, the duplicate entries may be summed together. See the documentation for the respective conversion functions.

Examples

use nalgebra_sparse::{coo::CooMatrix, csr::CsrMatrix, csc::CscMatrix};

// Initialize a matrix with all zeros (no explicitly stored entries).
let mut coo = CooMatrix::new(4, 4);
// Or initialize it with a set of triplets
coo = CooMatrix::try_from_triplets(4, 4, vec![1, 2], vec![0, 1], vec![3.0, 4.0]).unwrap();

// Push a few triplets
coo.push(2, 0, 1.0);
coo.push(0, 1, 2.0);

// Convert to other matrix formats
let csr = CsrMatrix::from(&coo);
let csc = CscMatrix::from(&coo);

Implementations

impl<T: Scalar> CooMatrix<T>

pub fn push_matrix<R: Dim, C: Dim, S: RawStorage<T, R, C>>( &mut self, r: usize, c: usize, m: &Matrix<T, R, C, S>, )

Pushes a dense matrix into the sparse one.

This adds the dense matrix m starting at the rth row and cth column to the matrix.

Panics

Panics if any part of the dense matrix is out of bounds of the sparse matrix when inserted at (r, c).

impl<T> CooMatrix<T>

pub fn new(nrows: usize, ncols: usize) -> Self

Construct a zero COO matrix of the given dimensions.

Specifically, the collection of triplets - corresponding to explicitly stored entries - is empty, so that the matrix (implicitly) represented by the COO matrix consists of all zero entries.

pub fn zeros(nrows: usize, ncols: usize) -> Self

Construct a zero COO matrix of the given dimensions.

Specifically, the collection of triplets - corresponding to explicitly stored entries - is empty, so that the matrix (implicitly) represented by the COO matrix consists of all zero entries.

pub fn try_from_triplets( nrows: usize, ncols: usize, row_indices: Vec<usize>, col_indices: Vec<usize>, values: Vec<T>, ) -> Result<Self, SparseFormatError>

Try to construct a COO matrix from the given dimensions and a collection of (i, j, v) triplets.

Returns an error if either row or column indices contain indices out of bounds, or if the data arrays do not all have the same length. Note that the COO format inherently supports duplicate entries.

pub fn try_from_triplets_iter( nrows: usize, ncols: usize, triplets: impl IntoIterator<Item = (usize, usize, T)>, ) -> Result<Self, SparseFormatError>

Try to construct a COO matrix from the given dimensions and a finite iterator of (i, j, v) triplets.

Returns an error if either row or column indices contain indices out of bounds. Note that the COO format inherently supports duplicate entries, but they are not eagerly summed.

Implementation note: Calls try_from_triplets so each value is scanned twice.

pub fn triplet_iter(&self) -> impl Iterator<Item = (usize, usize, &T)>

An iterator over triplets (i, j, v).

pub fn triplet_iter_mut( &mut self, ) -> impl Iterator<Item = (usize, usize, &mut T)>

A mutable iterator over triplets (i, j, v).

pub fn reserve(&mut self, additional: usize)

Reserves capacity for COO matrix by at least additional elements.

This increase the capacities of triplet holding arrays by reserving more space to avoid frequent reallocations in push operations.

Panics

Panics if any of the individual allocation of triplet arrays fails.

Example

let mut coo = CooMatrix::new(4, 4);
// Reserve capacity in advance
coo.reserve(10);
coo.push(1, 0, 3.0);

pub fn push(&mut self, i: usize, j: usize, v: T)

Push a single triplet to the matrix.

This adds the value v to the ith row and jth column in the matrix.

Panics

Panics if i or j is out of bounds.

pub fn clear_triplets(&mut self)

Clear all triplets from the matrix.

pub fn nrows(&self) -> usize

The number of rows in the matrix.

pub fn ncols(&self) -> usize

The number of columns in the matrix.

pub fn nnz(&self) -> usize

The number of explicitly stored entries in the matrix.

This number includes duplicate entries. For example, if the CooMatrix contains duplicate entries, then it may have a different number of non-zeros as reported by nnz() compared to its CSR representation.

pub fn row_indices(&self) -> &[usize]

The row indices of the explicitly stored entries.

pub fn col_indices(&self) -> &[usize]

The column indices of the explicitly stored entries.

pub fn values(&self) -> &[T]

The values of the explicitly stored entries.

pub fn disassemble(self) -> (Vec<usize>, Vec<usize>, Vec<T>)

Disassembles the matrix into individual triplet arrays.

Examples

let row_indices = vec![0, 1];
let col_indices = vec![1, 2];
let values = vec![1.0, 2.0];
let coo = CooMatrix::try_from_triplets(2, 3, row_indices, col_indices, values)
    .unwrap();

let (row_idx, col_idx, val) = coo.disassemble();
assert_eq!(row_idx, vec![0, 1]);
assert_eq!(col_idx, vec![1, 2]);
assert_eq!(val, vec![1.0, 2.0]);

Trait Implementations

impl<T: Clone> Clone for CooMatrix<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for CooMatrix<T>

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

Formats the value using the given formatter.

impl<'a, T> From<&'a CooMatrix<T>> for CscMatrix<T>

where T: Scalar + Zero + ClosedAddAssign,

fn from(matrix: &'a CooMatrix<T>) -> Self

Converts to this type from the input type.

impl<'a, T> From<&'a CooMatrix<T>> for CsrMatrix<T>

where T: Scalar + Zero + ClosedAddAssign,

fn from(matrix: &'a CooMatrix<T>) -> Self

Converts to this type from the input type.

impl<'a, T> From<&'a CooMatrix<T>> for DMatrix<T>

where T: Scalar + Zero + ClosedAddAssign,

fn from(coo: &'a CooMatrix<T>) -> Self

Converts to this type from the input type.

impl<'a, T> From<&'a CscMatrix<T>> for CooMatrix<T>

where T: Scalar + Zero,

fn from(matrix: &'a CscMatrix<T>) -> Self

Converts to this type from the input type.

impl<'a, T> From<&'a CsrMatrix<T>> for CooMatrix<T>

where T: Scalar + Zero + ClosedAddAssign,

fn from(matrix: &'a CsrMatrix<T>) -> Self

Converts to this type from the input type.

impl<'a, T, R, C, S> From<&'a Matrix<T, R, C, S>> for CooMatrix<T>

where T: Scalar + Zero, R: Dim, C: Dim, S: RawStorage<T, R, C>,

fn from(matrix: &'a Matrix<T, R, C, S>) -> Self

Converts to this type from the input type.

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

fn rows(&self) -> usize

fn cols(&self) -> usize

fn access(&self) -> Access<'_, T>

Expose dense or sparse access to the matrix.

impl<T: PartialEq> PartialEq for CooMatrix<T>

fn eq(&self, other: &CooMatrix<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: Clone> SparseAccess<T> for CooMatrix<T>

fn nnz(&self) -> usize

Number of non-zero elements in the matrix.

fn fetch_triplets(&self) -> Vec<(usize, usize, T)>

Retrieve the triplets that identify the coefficients of the sparse matrix.

impl<T: Eq> Eq for CooMatrix<T>

impl<T: MatrixMarketScalar> MatrixMarketExport<T> for CooMatrix<T>

impl<T> StructuralPartialEq for CooMatrix<T>