Struct russell_sparse::NumSparseMatrix

pub struct NumSparseMatrix<T>
where
    T: AddAssign + MulAssign + Num + NumCast + Copy + DeserializeOwned + Serialize,
{ /* private fields */ }

Unifies the sparse matrix representations by wrapping COO, CSC, and CSR structures

This structure is a wrapper around COO, CSC, or CSR matrices. For instance:

pub struct NumSparseMatrix<T> {
    coo: Option<NumCooMatrix<T>>,
    csc: Option<NumCscMatrix<T>>,
    csr: Option<NumCsrMatrix<T>>,
}

Notes

1. At least one of NumCooMatrix, NumCscMatrix, or NumCsrMatrix will be Some
2. (COO and CSC) or (COO and CSR) pairs may be Some at the same time
3. When getting data/information from the sparse matrix, the default priority is CSC -> CSR -> COO
4. If needed, the CSC or CSR are automatically computed from COO

Implementations

impl<T> NumSparseMatrix<T>

where T: AddAssign + MulAssign + Num + NumCast + Copy + DeserializeOwned + Serialize,

pub fn new_coo( nrow: usize, ncol: usize, max_nnz: usize, symmetric: Sym ) -> Result<Self, StrError>

Allocates a new sparse matrix as COO to be later updated with put and reset methods

Note: This is the most convenient structure for recurrent updates of the sparse matrix data; e.g. in finite element simulation codes. See the NumCooMatrix::put and NumCooMatrix::reset functions for more details.

Input

• nrow – (≥ 1) Is the number of rows of the sparse matrix (must be fit i32)
• ncol – (≥ 1) Is the number of columns of the sparse matrix (must be fit i32)
• max_nnz – (≥ 1) Maximum number of entries ≥ nnz (number of non-zeros), including entries with repeated indices. (must be fit i32)
• symmetric – indicates whether the matrix is symmetric or not. If symmetric, indicates the representation too.

pub fn new_csc( nrow: usize, ncol: usize, col_pointers: Vec<i32>, row_indices: Vec<i32>, values: Vec<T>, symmetric: Sym ) -> Result<Self, StrError>

Allocates a new sparse matrix as CSC from the underlying arrays

Note: The column pointers and row indices must be sorted in ascending order.

Input

• nrow – (≥ 1) number of rows
• ncol – (≥ 1) number of columns
• col_pointers – (len = ncol + 1) columns pointers with the last entry corresponding to the number of non-zero values (sorted)
• row_indices – (len = nnz) row indices (sorted)
• values – the non-zero components of the matrix
• symmetric – indicates whether the matrix is symmetric or not. If symmetric, indicates the representation too.

The following conditions must be satisfied (nnz is the number of non-zeros and nnz_dup is the number of non-zeros with possible duplicates):

nrow ≥ 1
ncol ≥ 1
col_pointers.len() = ncol + 1
row_indices.len() = nnz_dup
values.len() = nnz_dup
nnz = col_pointers[ncol] ≥ 1
nnz_dup ≥ nnz

pub fn new_csr( nrow: usize, ncol: usize, row_pointers: Vec<i32>, col_indices: Vec<i32>, values: Vec<T>, symmetric: Sym ) -> Result<Self, StrError>

Allocates a new sparse matrix as CSR from the underlying arrays

Note: The row pointers and column indices must be sorted in ascending order.

Input

• nrow – (≥ 1) number of rows
• ncol – (≥ 1) number of columns
• row_pointers – (len = nrow + 1) row pointers with the last entry corresponding to the number of non-zero values (sorted)
• col_indices – (len = nnz) column indices (sorted)
• values – the non-zero components of the matrix
• symmetric – indicates whether the matrix is symmetric or not. If symmetric, indicates the representation too.

The following conditions must be satisfied (nnz is the number of non-zeros and nnz_dup is the number of non-zeros with possible duplicates):

nrow ≥ 1
ncol ≥ 1
row_pointers.len() = nrow + 1
col_indices.len() = nnz_dup
values.len() = nnz_dup
nnz = row_pointers[nrow] ≥ 1
nnz_dup ≥ nnz

pub fn from_coo(coo: NumCooMatrix<T>) -> Self

Creates a new sparse matrix from COO (move occurs)

pub fn from_csc(csc: NumCscMatrix<T>) -> Self

Creates a new sparse matrix from CSC (move occurs)

