Struct nalgebra_sparse::coo::CooMatrix

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

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> 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 triplet_iter(&self) -> impl Iterator<Item = (usize, usize, &T)>

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

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 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.

pub 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<T: Eq> Eq for CooMatrix<T>

impl<'a, T> From<&'a CooMatrix<T>> for CsrMatrix<T> where
    T: Scalar + Zero + ClosedAdd, 

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

Performs the conversion.

impl<'a, T> From<&'a CooMatrix<T>> for CscMatrix<T> where
    T: Scalar + Zero + ClosedAdd, 

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

Performs the conversion.

impl<'a, T> From<&'a CscMatrix<T>> for CooMatrix<T> where
    T: Scalar + Zero, 

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

Performs the conversion.

impl<'a, T> From<&'a CsrMatrix<T>> for CooMatrix<T> where
    T: Scalar + Zero + ClosedAdd, 

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

Performs the conversion.

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: Storage<T, R, C>, 

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

Performs the conversion.

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<CooMatrix<T>> for CooMatrix<T>

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &CooMatrix<T>) -> bool

This method tests for !=.

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> StructuralEq for CooMatrix<T>

impl<T> StructuralPartialEq for CooMatrix<T>