Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 1 | namespace Eigen { |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 2 | /** \eigenManualPage SparseQuickRefPage Quick reference guide for sparse matrices |
| 3 | \eigenAutoToc |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 4 | |
| 5 | <hr> |
| 6 | |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 7 | In this page, we give a quick summary of the main operations available for sparse matrices in the class SparseMatrix. First, it is recommended to read the introductory tutorial at \ref TutorialSparse. The important point to have in mind when working on sparse matrices is how they are stored : |
| 8 | i.e either row major or column major. The default is column major. Most arithmetic operations on sparse matrices will assert that they have the same storage order. |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 9 | |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 10 | \section SparseMatrixInit Sparse Matrix Initialization |
| 11 | <table class="manual"> |
| 12 | <tr><th> Category </th> <th> Operations</th> <th>Notes</th></tr> |
| 13 | <tr><td>Constructor</td> |
| 14 | <td> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 15 | \code |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 16 | SparseMatrix<double> sm1(1000,1000); |
| 17 | SparseMatrix<std::complex<double>,RowMajor> sm2; |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 18 | \endcode |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 19 | </td> <td> Default is ColMajor</td> </tr> |
| 20 | <tr class="alt"> |
| 21 | <td> Resize/Reserve</td> |
| 22 | <td> |
| 23 | \code |
| 24 | sm1.resize(m,n); //Change sm1 to a m x n matrix. |
| 25 | sm1.reserve(nnz); // Allocate room for nnz nonzeros elements. |
| 26 | \endcode |
| 27 | </td> |
| 28 | <td> Note that when calling reserve(), it is not required that nnz is the exact number of nonzero elements in the final matrix. However, an exact estimation will avoid multiple reallocations during the insertion phase. </td> |
| 29 | </tr> |
| 30 | <tr> |
| 31 | <td> Assignment </td> |
| 32 | <td> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 33 | \code |
| 34 | SparseMatrix<double,Colmajor> sm1; |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 35 | // Initialize sm2 with sm1. |
| 36 | SparseMatrix<double,Rowmajor> sm2(sm1), sm3; |
| 37 | // Assignment and evaluations modify the storage order. |
| 38 | sm3 = sm1; |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 39 | \endcode |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 40 | </td> |
| 41 | <td> The copy constructor can be used to convert from a storage order to another</td> |
| 42 | </tr> |
| 43 | <tr class="alt"> |
| 44 | <td> Element-wise Insertion</td> |
| 45 | <td> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 46 | \code |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 47 | // Insert a new element; |
| 48 | sm1.insert(i, j) = v_ij; |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 49 | |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 50 | // Update the value v_ij |
| 51 | sm1.coeffRef(i,j) = v_ij; |
| 52 | sm1.coeffRef(i,j) += v_ij; |
| 53 | sm1.coeffRef(i,j) -= v_ij; |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 54 | \endcode |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 55 | </td> |
| 56 | <td> insert() assumes that the element does not already exist; otherwise, use coeffRef()</td> |
| 57 | </tr> |
| 58 | <tr> |
| 59 | <td> Batch insertion</td> |
| 60 | <td> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 61 | \code |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 62 | std::vector< Eigen::Triplet<double> > tripletList; |
| 63 | tripletList.reserve(estimation_of_entries); |
| 64 | // -- Fill tripletList with nonzero elements... |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 65 | sm1.setFromTriplets(TripletList.begin(), TripletList.end()); |
| 66 | \endcode |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 67 | </td> |
| 68 | <td>A complete example is available at \link TutorialSparseFilling Triplet Insertion \endlink.</td> |
| 69 | </tr> |
| 70 | <tr class="alt"> |
| 71 | <td> Constant or Random Insertion</td> |
| 72 | <td> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 73 | \code |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 74 | sm1.setZero(); // Set the matrix with zero elements |
| 75 | sm1.setConstant(val); //Replace all the nonzero values with val |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 76 | \endcode |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 77 | </td> |
| 78 | <td> The matrix sm1 should have been created before ???</td> |
| 79 | </tr> |
| 80 | </table> |
| 81 | |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 82 | |
| 83 | \section SparseBasicInfos Matrix properties |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 84 | Beyond the basic functions rows() and cols(), there are some useful functions that are available to easily get some informations from the matrix. |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 85 | <table class="manual"> |
| 86 | <tr> |
| 87 | <td> \code |
| 88 | sm1.rows(); // Number of rows |
| 89 | sm1.cols(); // Number of columns |
| 90 | sm1.nonZeros(); // Number of non zero values |
| 91 | sm1.outerSize(); // Number of columns (resp. rows) for a column major (resp. row major ) |
| 92 | sm1.innerSize(); // Number of rows (resp. columns) for a row major (resp. column major) |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 93 | sm1.norm(); // Euclidian norm of the matrix |
| 94 | sm1.squaredNorm(); // Squared norm of the matrix |
| 95 | sm1.blueNorm(); |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 96 | sm1.isVector(); // Check if sm1 is a sparse vector or a sparse matrix |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 97 | sm1.isCompressed(); // Check if sm1 is in compressed form |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 98 | ... |
| 99 | \endcode </td> |
| 100 | </tr> |
| 101 | </table> |
| 102 | |
| 103 | \section SparseBasicOps Arithmetic operations |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 104 | It is easy to perform arithmetic operations on sparse matrices provided that the dimensions are adequate and that the matrices have the same storage order. Note that the evaluation can always be done in a matrix with a different storage order. In the following, \b sm denotes a sparse matrix, \b dm a dense matrix and \b dv a dense vector. |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 105 | <table class="manual"> |
| 106 | <tr><th> Operations </th> <th> Code </th> <th> Notes </th></tr> |
| 107 | |
| 108 | <tr> |
| 109 | <td> add subtract </td> |
| 110 | <td> \code |
| 111 | sm3 = sm1 + sm2; |
| 112 | sm3 = sm1 - sm2; |
| 113 | sm2 += sm1; |
| 114 | sm2 -= sm1; \endcode |
| 115 | </td> |
| 116 | <td> |
| 117 | sm1 and sm2 should have the same storage order |
| 118 | </td> |
| 119 | </tr> |
| 120 | |
| 121 | <tr class="alt"><td> |
| 122 | scalar product</td><td>\code |
| 123 | sm3 = sm1 * s1; sm3 *= s1; |
| 124 | sm3 = s1 * sm1 + s2 * sm2; sm3 /= s1;\endcode |
| 125 | </td> |
| 126 | <td> |
| 127 | Many combinations are possible if the dimensions and the storage order agree. |
| 128 | </tr> |
| 129 | |
| 130 | <tr> |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 131 | <td> %Sparse %Product </td> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 132 | <td> \code |
| 133 | sm3 = sm1 * sm2; |
| 134 | dm2 = sm1 * dm1; |
| 135 | dv2 = sm1 * dv1; |
| 136 | \endcode </td> |
| 137 | <td> |
| 138 | </td> |
| 139 | </tr> |
| 140 | |
| 141 | <tr class='alt'> |
| 142 | <td> transposition, adjoint</td> |
| 143 | <td> \code |
| 144 | sm2 = sm1.transpose(); |
| 145 | sm2 = sm1.adjoint(); |
| 146 | \endcode </td> |
| 147 | <td> |
| 148 | Note that the transposition change the storage order. There is no support for transposeInPlace(). |
| 149 | </td> |
| 150 | </tr> |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 151 | <tr> |
| 152 | <td> Permutation </td> |
| 153 | <td> |
| 154 | \code |
| 155 | perm.indices(); // Reference to the vector of indices |
| 156 | sm1.twistedBy(perm); // Permute rows and columns |
| 157 | sm2 = sm1 * perm; //Permute the columns |
| 158 | sm2 = perm * sm1; // Permute the columns |
| 159 | \endcode |
| 160 | </td> |
| 161 | <td> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 162 | |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 163 | </td> |
| 164 | </tr> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 165 | <tr> |
| 166 | <td> |
| 167 | Component-wise ops |
| 168 | </td> |
| 169 | <td>\code |
| 170 | sm1.cwiseProduct(sm2); |
| 171 | sm1.cwiseQuotient(sm2); |
| 172 | sm1.cwiseMin(sm2); |
| 173 | sm1.cwiseMax(sm2); |
| 174 | sm1.cwiseAbs(); |
| 175 | sm1.cwiseSqrt(); |
| 176 | \endcode</td> |
| 177 | <td> |
| 178 | sm1 and sm2 should have the same storage order |
| 179 | </td> |
| 180 | </tr> |
| 181 | </table> |
| 182 | |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 183 | \section sparseotherops Other supported operations |
| 184 | <table class="manual"> |
| 185 | <tr><th>Operations</th> <th> Code </th> <th> Notes</th> </tr> |
| 186 | <tr> |
| 187 | <td>Sub-matrices</td> |
| 188 | <td> |
| 189 | \code |
| 190 | sm1.block(startRow, startCol, rows, cols); |
| 191 | sm1.block(startRow, startCol); |
| 192 | sm1.topLeftCorner(rows, cols); |
| 193 | sm1.topRightCorner(rows, cols); |
| 194 | sm1.bottomLeftCorner( rows, cols); |
| 195 | sm1.bottomRightCorner( rows, cols); |
| 196 | \endcode |
| 197 | </td> <td> </td> |
| 198 | </tr> |
| 199 | <tr> |
| 200 | <td> Range </td> |
| 201 | <td> |
| 202 | \code |
| 203 | sm1.innerVector(outer); |
| 204 | sm1.innerVectors(start, size); |
| 205 | sm1.leftCols(size); |
| 206 | sm2.rightCols(size); |
| 207 | sm1.middleRows(start, numRows); |
| 208 | sm1.middleCols(start, numCols); |
| 209 | sm1.col(j); |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 210 | \endcode |
Carlos Hernandez | 7faaa9f | 2014-08-05 17:53:32 -0700 | [diff] [blame] | 211 | </td> |
| 212 | <td>A inner vector is either a row (for row-major) or a column (for column-major). As stated earlier, the evaluation can be done in a matrix with different storage order </td> |
| 213 | </tr> |
| 214 | <tr> |
| 215 | <td> Triangular and selfadjoint views</td> |
| 216 | <td> |
| 217 | \code |
| 218 | sm2 = sm1.triangularview<Lower>(); |
| 219 | sm2 = sm1.selfadjointview<Lower>(); |
| 220 | \endcode |
| 221 | </td> |
| 222 | <td> Several combination between triangular views and blocks views are possible |
| 223 | \code |
| 224 | \endcode </td> |
| 225 | </tr> |
| 226 | <tr> |
| 227 | <td>Triangular solve </td> |
| 228 | <td> |
| 229 | \code |
| 230 | dv2 = sm1.triangularView<Upper>().solve(dv1); |
| 231 | dv2 = sm1.topLeftCorner(size, size).triangularView<Lower>().solve(dv1); |
| 232 | \endcode |
| 233 | </td> |
| 234 | <td> For general sparse solve, Use any suitable module described at \ref TopicSparseSystems </td> |
| 235 | </tr> |
| 236 | <tr> |
| 237 | <td> Low-level API</td> |
| 238 | <td> |
| 239 | \code |
| 240 | sm1.valuePtr(); // Pointer to the values |
| 241 | sm1.innerIndextr(); // Pointer to the indices. |
| 242 | sm1.outerIndexPtr(); //Pointer to the beginning of each inner vector |
| 243 | \endcode |
| 244 | </td> |
| 245 | <td> If the matrix is not in compressed form, makeCompressed() should be called before. Note that these functions are mostly provided for interoperability purposes with external libraries. A better access to the values of the matrix is done by using the InnerIterator class as described in \link TutorialSparse the Tutorial Sparse \endlink section</td> |
| 246 | </tr> |
| 247 | </table> |
Narayan Kamath | c981c48 | 2012-11-02 10:59:05 +0000 | [diff] [blame] | 248 | */ |
| 249 | } |