Class for representing a system matrix on an unstructured sparse form. More...

#include <SparseMatrix.h>

Inheritance diagram for SparseMatrix:

Collaboration diagram for SparseMatrix:

[legend]

Public Types
enum	SparseSolver { NONE , SUPERLU , S_A_M_G , UMFPACK }
	Available equation solvers for this matrix type.

Public Member Functions
	SparseMatrix (SparseSolver eqSolver=NONE, int nt=1)
	Default constructor creating an empty matrix.

	SparseMatrix (size_t m, size_t n=0, SparseSolver eqsolver=NONE)
	Constructor creating a \(m \times n\) matrix.

	SparseMatrix (const SparseMatrix &B)
	Copy constructor.

virtual	~SparseMatrix ()
	The destructor frees the dynamically allocated arrays.

virtual LinAlg::MatrixType	getType () const
	Returns the matrix type.

virtual SystemMatrix *	copy () const
	Creates a copy of the system matrix and returns a pointer to it.

virtual bool	lockPattern (bool doLock)
	Locks or unlocks the sparsity pattern. More...

void	resize (size_t r, size_t c=0, bool forceEditable=false)
	Resizes the matrix to dimension \(r \times c\). More...

bool	redim (size_t r, size_t c)
	Resizes the matrix to dimension \(r \times c\). More...

size_t	rows () const
	Query number of matrix rows.

size_t	cols () const
	Query number of matrix columns.

size_t	size () const
	Query total matrix size in terms of number of non-zero elements.

virtual size_t	dim (int idim=1) const
	Returns the dimension of the system matrix. More...

Real &	operator() (size_t r, size_t c)
	Index-1 based element access.

const Real &	operator() (size_t r, size_t c) const
	Index-1 based element reference.

const ValueMap &	getValues () const
	For traversal of the non-zero elements of an editable matrix.

void	printSparsity (std::ostream &os) const
	Print sparsity pattern - for inspection purposes.

void	printFull (std::ostream &os) const
	Print the matrix in full rectangular form. More...

virtual void	dump (std::ostream &os, LinAlg::StorageFormat format, const char *label)
	Dumps the system matrix on a specified format.

virtual void	initAssembly (const SAM &sam, char preAssembly)
	Initializes the element assembly process. More...

void	preAssemble (const SAM &sam, bool delayLocking)
	Initializes the element sparsity pattern based on node connections. More...

virtual void	preAssemble (const std::vector< IntVec > &MMNPC, size_t nel=0)
	Initializes the element sparsity pattern based on node connections. More...

virtual void	compressPattern ()
	Compresses the sparsity pattern.

virtual void	init ()
	Initializes the matrix to zero assuming it is properly dimensioned.

virtual bool	assemble (const Matrix &eM, const SAM &sam, int e)
	Adds an element matrix into the associated system matrix. More...

virtual bool	assemble (const Matrix &eM, const SAM &sam, SystemVector &B, int e)
	Adds an element matrix into the associated system matrix. More...

virtual bool	assemble (const Matrix &eM, const SAM &sam, SystemVector &B, const IntVec &meq)
	Adds an element matrix into the associated system matrix. More...

virtual bool	assemble (const Matrix &eM, const IntVec &meq)
	Adds an element matrix into the associated system matrix. More...

bool	assembleCol (const RealArray &V, const SAM &sam, int n, size_t col)
	Adds a nodal vector into columns of a non-symmetric sparse matrix. More...

bool	assembleCol (Real val, const SAM &sam, int n, size_t col)
	Adds a scalar value into columns of a non-symmetric sparse matrix. More...

virtual bool	augment (const SystemMatrix &B, size_t r0, size_t c0)
	Augments a similar matrix symmetrically to the current matrix. More...

virtual bool	truncate (Real threshold=Real(1.0e-16))
	Truncates all small matrix elements to zero. More...

virtual void	mult (Real alpha)
	Multiplication with a scalar.

virtual bool	add (const SystemMatrix &B, Real alpha)
	Adds a matrix with similar sparsity pattern to the current matrix. More...

virtual bool	add (Real sigma, int ieq)
	Adds the constant σ to the diagonal of this matrix.