pub fn from_csr(csr: NumCsrMatrix<T>) -> Self

Creates a new sparse matrix from CSR (move occurs)

pub fn get_info(&self) -> (usize, usize, usize, Sym)

Returns information about the dimensions and symmetry type

Returns (nrow, ncol, nnz, sym)

Priority: CSC -> CSR -> COO

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

Get an access to the values

Priority: CSC -> CSR -> COO

pub fn mat_vec_mul( &self, v: &mut NumVector<T>, alpha: T, u: &NumVector<T> ) -> Result<(), StrError>

Performs the matrix-vector multiplication

 v  :=  α ⋅  a   ⋅  u
(m)        (m,n)   (n)

Input

• u – Vector with dimension equal to the number of columns of the matrix

Output

• v – Vector with dimension equal to the number of rows of the matrix

Priority: CSC -> CSR -> COO

pub fn as_dense(&self) -> NumMatrix<T>

Converts the sparse matrix to dense format

Priority: CSC -> CSR -> COO

pub fn to_dense(&self, a: &mut NumMatrix<T>) -> Result<(), StrError>

Converts the sparse matrix to dense format

Priority: CSC -> CSR -> COO

pub fn put(&mut self, i: usize, j: usize, aij: T) -> Result<(), StrError>

Puts a new entry and updates pos (may be duplicate)

Input

• i – row index (indices start at zero; zero-based)
• j – column index (indices start at zero; zero-based)
• aij – the value A(i,j)

pub fn reset(&mut self) -> Result<(), StrError>

Resets the position of the current non-zero value

This function allows using put all over again.

pub fn get_coo(&self) -> Result<&NumCooMatrix<T>, StrError>

Returns a read-only access to the COO matrix, if available

pub fn get_coo_mut(&mut self) -> Result<&mut NumCooMatrix<T>, StrError>

Returns a read-write access to the COO matrix, if available

pub fn assign( &mut self, alpha: T, other: &NumSparseMatrix<T> ) -> Result<(), StrError>

Assigns this matrix to the values of another matrix (scaled)

Performs:

this = α · other

Warning: make sure to allocate max_nnz ≥ nnz(other).

pub fn augment( &mut self, alpha: T, other: &NumSparseMatrix<T> ) -> Result<(), StrError>

Augments this matrix with the entries of another matrix (scaled)

Effectively, performs:

this += α · other

Warning: make sure to allocate max_nnz ≥ nnz(this) + nnz(other).

pub fn get_csc(&self) -> Result<&NumCscMatrix<T>, StrError>

Returns a read-only access to the CSC matrix, if available

pub fn get_csc_mut(&mut self) -> Result<&mut NumCscMatrix<T>, StrError>

Returns a read-write access to the CSC matrix, if available

pub fn get_csc_or_from_coo(&mut self) -> Result<&NumCscMatrix<T>, StrError>

Returns the CSC or creates a CSC from COO or updates the CSC from COO

This function is convenient to update the COO recurrently and later automatically get the converted CSC matrix.

Priority: COO -> CSC

pub fn get_csr(&self) -> Result<&NumCsrMatrix<T>, StrError>

Returns a read-only access to the CSR matrix, if available

pub fn get_csr_mut(&mut self) -> Result<&mut NumCsrMatrix<T>, StrError>

Returns a read-write access to the CSR matrix, if available

pub fn get_csr_or_from_coo(&mut self) -> Result<&NumCsrMatrix<T>, StrError>

Returns the CSR or creates a CSR from COO or updates the CSR from COO

This function is convenient to update the COO recurrently and later automatically get the converted CSR matrix.

Priority: COO -> CSR

Trait Implementations

impl<T> Clone for NumSparseMatrix<T>

where T: AddAssign + MulAssign + Num + NumCast + Copy + DeserializeOwned + Serialize + Clone,

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for NumSparseMatrix<T>

where T: AddAssign + MulAssign + Num + NumCast + Copy + DeserializeOwned + Serialize + Debug,

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

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for NumSparseMatrix<T>

where T: AddAssign + MulAssign + Num + NumCast + Copy + DeserializeOwned + Serialize, NumCooMatrix<T>: Deserialize<'de>, NumCscMatrix<T>: Deserialize<'de>, NumCsrMatrix<T>: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Serialize for NumSparseMatrix<T>

where T: AddAssign + MulAssign + Num + NumCast + Copy + DeserializeOwned + Serialize + Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.