blob: b8264a44406f5ee569bd9af89b67fec930f0ba1f [file] [log] [blame]
 namespace Eigen { /** \eigenManualPage SparseQuickRefPage Quick reference guide for sparse matrices \eigenAutoToc
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 : 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. \section SparseMatrixInit Sparse Matrix Initialization
Category Operations Notes
Constructor \code SparseMatrix sm1(1000,1000); SparseMatrix,RowMajor> sm2; \endcode Default is ColMajor
Resize/Reserve \code sm1.resize(m,n); // Change sm1 to a m x n matrix. sm1.reserve(nnz); // Allocate room for nnz nonzeros elements. \endcode 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.
Assignment \code SparseMatrix sm1; // Initialize sm2 with sm1. SparseMatrix sm2(sm1), sm3; // Assignment and evaluations modify the storage order. sm3 = sm1; \endcode The copy constructor can be used to convert from a storage order to another
Element-wise Insertion \code // Insert a new element; sm1.insert(i, j) = v_ij; // Update the value v_ij sm1.coeffRef(i,j) = v_ij; sm1.coeffRef(i,j) += v_ij; sm1.coeffRef(i,j) -= v_ij; \endcode insert() assumes that the element does not already exist; otherwise, use coeffRef()
Batch insertion \code std::vector< Eigen::Triplet > tripletList; tripletList.reserve(estimation_of_entries); // -- Fill tripletList with nonzero elements... sm1.setFromTriplets(TripletList.begin(), TripletList.end()); \endcode A complete example is available at \link TutorialSparseFilling Triplet Insertion \endlink.
Constant or Random Insertion \code sm1.setZero(); \endcode Remove all non-zero coefficients
\section SparseBasicInfos Matrix properties Beyond the basic functions rows() and cols(), there are some useful functions that are available to easily get some information from the matrix.
\code 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(); // Squared norm of the matrix sm1.blueNorm(); sm1.isVector(); // Check if sm1 is a sparse vector or a sparse matrix sm1.isCompressed(); // Check if sm1 is in compressed form ... \endcode
\section SparseBasicOps Arithmetic operations 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.
Operations Code Notes
add subtract \code sm3 = sm1 + sm2; sm3 = sm1 - sm2; sm2 += sm1; sm2 -= sm1; \endcode sm1 and sm2 should have the same storage order
scalar product\code sm3 = sm1 * s1; sm3 *= s1; sm3 = s1 * sm1 + s2 * sm2; sm3 /= s1;\endcode Many combinations are possible if the dimensions and the storage order agree.
%Sparse %Product \code sm3 = sm1 * sm2; dm2 = sm1 * dm1; dv2 = sm1 * dv1; \endcode
transposition, adjoint \code sm2 = sm1.transpose(); sm2 = sm1.adjoint(); \endcode Note that the transposition change the storage order. There is no support for transposeInPlace().
Permutation \code perm.indices(); // Reference to the vector of indices sm1.twistedBy(perm); // Permute rows and columns sm2 = sm1 * perm; // Permute the columns sm2 = perm * sm1; // Permute the columns \endcode
Component-wise ops \code sm1.cwiseProduct(sm2); sm1.cwiseQuotient(sm2); sm1.cwiseMin(sm2); sm1.cwiseMax(sm2); sm1.cwiseAbs(); sm1.cwiseSqrt(); \endcode sm1 and sm2 should have the same storage order
\section sparseotherops Other supported operations
Code Notes
Sub-matrices
\code sm1.block(startRow, startCol, rows, cols); sm1.block(startRow, startCol); sm1.topLeftCorner(rows, cols); sm1.topRightCorner(rows, cols); sm1.bottomLeftCorner( rows, cols); sm1.bottomRightCorner( rows, cols); \endcode Contrary to dense matrices, here all these methods are read-only.\n See \ref TutorialSparse_SubMatrices and below for read-write sub-matrices.
Range
\code sm1.innerVector(outer); // RW sm1.innerVectors(start, size); // RW sm1.leftCols(size); // RW sm2.rightCols(size); // RO because sm2 is row-major sm1.middleRows(start, numRows); // RO because sm1 is column-major sm1.middleCols(start, numCols); // RW sm1.col(j); // RW \endcode A inner vector is either a row (for row-major) or a column (for column-major).\n As stated earlier, for a read-write sub-matrix (RW), the evaluation can be done in a matrix with different storage order.
\code sm1.valuePtr(); // Pointer to the values sm1.innerIndexPtr(); // Pointer to the indices. sm1.outerIndexPtr(); // Pointer to the beginning of each inner vector \endcode If the matrix is not in compressed form, makeCompressed() should be called before.\n Note that these functions are mostly provided for interoperability purposes with external libraries.\n 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