#include <SparseMatrix.h>

Inheritance diagram for mirtk::GenericSparseMatrix< TEntry >:

Collaboration diagram for mirtk::GenericSparseMatrix< TEntry >:

Public Types
typedef Array< Entry >	Entries
	List of non-zero entries.

typedef Pair< int, TEntry >	Entry
	Type of non-zero entry.

typedef TEntry	EntryType
	Type of matrix entry values.

enum	StorageLayout

Public Member Functions
virtual void	Clear ()
	Free all non-zero entries.

void	ClearIndex ()
	Free memory needed for precomputed indices.

void	Col (int, Entries &, bool=false)

Entries	Col (int) const

int	ColNNZ (int) const
	Number of non-zero entries in specified column.

EntryType	ColSum (int) const

void	Column (int, Entries &, bool=false)

Entries	Column (int) const

EntryType	ColumnSum (int) const

Vector	Diag () const
	Get diagonal values.

void	Diag (const Vector &d)
	Set diagonal to specified (non-zero) values.

void	Diag (TEntry d)
	Set diagonal to specified (non-zero) value.

int	Eigenvalues (Vector &v, int k, const char sigma="LM", int p=0, double tol=.0, int maxit=0, Vector v0=NULL) const

int	Eigenvectors (Matrix &E, int k, const char sigma="LM", int p=0, double tol=.0, int maxit=0, Vector v0=NULL) const

int	Eigenvectors (Matrix &E, Vector &v, int k, const char sigma="LM", int p=0, double tol=.0, int maxit=0, Vector v0=NULL) const

	GenericSparseMatrix (StorageLayout=CCS)
	Default constructor.

	GenericSparseMatrix (int, int=0, StorageLayout=CCS)
	Construct sparse m x n matrix.

	GenericSparseMatrix (int, int, int, StorageLayout=CCS)
	Construct sparse m x n matrix with specified number of non-zero entries.

template<class TOtherEntry >
	GenericSparseMatrix (const GenericSparseMatrix< TOtherEntry > &)
	Copy constructor.

EntryType	Get (int, int=-1) const
	Get value.

void	GetCol (int, Entries &) const

void	GetColumn (int, Entries &) const

void	GetDiag (Vector &d) const
	Get diagonal values.

int	GetRawData (int &, int &, TEntry *&) const
	Get raw access to index and data arrays.

void	GetRow (int, Entries &) const

void	Index ()

void	Initialize (int, int=0, int=0)
	Initialize sparse matrix.

void	Initialize (int, int, Array< Entries > &, bool=false)
	Initialize sparse matrix given compressed rows (CRS) or columns (CCS)

void	Initialize (int, int, Entries [], bool=false)
	Initialize sparse matrix given compressed rows (CRS) or columns (CCS)

bool	IsSymmetric () const
	Whether this matrix is symmetric.

void	Layout (StorageLayout)
	Change storage layout.

void	MakeSymmetric (bool extent=false)

	mirtkAttributeMacro (int, Size)
	Number of allocated elements.

	mirtkPublicAttributeMacro (int, MaxNumberOfUnusedEntries)
	Maximum number of unused entries, i.e., (_Size - _NNZ)

	mirtkReadOnlyAttributeMacro (enum StorageLayout, Layout)
	Storage layout.

	mirtkReadOnlyAttributeMacro (int, Rows)
	Number of rows.

	mirtkReadOnlyAttributeMacro (int, Cols)
	Number of columns.

	mirtkReadOnlyAttributeMacro (int, NNZ)
	Number of non-zero entries.

void	MultAv (EntryType [], EntryType []) const

EntryType &	operator() (int, int=-1)

GenericSparseMatrix	operator* (EntryType) const
	Multiply by a scalar.

GenericSparseMatrix &	operator*= (EntryType)
	Multiply by a scalar in-place.

GenericSparseMatrix	operator/ (EntryType) const
	Divide by a scalar.

GenericSparseMatrix &	operator/= (EntryType)
	Divide by a scalar in-place.

template<class TOtherEntry >
GenericSparseMatrix &	operator= (const GenericSparseMatrix< TOtherEntry > &)
	Assignment operator.

void	Put (int, int, EntryType)

TEntry *	RawPointer (int=0)
	Get raw access to non-zero values.

