The standard 'Sparse' matrix based on Armadillo. More...

#include <gmArmadilloSolverMatrix.h>

Inheritance diagram for GmArmadilloSparseSolverMatrix:

Collaboration diagram for GmArmadilloSparseSolverMatrix:

[legend]

Public Member Functions
	GmArmadilloSparseSolverMatrix (int nlin, int ncol, GmSparseMatrixOptions options)
	Constructor. Receives as parameters the matrix size.

virtual	~GmArmadilloSparseSolverMatrix ()
	Destructor.

virtual bool	supportsBatchInsert () const
	Does this matrix supports batch inserts? See comments on the class documentation.

virtual ParallelAddMode	supportedParallelAddMode () const
	Returns the supported mode for calling add.

virtual bool	beginBatchInsert (size_t expectedEntries=0)
	Begins a batch insert process. Important: see comments on the class documentation. More...

virtual bool	endBatchInsert (bool discardData=false)
	Ends a batch insert process. Important: see comments on the class documentation. More...

virtual bool	supportsRandomSet () const
	Does this matrix supports setting a value on a random position outside the matrix initialization process (either by a batch insert or a layout builder)?

virtual int	layoutSize () const
	Returns the size of the sparse matrix layout. More...

virtual void	add (int lin, int col, double val)
	Adds the given value to the value in the position Mat[lin][col]. More...

virtual void	clearLineAndColumnSet (const QList< int > &indexList, bool setDiagonal, bool keepSparseLayout)
	Clears a set of lines and columns from the matrix, filling them with zeroes, optionally puting a 1.0 at the diagonal. More...

virtual void	matAdd (const GmVector &a, const GmVector &b, double zeroTol=0.0)
	Adds to the current matrix ('X') the (dense) matrix resulting from multiplying the column vector 'a' by the transpose of the column vector 'b' (X = X + a * b.t()). More...

virtual void	set (int lin, int col, double val)
	Sets the value in the position Mat[lin][col] to the specified value. More...

virtual void	set (GmSolverMatrix A, GmSolverMatrix B, double c, bool sameStructure)
	Sets the values of the whole matrix to the result of the expresion A + c * B, where A and B are matrices with the same size as this one and c is a constant. More...

virtual void	columnMulAdd (int col, GmVector &f, double v, const bool *skipRows=NULL) const
	Updates the given vector adding to it a matrix column multiplied by a scalar value. More...

virtual size_t	usedMemory () const
	Returns an estimative of the memory used by the matrix in bytes. More...

Public Member Functions inherited from GmArmadilloSolverMatrixBase< arma::sp_mat >
	GmArmadilloSolverMatrixBase (int nlin, int ncol, GmSparseMatrixOptions options=GmSparseMatrixOptions(GM_ARMADILLO_TRIPLET_LIST))
	Constructor. Receives as parameters the matrix size.

virtual	~GmArmadilloSolverMatrixBase ()
	Destructor.

virtual bool	supportsSparseLayouts () const
	Does this matrix supports sparse layouts? See comments on the class documentation.

virtual GmSparseMatrixLayoutBuilder *	layoutBuilder () const
	If the matrix supports sparse layouts, returns a builder object that can be used to initialize the matrix layout. Otherwise returns NULL. If the layout is being shared by several matrices, only the main matrix, owning the layout should return it.

virtual bool	emptyLayout () const
	If the matrix supports sparse layouts and the layout is currently empty, returns true. Otherwise, returns false.

virtual bool	symmetric () const
	Returns true if the matrix was marked as symmetric by setSymmetric() (it does not check for matrix symmetry itself) More...

virtual void	setSymmetric (bool sym)
	Marks the matrix as symmetric or not. More...

virtual int	nlin () const
	Returns the number of lines in the matrix. IMPORTANT: This function implementation MUST be thread safe.

virtual int	ncol () const
	Returns the number of columns in the matrix. IMPORTANT: This function implementation MUST be thread safe.

virtual double	at (int lin, int col) const
	Returns the value in the position Mat[lin][col].

virtual bool	inLayout (int lin, int col) const
	Returns true if the given position belongs to the matrix sparse layout. More...

virtual void	clear (bool keepSparseLayout)
	Clears the matrix, filling it with zeros. The keepSparseLayout flag is a hint that the matrix layout (non zero positions) will remain the same when the matrix is re-filled with data, and so, if the matrix supports sparse layouts, they should not be removed. This function marks the matrix as unsymmetric.

