Detailed Description

A sparse matrix structure, wrapping T.

Davis' CSparse library (part of suitesparse) The type of the matrix entries is fixed to "double".

There are two formats for the non-zero entries in this matrix:

A "triplet" matrix: a set of (r,c)=val triplet entries.
A column-compressed sparse (CCS) matrix.

The latter is the "normal" format, which is expected by all mathematical operations defined in this class. There're three ways of initializing and populating a sparse matrix:

As a triplet (empty), then add entries, then compress:
CSparseMatrix SM(100,100);
SM.insert_entry(i,j, val); // or
SM.insert_submatrix(i,j, MAT); // ...
SM.compressFromTriplet();
As a triplet from a CSparseMatrixTemplate<double>:
CSparseMatrixTemplate<double> data;
data(row,col) = val;
...
CSparseMatrix SM(data);
From an existing dense matrix:
CMatrixDouble data(100,100); // or
CMatrixFloat data(100,100); // or
CMatrixFixedNumeric<double,4,6> data; // etc...
CSparseMatrix SM(data);

Due to its practical utility, there is a special inner class CSparseMatrix::CholeskyDecomp to handle Cholesky-related methods and data.

Note: This class was initially adapted from "robotvision", by Hauke Strasdat, Steven Lovegrove and Andrew J. Davison. See http://www.openslam.org/robotvision.html; CSparse is maintained by Timothy Davis: http://people.sc.fsu.edu/~jburkardt/c_src/csparse/csparse.html .; See also his book "Direct methods for sparse linear systems". http://books.google.es/books?id=TvwiyF8vy3EC&pg=PA12&lpg=PA12&dq=cs_compress&source=bl&ots=od9uGJ793j&sig=Wa-fBk4sZkZv3Y0Op8FNH8PvCUs&hl=es&ei=UjA0TJf-EoSmsQay3aXPAw&sa=X&oi=book_result&ct=result&resnum=8&ved=0CEQQ6AEwBw#v=onepage&q&f=false

See also: mrpt::math::MatrixBlockSparseCols, mrpt::math::CMatrixFixedNumeric, mrpt::math::CMatrixTemplateNumeric, etc.

Definition at line 95 of file CSparseMatrix.h.

#include <mrpt/math/CSparseMatrix.h>

Classes
class	CholeskyDecomp
	Auxiliary class to hold the results of a Cholesky factorization of a sparse matrix. More...

Public Member Functions
Constructors, destructor & copy operations
	CSparseMatrix (const size_t nRows=0, const size_t nCols=0)
	Create an initially empty sparse matrix, in the "triplet" form. More...

template<typename T >
	CSparseMatrix (const CSparseMatrixTemplate< T > &data)
	A good way to initialize a sparse matrix from a list of non nullptr elements. More...

template<typename T , size_t N, size_t M>
	CSparseMatrix (const CMatrixFixedNumeric< T, N, M > &MAT)
	Constructor from a dense matrix of any kind existing in MRPT, creating a "column-compressed" sparse matrix. More...

template<typename T >
	CSparseMatrix (const CMatrixTemplateNumeric< T > &MAT)
	Constructor from a dense matrix of any kind existing in MRPT, creating a "column-compressed" sparse matrix. More...

	CSparseMatrix (const CSparseMatrix &other)
	Copy constructor. More...

	CSparseMatrix (const cs *const sm)
	Copy constructor from an existing "cs" CSparse data structure. More...

virtual	~CSparseMatrix ()
	Destructor. More...

void	operator= (const CSparseMatrix &other)
	Copy operator from another existing object. More...

void	swap (CSparseMatrix &other)
	Fast swap contents with another sparse matrix. More...

void	clear (const size_t nRows=1, const size_t nCols=1)
	Erase all previous contents and leave the matrix as a "triplet" ROWS x COLS matrix without any nonzero entry. More...

