Improve doc and add examples

russell_sparse/examples/doc_csr_from_small_coo.rs

@@ -0,0 +1,56 @@
+use russell_sparse::prelude::*;
+use russell_sparse::StrError;
+
+fn main() -> Result<(), StrError> {
+    // allocate a square matrix and store as COO 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, ncol, nnz) = (5, 5, 13);
+    let mut coo = CooMatrix::new(Layout::Full, nrow, ncol, nnz)?;
+    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);
+    let correct_j = &[
+        //                         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_v = &[
+        //                                 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 correct_p = &[0, 2, 5, 8, 9, 12];
+
+    // check
+    assert_eq!(&csr.row_pointers, correct_p);
+    assert_eq!(&csr.col_indices, correct_j);
+    assert_eq!(&csr.values, correct_v);
+    Ok(())
+}

russell_sparse/examples/doc_csr_from_tiny_coo.rs

@@ -0,0 +1,43 @@
+use russell_sparse::prelude::*;
+use russell_sparse::StrError;
+
+fn main() -> Result<(), StrError> {
+    // allocate a square matrix and store as COO matrix
+    // ┌          ┐
+    // │  1  0  2 │
+    // │  0  0  3 │ << the diagonal 0 entry is optional,
+    // │  4  5  6 │    but should be saved for Intel DSS
+    // └          ┘
+    let (nrow, ncol, nnz) = (3, 3, 6);
+    let mut coo = CooMatrix::new(Layout::Full, nrow, ncol, nnz)?;
+    coo.put(0, 0, 1.0)?;
+    coo.put(0, 2, 2.0)?;
+    coo.put(1, 2, 3.0)?;
+    coo.put(2, 0, 4.0)?;
+    coo.put(2, 1, 5.0)?;
+    coo.put(2, 2, 6.0)?;
+
+    // convert to CSR matrix
+    let csr = CsrMatrix::from(&coo);
+    let correct_v = &[
+        //                               p
+        1.0, 2.0, //      i = 0, count = 0, 1
+        3.0, //           i = 1, count = 2
+        4.0, 5.0, 6.0, // i = 2, count = 3, 4, 5
+             //                  count = 6
+    ];
+    let correct_j = &[
+        //                         p
+        0, 2, //    i = 0, count = 0, 1
+        2, //       i = 1, count = 2
+        0, 1, 2, // i = 2, count = 3, 4, 5
+           //              count = 6
+    ];
+    let correct_p = &[0, 2, 3, 6];
+
+    // check
+    assert_eq!(&csr.row_pointers, correct_p);
+    assert_eq!(&csr.col_indices, correct_j);
+    assert_eq!(&csr.values, correct_v);
+    Ok(())
+}

russell_sparse/src/csr_matrix.rs

@@ -24,6 +24,55 @@ pub struct CsrMatrix {
 }
 
 impl CsrMatrix {
+    /// Creates a new CsrMatrix from a CooMatrix
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use russell_sparse::prelude::*;
+    /// use russell_sparse::StrError;
+    ///
+    /// fn main() -> Result<(), StrError> {
+    ///     // allocate a square matrix and store as COO matrix
+    ///     // ┌          ┐
+    ///     // │  1  0  2 │
+    ///     // │  0  0  3 │ << the diagonal 0 entry is optional,
+    ///     // │  4  5  6 │    but should be saved for Intel DSS
+    ///     // └          ┘
+    ///     let (nrow, ncol, nnz) = (3, 3, 6);
+    ///     let mut coo = CooMatrix::new(Layout::Full, nrow, ncol, nnz)?;
+    ///     coo.put(0, 0, 1.0)?;
+    ///     coo.put(0, 2, 2.0)?;
+    ///     coo.put(1, 2, 3.0)?;
+    ///     coo.put(2, 0, 4.0)?;
+    ///     coo.put(2, 1, 5.0)?;
+    ///     coo.put(2, 2, 6.0)?;
+    ///
+    ///     // convert to CSR matrix
+    ///     let csr = CsrMatrix::from(&coo);
+    ///     let correct_v = &[
+    ///         //                               p
+    ///         1.0, 2.0, //      i = 0, count = 0, 1
+    ///         3.0, //           i = 1, count = 2
+    ///         4.0, 5.0, 6.0, // i = 2, count = 3, 4, 5
+    ///              //                  count = 6
+    ///     ];
+    ///     let correct_j = &[
+    ///         //                         p
+    ///         0, 2, //    i = 0, count = 0, 1
+    ///         2, //       i = 1, count = 2
+    ///         0, 1, 2, // i = 2, count = 3, 4, 5
+    ///            //              count = 6
+    ///     ];
+    ///     let correct_p = &[0, 2, 3, 6];
+    ///
+    ///     // check
+    ///     assert_eq!(&csr.row_pointers, correct_p);
+    ///     assert_eq!(&csr.col_indices, correct_j);
+    ///     assert_eq!(&csr.values, correct_v);
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn from(coo: &CooMatrix) -> Self {
         // Based on the SciPy code from here:
         //

russell_sparse/src/prelude.rs

@@ -5,6 +5,7 @@
 
 pub use crate::config_solver::ConfigSolver;
 pub use crate::coo_matrix::CooMatrix;
+pub use crate::csr_matrix::CsrMatrix;
 pub use crate::enums::*;
 pub use crate::read_matrix_market;
 pub use crate::solver::Solver;

russell_sparse/zscripts/run-examples.bash

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+for example in examples/*.rs; do
+    filename="$(basename "$example")"
+    filekey="${filename%%.*}"
+    cargo run --example $filekey
+done

zscripts/run-examples.bash

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+for example in examples/*.rs; do
+    filename="$(basename "$example")"
+    filekey="${filename%%.*}"
+    cargo run --example $filekey
+done