1namespace Eigen { 2/** \page SparseQuickRefPage Quick reference guide for sparse matrices 3 4\b Table \b of \b contents 5 - \ref Constructors 6 - \ref SparseMatrixInsertion 7 - \ref SparseBasicInfos 8 - \ref SparseBasicOps 9 - \ref SparseInterops 10 - \ref sparsepermutation 11 - \ref sparsesubmatrices 12 - \ref sparseselfadjointview 13\n 14 15<hr> 16 17In 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 first the introductory tutorial at \ref TutorialSparse. The important point to have in mind when working on sparse matrices is how they are stored : 18i.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. Moreover, when interacting with external libraries that are not yet supported by Eigen, it is important to know how to send the required matrix pointers. 19 20\section Constructors Constructors and assignments 21SparseMatrix is the core class to build and manipulate sparse matrices in Eigen. It takes as template parameters the Scalar type and the storage order, either RowMajor or ColumnMajor. The default is ColumnMajor. 22 23\code 24 SparseMatrix<double> sm1(1000,1000); // 1000x1000 compressed sparse matrix of double. 25 SparseMatrix<std::complex<double>,RowMajor> sm2; // Compressed row major matrix of complex double. 26\endcode 27The copy constructor and assignment can be used to convert matrices from a storage order to another 28\code 29 SparseMatrix<double,Colmajor> sm1; 30 // Eventually fill the matrix sm1 ... 31 SparseMatrix<double,Rowmajor> sm2(sm1), sm3; // Initialize sm2 with sm1. 32 sm3 = sm1; // Assignment and evaluations modify the storage order. 33 \endcode 34 35\section SparseMatrixInsertion Allocating and inserting values 36resize() and reserve() are used to set the size and allocate space for nonzero elements 37 \code 38 sm1.resize(m,n); //Change sm to a mxn matrix. 39 sm1.reserve(nnz); // Allocate room for nnz nonzeros elements. 40 \endcode 41Note 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. 42 43Insertions of values in the sparse matrix can be done directly by looping over nonzero elements and use the insert() function 44\code 45// Direct insertion of the value v_ij; 46 sm1.insert(i, j) = v_ij; // It is assumed that v_ij does not already exist in the matrix. 47\endcode 48 49After insertion, a value at (i,j) can be modified using coeffRef() 50\code 51 // Update the value v_ij 52 sm1.coeffRef(i,j) = v_ij; 53 sm1.coeffRef(i,j) += v_ij; 54 sm1.coeffRef(i,j) -= v_ij; 55 ... 56\endcode 57 58The recommended way to insert values is to build a list of triplets (row, col, val) and then call setFromTriplets(). 59\code 60 sm1.setFromTriplets(TripletList.begin(), TripletList.end()); 61\endcode 62A complete example is available at \ref TutorialSparseFilling. 63 64The following functions can be used to set constant or random values in the matrix. 65\code 66 sm1.setZero(); // Reset the matrix with zero elements 67 ... 68\endcode 69 70\section SparseBasicInfos Matrix properties 71Beyond the functions rows() and cols() that are used to get the number of rows and columns, there are some useful functions that are available to easily get some informations from the matrix. 72<table class="manual"> 73<tr> 74 <td> \code 75 sm1.rows(); // Number of rows 76 sm1.cols(); // Number of columns 77 sm1.nonZeros(); // Number of non zero values 78 sm1.outerSize(); // Number of columns (resp. rows) for a column major (resp. row major ) 79 sm1.innerSize(); // Number of rows (resp. columns) for a row major (resp. column major) 80 sm1.norm(); // (Euclidian ??) norm of the matrix 81 sm1.squaredNorm(); // 82 sm1.isVector(); // Check if sm1 is a sparse vector or a sparse matrix 83 ... 84 \endcode </td> 85</tr> 86</table> 87 88\section SparseBasicOps Arithmetic operations 89It 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. 90<table class="manual"> 91<tr><th> Operations </th> <th> Code </th> <th> Notes </th></tr> 92 93<tr> 94 <td> add subtract </td> 95 <td> \code 96 sm3 = sm1 + sm2; 97 sm3 = sm1 - sm2; 98 sm2 += sm1; 99 sm2 -= sm1; \endcode 100 </td> 101 <td> 102 sm1 and sm2 should have the same storage order 103 </td> 104</tr> 105 106<tr class="alt"><td> 107 scalar product</td><td>\code 108 sm3 = sm1 * s1; sm3 *= s1; 109 sm3 = s1 * sm1 + s2 * sm2; sm3 /= s1;\endcode 110 </td> 111 <td> 112 Many combinations are possible if the dimensions and the storage order agree. 113</tr> 114 115<tr> 116 <td> Product </td> 117 <td> \code 118 sm3 = sm1 * sm2; 119 dm2 = sm1 * dm1; 120 dv2 = sm1 * dv1; 121 \endcode </td> 122 <td> 123 </td> 124</tr> 125 126<tr class='alt'> 127 <td> transposition, adjoint</td> 128 <td> \code 129 sm2 = sm1.transpose(); 130 sm2 = sm1.adjoint(); 131 \endcode </td> 132 <td> 133 Note that the transposition change the storage order. There is no support for transposeInPlace(). 134 </td> 135</tr> 136 137<tr> 138 <td> 139 Component-wise ops 140 </td> 141 <td>\code 142 sm1.cwiseProduct(sm2); 143 sm1.cwiseQuotient(sm2); 144 sm1.cwiseMin(sm2); 145 sm1.cwiseMax(sm2); 146 sm1.cwiseAbs(); 147 sm1.cwiseSqrt(); 148 \endcode</td> 149 <td> 150 sm1 and sm2 should have the same storage order 151 </td> 152</tr> 153</table> 154 155 156\section SparseInterops Low-level storage 157There are a set of low-levels functions to get the standard compressed storage pointers. The matrix should be in compressed mode which can be checked by calling isCompressed(); makeCompressed() should do the job otherwise. 158\code 159 // Scalar pointer to the values of the matrix, size nnz 160 sm1.valuePtr(); 161 // Index pointer to get the row indices (resp. column indices) for column major (resp. row major) matrix, size nnz 162 sm1.innerIndexPtr(); 163 // Index pointer to the beginning of each row (resp. column) in valuePtr() and innerIndexPtr() for column major (row major). The size is outersize()+1; 164 sm1.outerIndexPtr(); 165\endcode 166These pointers can therefore be easily used to send the matrix to some external libraries/solvers that are not yet supported by Eigen. 167 168\section sparsepermutation Permutations, submatrices and Selfadjoint Views 169In many cases, it is necessary to reorder the rows and/or the columns of the sparse matrix for several purposes : fill-in reducing during matrix decomposition, better data locality for sparse matrix-vector products... The class PermutationMatrix is available to this end. 170 \code 171 PermutationMatrix<Dynamic, Dynamic, int> perm; 172 // Reserve and fill the values of perm; 173 perm.inverse(n); // Compute eventually the inverse permutation 174 sm1.twistedBy(perm) //Apply the permutation on rows and columns 175 sm2 = sm1 * perm; // ??? Apply the permutation on columns ???; 176 sm2 = perm * sm1; // ??? Apply the permutation on rows ???; 177 \endcode 178 179\section sparsesubmatrices Sub-matrices 180The following functions are useful to extract a block of rows (resp. columns) from a row-major (resp. column major) sparse matrix. Note that because of the particular storage, it is not ?? efficient ?? to extract a submatrix comprising a certain number of subrows and subcolumns. 181 \code 182 sm1.innerVector(outer); // Returns the outer -th column (resp. row) of the matrix if sm is col-major (resp. row-major) 183 sm1.innerVectors(outer); // Returns the outer -th column (resp. row) of the matrix if mat is col-major (resp. row-major) 184 sm1.middleRows(start, numRows); // For row major matrices, get a range of numRows rows 185 sm1.middleCols(start, numCols); // For column major matrices, get a range of numCols cols 186 \endcode 187 Examples : 188 189\section sparseselfadjointview Sparse triangular and selfadjoint Views 190 \code 191 sm2 = sm1.triangularview<Lower>(); // Get the lower triangular part of the matrix. 192 dv2 = sm1.triangularView<Upper>().solve(dv1); // Solve the linear system with the uppper triangular part. 193 sm2 = sm1.selfadjointview<Lower>(); // Build a selfadjoint matrix from the lower part of sm1. 194 \endcode 195 196 197*/ 198} 199