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

An 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 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 DMatrix<T> where
    T: Scalar + Zero + ClosedAdd, 

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

Performs the conversion.

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

impl<T> StructuralEq for CooMatrix<T>

impl<T> StructuralPartialEq for CooMatrix<T>