Math operations (the interesting stuff...)
void	add_AB (const CSparseMatrix &A, const CSparseMatrix &B)
	this = A+B More...

void	multiply_AB (const CSparseMatrix &A, const CSparseMatrix &B)
	this = A*B More...

void	multiply_Ab (const mrpt::math::CVectorDouble &b, mrpt::math::CVectorDouble &out_res) const
	out_res = this * b More...

CSparseMatrix	operator+ (const CSparseMatrix &other) const

CSparseMatrix	operator* (const CSparseMatrix &other) const

mrpt::math::CVectorDouble	operator* (const mrpt::math::CVectorDouble &other) const

void	operator+= (const CSparseMatrix &other)

void	operator*= (const CSparseMatrix &other)

CSparseMatrix	transpose () const

Private Member Functions
template<class MATRIX >
void	construct_from_mrpt_mat (const MATRIX &C)
	Initialization from a dense matrix of any kind existing in MRPT. More...

void	construct_from_triplet (const cs &triplet)
	Initialization from a triplet "cs", which is first compressed. More...

void	construct_from_existing_cs (const cs &sm)
	To be called by constructors only, assume previous pointers are trash and overwrite them. More...

void	internal_free_mem ()
	free buffers (deallocate the memory of the i,p,x buffers) More...

void	copy (const cs *const sm)
	Copy the data from an existing "cs" CSparse data structure. More...

void	copy_fast (cs *const sm)
	Fast copy the data from an existing "cs" CSparse data structure, copying the pointers and leaving NULLs in the source structure. More...

Private Attributes
cs	sparse_matrix

void	insert_entry (const size_t row, const size_t col, const double val)
	@ Access the matrix, get, set elements, etc. More...

void	insert_entry_fast (const size_t row, const size_t col, const double val)
	This was an optimized version, but is now equivalent to insert_entry() due to the need to be compatible with unmodified CSparse system libraries. More...

template<class MATRIX >
void	insert_submatrix (const size_t row, const size_t col, const MATRIX &M)
	ONLY for TRIPLET matrices: insert a given matrix (in any of the MRPT formats) at a given location of the sparse matrix. More...

void	compressFromTriplet ()
	ONLY for TRIPLET matrices: convert the matrix in a column-compressed form. More...

void	get_dense (CMatrixDouble &outMat) const
	Return a dense representation of the sparse matrix. More...

bool	saveToTextFile_dense (const std::string &filName)
	save as a dense matrix to a text file More...

bool	saveToTextFile_sparse (const std::string &filName)
	Save sparse structure to a text file loadable from MATLAB (can be called on triplet or CCS matrices). More...

size_t	rows () const

size_t	cols () const

