Struct sparse::dok::DokMat

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

Dictionary Of Keys (DOK) format sparse matrix.

Format

The dictionnary of keys format stores (indices, value) pairs for each non-zero element of the matrix.

Properties

• The dictionnary of keys format is intented for incremental matrix constructions.
• The dictionnary of keys format does not allow duplicates.

Usage

Common usage of the dictionnary of keys format is:

1. Creation
2. Entry insertion/removal
3. (Optional) Querying
4. (Optional) Iterators
5. Conversion

Creation

DokMat provides multiple constructors:

use sparse::DokMat;

// Create an empty DOK matrix
let rows = 2;
let cols = 3;
let a = DokMat::<f64>::new(rows, cols);

// Create an empty DOK matrix with initial capacity
let rows = 2;
let cols = 3;
let capacity = 6;
let b = DokMat::<f64>::with_capacity(rows, cols, capacity);

// Create a DOK matrix with initial entries from entry vector
// Providing shape ...
let rows = 2;
let cols = 2;
let entries = vec![(0, 0, 1.0), (1, 1, 2.0)];
let c = DokMat::with_entries(rows, cols, entries);
// ... or not
let entries = vec![(0, 0, 1.0), (1, 1, 2.0)];
let c: DokMat::<f64> = entries.into_iter().collect();

// Create a DOK matrix with initial capacity and entries from entry vector
let rows = 2;
let cols = 2;
let capacity = 4;
let entries = vec![(0, 0, 1.0), (1, 1, 2.0)];
let d = DokMat::with_capacity_and_entries(rows, cols, capacity, entries);

// Create a DOK matrix with initial entries from triplet vectors
let rows = 2;
let cols = 2;
let rowind = vec![0, 1];
let colind = vec![0, 1];
let values = vec![1.0, 2.0];
let e = DokMat::with_triplets(rows, cols, rowind, colind, values);

// Create a DOK matrix with initial capacity and entries from triplet vectors
let rows = 2;
let cols = 2;
let capacity = 4;
let rowind = vec![0, 1];
let colind = vec![0, 1];
let values = vec![1.0, 2.0];
let f = DokMat::with_capacity_and_triplets(rows, cols, capacity, rowind, colind, values);

// Create an eye DOK matrix
let rows = 2;
let cols = 3;
let g = DokMat::<f64>::eye(rows, cols);

// Create an identity DOK matrix
let dim = 2;
let h = DokMat::<f64>::identity(dim);

Prefer with_capacity* variants to prevent reallocating.

Entry insertion/removal

Matrix entries can be inserted/removed/clear to/from the DOK matrix:

use sparse::DokMat;
let mut matrix = DokMat::with_capacity(3, 3, 9);
// matrix:
// | 0 0 0 |
// | 0 0 0 |
// | 0 0 0 |

// Insert new entries one by one
matrix.insert(0, 0, 1.0);
matrix.insert(0, 1, 2.0);
matrix.insert(1, 0, 3.0);
matrix.insert(1, 1, 4.0);
// matrix:
// | 1 2 0 |
// | 3 4 0 |
// | 0 0 0 |
assert_eq!(matrix.nnz(), 4);

// Get an immutable reference to an entry
let entry = matrix.get_entry(0, 0);
assert_eq!(entry, Some((&0, &0, &1.0)));

// Get a mutable reference to an entry and modify it
// (only the value is mutable)
if let Some((r, c, v)) = matrix.get_entry_mut(0, 0) {
    *v *= -1.0;
}
// matrix:
// |-1 2 0 |
// | 3 4 0 |
// | 0 0 0 |
let entry = matrix.get_entry(0, 0);
assert_eq!(entry, Some((&0, &0, &-1.0)));

// Extend the matrix with new entries
let entries = vec![
    (0, 2, 5.0),
    (1, 2, 6.0),
    (2, 0, 7.0),
    (2, 1, 8.0),
    (2, 2, 9.0),
];
matrix.extend(entries);
// matrix:
// |-1 2 5 |
// | 3 4 6 |
// | 7 8 9 |
assert_eq!(matrix.nnz(), 9);

// Remove a specific entry
let entry = matrix.remove(1, 1);
assert_eq!(entry, Some(4.0));
// matrix:
// |-1 2 5 |
// | 3 0 6 |
// | 7 8 9 |
assert_eq!(matrix.nnz(), 8);

// Clear matrix
matrix.clear();
assert!(matrix.is_empty())

Querying

DokMat provides multiple query operations:

use sparse::DokMat;
let rowind = vec![0, 0, 1, 1];
let colind = vec![0, 1, 0, 1];
let values = vec![1.0, 2.0, 3.0, 4.0];
let mut matrix = DokMat::with_capacity_and_triplets(2, 2, 9, rowind, colind, values);

