template<typename _Scalar, int _Options, typename _StorageIndex>
Eigen::SparseMatrix class

A versatible sparse matrix representation.

Template parameters
_Scalar the scalar type, i.e. the type of the coefficients
_Options Union of bit flags controlling the storage scheme. Currently the only possibility is ColMajor or RowMajor. The default is 0 which means column-major.
_StorageIndex the type of the indices. It has to be a signed type (e.g., short, int, std::ptrdiff_t). Default is int.

Contents

This class implements a more versatile variants of the common compressed row/column storage format. Each colmun's (resp. row) non zeros are stored as a pair of value with associated row (resp. colmiun) index. All the non zeros are stored in a single large buffer. Unlike the compressed format, there might be extra space in between the nonzeros of two successive colmuns (resp. rows) such that insertion of new non-zero can be done with limited memory reallocation and copies.

A call to the function makeCompressed() turns the matrix into the standard compressed format compatible with many library.

More details on this storage sceheme are given in the manual pages.

This class can be extended with the help of the plugin mechanism described on the page Extending MatrixBase (and other classes) by defining the preprocessor symbol EIGEN_SPARSEMATRIX_PLUGIN.

Base classes

template<typename Derived>
class SparseCompressedBase
Common base class for sparse [compressed]-{row|column}-storage format.

Constructors, destructors, conversion operators

SparseMatrix()
SparseMatrix(Index rows, Index cols)
template<typename OtherDerived>
SparseMatrix(const SparseMatrixBase<OtherDerived>& other)
template<typename OtherDerived, unsigned int UpLo>
SparseMatrix(const SparseSelfAdjointView<OtherDerived, UpLo>& other)
SparseMatrix(const SparseMatrix& other)
template<typename OtherDerived>
SparseMatrix(const ReturnByValue<OtherDerived>& other)
Copy constructor with in-place evaluation.
template<typename OtherDerived>
SparseMatrix(const DiagonalBase<OtherDerived>& other) explicit
Copy constructor with in-place evaluation.
~SparseMatrix()

Public functions

auto coeff(Index row, Index col) const -> Scalar
auto coeffRef(Index row, Index col) -> Scalar&
auto cols() const -> Index
void conservativeResize(Index rows, Index cols)
auto diagonal() const -> const ConstDiagonalReturnType
auto diagonal() -> DiagonalReturnType
auto innerIndexPtr() const -> const StorageIndex*
auto innerIndexPtr() -> StorageIndex*
auto innerNonZeroPtr() const -> const StorageIndex*
auto innerNonZeroPtr() -> StorageIndex*
auto innerSize() const -> Index
auto insert(Index row, Index col) -> Scalar&
auto isCompressed() const -> bool
void makeCompressed()
auto nonZeros() const -> Index
auto outerIndexPtr() const -> const StorageIndex*
auto outerIndexPtr() -> StorageIndex*
auto outerSize() const -> Index
void prune(const Scalar& reference, const RealScalar& epsilon = NumTraits<RealScalar>::dummy_precision())
template<typename KeepFunc>
void prune(const KeepFunc& keep = KeepFunc())
void reserve(Index reserveSize)
template<class SizesType>
void reserve(const SizesType& reserveSizes)
void resize(Index rows, Index cols)
auto rows() const -> Index
template<typename InputIterators>
void setFromTriplets(const InputIterators& begin, const InputIterators& end)
template<typename InputIterators, typename DupFunctor>
void setFromTriplets(const InputIterators& begin, const InputIterators& end, DupFunctor dup_func)
void setIdentity()
void setZero()
auto sum() const -> Scalar
void swap(SparseMatrix& other)
void uncompress()
auto valuePtr() const -> const Scalar*
auto valuePtr() -> Scalar*

Function documentation

template<typename _Scalar, int _Options, typename _StorageIndex>
Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::SparseMatrix()

Default constructor yielding an empty 0 x 0 matrix

template<typename _Scalar, int _Options, typename _StorageIndex>
Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::SparseMatrix(Index rows, Index cols)

Constructs a rows x cols empty matrix

template<typename _Scalar, int _Options, typename _StorageIndex> template<typename OtherDerived>
Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::SparseMatrix(const SparseMatrixBase<OtherDerived>& other)

Constructs a sparse matrix from the sparse expression other

template<typename _Scalar, int _Options, typename _StorageIndex> template<typename OtherDerived, unsigned int UpLo>
Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::SparseMatrix(const SparseSelfAdjointView<OtherDerived, UpLo>& other)

Constructs a sparse matrix from the sparse selfadjoint view other

