Struct SparsityPattern

pub struct SparsityPattern { /* private fields */ }

A representation of the sparsity pattern of a CSR or CSC matrix.

CSR and CSC matrices store matrices in a very similar fashion. In fact, in a certain sense, they are transposed. More precisely, when reinterpreting the three data arrays of a CSR matrix as a CSC matrix, we obtain the CSC representation of its transpose.

SparsityPattern is an abstraction built on this observation. Whereas CSR matrices store a matrix row-by-row, and a CSC matrix stores a matrix column-by-column, a SparsityPattern represents only the index data structure of a matrix lane-by-lane. Here, a lane is a generalization of rows and columns. We further define major lanes and minor lanes. The sparsity pattern of a CSR matrix is then obtained by interpreting major/minor as row/column. Conversely, we obtain the sparsity pattern of a CSC matrix by interpreting major/minor as column/row.

This allows us to use a common abstraction to talk about sparsity patterns of CSR and CSC matrices. This is convenient, because at the abstract level, the invariants of the formats are the same. Hence we may encode the invariants of the index data structure separately from the scalar values of the matrix. This is especially useful in applications where the sparsity pattern is built ahead of the matrix values, or the same sparsity pattern is re-used between different matrices. Finally, we can use SparsityPattern to encode adjacency information in graphs.

Format

The format is exactly the same as for the index data structures of CSR and CSC matrices. This means that the sparsity pattern of an m x n sparse matrix with nnz non-zeros, where in this case m x n does not mean rows x columns, but rather majors x minors, is represented by the following two arrays:

• major_offsets, an array of integers with length m + 1.
• minor_indices, an array of integers with length nnz.

The invariants and relationship between major_offsets and minor_indices remain the same as for row_offsets and col_indices in the CSR format specification.

Implementations

impl SparsityPattern

pub fn zeros(major_dim: usize, minor_dim: usize) -> Self

Create a sparsity pattern of the given dimensions without explicitly stored entries.

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

The offsets for the major dimension.

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

The indices for the minor dimension.

pub fn major_dim(&self) -> usize

The number of major lanes in the pattern.

pub fn minor_dim(&self) -> usize

The number of minor lanes in the pattern.

pub fn nnz(&self) -> usize

The number of “non-zeros”, i.e. explicitly stored entries in the pattern.

pub fn lane(&self, major_index: usize) -> &[usize]

Get the lane at the given index.

Panics

Panics if major_index is out of bounds.

pub fn get_lane(&self, major_index: usize) -> Option<&[usize]>

Get the lane at the given index, or None if out of bounds.

pub fn try_from_offsets_and_indices( major_dim: usize, minor_dim: usize, major_offsets: Vec<usize>, minor_indices: Vec<usize>, ) -> Result<Self, SparsityPatternFormatError>

Try to construct a sparsity pattern from the given dimensions, major offsets and minor indices.

Returns an error if the data does not conform to the requirements.

pub unsafe fn from_offset_and_indices_unchecked( major_dim: usize, minor_dim: usize, major_offsets: Vec<usize>, minor_indices: Vec<usize>, ) -> Self

Try to construct a sparsity pattern from the given dimensions, major offsets and minor indices.

Panics

Panics if the number of major offsets is not exactly one greater than the major dimension or if major offsets do not start with 0 and end with the number of minor indices.

Safety

Assumes that the major offsets and indices adhere to the requirements of being a valid sparsity pattern. Specifically, that major offsets is monotonically increasing, and major_offsets[i]..major_offsets[i+1] refers to a major lane in the sparsity pattern, and minor_indices[major_offsets[i]..major_offsets[i+1]] is monotonically increasing.

pub fn entries(&self) -> SparsityPatternIter<'_>

An iterator over the explicitly stored “non-zero” entries (i, j).

The iteration happens in a lane-major fashion, meaning that the lane index i increases monotonically, and the minor index j increases monotonically within each lane i.

Examples

let offsets = vec![0, 2, 3, 4];
let minor_indices = vec![0, 2, 1, 0];
let pattern = SparsityPattern::try_from_offsets_and_indices(3, 4, offsets, minor_indices)
    .unwrap();

let entries: Vec<_> = pattern.entries().collect();
assert_eq!(entries, vec![(0, 0), (0, 2), (1, 1), (2, 0)]);

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

Returns the raw offset and index data for the sparsity pattern.

Examples

let offsets = vec![0, 2, 3, 4];
let minor_indices = vec![0, 2, 1, 0];
let pattern = SparsityPattern::try_from_offsets_and_indices(
        3,
        4,
        offsets.clone(),
        minor_indices.clone())
    .unwrap();
let (offsets2, minor_indices2) = pattern.disassemble();
assert_eq!(offsets2, offsets);
assert_eq!(minor_indices2, minor_indices);

pub fn transpose(&self) -> Self

Computes the transpose of the sparsity pattern.

This is analogous to matrix transposition, i.e. an entry (i, j) becomes (j, i) in the new pattern.

Trait Implementations

impl Clone for SparsityPattern

fn clone(&self) -> SparsityPattern

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SparsityPattern

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

Formats the value using the given formatter.

impl Default for SparsityPattern

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for SparsityPattern

fn eq(&self, other: &SparsityPattern) -> 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 Eq for SparsityPattern

impl StructuralPartialEq for SparsityPattern