Struct NumCsrMatrix 

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

Holds the arrays needed for a CSR (compressed sparse row) matrix

Examples

The sparse matrix is (dots indicate zero values);

 1  -1   .  -3   .
-2   5   .   .   .
 .   .   4   6   4
-4   .   2   7   .
 .   8   .   .  -5

The values in compressed row order are (note the row indices i and pointers p):

                                  p
 1.0, -1.0, -3.0,  i = 0, count = 0,  1,  2,
-2.0,  5.0,        i = 1, count = 3,  4,
 4.0,  6.0,  4.0,  i = 2, count = 5,  6,  7,
-4.0,  2.0,  7.0,  i = 3, count = 8,  9,  10,
 8.0, -5.0,        i = 4, count= 11, 12,
                                 13

The column indices are:

0, 1, 3,
0, 1,
2, 3, 4,
0, 2, 3,
1, 4,

And the row pointers are (see the column indicated by p above):

0, 3, 5, 8, 11, 13

Note: The number of non-zero values is nnz = row_pointers[nrow]

Implementations

impl<T> NumCsrMatrix<T>

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

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

Creates a new CSR matrix from (sorted) data 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

Examples

use russell_sparse::prelude::*;
use russell_sparse::StrError;

fn main() -> Result<(), StrError> {
    // allocate a square matrix and store as CSR matrix
    //  2  3  .  .  .
    //  3  .  4  .  6
    //  . -1 -3  2  .
    //  .  .  1  .  .
    //  .  4  2  .  1
    let nrow = 5;
    let ncol = 5;
    let row_pointers = vec![0, 2, 5, 8, 9, 12];
    let col_indices = vec![
        //                         p
        0, 1, //    i = 0, count = 0, 1
        0, 2, 4, // i = 1, count = 2, 3, 4
        1, 2, 3, // i = 2, count = 5, 6, 7
        2, //       i = 3, count = 8
        1, 2, 4, // i = 4, count = 9, 10, 11
           //              count = 12
    ];
    let values = vec![
        //                                 p
        2.0, 3.0, //        i = 0, count = 0, 1
        3.0, 4.0, 6.0, //   i = 1, count = 2, 3, 4
        -1.0, -3.0, 2.0, // i = 2, count = 5, 6, 7
        1.0, //             i = 3, count = 8
        4.0, 2.0, 1.0, //   i = 4, count = 9, 10, 11
             //                    count = 12
    ];
    let csr = CsrMatrix::new(nrow, ncol, row_pointers, col_indices, values, Sym::No)?;

    // covert to dense
    let a = csr.as_dense();
    let correct = "┌                ┐\n\
                   │  2  3  0  0  0 │\n\
                   │  3  0  4  0  6 │\n\
                   │  0 -1 -3  2  0 │\n\
                   │  0  0  1  0  0 │\n\
                   │  0  4  2  0  1 │\n\
                   └                ┘";
    assert_eq!(format!("{}", a), correct);
    Ok(())
}

pub fn from_coo(coo: &NumCooMatrix<T>) -> Result<Self, StrError>

Creates a new CSR matrix from a COO matrix

Note: The final nnz may be smaller than the initial nnz because duplicates may have been summed up. The final nnz is available as nnz = row_pointers[nrow].

Examples

use russell_sparse::prelude::*;
use russell_sparse::StrError;