virtual bool	multiply (const SystemVector &B, SystemVector &C) const
	Performs the matrix-vector multiplication C = this B.

virtual bool	solve (SystemVector &B, Real *rc=nullptr)
	Solves the linear system of equations for a given right-hand-side. More...

void	calcCSR (IntVec &iA, IntVec &jA) const
	Calculates compressed-sparse-row arrays from the element map. More...

bool	split (std::array< SparseMatrix, 4 > &Asub, const IntVec &meqn2) const
	Splits the matrix into four sub-matrices, A11, A12, A21, A22. More...

bool	getColumn (size_t c, Vector &col) const
	Extracts a specified column from the matrix. More...

virtual Real	Linfnorm () const
	Returns the L-infinity norm of the matrix.

bool	isFactored () const
	Returns whether the matrix has been factored or not.

virtual bool	solve (SystemVector &b, Real *rc=nullptr)=0
	Solves the linear system of equations for a given right-hand-side. More...

virtual bool	solve (const SystemVector &b, SystemVector &x)
	Solves the linear system of equations for a given right-hand-side. More...

Public Member Functions inherited from SystemMatrix
virtual	~SystemMatrix ()
	Empty destructor.

virtual bool	empty () const
	Checks if the matrix is empty.

bool	isZero () const
	Checks if the matrix have no non-zero contributions.

void	initNonZeroEqs ()
	Initializes the nonZeroEqs flags.

bool	flagNonZeroEqs (const IntVec &meq={})
	Flags the equations meq as pivots with non-zero contributions.

bool	flagNonZeroEqs (const SystemMatrix &B)
	Flags the non-zero equations from B as non-zero pivots in this.

virtual bool	endAssembly ()
	Finalizes the system matrix assembly. More...

virtual bool	solve (const SystemVector &b, SystemVector &x)
	Solves the linear system of equations for a given right-hand-side. More...

virtual void	dump (const char *fileName, std::streamsize precision=0, LinAlg::StorageFormat format=LinAlg::FLAT)
	Dumps the system matrix to specified file.

virtual bool	load (const char *, bool=false)
	Loads the system matrix from specified file.

StdVector	operator* (const SystemVector &b) const
	Calculates a matrix-vector product.

StdVector	operator/ (const SystemVector &b)
	Solves a linear equation system.

Static Public Attributes
static bool	printSLUstat = false
	Print solution statistics for SuperLU?

Protected Member Functions
bool	optimiseRows (bool transposed=false)
	Converts the matrix to an optimized row-oriented format.

bool	optimiseCols ()
	Converts the matrix to an optimized column-oriented format. More...

bool	optimiseCols (const std::vector< std::set< int > > &dofc)
	Converts the matrix to an optimized column-oriented format. More...

bool	solveSAMG (Vector &B)
	Invokes the SAMG equation solver for a given right-hand-side. More...

bool	solveSLU (Vector &B)
	Invokes the SuperLU equation solver for a given right-hand-side. More...

bool	solveSLUx (Vector &B, Real *rcond)
	Invokes the SuperLU equation solver for a given right-hand-side. More...

bool	solveUMF (Vector &B, Real *rcond)
	Invokes the UMFPACK equation solver for a given right-hand-side. More...

virtual std::ostream &	write (std::ostream &os) const
	Writes the system matrix to the given output stream.

Protected Member Functions inherited from SystemMatrix
	SystemMatrix ()
	Default constructor.

	SystemMatrix (const SystemMatrix &a)
	Copy constructor.

Protected Attributes
bool	factored
	Set to true when the matrix is factorized.

IntVec	IA
	Identifies the beginning of each row or column.

IntVec	JA
	Specifies column/row index of each nonzero element.

Vector	A
	Stores the nonzero matrix elements.

Private Attributes
char	editable
	Flag for the editability of the matrix elements. More...

size_t	nrow
	Number of matrix rows.

size_t	ncol
	Number of matrix columns.

ValueMap	elem
	Stores nonzero matrix elements with index pairs.

SparseSolver	solver
	Which equation solver to use.

SuperLUdata *	slu
	Matrix data for the SuperLU equation solver.

int	numThreads
	Number of threads to use for the SuperLU_MT solver.