virtual void	ensureDiagonal ()
	Updates any zero diagonal value to 1.0. If diagonal values do not belong to the layout, the matrix must NOT be shared!

virtual void	mul (const GmVector &a, GmVector &b) const
	Multiplies the matrix ('X') by a vector 'a' storing the result in 'b' (b = X * a). More...

virtual void	mulAdd (const GmVector &a, GmVector &b) const
	Multiplies the matrix ('X') by a vector 'a' adding the result to 'b' (b = b + X * a). More...

virtual void	mulSub (const GmVector &a, GmVector &b) const
	Multiplies the matrix ('X') by a vector 'a' subtracting the result from 'b' (b = b - X * a). More...

arma::sp_mat &	armadilloMatrix ()
	Returns the internal Armadillo matrix.

Public Member Functions inherited from GmSolverMatrix
virtual	~GmSolverMatrix ()
	Virtual destructor.

double	operator() (int lin, int col) const
	Returns the value in the position Mat[lin][col]. More...

bool	isSymmetric (double relTol=GM_DOUBLECMP_RELTOL, double absTol=GM_DOUBLECMP_ABSTOL) const
	Returns true if the matrix is symmetric, false otherwise. More...

void	print (const GmLogCategory &logger, GmLogLevel level, int fieldWidth=0, char format='g', int precision=-1)
	Prints the matrix using the specified logger, level and precision fields.

Protected Attributes
GmSparseMatrixOptions	_opt
	The set of sparse matrix options, reused from GmSparseMatrix.

bool	_batch
	Are we in batch mode?

GmAppendBuffer< arma::uword > *	_positions
	The positions array ordered as (row, column) pairs while batch inserting values.

GmAppendBuffer< double > *	_values
	The values array while batch inserting values (size = _positions size / 2)

Protected Attributes inherited from GmArmadilloSolverMatrixBase< arma::sp_mat >
arma::sp_mat	_mat
	The Armadillo matrix.

QAtomicInt	_sym
	Flag marking the matrix as symmetric or not.

Private Member Functions
bool	doEnd (bool ordered)
	Work horse for endBatchInsert. If ordered is true, expects the list to have a single entry per (i,j) pair and entries to be ordered in column-major format.

virtual void	addFromThread (int tid, int lin, int col, double val)
	Simillar to add(int lin, int col, double val) but, when working with multiple threads, specifying the origin thread by a tid instead of getting that information from GmThreadManager::currentId(). Necessary when working with OpenMP threads (remember that for the Thread Manager the first worker thread has a tid of 1. 0 is for the main thread)

Additional Inherited Members
Public Types inherited from GmSolverMatrix
enum	ParallelAddMode { NO_SUPPORT, THREAD_SAFE_SUPPORT, REENTRANT_SUPPORT }
	Supported modes for calling add from multiple threads in parallel. More...

Detailed Description

The standard 'Sparse' matrix based on Armadillo.

Member Function Documentation

◆ add()

void GmArmadilloSparseSolverMatrix::add	(	int	lin,
		int	col,
		double	val
	)

virtual

Adds the given value to the value in the position Mat[lin][col].

In general this function can be used only to change values over positions that belong to the matrix sparse layout (its set of non zero positions) or inside a beginBatchInsert() / endBatchInsert() region. It can only be used to set values on random positions if supportsRandomSet() returns true.

See the class description for comments about calling this function from multiple threads in parallel.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ beginBatchInsert()

bool GmArmadilloSparseSolverMatrix::beginBatchInsert ( size_t expectedEntries = 0 )

virtual

Begins a batch insert process. Important: see comments on the class documentation.

The expectedEntries parameters is an estimative of the number of times that add() will be called for this beginBatchInsert() / endBatchInsert() block.

Uses a 64 bits value for the size since this list can grow quite quickly and a 32 bits limit can be achieved. An hex27 element with 5 dofs per node generates a 135 x 135 local matrix, translating into 135 * 135 = 18.225 calls to append() per mesh element. That will overflow a standard int with less than 120.000 elements.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ clearLineAndColumnSet()

void GmArmadilloSparseSolverMatrix::clearLineAndColumnSet	(	const QList< int > &	indexList,
		bool	setDiagonal,
		bool	keepSparseLayout
	)

virtual

Clears a set of lines and columns from the matrix, filling them with zeroes, optionally puting a 1.0 at the diagonal.

This function is semantically equivalent to the code below, but potentially quicker for sparse matrices. It should be used only for square matrices.

