1namespace Eigen {
2/** \eigenManualPage SparseQuickRefPage Quick reference guide for sparse matrices
3\eigenAutoToc
4
5<hr>
6
7In 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 :
8i.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>
69</tr>
70<tr class="alt">
71<td> Constant or Random Insertion</td>
72<td>
73\code
74sm1.setZero(); // Set the matrix with zero elements
75sm1.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
84Beyond 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
104It 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>
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'>
143  <td> \code
144  sm2 = sm1.transpose();
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
155perm.indices(); // Reference to the vector of indices
156sm1.twistedBy(perm); // Permute rows and columns
157sm2 = sm1 * perm; //Permute the columns
158sm2 = 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>
216<td>
217\code
218  sm2 = sm1.triangularview<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
240sm1.valuePtr(); // Pointer to the values
241sm1.innerIndextr(); // Pointer to the indices.
242sm1.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