fn main() -> Result<(), StrError> {
    // allocate a square matrix and store as COO matrix
    //  2  3  .  .  .
    //  3  .  4  .  6
    //  . -1 -3  2  .
    //  .  .  1  .  .
    //  .  4  2  .  1
    let (nrow, ncol, nnz) = (5, 5, 13);
    let mut coo = CooMatrix::new(nrow, ncol, nnz, Sym::No)?;
    coo.put(0, 0, 1.0)?; // << (0, 0, a00/2) duplicate
    coo.put(0, 0, 1.0)?; // << (0, 0, a00/2) duplicate
    coo.put(1, 0, 3.0)?;
    coo.put(0, 1, 3.0)?;
    coo.put(2, 1, -1.0)?;
    coo.put(4, 1, 4.0)?;
    coo.put(1, 2, 4.0)?;
    coo.put(2, 2, -3.0)?;
    coo.put(3, 2, 1.0)?;
    coo.put(4, 2, 2.0)?;
    coo.put(2, 3, 2.0)?;
    coo.put(1, 4, 6.0)?;
    coo.put(4, 4, 1.0)?;

    // convert to CSR matrix
    let csr = CsrMatrix::from_coo(&coo)?;
    let correct_pp = &[0, 2, 5, 8, 9, 12];
    let correct_jj = &[
        //                         p
        0, 1, //    i = 0, count = 0, 1
        0, 2, 4, // i = 1, count = 2, 3, 4
        1, 2, 3, // i = 2, count = 5, 6, 7
        2, //       i = 3, count = 8
        1, 2, 4, // i = 4, count = 9, 10, 11
           //              count = 12
    ];
    let correct_vv = &[
        //                                 p
        2.0, 3.0, //        i = 0, count = 0, 1
        3.0, 4.0, 6.0, //   i = 1, count = 2, 3, 4
        -1.0, -3.0, 2.0, // i = 2, count = 5, 6, 7
        1.0, //             i = 3, count = 8
        4.0, 2.0, 1.0, //   i = 4, count = 9, 10, 11
             //                    count = 12
    ];

    // check
    let pp = csr.get_row_pointers();
    let jj = csr.get_col_indices();
    let vv = csr.get_values();
    let final_nnz = pp[nrow] as usize;
    assert_eq!(final_nnz, 12);
    assert_eq!(pp, correct_pp);
    assert_eq!(&jj[0..final_nnz], correct_jj);
    assert_eq!(&vv[0..final_nnz], correct_vv);
    Ok(())
}

pub fn update_from_coo(&mut self, coo: &NumCooMatrix<T>) -> Result<(), StrError>

Updates this CSR matrix from a COO matrix with a compatible structure

Note: The COO matrix must match the symmetric type, nrow, and ncol values of the CSR matrix. Also, the nnz (may include duplicates) of the COO matrix must match col_indices.len() = values.len().

Note: The final nnz may be smaller than the initial nnz because duplicates may have been summed up. The final nnz is available as nnz = row_pointers[nrow].

pub fn from_csc(csc: &NumCscMatrix<T>) -> Result<Self, StrError>

Creates a new CSR matrix from a CSC matrix

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

Converts this CSR matrix to a dense matrix

Examples

use russell_sparse::prelude::*;
use russell_sparse::StrError;

fn main() -> Result<(), StrError> {
    // allocate a square matrix and store as CSR matrix
    // ┌                ┐
    // │  2  3  0  0  0 │
    // │  3  0  4  0  6 │
    // │  0 -1 -3  2  0 │
    // │  0  0  1  0  0 │
    // │  0  4  2  0  1 │
    // └                ┘
    let nrow = 5;
    let ncol = 5;
    let row_pointers = vec![0, 2, 5, 8, 9, 12];
    let col_indices = vec![
        //                         p
        0, 1, //    i = 0, count = 0, 1
        0, 2, 4, // i = 1, count = 2, 3, 4
        1, 2, 3, // i = 2, count = 5, 6, 7
        2, //       i = 3, count = 8
        1, 2, 4, // i = 4, count = 9, 10, 11
           //              count = 12
    ];
    let values = vec![
        //                                 p
        2.0, 3.0, //        i = 0, count = 0, 1
        3.0, 4.0, 6.0, //   i = 1, count = 2, 3, 4
        -1.0, -3.0, 2.0, // i = 2, count = 5, 6, 7
        1.0, //             i = 3, count = 8
        4.0, 2.0, 1.0, //   i = 4, count = 9, 10, 11
             //                    count = 12
    ];
    let csr = CsrMatrix::new(nrow, ncol, row_pointers, col_indices, values, Sym::No)?;

    // covert to dense
    let a = csr.as_dense();
    let correct = "┌                ┐\n\
                   │  2  3  0  0  0 │\n\
                   │  3  0  4  0  6 │\n\
                   │  0 -1 -3  2  0 │\n\
                   │  0  0  1  0  0 │\n\
                   │  0  4  2  0  1 │\n\
                   └                ┘";
    assert_eq!(format!("{}", a), correct);
    Ok(())
}

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