// Number of rows, cols and shape
assert_eq!(matrix.rows(), 2);
assert_eq!(matrix.cols(), 2);
assert_eq!(matrix.shape(), (2, 2));

// Number of entries
assert!(!matrix.is_empty());
assert_eq!(matrix.nnz(), 4);

// Capacity
assert!(matrix.capacity() >= 9);

// Get an immutable reference to an entry
let entry = matrix.get_entry(0, 0);
assert_eq!(entry, Some((&0, &0, &1.0)));

Iterators

DokMat also provides convenient Iterators/IntoIterator (arbitrary order):

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = DokMat::with_entries(2, 2, entries);

// Iterator over indices
let mut iter = matrix.indices();
let max_row = iter.map(|(&r, &c)| r).max().unwrap_or(0);
assert_eq!(max_row, 1);

// Iterator over values
let mut iter = matrix.values();
let min_val = iter.fold(f64::INFINITY, |a, &b| a.min(b));
assert_eq!(min_val, 1.0);

// Iterator over mutable values
{
    for v in matrix.values_mut() {
        *v += 1.0
    }
}
let mut iter = matrix.values();
let min_val = iter.fold(f64::INFINITY, |a, &b| a.min(b));
assert_eq!(min_val, 2.0);

// Iterator over entries
let mut iter = matrix.entries();
assert_eq!(iter.len(), 4);

// Mutable iterator over entries
let mut iter = matrix.entries_mut();
for (r, c, v) in iter {
    *v *= 2.0;
}

// Turn matrix into iterator
for (r, c, v) in matrix {
    println!("row = {}, col = {}, value = {}", r, c, v);
}

Conversion

DokMat provides fast conversion to more arithmetic operation friendly format.

use sparse::DokMat;
use sparse::CscMat;
use sparse::CsrMat;

// Conversion to compressed sparse column format (CSC)
let dokmat = DokMat::<f64>::identity(2);
let cscmat: CscMat<_> = dokmat.into();

// Conversion to compressed sparse row format (CSR)
let dokmat = DokMat::<f64>::identity(2);
let csrmat: CsrMat<_> = dokmat.into();

Implementations

impl<T> DokMat<T> where
    T: Num, 

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

Creates a dictionnary of keys format sparse matrix with specified shape (rows, cols).

Example

use sparse::DokMat;
// With type annotation ...
let matrix: DokMat<f64> = DokMat::new(2, 2);
assert_eq!(matrix.shape(), (2, 2));
assert!(matrix.is_empty());
assert_eq!(matrix.capacity(), 0);

// ... or with turbofish operator
let matrix = DokMat::<f64>::new(3, 4);
assert_eq!(matrix.shape(), (3, 4));
assert!(matrix.is_empty());
assert_eq!(matrix.capacity(), 0);

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

Creates a dictionnary of keys format sparse matrix with specified shape (rows, cols) and capacity.

Example

use sparse::DokMat;
let matrix = DokMat::<f64>::with_capacity(2, 2, 4);
assert_eq!(matrix.shape(), (2, 2));
assert!(matrix.is_empty());
assert!(matrix.capacity() >= 4);

pub fn with_entries<I>(rows: usize, cols: usize, entries: I) -> Self where
    I: IntoIterator<Item = (usize, usize, T)>, 

Creates a dictionnary of keys format sparse matrix with specified shape (rows, cols) and entries.

Panics

Panics if any entry’s row or column index exceeds number of rows or columns respectively.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = DokMat::with_entries(2, 2, entries);
assert_eq!(matrix.shape(), (2, 2));
assert_eq!(matrix.nnz(), 4);
assert!(matrix.capacity() >= 4);

pub fn with_capacity_and_entries<I>(
    rows: usize,
    cols: usize,
    capacity: usize,
    entries: I
) -> Self where
    I: IntoIterator<Item = (usize, usize, T)>, 

Creates a dictionnary of keys format sparse matrix with specified shape (rows, cols) capacity and entries.

Panics

Panics if any entry’s row or column index exceeds number of rows or columns respectively.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = DokMat::with_capacity_and_entries(3, 3, 9, entries);
assert_eq!(matrix.shape(), (3, 3));
assert_eq!(matrix.nnz(), 4);
assert!(matrix.capacity() >= 9);

pub fn with_triplets<I, V>(
    rows: usize,
    cols: usize,
    rowind: I,
    colind: I,
    values: V
) -> Self where
    I: IntoIterator<Item = usize>,
    V: IntoIterator<Item = T>, 