const TEntry *	RawPointer (int=0) const
	Get raw access to non-zero values.

bool	ReadMAT (const char , const char ="A")

void	RemoveZeros ()
	Remove any zero entries.

void	Reserve (int)
	Reserve more memory.

void	Row (int, Entries &, bool=false)

Entries	Row (int) const

int	RowNNZ (int) const
	Number of non-zero entries in specified row.

EntryType	RowSum (int) const

GenericSparseMatrix &	ScaleCol (int, EntryType)

GenericSparseMatrix &	ScaleColumn (int, EntryType)

GenericSparseMatrix &	ScaleRow (int, EntryType)

GenericSparseMatrix	Sub (int, int, int, int) const
	Get non-zero entries of specified submatrix.

void	Sub (int, int, const GenericSparseMatrix &)
	Set non-zero entries of specified submatrix.

int	SubNNZ (int, int, int, int) const
	Number of non-zero entries in specified submatrix.

void	Transpose (bool keep_layout=false)

bool	WriteMAT (const char , const char ="A") const

void	WriteMFile (const char , const char ="A") const

void	Zero ()
	Set all non-zero entries to zero (i.e., remove)

virtual	~GenericSparseMatrix ()
	Destructor.

Public Member Functions inherited from mirtk::Object
virtual const char *	NameOfClass () const =0
	Get name of class, which this object is an instance of.

virtual ParameterList	Parameter () const
	Get parameter name/value pairs.

bool	Parameter (const ParameterList &)
	Set parameters from name/value pairs.

virtual bool	Set (const char name, const char value)

virtual	~Object ()
	Destructor.

Protected Member Functions
void	CheckEntries (Entries &) const
	Check non-zero entries, sort them, remove zero entries, and sum up duplicates.

template<class TOtherEntry >
void	CopyAttributes (const GenericSparseMatrix< TOtherEntry > &)
	Copy other matrix, used by copy constructor and assignment operator only.

Protected Member Functions inherited from mirtk::Object
template<typename... Args>
void	Throw (ErrorType err, const char *func, Args... args) const

Protected Attributes
int *	_Col

EntryType *	_Data
	Non-zero entries.

Array< int > *	_Index

int *	_Row

Additional Inherited Members
Static Public Member Functions inherited from mirtk::Object
static const char *	NameOfType ()
	Get name of this class type.

Static Protected Member Functions inherited from mirtk::Object
template<typename... Args>
static void	ThrowStatic (ErrorType err, const char cls, const char func, Args... args)

Detailed Description

template<class TEntry>
class mirtk::GenericSparseMatrix< TEntry >

Sparse matrix with generic non-zero value type

Definition at line 51 of file SparseMatrix.h.

Member Enumeration Documentation

§ StorageLayout

template<class TEntry>

enum mirtk::GenericSparseMatrix::StorageLayout

Enumeration of implemented storage layouts, i.e., either compressed row storage (CRS) or compressed column storage (CCS)

Definition at line 61 of file SparseMatrix.h.

Member Function Documentation

§ Col() [1/2]

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::Col	(	int	c,
		Entries &	col,
		bool	as_is = `false`
	)

Set non-zero entries of specified column

Note: More efficient then Put when the CCS layout is used. Implicitly sorts the input entries.

Remarks: This function is not thread-safe.

Definition at line 1204 of file SparseMatrix.h.

§ Col() [2/2]

template<class TEntry >

GenericSparseMatrix< TEntry >::Entries mirtk::GenericSparseMatrix< TEntry >::Col ( int c ) const

Get non-zero entries of specified column

Note: This function is most efficient when the CCS layout is used.

Definition at line 1319 of file SparseMatrix.h.

§ ColSum()

template<class TEntry >

TEntry mirtk::GenericSparseMatrix< TEntry >::ColSum ( int c ) const

Calculate sum of all entries in specified column

Note: This function is most efficient when the CCS layout is used.

Definition at line 1617 of file SparseMatrix.h.

§ Column() [1/2]

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::Column	(	int	c,
		Entries &	col,
		bool	as_is = `false`
	)

Set non-zero entries of specified column

Note: More efficient then Put when the CCS layout is used. Implicitly sorts the input entries.

Definition at line 1273 of file SparseMatrix.h.

§ Column() [2/2]

