Table of contents
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 first the introductory tutorial at Tutorial page 9 - Sparse Matrix. The important point to have in mind when working on sparse matrices is how they are stored : 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. 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.
SparseMatrix 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. ??? It is possible to modify the default storage order at compile-time with the cmake variable EIGEN_DEFAULT_ROW_MAJOR ???
The copy constructor and assignment can be used to convert matrices from a storage order to another
resize() and reserve() are used to set the size and allocate space for nonzero elements
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.
Insertions of values in the sparse matrix can be done directly by looping over nonzero elements and use the insert() function
After insertion, a value at (i,j) can be modified using coeffRef()
The recommended way to insert values is to build a list of triplets (row, col, val) and then call setFromTriplets().
A complete example is available at Filling a sparse matrix.
The following functions can be used to set constant or random values in the matrix.
Beyond 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.
sm1.rows(); // Number of rows
sm1.cols(); // Number of columns
sm1.nonZeros(); // Number of non zero values
sm1.outerSize(); // Number of columns (resp. rows) for a column major (resp. row major )
sm1.innerSize(); // Number of rows (resp. columns) for a row major (resp. column major)
sm1.norm(); // (Euclidian ??) norm of the matrix
sm1.squaredNorm(); //
sm1.isVector(); // Check if sm1 is a sparse vector or a sparse matrix
...
|
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.
Operations | Code | Notes |
---|---|---|
add subtract | sm3 = sm1 + sm2;
sm3 = sm1 - sm2;
sm2 += sm1;
sm2 -= sm1;
| sm1 and sm2 should have the same storage order |
scalar product | sm3 = sm1 * s1; sm3 *= s1;
sm3 = s1 * sm1 + s2 * sm2; sm3 /= s1;
| Many combinations are possible if the dimensions and the storage order agree. |
Product | sm3 = sm1 * sm2;
dm2 = sm1 * dm1;
dv2 = sm1 * dv1;
| |
transposition, adjoint | sm2 = sm1.transpose();
sm2 = sm1.adjoint();
| Note that the transposition change the storage order. There is no support for transposeInPlace(). |
Component-wise ops | sm1.cwiseProduct(sm2);
sm1.cwiseQuotient(sm2);
sm1.cwiseMin(sm2);
sm1.cwiseMax(sm2);
sm1.cwiseAbs();
sm1.cwiseSqrt();
| sm1 and sm2 should have the same storage order |
There 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.
These pointers can therefore be easily used to send the matrix to some external libraries/solvers that are not yet supported by Eigen.
In 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.
The 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.
Examples :