Creates a dictionnary of keys format sparse matrix with specified shape (rows, cols) and triplets.

Panics

Panics if any row or column index exceeds number of rows or columns respectively.

Example

use sparse::DokMat;
let rowind = vec![0, 0, 1, 1];
let colind = vec![0, 1, 0, 1];
let values = vec![1.0, 2.0, 3.0, 4.0];
let matrix = DokMat::with_triplets(2, 2, rowind, colind, values);
assert_eq!(matrix.shape(), (2, 2));
assert_eq!(matrix.nnz(), 4);
assert!(matrix.capacity() >= 4);

pub fn with_capacity_and_triplets<I, V>(
    rows: usize,
    cols: usize,
    capacity: usize,
    rowind: I,
    colind: I,
    values: V
) -> Self where
    I: IntoIterator<Item = usize>,
    V: IntoIterator<Item = T>, 

Creates a dictionnary of keys format sparse matrix with specified shape (rows, cols), capacity and triplets.

Panics

Panics if any row or column index exceeds number of rows or columns respectively.

Example

use sparse::DokMat;
let rowind = vec![0, 0, 1, 1];
let colind = vec![0, 1, 0, 1];
let values = vec![1.0, 2.0, 3.0, 4.0];
let matrix = DokMat::with_capacity_and_triplets(3, 3, 9, rowind, colind, values);
assert_eq!(matrix.shape(), (3, 3));
assert_eq!(matrix.nnz(), 4);
assert!(matrix.capacity() >= 9);

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

Creates a dictionnary of keys format sparse matrix with specified shape (rows, cols) and ones on the main diagonal.

Example

use sparse::DokMat;
let matrix = DokMat::<f64>::eye(2, 3);
assert_eq!(matrix.shape(), (2, 3));
assert_eq!(matrix.nnz(), 2);
assert_eq!(matrix.get_entry(0, 0), Some((&0, &0, &1.0)));
assert_eq!(matrix.get_entry(1, 1), Some((&1, &1, &1.0)));

pub fn identity(dim: usize) -> Self

Creates a dictionnary of keys format sparse matrix with specified dimension (dim, dim) and ones on the diagonal.

Example

use sparse::DokMat;
let matrix = DokMat::<f64>::identity(2);
assert_eq!(matrix.shape(), (2, 2));
assert_eq!(matrix.nnz(), 2);
assert_eq!(matrix.get_entry(0, 0), Some((&0, &0, &1.0)));
assert_eq!(matrix.get_entry(1, 1), Some((&1, &1, &1.0)));

pub fn rows(&self) -> usize

Returns the number of rows of the matrix.

Example

use sparse::DokMat;
let matrix = DokMat::<f64>::new(1, 2);
assert_eq!(matrix.rows(), 1);

pub fn cols(&self) -> usize

Returns the number of cols of the matrix.

Example

use sparse::DokMat;
let matrix = DokMat::<f64>::new(1, 2);
assert_eq!(matrix.cols(), 2);

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

Returns the shape of the matrix.

Example

use sparse::DokMat;
let matrix = DokMat::<f64>::new(1, 2);
assert_eq!(matrix.shape(), (1, 2));

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

Returns an immutable reference to the value at specified indices.

pub fn get_entry(&self, row: usize, col: usize) -> Option<(&usize, &usize, &T)>

Returns an immutable reference to the entry at specified indices.

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

Returns a mutable reference to the entry at specified indices.

pub fn insert(&mut self, row: usize, col: usize, val: T) -> Option<T>

Inserts an entry in the matrix.

If the matrix already contains an entry at specified indices, the value is updated and Some(old_value) is returned. Otherwise None is returned.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 1, 4.0),
];
let mut matrix = DokMat::with_capacity_and_entries(2, 2, 4, entries);
assert_eq!(matrix.insert(1, 0, 3.0), None);
assert_eq!(matrix.nnz(), 4);
assert_eq!(matrix.get(1, 0), Some(&3.0));
assert_eq!(matrix.insert(1, 0, 5.0), Some(3.0));
assert_eq!(matrix.nnz(), 4);
assert_eq!(matrix.get(1, 0), Some(&5.0));

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

Removes an entry from the matrix.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = DokMat::with_entries(2, 2, entries);
assert_eq!(matrix.remove(1, 0), Some(3.0));
assert_eq!(matrix.nnz(), 3);

pub fn contains(&self, row: usize, col: usize) -> bool

Returns true if the matrix contains an entry at (row, col) indices.

Example

use sparse::DokMat;
let mut matrix: DokMat::<f64> = DokMat::identity(1);
assert!(matrix.contains(0, 0));

pub fn clear(&mut self)

