1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208
//! An implementation of the COO sparse matrix format. use crate::SparseFormatError; /// A COO representation of a sparse matrix. /// /// A COO matrix stores entries in coordinate-form, that is triplets `(i, j, v)`, where `i` and `j` /// correspond to row and column indices of the entry, and `v` to the value of the entry. /// The format is of limited use for standard matrix operations. Its main purpose is to facilitate /// easy construction of other, more efficient matrix formats (such as CSR/COO), and the /// conversion between different formats. /// /// # Format /// /// For given dimensions `nrows` and `ncols`, the matrix is represented by three same-length /// arrays `row_indices`, `col_indices` and `values` that constitute the coordinate triplets /// of the matrix. The indices must be in bounds, but *duplicate entries are explicitly allowed*. /// Upon conversion to other formats, the duplicate entries may be summed together. See the /// documentation for the respective conversion functions. /// /// # Examples /// /// ```rust /// use nalgebra_sparse::{coo::CooMatrix, csr::CsrMatrix, csc::CscMatrix}; /// /// // Initialize a matrix with all zeros (no explicitly stored entries). /// let mut coo = CooMatrix::new(4, 4); /// // Or initialize it with a set of triplets /// coo = CooMatrix::try_from_triplets(4, 4, vec![1, 2], vec![0, 1], vec![3.0, 4.0]).unwrap(); /// /// // Push a few triplets /// coo.push(2, 0, 1.0); /// coo.push(0, 1, 2.0); /// /// // Convert to other matrix formats /// let csr = CsrMatrix::from(&coo); /// let csc = CscMatrix::from(&coo); /// ``` #[derive(Debug, Clone, PartialEq, Eq)] pub struct CooMatrix<T> { nrows: usize, ncols: usize, row_indices: Vec<usize>, col_indices: Vec<usize>, values: Vec<T>, } impl<T> CooMatrix<T> { /// Construct a zero COO matrix of the given dimensions. /// /// Specifically, the collection of triplets - corresponding to explicitly stored entries - /// is empty, so that the matrix (implicitly) represented by the COO matrix consists of all /// zero entries. pub fn new(nrows: usize, ncols: usize) -> Self { Self { nrows, ncols, row_indices: Vec::new(), col_indices: Vec::new(), values: Vec::new(), } } /// Construct a zero COO matrix of the given dimensions. /// /// Specifically, the collection of triplets - corresponding to explicitly stored entries - /// is empty, so that the matrix (implicitly) represented by the COO matrix consists of all /// zero entries. pub fn zeros(nrows: usize, ncols: usize) -> Self { Self::new(nrows, ncols) } /// Try to construct a COO matrix from the given dimensions and a collection of /// (i, j, v) triplets. /// /// Returns an error if either row or column indices contain indices out of bounds, /// or if the data arrays do not all have the same length. Note that the COO format /// inherently supports duplicate entries. pub fn try_from_triplets( nrows: usize, ncols: usize, row_indices: Vec<usize>, col_indices: Vec<usize>, values: Vec<T>, ) -> Result<Self, SparseFormatError> { use crate::SparseFormatErrorKind::*; if row_indices.len() != col_indices.len() { return Err(SparseFormatError::from_kind_and_msg( InvalidStructure, "Number of row and col indices must be the same.", )); } else if col_indices.len() != values.len() { return Err(SparseFormatError::from_kind_and_msg( InvalidStructure, "Number of col indices and values must be the same.", )); } let row_indices_in_bounds = row_indices.iter().all(|i| *i < nrows); let col_indices_in_bounds = col_indices.iter().all(|j| *j < ncols); if !row_indices_in_bounds { Err(SparseFormatError::from_kind_and_msg( IndexOutOfBounds, "Row index out of bounds.", )) } else if !col_indices_in_bounds { Err(SparseFormatError::from_kind_and_msg( IndexOutOfBounds, "Col index out of bounds.", )) } else { Ok(Self { nrows, ncols, row_indices, col_indices, values, }) } } /// An iterator over triplets (i, j, v). // TODO: Consider giving the iterator a concrete type instead of impl trait...? pub fn triplet_iter(&self) -> impl Iterator<Item = (usize, usize, &T)> { self.row_indices .iter() .zip(&self.col_indices) .zip(&self.values) .map(|((i, j), v)| (*i, *j, v)) } /// Push a single triplet to the matrix. /// /// This adds the value `v` to the `i`th row and `j`th column in the matrix. /// /// Panics /// ------ /// /// Panics if `i` or `j` is out of bounds. #[inline] pub fn push(&mut self, i: usize, j: usize, v: T) { assert!(i < self.nrows); assert!(j < self.ncols); self.row_indices.push(i); self.col_indices.push(j); self.values.push(v); } /// The number of rows in the matrix. #[inline] pub fn nrows(&self) -> usize { self.nrows } /// The number of columns in the matrix. #[inline] pub fn ncols(&self) -> usize { self.ncols } /// The number of explicitly stored entries in the matrix. /// /// This number *includes* duplicate entries. For example, if the `CooMatrix` contains duplicate /// entries, then it may have a different number of non-zeros as reported by `nnz()` compared /// to its CSR representation. #[inline] pub fn nnz(&self) -> usize { self.values.len() } /// The row indices of the explicitly stored entries. pub fn row_indices(&self) -> &[usize] { &self.row_indices } /// The column indices of the explicitly stored entries. pub fn col_indices(&self) -> &[usize] { &self.col_indices } /// The values of the explicitly stored entries. pub fn values(&self) -> &[T] { &self.values } /// Disassembles the matrix into individual triplet arrays. /// /// Examples /// -------- /// /// ``` /// # use nalgebra_sparse::coo::CooMatrix; /// let row_indices = vec![0, 1]; /// let col_indices = vec![1, 2]; /// let values = vec![1.0, 2.0]; /// let coo = CooMatrix::try_from_triplets(2, 3, row_indices, col_indices, values) /// .unwrap(); /// /// let (row_idx, col_idx, val) = coo.disassemble(); /// assert_eq!(row_idx, vec![0, 1]); /// assert_eq!(col_idx, vec![1, 2]); /// assert_eq!(val, vec![1.0, 2.0]); /// ``` pub fn disassemble(self) -> (Vec<usize>, Vec<usize>, Vec<T>) { (self.row_indices, self.col_indices, self.values) } }