template<typename _Scalar, int _Options, typename _StorageIndex>
Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::SparseMatrix(const SparseMatrix& other)

Copy constructor (it performs a deep copy)

template<typename _Scalar, int _Options, typename _StorageIndex>
Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::~SparseMatrix()

Destructor

template<typename _Scalar, int _Options, typename _StorageIndex>
Scalar Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::coeff(Index row, Index col) const

Returns the value of the matrix at position i, j This function returns Scalar(0) if the element is an explicit zero

template<typename _Scalar, int _Options, typename _StorageIndex>
Scalar& Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::coeffRef(Index row, Index col)

Returns a non-const reference to the value of the matrix at position i, j

If the element does not exist then it is inserted via the insert(Index,Index) function which itself turns the matrix into a non compressed form if that was not the case.

This is a O(log(nnz_j)) operation (binary search) plus the cost of insert(Index,Index) function if the element does not already exist.

template<typename _Scalar, int _Options, typename _StorageIndex>
Index Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::cols() const

Returns the number of columns of the matrix

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::conservativeResize(Index rows, Index cols)

Resizes the matrix to a rows x cols matrix leaving old values untouched.

If the sizes of the matrix are decreased, then the matrix is turned to uncompressed-mode and the storage of the out of bounds coefficients is kept and reserved. Call makeCompressed() to pack the entries and squeeze extra memory.

template<typename _Scalar, int _Options, typename _StorageIndex>
const ConstDiagonalReturnType Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::diagonal() const

Returns a const expression of the diagonal coefficients.

template<typename _Scalar, int _Options, typename _StorageIndex>
DiagonalReturnType Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::diagonal()

Returns a read-write expression of the diagonal coefficients.

template<typename _Scalar, int _Options, typename _StorageIndex>
const StorageIndex* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::innerIndexPtr() const

Returns a const pointer to the array of inner indices. This function is aimed at interoperability with other libraries.

template<typename _Scalar, int _Options, typename _StorageIndex>
StorageIndex* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::innerIndexPtr()

Returns a non-const pointer to the array of inner indices. This function is aimed at interoperability with other libraries.

template<typename _Scalar, int _Options, typename _StorageIndex>
const StorageIndex* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::innerNonZeroPtr() const

Returns a const pointer to the array of the number of non zeros of the inner vectors. This function is aimed at interoperability with other libraries.

template<typename _Scalar, int _Options, typename _StorageIndex>
StorageIndex* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::innerNonZeroPtr()

Returns a non-const pointer to the array of the number of non zeros of the inner vectors. This function is aimed at interoperability with other libraries.

template<typename _Scalar, int _Options, typename _StorageIndex>
Index Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::innerSize() const

Returns the number of rows (resp. columns) of the matrix if the storage order column major (resp. row major)

template<typename _Scalar, int _Options, typename _StorageIndex>
Scalar& Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::insert(Index row, Index col)

Returns a reference to a novel non zero coefficient with coordinates row x col. The non zero coefficient must not already exist.

If the matrix *this is in compressed mode, then *this is turned into uncompressed mode while reserving room for 2 x this->innerSize() non zeros if reserve(Index) has not been called earlier. In this case, the insertion procedure is optimized for a sequential insertion mode where elements are assumed to be inserted by increasing outer-indices.

If that's not the case, then it is strongly recommended to either use a triplet-list to assemble the matrix, or to first call reserve(const SizesType &) to reserve the appropriate number of non-zero elements per inner vector.

Assuming memory has been appropriately reserved, this function performs a sorted insertion in O(1) if the elements of each inner vector are inserted in increasing inner index order, and in O(nnz_j) for a random insertion.

template<typename _Scalar, int _Options, typename _StorageIndex>
bool Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::isCompressed() const

Returns whether *this is in compressed form.

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::makeCompressed()

Turns the matrix into the compressed format.

template<typename _Scalar, int _Options, typename _StorageIndex>
Index Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::nonZeros() const

Returns the number of non zero coefficients

template<typename _Scalar, int _Options, typename _StorageIndex>
const StorageIndex* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::outerIndexPtr() const

Returns a const pointer to the array of the starting positions of the inner vectors. This function is aimed at interoperability with other libraries.

template<typename _Scalar, int _Options, typename _StorageIndex>
StorageIndex* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::outerIndexPtr()

Returns a non-const pointer to the array of the starting positions of the inner vectors. This function is aimed at interoperability with other libraries.

template<typename _Scalar, int _Options, typename _StorageIndex>
Index Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::outerSize() const

Returns the number of columns (resp. rows) of the matrix if the storage order column major (resp. row major)

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::prune(const Scalar& reference, const RealScalar& epsilon = NumTraits<RealScalar>::dummy_precision())

Suppresses all nonzeros which are much smaller than reference under the tolerance epsilon

template<typename _Scalar, int _Options, typename _StorageIndex> template<typename KeepFunc>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::prune(const KeepFunc& keep = KeepFunc())

Turns the matrix into compressed format, and suppresses all nonzeros which do not satisfy the predicate keep. The functor type KeepFunc must implement the following function: bool operator() (const Index& row, const Index& col, const Scalar& value) const;

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::reserve(Index reserveSize)

Preallocates reserveSize non zeros.

Precondition: the matrix must be in compressed mode.

template<typename _Scalar, int _Options, typename _StorageIndex> template<class SizesType>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::reserve(const SizesType& reserveSizes)

Preallocates reserveSize[j] non zeros for each column (resp. row) j.

This function turns the matrix in non-compressed mode.

The type SizesType must expose the following interface:

typedef value_type;
const value_type& operator[](i) const;

for i in the [0,this->outerSize()[ range. Typical choices include std::vector<int>, Eigen::VectorXi, Eigen::VectorXi::Constant, etc.

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::resize(Index rows, Index cols)

Resizes the matrix to a rows x cols matrix and initializes it to zero.

This function does not free the currently allocated memory. To release as much as memory as possible, call mat.data().squeeze(); after resizing it.

template<typename _Scalar, int _Options, typename _StorageIndex>
Index Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::rows() const

Returns the number of rows of the matrix

template<typename _Scalar, int _Options, typename _StorageIndex> template<typename InputIterators>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::setFromTriplets(const InputIterators& begin, const InputIterators& end)

Fill the matrix *this with the list of triplets defined by the iterator range begin - end.

A triplet is a tuple (i,j,value) defining a non-zero element. The input list of triplets does not have to be sorted, and can contains duplicated elements. In any case, the result is a sorted and compressed sparse matrix where the duplicates have been summed up. This is a O(n) operation, with n the number of triplet elements. The initial contents of *this is destroyed. The matrix *this must be properly resized beforehand using the SparseMatrix(Index,Index) constructor, or the resize(Index,Index) method. The sizes are not extracted from the triplet list.

The InputIterators value_type must provide the following interface:

Scalar value() const; // the value
Scalar row() const;   // the row index i
Scalar col() const;   // the column index j

See for instance the Eigen::Triplet template class.

Here is a typical usage example:

typedef Triplet<double> T;
std::vector<T> tripletList;
triplets.reserve(estimation_of_entries);
for(...)
{
  // ...
  tripletList.push_back(T(i,j,v_ij));
}
SparseMatrixType m(rows,cols);
m.setFromTriplets(tripletList.begin(), tripletList.end());
// m is ready to go!

template<typename _Scalar, int _Options, typename _StorageIndex> template<typename InputIterators, typename DupFunctor>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::setFromTriplets(const InputIterators& begin, const InputIterators& end, DupFunctor dup_func)

The same as setFromTriplets but when duplicates are met the functor dup_func is applied: value = dup_func(OldValue, NewValue) Here is a C++11 example keeping the latest entry only: mat.setFromTriplets(triplets.begin(), triplets.end(), [] (const Scalar&,const Scalar &b) { return b; });

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::setIdentity()

Sets *this to the identity matrix. This function also turns the matrix into compressed mode, and drop any reserved memory.

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::setZero()

Removes all non zeros but keep allocated memory

This function does not free the currently allocated memory. To release as much as memory as possible, call mat.data().squeeze(); after resizing it.

template<typename _Scalar, int _Options, typename _StorageIndex>
Scalar Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::sum() const

Overloaded for performance

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::swap(SparseMatrix& other)

Swaps the content of two sparse matrices of the same type. This is a fast operation that simply swaps the underlying pointers and parameters.

template<typename _Scalar, int _Options, typename _StorageIndex>
void Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::uncompress()

Turns the matrix into the uncompressed mode

template<typename _Scalar, int _Options, typename _StorageIndex>
const Scalar* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::valuePtr() const

Returns a const pointer to the array of values. This function is aimed at interoperability with other libraries.

template<typename _Scalar, int _Options, typename _StorageIndex>
Scalar* Eigen::SparseMatrix<_Scalar, _Options, _StorageIndex>::valuePtr()

Returns a non-const pointer to the array of values. This function is aimed at interoperability with other libraries.