iRoCS Toolbox  1.1.0
Public Member Functions | Related Functions
atb::SparseMatrix< T > Class Template Reference

The SparseMatrix class provides a sparse matrix data structure and corresponding arithmetics. More...

#include "libArrayToolbox/SparseMatrix.hh"

Collaboration diagram for atb::SparseMatrix< T >:

Public Member Functions

 SparseMatrix ()
 Create a new empty SparseMatrix object. More...
 
 SparseMatrix (size_t r, size_t c)
 Create a new empty SparseMatrix object with given number of rows and colums. More...
 
 SparseMatrix (SparseMatrix const &m)
 Create a new deep copy of the given SparseMatrix object. More...
 
 SparseMatrix (blitz::Array< T, 2 > const &m)
 Create a new SparseMatrix object from a dense blitz++ Array. More...
 
template<int NRows, int NCols>
 SparseMatrix (blitz::TinyMatrix< T, NRows, NCols > const &m)
 Create a new SparseMatrix object from a dense blitz++ TinyMatrix. More...
 
 ~SparseMatrix ()
 Destroy the SparseMatrix object and release all its ressources. More...
 
void clear ()
 Set all entries of this matrix to zero. More...
 
void clearColumn (size_t c)
 Set all entries of the given matrix column to zero. More...
 
void clearRow (size_t r)
 Set all entries of the given matrix row to zero. More...
 
SparseVector< T > const & column (size_t c) const
 Get a read-only sparse vector view of the selected matrix column. More...
 
SparseVector< T >::const_iterator erase (size_t r, size_t c)
 Clear the matrix entry at the given position (set it zero). More...
 
void load (std::string const &fileName, std::string const &groupName, bool throwErrors=false)
 Load the SparseMatrix from an HDF5 group in a file with given name. More...
 
size_t nColumns () const
 Get the number of rows of this SparseMatrix. More...
 
size_t nNonZeroEntries () const
 Get the number of non-zero entries of this SparseMatrix. More...
 
bool nonZero (size_t r, size_t c) const
 Check whether the given matrix entry is non-zero. More...
 
size_t nRows () const
 Get the number of rows of this SparseMatrix. More...
 
T const & operator() (size_t r, size_t c) const
 Get a read-only reference on the entry at the specified position in the matrix. More...
 
T & operator() (size_t r, size_t c)
 Get a random-access reference on the entry at the specified position in the matrix. More...
 
void operator*= (T const &alpha)
 Multiply every entry of this matrix with the given scalar. More...
 
void operator+= (SparseMatrix< T > const &m)
 Add the given matrix to this matrix. More...
 
void operator-= (SparseMatrix< T > const &m)
 Subtract the given matrix from this matrix. More...
 
void operator/= (T const &alpha)
 Divide every entry of this matrix by the given scalar. More...
 
void resize (size_t r, size_t c)
 Resize the SparseMatrix to the given number of rows and columns. More...
 
SparseVector< T > const & row (size_t r) const
 Get a read-only sparse vector view of the selected matrix row. More...
 
void save (std::string const &fileName, std::string const &groupName, bool throwErrors=false)
 Save this SparseMatrix to an HDF5 group in a file with given name. More...
 
blitz::TinyVector< size_t, 2 > shape () const
 Get the shape of this SparseMatrix. More...
 
blitz::Array< T, 2 > toBlitz () const
 Get a dense blitz++ Array copy of this SparseMatrix. More...
 

Related Functions

(Note that these are not member functions.)

template<typename T >
SparseVector< T > operator* (SparseMatrix< T > const &A, SparseVector< T > const &x)
 
template<typename T >
blitz::Array< T, 1 > operator* (SparseMatrix< T > const &A, blitz::Array< T, 1 > const &x)
 
template<typename T , int Dim>
blitz::TinyVector< T, Dim > operator* (SparseMatrix< T > const &A, blitz::TinyVector< T, Dim > const &x)
 
template<typename T >
SparseMatrix< T > operator* (SparseMatrix< T > const &A, SparseMatrix< T > const &B)
 
template<typename T >
SparseMatrix< T > operator* (blitz::Array< T, 2 > const &A, SparseMatrix< T > const &B)
 
template<typename T >
SparseMatrix< T > operator* (SparseMatrix< T > const &A, blitz::Array< T, 2 > const &B)
 

Detailed Description

template<typename T>
class atb::SparseMatrix< T >

The SparseMatrix class provides a sparse matrix data structure and corresponding arithmetics.

Definition at line 90 of file SparseMatrix.hh.

Constructor & Destructor Documentation

◆ SparseMatrix() [1/5]

template<typename T>
atb::SparseMatrix< T >::SparseMatrix ( )

Create a new empty SparseMatrix object.

◆ SparseMatrix() [2/5]

template<typename T>
atb::SparseMatrix< T >::SparseMatrix ( size_t  r,
size_t  c 
)

Create a new empty SparseMatrix object with given number of rows and colums.

Parameters
rThe number of matrix rows
cThe number of matrix columns

◆ SparseMatrix() [3/5]