template<class TEntry >

GenericSparseMatrix< TEntry >::Entries mirtk::GenericSparseMatrix< TEntry >::Column ( int c ) const

Get non-zero entries of specified column

Note: This function is most efficient when the CCS layout is used.

Definition at line 1329 of file SparseMatrix.h.

§ ColumnSum()

template<class TEntry >

TEntry mirtk::GenericSparseMatrix< TEntry >::ColumnSum ( int c ) const

Calculate sum of all entries in specified column

Note: This function is most efficient when the CCS layout is used.

Definition at line 1642 of file SparseMatrix.h.

§ Eigenvalues()

template<class TEntry>

int mirtk::GenericSparseMatrix< TEntry >::Eigenvalues	(	Vector &	v,
		int	k,
		const char *	sigma = `"LM"`,
		int	p = `0`,
		double	tol = `.0`,
		int	maxit = `0`,
		Vector *	v0 = `NULL`
	)		const

Largest/Smallest eigenvalues

Uses an iterative eigen solver to compute the k eigenvalues which have largest or smallest magnitude, respectively, or are closest in magnitude to the specified sigma value. Uses the Implicitly Restarted Arnoldi Method implemented by ARPACK. The LU factorization used for the shift-and-invert mode is computed using UMFPACK.

Parameters

[out]	v	Converged eigenvalues.
[in]	k	Number of requested eigenvalues.
[in]	sigma	Which eigenvalues of the spectrum, i.e., 'LM', 'LA', 'SM', 'SA', or numeric value sigma used for shift-and-invert mode.
[in]	p	Number of Lanczos basis vectors.
[in]	tol	Ritz estimate residual <= tol*norm(this).
[in]	maxit	Maximum number of iterations.
[in]	v0	Starting vector. By default randomly generated.

Returns: Number of converged eigenvalues.

Note: Only implemented for real double precision sparse matrices. Use only when MIRTK_Numerics_WITH_eigs is 1.

§ Eigenvectors() [1/2]

template<class TEntry>

int mirtk::GenericSparseMatrix< TEntry >::Eigenvectors	(	Matrix &	E,
		int	k,
		const char *	sigma = `"LM"`,
		int	p = `0`,
		double	tol = `.0`,
		int	maxit = `0`,
		Vector *	v0 = `NULL`
	)		const

Eigenvectors of largest/smallest eigenvalues

Uses an iterative eigen solver to compute the eigenvectors corresponding to the k eigenvalues which have largest or smallest magnitude, respectively, or are closest in magnitude to the specified sigma value. Uses the Implicitly Restarted Arnoldi Method (IRAM) implemented by ARPACK. The LU factorization for the shift-and-invert mode is computed using UMFPACK.

Parameters

[out]	E	Matrix of eigenvectors in columns.
[in]	k	Number of requested eigenvalues.
[in]	sigma	Which eigenvalues of the spectrum, i.e., 'LM', 'LA', 'SM', 'SA', or numeric value sigma used for shift-and-invert mode.
[in]	p	Number of Lanczos basis vectors.
[in]	tol	Ritz estimate residual <= tol*norm(this).
[in]	maxit	Maximum number of iterations.
[in,out]	v0	Input: Starting vector. By default randomly generated. Output: Final residual vector.

Returns: Number of converged eigenvalues.

Note: Only implemented for real double precision sparse matrices. Use only when MIRTK_Numerics_WITH_eigs is 1.

§ Eigenvectors() [2/2]

template<class TEntry>

int mirtk::GenericSparseMatrix< TEntry >::Eigenvectors	(	Matrix &	E,
		Vector &	v,
		int	k,
		const char *	sigma = `"LM"`,
		int	p = `0`,
		double	tol = `.0`,
		int	maxit = `0`,
		Vector *	v0 = `NULL`
	)		const

Largest/Smallest eigenvalues and -vectors

Uses an iterative eigen solver to compute the k eigenvalues which have largest or smallest magnitude, respectively, or are closest in magnitude to the specified sigma value. Uses the Implicitly Restarted Arnoldi Method implemented by ARPACK. The LU factorization used for the shift-and-invert mode is computed using UMFPACK.

Parameters