Clears the matrix.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = DokMat::with_entries(2, 2, entries);
matrix.clear();
assert!(matrix.is_empty());

pub fn nnz(&self) -> usize

Returns the number of entries in the matrix.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = DokMat::with_entries(2, 2, entries);
assert_eq!(matrix.nnz(), 4);

pub fn is_empty(&self) -> bool

Returns true if the matrix contains no entry.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = DokMat::with_entries(2, 2, entries);
let empty = DokMat::<f64>::new(2, 2);
assert!(!matrix.is_empty());
assert!(empty.is_empty());

pub fn capacity(&self) -> usize

Returns the capacity of the matrix.

Example

use sparse::DokMat;
let matrix = DokMat::<f64>::with_capacity(1, 1, 42);
assert!(matrix.capacity() >= 42);

pub fn shrink(&mut self)

Shrink the capacity of the matrix.

Example

use sparse::DokMat;
let mut matrix = DokMat::<f64>::with_capacity(1, 1, 42);
assert!(matrix.capacity() >= 42);
matrix.shrink();
assert!(matrix.capacity() <= 42);

pub fn indices(&self) -> Indices<'_, T>

An iterator visiting all indices in arbitrary order. The iterator element type is &'a (usize, usize).

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = DokMat::with_entries(2, 2, entries);
let max_indices = matrix.indices().max_by_key(|(&r, &c)| r + c).unwrap();
assert_eq!(max_indices, (&1, &1));

pub fn values(&self) -> Values<'_, T>

An iterator visiting all values in arbitrary order. The iterator element type is &'a T.

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1),
    (0, 1, 2),
    (1, 0, 3),
    (1, 1, 4),
];
let matrix = DokMat::with_entries(2, 2, entries);
let max_value = matrix.values().max().unwrap();
assert_eq!(max_value, &4);

pub fn values_mut(&mut self) -> ValuesMut<'_, T>

An iterator visiting all values mutably in arbitrary order. The iterator element type is &'a mut T

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = DokMat::with_entries(2, 2, entries);
for v in matrix.values_mut() {
    *v *= 2.0;
}
assert_eq!(matrix.get(0, 0), Some(&2.0));
assert_eq!(matrix.get(0, 1), Some(&4.0));
assert_eq!(matrix.get(1, 0), Some(&6.0));
assert_eq!(matrix.get(1, 1), Some(&8.0));

pub fn entries(&self) -> Entries<'_, T>

An iterator visiting all entries of the matrix. The iterator element type is (&'a usize, &'a usize, &'a T).

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = DokMat::with_entries(2, 2, entries);
for (r, c, v) in matrix.entries() {
    println!("row = {}, col = {}, value = {}", r, c, v);
}

pub fn entries_mut(&mut self) -> EntriesMut<'_, T>

An iterator visiting all mutable entries of the matrix. The iterator element type is (&'a usize, &'a usize, &'a mut T).

Example

use sparse::DokMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = DokMat::with_entries(2, 2, entries);
for (r, c, v) in matrix.entries_mut() {
    *v = (*r as f64) + (*c as f64);
}
assert_eq!(matrix.get(0, 0), Some(&0.0));
assert_eq!(matrix.get(0, 1), Some(&1.0));
assert_eq!(matrix.get(1, 0), Some(&1.0));
assert_eq!(matrix.get(1, 1), Some(&2.0));

Trait Implementations

impl<T: Clone> Clone for DokMat<T>

fn clone(&self) -> DokMat<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 DokMat<T>

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

Formats the value using the given formatter.

impl<T> Default for DokMat<T> where
    T: Num, 

fn default() -> Self

Returns the default DOK matrix (a 1-by-1 empty matrix).

impl<T> Extend<(usize, usize, T)> for DokMat<T> where
    T: Num, 

fn extend<I: IntoIterator<Item = (usize, usize, T)>>(&mut self, iter: I)

Appends specified entries to the DOK matrix.

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

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

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> From<DokMat<T>> for CscMat<T> where
    T: Num, 

fn from(dokmat: DokMat<T>) -> Self

Performs the conversion.

impl<T> From<DokMat<T>> for CsrMat<T> where
    T: Num, 

fn from(dokmat: DokMat<T>) -> Self

Performs the conversion.

impl<T> FromIterator<(usize, usize, T)> for DokMat<T> where
    T: Num, 

fn from_iter<I: IntoIterator<Item = (usize, usize, T)>>(iter: I) -> Self

Creates a DOK matrix with specified entries.

impl<T> IntoIterator for DokMat<T>

type Item = (usize, usize, T)

The type of the elements being iterated over.

type IntoIter = IntoEntries<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.