Converts this CSR matrix to a dense matrix

Input

• a – where to store the dense matrix; it must be (nrow, ncol)

Examples

use russell_sparse::prelude::*;
use russell_sparse::StrError;

fn main() -> Result<(), StrError> {
    // allocate a square matrix and store as CSR matrix
    // ┌                ┐
    // │  2  3  0  0  0 │
    // │  3  0  4  0  6 │
    // │  0 -1 -3  2  0 │
    // │  0  0  1  0  0 │
    // │  0  4  2  0  1 │
    // └                ┘
    let nrow = 5;
    let ncol = 5;
    let row_pointers = vec![0, 2, 5, 8, 9, 12];
    let col_indices = vec![
        //                         p
        0, 1, //    i = 0, count = 0, 1
        0, 2, 4, // i = 1, count = 2, 3, 4
        1, 2, 3, // i = 2, count = 5, 6, 7
        2, //       i = 3, count = 8
        1, 2, 4, // i = 4, count = 9, 10, 11
           //              count = 12
    ];
    let values = vec![
        //                                 p
        2.0, 3.0, //        i = 0, count = 0, 1
        3.0, 4.0, 6.0, //   i = 1, count = 2, 3, 4
        -1.0, -3.0, 2.0, // i = 2, count = 5, 6, 7
        1.0, //             i = 3, count = 8
        4.0, 2.0, 1.0, //   i = 4, count = 9, 10, 11
             //                    count = 12
    ];
    let csr = CsrMatrix::new(nrow, ncol, row_pointers, col_indices, values, Sym::No)?;

    // covert to dense
    let a = csr.as_dense();
    let correct = "┌                ┐\n\
                   │  2  3  0  0  0 │\n\
                   │  3  0  4  0  6 │\n\
                   │  0 -1 -3  2  0 │\n\
                   │  0  0  1  0  0 │\n\
                   │  0  4  2  0  1 │\n\
                   └                ┘";
    assert_eq!(format!("{}", a), correct);
    Ok(())
}

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

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

Returns information about the dimensions and symmetric type

Returns (nrow, ncol, nnz, sym)

Examples

use russell_sparse::prelude::*;
use russell_sparse::StrError;

fn main() -> Result<(), StrError> {
    // ┌       ┐
    // │ 10 20 │
    // └       ┘
    let row_pointers = vec![0, 2];
    let col_indices = vec![0, 1];
    let values = vec![10.0, 20.0];
    let csr = CsrMatrix::new(1, 2,
        row_pointers, col_indices, values, Sym::No)?;
    let (nrow, ncol, nnz, sym) = csr.get_info();
    assert_eq!(nrow, 1);
    assert_eq!(ncol, 2);
    assert_eq!(nnz, 2);
    assert_eq!(sym, Sym::No);
    let a = csr.as_dense();
    let correct = "┌       ┐\n\
                   │ 10 20 │\n\
                   └       ┘";
    assert_eq!(format!("{}", a), correct);
    Ok(())
}

pub fn get_row_pointers(&self) -> &[i32]

Get an access to the row pointers

row_pointers.len() = nrow + 1

pub fn get_col_indices(&self) -> &[i32]

Get an access to the column indices

nnz = row_pointers[nrow]
col_indices.len() == nnz

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

Get an access to the values

nnz = row_pointers[nrow]
values.len() == nnz

pub fn get_values_mut(&mut self) -> &mut [T]

Get a mutable access to the values

nnz = row_pointers[nrow]
values.len() == nnz

Note: the values may be modified externally, but not the pointers or indices.

Trait Implementations

impl<T> Clone for NumCsrMatrix<T>

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

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for NumCsrMatrix<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 NumCsrMatrix<T>

where T: AddAssign + MulAssign + Num + NumCast + Copy + DeserializeOwned + Serialize + Default, Vec<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 NumCsrMatrix<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.