[out]	E	Matrix of eigenvectors in columns.
[out]	v	Converged eigenvalues.
[in]	k	Number of requested eigenvalues.
[in]	sigma	Which eigenvalues of the spectrum, i.e., 'LM', 'LA', 'SM', 'SA', or numeric value sigma used for shift-and-invert mode.
[in]	p	Number of Lanczos basis vectors.
[in]	tol	Ritz estimate residual <= tol*norm(this).
[in]	maxit	Maximum number of iterations.
[in]	v0	Starting vector. By default randomly generated.

Returns: Number of converged eigenvalues.

Note: Only implemented for real double precision sparse matrices. Use only when MIRTK_Numerics_WITH_eigs is 1.

§ GetCol()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::GetCol	(	int	c,
		Entries &	col
	)		const

Get non-zero entries of specified column

Note: This function is most efficient when the CCS layout is used.

Definition at line 1280 of file SparseMatrix.h.

§ GetColumn()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::GetColumn	(	int	c,
		Entries &	col
	)		const

Get non-zero entries of specified column

Note: This function is most efficient when the CCS layout is used.

Definition at line 1311 of file SparseMatrix.h.

§ GetRow()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::GetRow	(	int	r,
		Entries &	row
	)		const

Get non-zero entries of specified row

Note: This function is most efficient when the CRS layout is used.

Definition at line 1163 of file SparseMatrix.h.

§ Index()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::Index ( )

Precompute indices to speed up successive row and column operations. Not required for operations that only act on entries of a given row in case of the CRS layout or columns in case of CCS layout. Column (row) operations on a matrix in CRS (CCS) layout are significantly more efficient after a call to this function, which however requires O(NNZ) more memory.

Note: The precomputed index is automatically cleared whenever a new non-zero entry is inserted or an existing one is removed.

Definition at line 944 of file SparseMatrix.h.

§ MakeSymmetric()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::MakeSymmetric ( bool extent = false )

Make square matrix symmetric by adding its transpose and divide by 2

Parameters

[in] extent Whether to copy the entry of existing entries to their respective transpose entries without dividing by two. This option can be used to create a symmetric matrix from a lower or upper triangular matrix by simply adding the transpose of the triangular matrix to this (while leaving the diagonal entries unmodified).

Definition at line 1796 of file SparseMatrix.h.

§ MultAv()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::MultAv	(	EntryType	v[],
		EntryType	w[]
	)		const

Multiply matrix by vector, used to interface with ARPACK

Note: This function is most efficient when the CRS layout is used.

Definition at line 1649 of file SparseMatrix.h.

§ operator()()

template<class TEntry >

TEntry & mirtk::GenericSparseMatrix< TEntry >::operator()	(	int	r,
		int	c = `-1`
	)

Get reference to (non-zero) matrix entry

Attention: This operator always inserts a new entry if none exists. Use Put to set an entry to zero and remove the previous non-zero entry from the sparse matrix. Do not use to iterate over all matrix entries as otherwise a new entry is added for each matrix row and column index pair! Use Get instead.

Remarks: This function is not thread-safe if non-zero entry does not exist.

Definition at line 991 of file SparseMatrix.h.

§ Put()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::Put	(	int	r,
		int	c,
		EntryType	v
	)

Set value

Remarks: This function is not thread-safe if non-zero entry does not exist.

Definition at line 1034 of file SparseMatrix.h.

§ ReadMAT()

template<class TEntry >

bool mirtk::GenericSparseMatrix< TEntry >::ReadMAT	(	const char *	fname,
		const char *	varname = `"A"`
	)

Read sparse matrix from MAT-file

This function is most efficient when the CCS layout is used.

Note: Use this function only when MIRTK_Numerics_WITH_MATLAB is 1.

Definition at line 1894 of file SparseMatrix.h.

§ Row() [1/2]

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::Row	(	int	r,
		Entries &	row,
		bool	as_is = `false`
	)

Set non-zero entries of specified row

Note: More efficient then Put when the CRS layout is used. Implicitly sorts the input entries.

Remarks: This function is not thread-safe.

Definition at line 1094 of file SparseMatrix.h.

§ Row() [2/2]

template<class TEntry >

GenericSparseMatrix< TEntry >::Entries mirtk::GenericSparseMatrix< TEntry >::Row ( int r ) const

Get non-zero entries of specified row

Note: This function is most efficient when the CRS layout is used.