void *	umfSymbolic
	Symbolically factored matrix for UMFPACK.

Additional Inherited Members
Static Public Member Functions inherited from SystemMatrix
static SystemMatrix *	create (const ProcessAdm *adm, LinAlg::MatrixType mType, int num_thread_SLU=1)
	Static method creating a matrix of the given type.

static SystemMatrix *	create (const ProcessAdm *adm, LinAlg::MatrixType mType, const LinSolParams &spar)
	Static method creating a matrix of the given type.

Detailed Description

Class for representing a system matrix on an unstructured sparse form.

The sparse matrix is editable in the sense that non-zero entries may be added at arbitrary locations. The class comes with methods for solving a linear system of equations based on the current matrix and a given RHS-vector, using either the commercial SAMG package or the public domain SuperLU package.

Member Function Documentation

◆ add()

bool SparseMatrix::add	(	const SystemMatrix &	B,
		Real	alpha
	)

virtual

Adds a matrix with similar sparsity pattern to the current matrix.

Parameters

[in]	B	The matrix to be added
[in]	alpha	Scale factor for matrix B

Reimplemented from SystemMatrix.

References A, utl::vector< T >::add(), editable, elem, SystemMatrix::flagNonZeroEqs(), IA, SystemMatrix::isZero(), JA, ncol, nrow, utl::vector< T >::size(), and solver.

◆ assemble() [1/4]

bool SparseMatrix::assemble	(	const Matrix &	eM,
		const IntVec &	meq
	)

virtual

Adds an element matrix into the associated system matrix.

Parameters

[in]	eM	The element matrix
[in]	meq	Matrix of element equation numbers (0 based)

Returns: true on successful assembly, otherwise false

To be used when there is no underlying SAM

Implements SystemMatrix.

References utl::matrix< T >::cols(), and utl::matrix< T >::rows().

◆ assemble() [2/4]

bool SparseMatrix::assemble	(	const Matrix &	eM,
		const SAM &	sam,
		int	e
	)

virtual

Adds an element matrix into the associated system matrix.

Parameters

[in]	eM	The element matrix
[in]	sam	Auxiliary data for FE assembly management
[in]	e	Identifier for the element that eM belongs to

Returns: true on successful assembly, otherwise false

Implements SystemMatrix.

References assemSparse(), SystemMatrix::flagNonZeroEqs(), SAM::getElmEqns(), SAM::meqn, SAM::mmceq, SAM::mpmceq, utl::matrix< T >::rows(), and SAM::ttcc.

◆ assemble() [3/4]

bool SparseMatrix::assemble	(	const Matrix &	eM,
		const SAM &	sam,
		SystemVector &	B,
		const IntVec &	meq
	)

virtual

Adds an element matrix into the associated system matrix.

Parameters

[in]	eM	The element matrix
[in]	sam	Auxiliary data for FE assembly management
	B	The system right-hand-side vector
[in]	meq	Matrix of element equation numbers

Returns: true on successful assembly, otherwise false

When multi-point constraints are present, contributions from these are also added into the system right-hand-side vector, B.

Implements SystemMatrix.

References assemSparse(), utl::matrix< T >::cols(), SystemMatrix::flagNonZeroEqs(), SAM::meqn, SAM::mmceq, SAM::mpmceq, utl::matrix< T >::rows(), and SAM::ttcc.

◆ assemble() [4/4]

bool SparseMatrix::assemble	(	const Matrix &	eM,
		const SAM &	sam,
		SystemVector &	B,
		int	e
	)

virtual

Adds an element matrix into the associated system matrix.

Parameters

[in]	eM	The element matrix
[in]	sam	Auxiliary data for FE assembly management
	B	The system right-hand-side vector
[in]	e	Identifier for the element that eM belongs to

Returns: true on successful assembly, otherwise false

When multi-point constraints are present, contributions from these are also added into the system right-hand-side vector, B.

Implements SystemMatrix.

References assemSparse(), SystemMatrix::flagNonZeroEqs(), SAM::getElmEqns(), SAM::meqn, SAM::mmceq, SAM::mpmceq, utl::matrix< T >::rows(), and SAM::ttcc.