template<typename T>
atb::SparseMatrix< T >::SparseMatrix ( SparseMatrix< T > const &  m)

Create a new deep copy of the given SparseMatrix object.

Parameters
mThe sparse matrix to copy

◆ SparseMatrix() [4/5]

template<typename T>
atb::SparseMatrix< T >::SparseMatrix ( blitz::Array< T, 2 > const &  m)

Create a new SparseMatrix object from a dense blitz++ Array.

SparseMatrix dimensions and content will be taken from the given Array.

Parameters
mThe blitz++ Array containing the values to copy into the new SparseMatrix object

◆ SparseMatrix() [5/5]

template<typename T>
template<int NRows, int NCols>
atb::SparseMatrix< T >::SparseMatrix ( blitz::TinyMatrix< T, NRows, NCols > const &  m)

Create a new SparseMatrix object from a dense blitz++ TinyMatrix.

SparseMatrix dimensions and content will be taken from the given TinyMatrix.

Parameters
mThe blitz++ TinyMatrix containing the values to copy into the new SparseMatrix object

◆ ~SparseMatrix()

template<typename T>
atb::SparseMatrix< T >::~SparseMatrix ( )

Destroy the SparseMatrix object and release all its ressources.

Any existing references to this SparseMatrix or views of its rows and columns get invalidated.

Member Function Documentation

◆ resize()

template<typename T>
void atb::SparseMatrix< T >::resize ( size_t  r,
size_t  c 
)

Resize the SparseMatrix to the given number of rows and columns.

Parameters
rThe number of matrix rows
cThe number of matrix columns

◆ nRows()

template<typename T>
size_t atb::SparseMatrix< T >::nRows ( ) const

Get the number of rows of this SparseMatrix.

Returns
The number of matrix rows

◆ nColumns()

template<typename T>
size_t atb::SparseMatrix< T >::nColumns ( ) const

Get the number of rows of this SparseMatrix.

Returns
The number of matrix columns

◆ shape()

template<typename T>
blitz::TinyVector<size_t,2> atb::SparseMatrix< T >::shape ( ) const

Get the shape of this SparseMatrix.

Returns
The matrix shape (nRows, nColumns)

◆ nNonZeroEntries()

template<typename T>
size_t atb::SparseMatrix< T >::nNonZeroEntries ( ) const

Get the number of non-zero entries of this SparseMatrix.

Returns
The number of non-zero matrix entries

◆ clear()

template<typename T>
void atb::SparseMatrix< T >::clear ( )

Set all entries of this matrix to zero.

◆ clearRow()

template<typename T>
void atb::SparseMatrix< T >::clearRow ( size_t  r)

Set all entries of the given matrix row to zero.

Parameters
rThe row to clear

◆ clearColumn()

template<typename T>
void atb::SparseMatrix< T >::clearColumn ( size_t  c)

Set all entries of the given matrix column to zero.

Parameters
cThe column to clear

◆ row()

template<typename T>
SparseVector<T> const& atb::SparseMatrix< T >::row ( size_t  r) const

Get a read-only sparse vector view of the selected matrix row.

This is a O(1) operation.

Parameters
rThe matrix row to get a view for
Returns
A read-only view on the r'th row of this matrix

◆ column()

template<typename T>
SparseVector<T> const& atb::SparseMatrix< T >::column ( size_t  c) const

Get a read-only sparse vector view of the selected matrix column.

Getting a matrix column for the first time is quite expensive because a new SparseVector must be created and columns entries searched in the matrix. Collecting the column entries requires to iterate over the rows. Later access to the same column is an O(1) operation if column entries did not change (Requesting a random-access reference is regarded as change! However, when changing a column through an old random-access reference will not be recognized. At best never store random-access references!).

Parameters
cThe matrix column to get a view for
Returns
A read-only view on the c'th column of this matrix

◆ nonZero()

template<typename T>
bool atb::SparseMatrix< T >::nonZero ( size_t  r,
size_t  c 
) const

Check whether the given matrix entry is non-zero.

Parameters
rThe row index
cThe column index
Returns
true if the matrix entry at the given row and column is non-zero, false otherwise

◆ operator()() [1/2]

template<typename T>
T const& atb::SparseMatrix< T >::operator() ( size_t  r,
size_t  c 
) const

Get a read-only reference on the entry at the specified position in the matrix.

Parameters
rThe row index
cThe column index
Returns
A read only reference to the matrix entry at the given position.

◆ operator()() [2/2]

template<typename T>
T& atb::SparseMatrix< T >::operator() ( size_t  r,
size_t  c 
)

Get a random-access reference on the entry at the specified position in the matrix.

If the entry contains zero (is not yet contained in the matrix) it will be created. Using this operator invalidates any views on the specified column, because it can potentially change. Only use these references directly. When using "old" previously stored references the column cache will not be updated!

Parameters
rThe row index
cThe column index
Returns
A random-access reference to the matrix entry at the given position.

◆ erase()

template<typename T>
SparseVector<T>::const_iterator atb::SparseMatrix< T >::erase ( size_t  r,
size_t  c 
)

Clear the matrix entry at the given position (set it zero).