foreach(int i, indexList)
{
  clearLine(i);
  clearColumn(i)
  if(setDiagonal)
    set(i, i, 1.0);
}

If keepSparseLayout is set to true, matrix values will be changed without updating the internal matrix sparse layout. This can be important for performance if the matrix is later reused to host another set of values with the same layout as the one before removing the set of lines and columns.

IMPORTANT: When enabling both keepSparseLayout and setDiagonal, it is NECESSARY that the diagonal items of the selected rows belong to the current sparse layout. In most cases this is true anyway. Failing to do so will result in undefined behaviour.

If keepSpraseLayout is set to false, the matrix layout can NOT be shared with other matrices since this operation would change the layout.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ columnMulAdd()

void GmArmadilloSparseSolverMatrix::columnMulAdd	(	int	col,
		GmVector &	f,
		double	v,
		const bool *	skipRows = `NULL`
	)		const

virtual

Updates the given vector adding to it a matrix column multiplied by a scalar value.

Given the matrix column 'col', for each row 'i' in the matrix makes f[i] += Mat[i][col] * v. If the boolean vector skipRows is not NULL, the above operation will be executed only if skipRows[i] is not true.

This function is semantically equivalent to the code below, but potentially quicker for sparse matrices.

foreach row i in the matrix
{
  if(skipRows && skipRows[i])
    continue;
  f[i] += Mat(i, col) * v;
}

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ endBatchInsert()

bool GmArmadilloSparseSolverMatrix::endBatchInsert ( bool discardData = false )

virtual

Ends a batch insert process. Important: see comments on the class documentation.

The discardData parameter is a flag that when set to true informs that the matrix building process was interrupted and so the current matrix data is invalid and should be discarded.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ layoutSize()

virtual int GmArmadilloSparseSolverMatrix::layoutSize ( ) const

inlinevirtual

Returns the size of the sparse matrix layout.

The returned size is aproximatelly equal to the number of nonzero entries in the matrix. It will be different if the layout includes places for zero values that might change in the future. If the matriz does not have that information, returns -1.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ matAdd()

void GmArmadilloSparseSolverMatrix::matAdd	(	const GmVector &	a,
		const GmVector &	b,
		double	zeroTol = `0.0`
	)

virtual

Adds to the current matrix ('X') the (dense) matrix resulting from multiplying the column vector 'a' by the transpose of the column vector 'b' (X = X + a * b.t()).

In order to keep some kind of sparsisity of the matrix, if the resulting values is smaller than the given tolerance, it will not be stored (set to zero).

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ set() [1/2]

virtual void GmArmadilloSparseSolverMatrix::set	(	int	lin,
		int	col,
		double	val
	)

inlinevirtual

Sets the value in the position Mat[lin][col] to the specified value.

In general this function can be used only to set values over positions that belong to the matrix sparse layout (its set of non zero positions). It can only be used to set values on random positions if supportsRandomSet() returns true. (For performance reasons, no exception is made, even when setting a value of 0.0 over an already 0.0 value since that would probably add an if to the critical path).

This function can not be called at all while inside a beginBatchInsert() / endBatchInsert() region.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ set() [2/2]

void GmArmadilloSparseSolverMatrix::set	(	GmSolverMatrix *	A,
		GmSolverMatrix *	B,
		double	c,
		bool	sameStructure
	)

virtual

Sets the values of the whole matrix to the result of the expresion A + c * B, where A and B are matrices with the same size as this one and c is a constant.

Conceptually this operation is equivalent to calling set(i, j, A(i, j) + c * B(i, j)) for every line & column of the matrices, but when working with sparse matrices doing it in a batch can be much faster.

If sameStructure is set to true, this functions assumes that A, B and the current matrix object have all the SAME layout (same non-zero structure). When set to false, the matrix layout can not be shared with other matrices since it would change the layout.

Keep in mind that matrix A or matrix B CAN be equal to the current matrix (this).

If the current matrix is marked as symmetric and either A or B is not marked as symmetric, the current matrix will be marked as unsymmetric.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

◆ usedMemory()

size_t GmArmadilloSparseSolverMatrix::usedMemory ( ) const

virtual

Returns an estimative of the memory used by the matrix in bytes.

It returns in general the variable memory that depends on the number of set entries but does not include constant overheads used by the class for control

In particular, this method might return different values before and after a call to endBatchInsert(). If the matrix shares a layout with another matrix, only the layout owner will account for its size.

Reimplemented from GmArmadilloSolverMatrixBase< arma::sp_mat >.

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