◆ assembleCol() [1/2]

bool SparseMatrix::assembleCol	(	const RealArray &	V,
		const SAM &	sam,
		int	n,
		size_t	col
	)

Adds a nodal vector into columns of a non-symmetric sparse matrix.

Parameters

[in]	V	The nodal vector
[in]	sam	Auxiliary data for FE assembly management
[in]	n	Identifier for the node that V belongs to
[in]	col	Index of first column which should receive contributions

Returns: true on successful assembly, otherwise false

This method can be used for rectangular matrices whose rows correspond to the equation ordering from the provided sam object.

References assemSparse(), SystemMatrix::flagNonZeroEqs(), SAM::getNodeEqns(), SAM::meqn, SAM::mmceq, SAM::mpmceq, ncol, and SAM::ttcc.

Referenced by assembleCol().

◆ assembleCol() [2/2]

bool SparseMatrix::assembleCol	(	Real	val,
		const SAM &	sam,
		int	n,
		size_t	col
	)

inline

Adds a scalar value into columns of a non-symmetric sparse matrix.

Parameters

[in]	val	The value to add for each DOF of the specified node
[in]	sam	Auxiliary data for FE assembly management
[in]	n	Identifier for the node that val belongs to
[in]	col	Index of first column which should receive contributions

Returns: true on successful assembly, otherwise false

This method can be used for rectangular matrices whose rows correspond to the equation ordering from the provided sam object.

References assembleCol().

◆ augment()

bool SparseMatrix::augment	(	const SystemMatrix &	B,
		size_t	r0,
		size_t	c0
	)

virtual

Augments a similar matrix symmetrically to the current matrix.

Parameters

[in]	B	The matrix to be augmented
[in]	r0	Row offset for the augmented matrix
[in]	c0	Column offset for the augmented matrix

Reimplemented from SystemMatrix.

References editable, elem, ncol, and nrow.

◆ calcCSR()

void SparseMatrix::calcCSR	(	IntVec &	iA,
		IntVec &	jA
	)		const

Calculates compressed-sparse-row arrays from the element map.

Parameters

[out]	iA	Start index of each row in jA
[out]	jA	Column indices

References elem, and nrow.

◆ dim()

size_t SparseMatrix::dim ( int idim = 1 ) const

virtual

Returns the dimension of the system matrix.

Parameters

[in] idim Which direction to return the dimension in.

Implements SystemMatrix.

Reimplemented in ISTLMatrix.

References ncol, nrow, and size().

Referenced by L2GlobalInt::assemble(), GlbL2::solve(), and solve().

◆ getColumn()

bool SparseMatrix::getColumn	(	size_t	c,
		Vector &	col
	)		const

Extracts a specified column from the matrix.

Parameters

[in]	c	One-based column index
[out]	col	Extracted column data

References elem, ncol, nrow, and utl::vector< T >::resize().

◆ initAssembly()

void SparseMatrix::initAssembly	(	const SAM &	sam,
		char	preAssembly
	)

virtual

Initializes the element assembly process.

Parameters

[in]	sam	Auxiliary data describing the FE model topology, etc.
[in]	preAssembly	Flag for doing preassembly F : Force preassembly always, and lock the sparsity pattern f : Force preassembly always, but delay locking the sparsity pattern d : Do preassembly only if multi-threaded assembly, but delay locking the sparsity pattern 0 : Do preassembly if multi-threading, and lock parsity pattern

Implements SystemMatrix.

Reimplemented in ISTLMatrix.

References SAM::neq, preAssemble(), and resize().

◆ lockPattern()

bool SparseMatrix::lockPattern ( bool doLock )

virtual

Locks or unlocks the sparsity pattern.

Parameters

[in] doLock If true, lock pattern, otherwise unlock it

Returns: true, if the pattern already was locked

Reimplemented from SystemMatrix.

References editable.

◆ optimiseCols() [1/2]

bool SparseMatrix::optimiseCols ( )

protected

Converts the matrix to an optimized column-oriented format.

This method is based on the function dreadtriple() from the SuperLU package.

References A, editable, elem, IA, JA, ncol, nrow, utl::vector< T >::resize(), and size().