Definition at line 1195 of file SparseMatrix.h.

§ RowSum()

template<class TEntry >

TEntry mirtk::GenericSparseMatrix< TEntry >::RowSum ( int r ) const

Calculate sum of all entries in specified row

Note: This function is most efficient when the CRS layout is used.

Definition at line 1592 of file SparseMatrix.h.

§ ScaleCol()

template<class TEntry >

GenericSparseMatrix< TEntry > & mirtk::GenericSparseMatrix< TEntry >::ScaleCol	(	int	c,
		EntryType	s
	)

Multiply specified column by a scalar

Note: This function is most efficient when the CCS layout is used.

Definition at line 1760 of file SparseMatrix.h.

§ ScaleColumn()

template<class TEntry >

GenericSparseMatrix< TEntry > & mirtk::GenericSparseMatrix< TEntry >::ScaleColumn	(	int	c,
		EntryType	s
	)

Multiply specified column by a scalar

Note: This function is most efficient when the CCS layout is used.

Definition at line 1736 of file SparseMatrix.h.

§ ScaleRow()

template<class TEntry >

GenericSparseMatrix< TEntry > & mirtk::GenericSparseMatrix< TEntry >::ScaleRow	(	int	r,
		EntryType	s
	)

Multiply specified row by a scalar

Note: This function is most efficient when the CRS layout is used.

Definition at line 1712 of file SparseMatrix.h.

§ Transpose()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::Transpose ( bool keep_layout = false )

Transpose matrix

Parameters

[in] keep_layout Whether to keep the storage layout. If false, transposing a CRS matrix is achieved by simply changing to CCS and vice versa.

Definition at line 1568 of file SparseMatrix.h.

§ WriteMAT()

template<class TEntry >

bool mirtk::GenericSparseMatrix< TEntry >::WriteMAT	(	const char *	fname,
		const char *	varname = `"A"`
	)		const

Write sparse matrix to MAT-file

This function is most efficient when the CCS layout is used.

Note: Use this function only when MIRTK_Numerics_WITH_MATLAB is 1.

Definition at line 1916 of file SparseMatrix.h.

§ WriteMFile()

template<class TEntry >

void mirtk::GenericSparseMatrix< TEntry >::WriteMFile	(	const char *	fname,
		const char *	varname = `"A"`
	)		const

Write matrix to MATLAB script

This function is most efficient when the CCS layout is used.

Definition at line 1939 of file SparseMatrix.h.

Member Data Documentation

§ _Col

template<class TEntry>

int* mirtk::GenericSparseMatrix< TEntry >::_Col

protected

CRS: Column indices of non-zero entries CCS: Index of first non-zero entry in i-th column

Definition at line 101 of file SparseMatrix.h.

§ _Index

template<class TEntry>

Array<int>* mirtk::GenericSparseMatrix< TEntry >::_Index

protected

CRS: Indices of non-zero entries for each column CCS: Indices of non-zero entries for each row

Definition at line 108 of file SparseMatrix.h.

§ _Row

template<class TEntry>

int* mirtk::GenericSparseMatrix< TEntry >::_Row

protected

CRS: Index of first non-zero entry in i-th row CCS: Row indices of non-zero entries

Definition at line 97 of file SparseMatrix.h.

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

SparseMatrix.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

template<class TEntry> class mirtk::GenericSparseMatrix< TEntry >

Member Enumeration Documentation

§ StorageLayout

Member Function Documentation

§ Col() [1/2]

§ Col() [2/2]

§ ColSum()

§ Column() [1/2]

§ Column() [2/2]

§ ColumnSum()

§ Eigenvalues()

§ Eigenvectors() [1/2]

§ Eigenvectors() [2/2]

§ GetCol()

§ GetColumn()

§ GetRow()

§ Index()

§ MakeSymmetric()

§ MultAv()

§ operator()()

§ Put()

§ ReadMAT()

§ Row() [1/2]

§ Row() [2/2]

§ RowSum()

§ ScaleCol()

§ ScaleColumn()

§ ScaleRow()

§ Transpose()

§ WriteMAT()

§ WriteMFile()

Member Data Documentation

§ _Col

§ _Index

§ _Row

template<class TEntry>
class mirtk::GenericSparseMatrix< TEntry >