void	setRowCount (const size_t nRows)
	Change the number of rows in the matrix (can't be lower than current size) More...

void	setColCount (const size_t nCols)

bool	isTriplet () const
	Returns true if this sparse matrix is in "triplet" form. More...

bool	isColumnCompressed () const
	Returns true if this sparse matrix is in "column compressed" form. More...

static void	cs2dense (const cs &SM, CMatrixDouble &outMat)
	Static method to convert a "cs" structure into a dense representation of the sparse matrix. More...

Constructor & Destructor Documentation

◆ CSparseMatrix() [1/6]

CSparseMatrix::CSparseMatrix	(	const size_t	nRows = `0`,
		const size_t	nCols = `0`
	)

Create an initially empty sparse matrix, in the "triplet" form.

Notice that you must call "compressFromTriplet" after populating the matrix and before using the math operatons on this matrix. The initial size can be later on extended with insert_entry() or setRowCount() & setColCount().

See also: insert_entry, setRowCount, setColCount

Notice that you must call "compressFromTriplet" after populating the matrix and before using the math operatons on this matrix. The initial size can be later on extended with insert_entry() or setRowCount() & setColCount().

Definition at line 149 of file CSparseMatrix.cpp.

References sparse_matrix.

◆ CSparseMatrix() [2/6]

template<typename T >

mrpt::math::CSparseMatrix::CSparseMatrix ( const CSparseMatrixTemplate< T > & data )

inline

A good way to initialize a sparse matrix from a list of non nullptr elements.

This constructor takes all the non-zero entries in "data" and builds a column-compressed sparse representation.

Definition at line 178 of file CSparseMatrix.h.

References ASSERTMSG_, construct_from_triplet(), insert_entry_fast(), and sparse_matrix.

◆ CSparseMatrix() [3/6]

template<typename T , size_t N, size_t M>

mrpt::math::CSparseMatrix::CSparseMatrix ( const CMatrixFixedNumeric< T, N, M > & MAT )

inlineexplicit

Constructor from a dense matrix of any kind existing in MRPT, creating a "column-compressed" sparse matrix.

Definition at line 207 of file CSparseMatrix.h.

References construct_from_mrpt_mat().

◆ CSparseMatrix() [4/6]

template<typename T >

mrpt::math::CSparseMatrix::CSparseMatrix ( const CMatrixTemplateNumeric< T > & MAT )

inlineexplicit

Constructor from a dense matrix of any kind existing in MRPT, creating a "column-compressed" sparse matrix.

Definition at line 215 of file CSparseMatrix.h.

References construct_from_mrpt_mat().

◆ CSparseMatrix() [5/6]

CSparseMatrix::CSparseMatrix ( const CSparseMatrix & other )

Copy constructor.

Definition at line 23 of file CSparseMatrix.cpp.

References construct_from_existing_cs(), copy(), and sparse_matrix.

◆ CSparseMatrix() [6/6]

CSparseMatrix::CSparseMatrix ( const cs *const sm )

explicit

Copy constructor from an existing "cs" CSparse data structure.

Definition at line 30 of file CSparseMatrix.cpp.

References construct_from_existing_cs(), and copy().

◆ ~CSparseMatrix()

CSparseMatrix::~CSparseMatrix ( )

virtual

Destructor.

Definition at line 95 of file CSparseMatrix.cpp.

References internal_free_mem().

Member Function Documentation

◆ add_AB()

void CSparseMatrix::add_AB	(	const CSparseMatrix &	A,
		const CSparseMatrix &	B
	)

this = A+B

Definition at line 189 of file CSparseMatrix.cpp.

References ASSERT_, cols(), copy_fast(), rows(), and sparse_matrix.

Referenced by operator+(), and operator+=().

◆ clear()

void CSparseMatrix::clear	(	const size_t	nRows = `1`,
		const size_t	nCols = `1`
	)

Erase all previous contents and leave the matrix as a "triplet" ROWS x COLS matrix without any nonzero entry.

Erase all previous contents and leave the matrix as a "triplet" 1x1 matrix without any data.

Definition at line 98 of file CSparseMatrix.cpp.

References internal_free_mem(), and sparse_matrix.

Referenced by generateRandomSparseMatrix().

◆ cols()

size_t mrpt::math::CSparseMatrix::cols ( ) const

inline

Definition at line 382 of file CSparseMatrix.h.

References sparse_matrix.

Referenced by add_AB(), mrpt::math::CSparseMatrix::CholeskyDecomp::CholeskyDecomp(), multiply_AB(), and multiply_Ab().

◆ compressFromTriplet()

void CSparseMatrix::compressFromTriplet ( )

ONLY for TRIPLET matrices: convert the matrix in a column-compressed form.

See also: insert_entry

Definition at line 263 of file CSparseMatrix.cpp.

References copy_fast(), isTriplet(), sparse_matrix, and THROW_EXCEPTION.

Referenced by mrpt::vision::bundle_adj_full(), generateRandomSparseMatrix(), mrpt::graphslam::optimize_graph_spa_levmarq(), and TEST().

◆ construct_from_existing_cs()

void CSparseMatrix::construct_from_existing_cs ( const cs & sm )

private

To be called by constructors only, assume previous pointers are trash and overwrite them.

Definition at line 133 of file CSparseMatrix.cpp.

References ASSERTMSG_, and sparse_matrix.

Referenced by CSparseMatrix().

◆ construct_from_mrpt_mat()

template<class MATRIX >

void mrpt::math::CSparseMatrix::construct_from_mrpt_mat ( const MATRIX & C )

inlineprivate

Initialization from a dense matrix of any kind existing in MRPT.

Definition at line 102 of file CSparseMatrix.h.

References mrpt::system::os::memcpy(), and sparse_matrix.

Referenced by CSparseMatrix().

◆ construct_from_triplet()

void CSparseMatrix::construct_from_triplet ( const cs & triplet )

private

Initialization from a triplet "cs", which is first compressed.

Definition at line 122 of file CSparseMatrix.cpp.

References copy_fast().

Referenced by CSparseMatrix().

◆ copy()

void CSparseMatrix::copy ( const cs *const sm )

private

Copy the data from an existing "cs" CSparse data structure.

Definition at line 37 of file CSparseMatrix.cpp.

References ASSERTMSG_, mrpt::system::os::memcpy(), and sparse_matrix.

Referenced by CSparseMatrix(), and operator=().

◆ copy_fast()

void CSparseMatrix::copy_fast ( cs *const sm )

private

Fast copy the data from an existing "cs" CSparse data structure, copying the pointers and leaving NULLs in the source structure.

Definition at line 57 of file CSparseMatrix.cpp.

References internal_free_mem(), and sparse_matrix.

Referenced by add_AB(), compressFromTriplet(), construct_from_triplet(), and multiply_AB().

◆ cs2dense()

void CSparseMatrix::cs2dense	(	const cs &	SM,
		CMatrixDouble &	outMat
	)

static

Static method to convert a "cs" structure into a dense representation of the sparse matrix.

Definition at line 232 of file CSparseMatrix.cpp.

References ASSERT_.

Referenced by get_dense(), and mrpt::math::CSparseMatrix::CholeskyDecomp::get_L().

◆ get_dense()

void CSparseMatrix::get_dense ( CMatrixDouble & outMat ) const

Return a dense representation of the sparse matrix.

See also: saveToTextFile_dense

Definition at line 258 of file CSparseMatrix.cpp.

References cs2dense(), and sparse_matrix.

Referenced by do_matrix_op_test(), do_test_init_random(), do_test_init_to_unit(), saveToTextFile_dense(), and TEST().

◆ insert_entry()

void CSparseMatrix::insert_entry	(	const size_t	row,
		const size_t	col,
		const double	val
	)

@ Access the matrix, get, set elements, etc.

Insert an element into a "cs", return false on error.

ONLY for TRIPLET matrices: insert a new non-zero entry in the matrix. This method cannot be used once the matrix is in column-compressed form. The size of the matrix will be automatically extended if the indices are out of the current limits.

See also: isTriplet, compressFromTriplet

Definition at line 161 of file CSparseMatrix.cpp.

References isTriplet(), sparse_matrix, THROW_EXCEPTION, and val.

Referenced by generateRandomSparseMatrix(), insert_entry_fast(), and TEST().

◆ insert_entry_fast()

void mrpt::math::CSparseMatrix::insert_entry_fast	(	const size_t	row,
		const size_t	col,
		const double	val
	)

inline

This was an optimized version, but is now equivalent to insert_entry() due to the need to be compatible with unmodified CSparse system libraries.

Definition at line 299 of file CSparseMatrix.h.

References insert_entry(), and val.

Referenced by CSparseMatrix(), insert_submatrix(), and mrpt::graphslam::optimize_graph_spa_levmarq().

◆ insert_submatrix()

template<class MATRIX >

void mrpt::math::CSparseMatrix::insert_submatrix	(	const size_t	row,
		const size_t	col,
		const MATRIX &	M
	)

inline

ONLY for TRIPLET matrices: insert a given matrix (in any of the MRPT formats) at a given location of the sparse matrix.

This method cannot be used once the matrix is in column-compressed form. The size of the matrix will be automatically extended if the indices are out of the current limits. Since this is inline, it can be very efficient for fixed-size MRPT matrices.

See also: isTriplet, compressFromTriplet, insert_entry

Definition at line 316 of file CSparseMatrix.h.

References insert_entry_fast(), isTriplet(), sparse_matrix, and THROW_EXCEPTION.

Referenced by mrpt::vision::bundle_adj_full(), mrpt::graphslam::optimize_graph_spa_levmarq(), and TEST().

◆ internal_free_mem()

void CSparseMatrix::internal_free_mem ( )

private

free buffers (deallocate the memory of the i,p,x buffers)

Definition at line 114 of file CSparseMatrix.cpp.

References sparse_matrix.

Referenced by clear(), copy_fast(), and ~CSparseMatrix().

◆ isColumnCompressed()

bool mrpt::math::CSparseMatrix::isColumnCompressed ( ) const

inline

Returns true if this sparse matrix is in "column compressed" form.

See also: isTriplet

Definition at line 405 of file CSparseMatrix.h.

References sparse_matrix.

Referenced by mrpt::math::CSparseMatrix::CholeskyDecomp::CholeskyDecomp().

◆ isTriplet()

bool mrpt::math::CSparseMatrix::isTriplet ( ) const

inline

Returns true if this sparse matrix is in "triplet" form.

See also: isColumnCompressed

Definition at line 398 of file CSparseMatrix.h.

References sparse_matrix.

Referenced by compressFromTriplet(), insert_entry(), and insert_submatrix().

◆ multiply_AB()

void CSparseMatrix::multiply_AB	(	const CSparseMatrix &	A,
		const CSparseMatrix &	B
	)

this = A*B

Definition at line 199 of file CSparseMatrix.cpp.

References ASSERT_, cols(), copy_fast(), rows(), and sparse_matrix.

Referenced by operator*(), and operator*=().

◆ multiply_Ab()

void CSparseMatrix::multiply_Ab	(	const mrpt::math::CVectorDouble &	b,
		mrpt::math::CVectorDouble &	out_res
	)		const

out_res = this * b

Definition at line 209 of file CSparseMatrix.cpp.

References ASSERT_EQUAL_, cols(), rows(), and sparse_matrix.

Referenced by operator*().

◆ operator*() [1/2]

CSparseMatrix mrpt::math::CSparseMatrix::operator* ( const CSparseMatrix & other ) const

inline

Definition at line 259 of file CSparseMatrix.h.

References multiply_AB().

◆ operator*() [2/2]

mrpt::math::CVectorDouble mrpt::math::CSparseMatrix::operator* ( const mrpt::math::CVectorDouble & other ) const

inline

Definition at line 265 of file CSparseMatrix.h.

References multiply_Ab().

◆ operator*=()

void mrpt::math::CSparseMatrix::operator*= ( const CSparseMatrix & other )

inline

Definition at line 276 of file CSparseMatrix.h.

References multiply_AB().

◆ operator+()

CSparseMatrix mrpt::math::CSparseMatrix::operator+ ( const CSparseMatrix & other ) const

inline

Definition at line 253 of file CSparseMatrix.h.

References add_AB().

◆ operator+=()

void mrpt::math::CSparseMatrix::operator+= ( const CSparseMatrix & other )

inline

Definition at line 272 of file CSparseMatrix.h.

References add_AB().

◆ operator=()

void CSparseMatrix::operator= ( const CSparseMatrix & other )

Copy operator from another existing object.

Definition at line 174 of file CSparseMatrix.cpp.

References copy(), and sparse_matrix.

◆ rows()

size_t mrpt::math::CSparseMatrix::rows ( ) const

inline

Definition at line 381 of file CSparseMatrix.h.

References sparse_matrix.

Referenced by add_AB(), mrpt::math::CSparseMatrix::CholeskyDecomp::CholeskyDecomp(), multiply_AB(), and multiply_Ab().

◆ saveToTextFile_dense()

bool CSparseMatrix::saveToTextFile_dense ( const std::string & filName )

save as a dense matrix to a text file

Returns: False on any error.

Definition at line 278 of file CSparseMatrix.cpp.

References get_dense().

◆ saveToTextFile_sparse()

bool CSparseMatrix::saveToTextFile_sparse ( const std::string & filName )

Save sparse structure to a text file loadable from MATLAB (can be called on triplet or CCS matrices).

The format of the text file is:

NUM_ROWS   NUM_COLS   NUM_NON_ZERO_MAX
row_1   col_1   value_1
row_2   col_2   value_2
...

Instructions for loading from MATLAB in triplet form will be automatically writen to the output file as comments in th first lines:

D=load('file.txt');
SM=spconvert(D(2:end,:));
  or, to always preserve the actual matrix size m x n:
m=D(1,1); n=D(1,2); nzmax=D(1,3);
Di=D(2:end,1); Dj=D(2:end,2); Ds=D(2:end,3);
M=sparse(Di,Dj,Ds, m,n, nzmax);

Returns: False on any error.

Definition at line 297 of file CSparseMatrix.cpp.

References ASSERT_, mrpt::system::os::fclose(), mrpt::system::os::fopen(), mrpt::system::os::fprintf(), and sparse_matrix.

◆ setColCount()

void mrpt::math::CSparseMatrix::setColCount ( const size_t nCols )

inline

Definition at line 390 of file CSparseMatrix.h.

References ASSERT_, and sparse_matrix.

Referenced by generateRandomSparseMatrix(), and TEST().

◆ setRowCount()

void mrpt::math::CSparseMatrix::setRowCount ( const size_t nRows )

inline

Change the number of rows in the matrix (can't be lower than current size)

Definition at line 385 of file CSparseMatrix.h.

References ASSERT_, and sparse_matrix.

Referenced by generateRandomSparseMatrix(), and TEST().

◆ swap()

void CSparseMatrix::swap ( CSparseMatrix & other )

Fast swap contents with another sparse matrix.

Definition at line 81 of file CSparseMatrix.cpp.

References sparse_matrix.

◆ transpose()

CSparseMatrix CSparseMatrix::transpose ( ) const

Definition at line 220 of file CSparseMatrix.cpp.

References ASSERT_, and sparse_matrix.

Member Data Documentation

◆ sparse_matrix

cs mrpt::math::CSparseMatrix::sparse_matrix

private

Detailed Description

Classes

Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ CSparseMatrix() [1/6]

◆ CSparseMatrix() [2/6]

◆ CSparseMatrix() [3/6]

◆ CSparseMatrix() [4/6]

◆ CSparseMatrix() [5/6]

◆ CSparseMatrix() [6/6]

◆ ~CSparseMatrix()

Member Function Documentation

◆ add_AB()

◆ clear()

◆ cols()

◆ compressFromTriplet()

◆ construct_from_existing_cs()

◆ construct_from_mrpt_mat()

◆ construct_from_triplet()

◆ copy()

◆ copy_fast()

◆ cs2dense()

◆ get_dense()

◆ insert_entry()

◆ insert_entry_fast()

◆ insert_submatrix()

◆ internal_free_mem()

◆ isColumnCompressed()

◆ isTriplet()

◆ multiply_AB()

◆ multiply_Ab()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator*=()

◆ operator+()

◆ operator+=()

◆ operator=()

◆ rows()

◆ saveToTextFile_dense()

◆ saveToTextFile_sparse()

◆ setColCount()

◆ setRowCount()

◆ swap()

◆ transpose()

Member Data Documentation

◆ sparse_matrix