Referenced by compressPattern(), preAssemble(), solveSLU(), solveSLUx(), and solveUMF().

◆ optimiseCols() [2/2]

bool SparseMatrix::optimiseCols ( const std::vector< std::set< int > > & dofc )

protected

Converts the matrix to an optimized column-oriented format.

Parameters

[in] dofc Set of free DOFs coupled to each free DOF

This method does not use the internal index-pair to value map elem.

References A, editable, IA, JA, ncol, nrow, and utl::vector< T >::resize().

◆ preAssemble() [1/2]

void SparseMatrix::preAssemble	(	const SAM &	sam,
		bool	delayLocking
	)

Initializes the element sparsity pattern based on node connections.

Parameters

[in]	sam	Auxiliary data describing the FE model topology, etc.
[in]	delayLocking	If true, do not lock the sparsity pattern yet

References IFEM::cout, editable, SAM::getDofCouplings(), ncol, nrow, optimiseCols(), optimiseRows(), size(), and solver.

Referenced by initAssembly(), ISTLMatrix::initAssembly(), and GlbL2::preAssemble().

◆ preAssemble() [2/2]

void SparseMatrix::preAssemble	(	const std::vector< IntVec > &	MMNPC,
		size_t	nel = `0`
	)

virtual

Initializes the element sparsity pattern based on node connections.

Parameters

[in]	MMNPC	Matrix of matrices of nodal point correspondances
[in]	nel	Number of elements to consider (if zero use MMNPC.size())

Reimplemented from SystemMatrix.

References compressPattern().

◆ printFull()

void SparseMatrix::printFull ( std::ostream & os ) const

Print the matrix in full rectangular form.

Warning: Not recommended for matrices of nontrivial size.

References ncol, and nrow.

◆ redim()

bool SparseMatrix::redim	(	size_t	r,
		size_t	c
	)

Resizes the matrix to dimension \(r \times c\).

Will preserve existing matrix content within the new dimension.

References editable, elem, ncol, and nrow.

◆ resize()

void SparseMatrix::resize	(	size_t	r,
		size_t	c = `0`,
		bool	forceEditable = `false`
	)

Resizes the matrix to dimension \(r \times c\).

Will erase previous content, also if the size is unchanged. If the size is not changed, the sparsity pattern stored in the members IA and JA is retained such that subsequent matrix assembly steps may be performed directly into the optimized storage format, unless forceEditable is true.

References A, utl::vector< T >::begin(), utl::vector< T >::clear(), editable, elem, utl::vector< T >::end(), factored, IA, JA, ncol, nrow, Real, slu, and umfSymbolic.

Referenced by ASMu2D::edgeL2projection(), ASMu3D::faceL2projection(), init(), initAssembly(), ISTLMatrix::initAssembly(), ASMu2D::regularInterpolation(), and ASMu3D::regularInterpolation().

◆ solve() [1/3]

virtual bool SystemMatrix::solve

inline

Solves the linear system of equations for a given right-hand-side.

Parameters

[in]	b	Right-hand-side vector
[out]	x	Solution vector

◆ solve() [2/3]

bool SparseMatrix::solve	(	SystemVector &	B,
		Real *	rc = `nullptr`
	)

virtual

Solves the linear system of equations for a given right-hand-side.

Parameters

	B	Right-hand-side vector on input, solution vector on output
[out]	rc	Reciprocal condition number of the LHS-matrix (optional)

Implements SystemMatrix.

Reimplemented in ISTLMatrix.

References dim(), solver, solveSAMG(), solveSLUx(), and solveUMF().

Referenced by ASMu2D::regularInterpolation(), ASMu3D::regularInterpolation(), and GlbL2::solve().

◆ solve() [3/3]

virtual bool SystemMatrix::solve

Solves the linear system of equations for a given right-hand-side.

Parameters

	b	Right-hand-side vector on input, solution vector on output
[out]	rc	Reciprocal condition number of the LHS-matrix (optional)

◆ solveSAMG()

bool SparseMatrix::solveSAMG ( Vector & B )

protected

Invokes the SAMG equation solver for a given right-hand-side.

Parameters

B	Right-hand-side vector on input, solution vector on output

References A, factored, IA, JA, optimiseRows(), utl::vector< T >::ptr(), Real, rows(), LinAlg::SAMG, utl::vector< T >::size(), size(), and utl::vector< T >::swap().

Referenced by solve().

◆ solveSLU()

bool SparseMatrix::solveSLU ( Vector & B )

protected

Invokes the SuperLU equation solver for a given right-hand-side.

Parameters

B	Right-hand-side vector on input, solution vector on output

This method uses the simple driver dgssv or its multi-threaded equivalent pdgssv.

References A, factored, IA, JA, ncol, nrow, numThreads, optimiseCols(), printSLUstat, utl::vector< T >::ptr(), utl::vector< T >::size(), and slu.

◆ solveSLUx()

bool SparseMatrix::solveSLUx	(	Vector &	B,
		Real *	rcond
	)

protected

Invokes the SuperLU equation solver for a given right-hand-side.

Parameters

	B	Right-hand-side vector on input, solution vector on output
[out]	rcond	Reciprocal condition number of the LHS-matrix (optional)

This method uses the expert driver dgssvx or its multi-threaded equivalent pdgssvx.

References A, IFEM::cout, factored, IA, JA, ncol, nrow, numThreads, optimiseCols(), printSLUstat, utl::vector< T >::ptr(), Real, utl::vector< T >::size(), slu, and utl::vector< T >::swap().

Referenced by solve().

◆ solveUMF()

bool SparseMatrix::solveUMF	(	Vector &	B,
		Real *	rcond
	)

protected

Invokes the UMFPACK equation solver for a given right-hand-side.

Parameters

	B	Right-hand-side vector on input, solution vector on output
[out]	rcond	Reciprocal condition number of the LHS-matrix (optional)

References A, factored, IA, JA, ncol, nrow, optimiseCols(), utl::vector< T >::ptr(), utl::vector< T >::size(), and umfSymbolic.

Referenced by solve().

◆ split()

bool SparseMatrix::split	(	std::array< SparseMatrix, 4 > &	Asub,
		const IntVec &	meqn2
	)		const

Splits the matrix into four sub-matrices, A11, A12, A21, A22.

Parameters

[out]	Asub	The resulting four sub-matrices
[in]	meqn2	List of equation numbers in the A22-matrix

References elem, ncol, nrow, and solver.

Referenced by AlgEqSystem::staticCondensation().

◆ truncate()

bool SparseMatrix::truncate ( Real threshold = Real(1.0e-16) )

virtual

Truncates all small matrix elements to zero.

Parameters

[in] threshold Zero tolerance relative to largest diagonal element

Reimplemented from SystemMatrix.

References IFEM::cout, editable, elem, and Real.

Member Data Documentation

◆ editable

char SparseMatrix::editable

private

Flag for the editability of the matrix elements.

'V' : Values may be edited but the pattern is temporarily locked
'P' : Both values and pattern may be edited
'\0' : Values may be edited but the pattern is permanently locked

Referenced by add(), augment(), dump(), Linfnorm(), lockPattern(), mult(), multiply(), operator()(), optimiseCols(), optimiseRows(), preAssemble(), printSparsity(), redim(), resize(), size(), SparseMatrix(), truncate(), and write().

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

src/LinAlg/SparseMatrix.h
src/LinAlg/SparseMatrix.C

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ add()

◆ assemble() [1/4]

◆ assemble() [2/4]

◆ assemble() [3/4]

◆ assemble() [4/4]

◆ assembleCol() [1/2]

◆ assembleCol() [2/2]

◆ augment()

◆ calcCSR()

◆ dim()

◆ getColumn()

◆ initAssembly()

◆ lockPattern()

◆ optimiseCols() [1/2]

◆ optimiseCols() [2/2]

◆ preAssemble() [1/2]

◆ preAssemble() [2/2]

◆ printFull()

◆ redim()

◆ resize()

◆ solve() [1/3]

◆ solve() [2/3]

◆ solve() [3/3]

◆ solveSAMG()

◆ solveSLU()

◆ solveSLUx()

◆ solveUMF()

◆ split()

◆ truncate()

Member Data Documentation

◆ editable