Parameters
rThe row index
cThe column index
Returns
A read-only iterator to the next non-zero element in the row or end() if no non-zero elements follow column c.

◆ toBlitz()

template<typename T>
blitz::Array<T,2> atb::SparseMatrix< T >::toBlitz ( ) const

Get a dense blitz++ Array copy of this SparseMatrix.

Returns
A dense blitz++ Array

◆ operator+=()

template<typename T>
void atb::SparseMatrix< T >::operator+= ( SparseMatrix< T > const &  m)

Add the given matrix to this matrix.

Parameters
mThe matrix to add to this matrix

◆ operator-=()

template<typename T>
void atb::SparseMatrix< T >::operator-= ( SparseMatrix< T > const &  m)

Subtract the given matrix from this matrix.

Parameters
mThe matrix to subtract from this matrix

◆ operator*=()

template<typename T>
void atb::SparseMatrix< T >::operator*= ( T const &  alpha)

Multiply every entry of this matrix with the given scalar.

Parameters
alphaThe scalar the matrix entries are scaled with

◆ operator/=()

template<typename T>
void atb::SparseMatrix< T >::operator/= ( T const &  alpha)

Divide every entry of this matrix by the given scalar.

Parameters
alphaThe scalar the matrix entries are divided by

◆ save()

template<typename T>
void atb::SparseMatrix< T >::save ( std::string const &  fileName,
std::string const &  groupName,
bool  throwErrors = false 
)

Save this SparseMatrix to an HDF5 group in a file with given name.

Parameters
fileNameThe name of the HDF5 file
groupNameThe name of the HDF5 group
throwErrorsIf false is given the program aborts on error with exit code -1, otherwise a BlitzH5Error is thrown
Exceptions
BlitzH5ErrorIf the matrix cannot be saved and throwErrors is set to true.

◆ load()

template<typename T>
void atb::SparseMatrix< T >::load ( std::string const &  fileName,
std::string const &  groupName,
bool  throwErrors = false 
)

Load the SparseMatrix from an HDF5 group in a file with given name.

This function resizes the matrix accordingly and fills in the values stored in the HDF5 file. Previous content of this SparseMatrix is lost.

Parameters
fileNameThe name of the HDF5 file
groupNameThe name of the HDF5 group
throwErrorsIf false is given the program aborts on error with exit code -1, otherwise a BlitzH5Error is thrown
Exceptions
BlitzH5ErrorIf the matrix cannot be loaded and throwErrors is set to true.

Friends And Related Function Documentation

◆ operator*() [1/6]

template<typename T >
SparseVector< T > operator* ( SparseMatrix< T > const &  A,
SparseVector< T > const &  x 
)
related

Matrix-vector product for sparse matrices and sparse vectors.

Parameters
AThe left-hand-side matrix
xThe right-hand-side vector
Returns
The sparse vector of dot products of all rows of A with x.

◆ operator*() [2/6]

template<typename T >
blitz::Array< T, 1 > operator* ( SparseMatrix< T > const &  A,
blitz::Array< T, 1 > const &  x 
)
related

Matrix-vector product for sparse matrices and dense 1-D blitz++ Arrays.

Parameters
AThe left-hand-side matrix
xThe right-hand-side vector
Returns
The dense 1-D blitz++ Array of dot products of all rows of A with x.

◆ operator*() [3/6]

template<typename T , int Dim>
blitz::TinyVector< T, Dim > operator* ( SparseMatrix< T > const &  A,
blitz::TinyVector< T, Dim > const &  x 
)
related

Matrix-vector product for quadratic sparse matrices and blitz++ TinyVectors.

Parameters
AThe left-hand-side matrix
xThe right-hand-side vector
Returns
The blitz++ TinyVector of dot products of all rows of A with x.

◆ operator*() [4/6]

template<typename T >
SparseMatrix< T > operator* ( SparseMatrix< T > const &  A,
SparseMatrix< T > const &  B 
)
related

Matrix-Matrix product for sparse matrices.

Parameters
AThe left-hand-side matrix (n x k)
BThe right-hand-side matrix (k x m)
Returns
The sparse matrix (n x m) resulting from the matrix-matrix product.

◆ operator*() [5/6]

template<typename T >
SparseMatrix< T > operator* ( blitz::Array< T, 2 > const &  A,
SparseMatrix< T > const &  B 
)
related

Matrix-Matrix product for blitz++ Array and sparse matrix.

Parameters
AThe left-hand-side matrix (n x k)
BThe right-hand-side matrix (k x m)
Returns
The sparse matrix (n x m) resulting from the matrix-matrix product.

◆ operator*() [6/6]

template<typename T >
SparseMatrix< T > operator* ( SparseMatrix< T > const &  A,
blitz::Array< T, 2 > const &  B 
)
related

Matrix-Matrix product for sparse matrix and blitz++ Array.

Parameters
AThe left-hand-side matrix (n x k)
BThe right-hand-side matrix (k x m)
Returns
The sparse matrix (n x m) resulting from the matrix-matrix product.

The documentation for this class was generated from the following file: