class mrpt::math::CSparseMatrix

Overview

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
CMatrixFixed<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.

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.

#include <mrpt/math/CSparseMatrix.h>

class CSparseMatrix
{
public:
    // classes

    class CholeskyDecomp;

    // construction

    CSparseMatrix(size_t nRows = 0, size_t nCols = 0);

    template <typename T>
    CSparseMatrix(const CSparseMatrixTemplate<T>& data);

    template <typename T, size_t N, size_t M>
    CSparseMatrix(const CMatrixFixed<T, N, M>& MAT);

    template <typename T>
    CSparseMatrix(const CMatrixDynamic<T>& MAT);

    CSparseMatrix(const CSparseMatrix& other);
    CSparseMatrix(const cs*const sm);

    // methods

    CSparseMatrix& operator = (const CSparseMatrix& other);
    void swap(CSparseMatrix& other);
    void clear(size_t nRows = 1, size_t nCols = 1);
    void add_AB(const CSparseMatrix& A, const CSparseMatrix& B);
    void multiply_AB(const CSparseMatrix& A, const CSparseMatrix& B);
    void matProductOf_Ab(const mrpt::math::CVectorDouble& b, mrpt::math::CVectorDouble& out_res) const;
    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;
    void insert_entry(size_t row, size_t col, const double val);
    void insert_entry_fast(size_t row, size_t col, const double val);

    template <class MATRIX>
    void insert_submatrix(size_t row, size_t col, const MATRIX& M);

    void compressFromTriplet();
    void get_dense(CMatrixDouble& outMat) const;
    bool saveToTextFile_dense(const std::string& filName);
    bool saveToTextFile_sparse(const std::string& filName);
    size_t rows() const;
    size_t cols() const;
    void setRowCount(size_t nRows);
    void setColCount(size_t nCols);
    bool isTriplet() const;
    bool isColumnCompressed() const;
    static void cs2dense(const cs& SM, CMatrixDouble& outMat);
};

Construction

CSparseMatrix(size_t nRows = 0, 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(). 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

template <typename T>
CSparseMatrix(const CSparseMatrixTemplate<T>& data)

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.

template <typename T, size_t N, size_t M>
CSparseMatrix(const CMatrixFixed<T, N, M>& MAT)

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

template <typename T>
CSparseMatrix(const CMatrixDynamic<T>& MAT)

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

CSparseMatrix(const CSparseMatrix& other)

Copy constructor.

CSparseMatrix(const cs*const sm)

Copy constructor from an existing “cs” CSparse data structure.

Methods

CSparseMatrix& operator = (const CSparseMatrix& other)

Copy operator from another existing object.

void swap(CSparseMatrix& other)

Fast swap contents with another sparse matrix.

void clear(size_t nRows = 1, 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.

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

this = A+B

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

this = A*B

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

out_res = this * b

void insert_entry(size_t row, 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

void insert_entry_fast(size_t row, 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.

template <class MATRIX>
void insert_submatrix(
    size_t row,
    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.

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.

void compressFromTriplet()

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

See also:

insert_entry

void get_dense(CMatrixDouble& outMat) const

Return a dense representation of the sparse matrix.

See also:

saveToTextFile_dense

bool saveToTextFile_dense(const std::string& filName)

save as a dense matrix to a text file

Returns:

False on any error.

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).

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 written 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.

void setRowCount(size_t nRows)

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

bool isTriplet() const

Returns true if this sparse matrix is in “triplet” form.

See also:

isColumnCompressed

bool isColumnCompressed() const

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

See also:

isTriplet

static void cs2dense(const cs& SM, CMatrixDouble& outMat)

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