1 namespace Eigen { 2 /** \eigenManualPage SparseQuickRefPage Quick reference guide for sparse matrices 3 \eigenAutoToc 4 5 <hr> 6 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. 9 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> 15 \code 16 SparseMatrix<double> sm1(1000,1000); 17 SparseMatrix<std::complex<double>,RowMajor> sm2; 18 \endcode 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> 33 \code 34 SparseMatrix<double,Colmajor> sm1; 35 // Initialize sm2 with sm1. 36 SparseMatrix<double,Rowmajor> sm2(sm1), sm3; 37 // Assignment and evaluations modify the storage order. 38 sm3 = sm1; 39 \endcode 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> 46 \code 47 // Insert a new element; 48 sm1.insert(i, j) = v_ij; 49 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; 54 \endcode 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> 61 \code 62 std::vector< Eigen::Triplet<double> > tripletList; 63 tripletList.reserve(estimation_of_entries); 64 // -- Fill tripletList with nonzero elements... 65 sm1.setFromTriplets(TripletList.begin(), TripletList.end()); 66 \endcode 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> 73 \code 74 sm1.setZero(); // Set the matrix with zero elements 75 sm1.setConstant(val); //Replace all the nonzero values with val 76 \endcode 77 </td> 78 <td> The matrix sm1 should have been created before ???</td> 79 </tr> 80 </table> 81 82 83 \section SparseBasicInfos Matrix properties 84 Beyond the basic functions rows() and cols(), there are some useful functions that are available to easily get some informations from the matrix. 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) 93 sm1.norm(); // Euclidian norm of the matrix 94 sm1.squaredNorm(); // Squared norm of the matrix 95 sm1.blueNorm(); 96 sm1.isVector(); // Check if sm1 is a sparse vector or a sparse matrix 97 sm1.isCompressed(); // Check if sm1 is in compressed form 98 ... 99 \endcode </td> 100 </tr> 101 </table> 102 103 \section SparseBasicOps Arithmetic operations 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. 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> 131 <td> %Sparse %Product </td> 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> 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> 162 163 </td> 164 </tr> 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 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); 210 \endcode 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> 248 */ 249 } 250
