An efficient implementation of a dynamically-allocated sparse 2D array. More...

#include <SparseMatrix.h>

Inheritance diagram for SparseMatrix:

[legend]

Collaboration diagram for SparseMatrix:

[legend]

Public Member Functions
	SparseMatrix (int r, int c, BGFLOAT m, TiXmlElement *e)

	SparseMatrix (int r, int c, BGFLOAT m, const char *v=nullptr)

	SparseMatrix (int r=1, int c=1)

	SparseMatrix (const SparseMatrix &oldM)
	Copy constructor. Performs a deep copy.

virtual	~SparseMatrix ()
	De-allocate storage.

SparseMatrix &	operator= (const SparseMatrix &rhs)
	Assignment operator.

BGFLOAT &	operator() (int r, int c)
	Access value of element at (row, column) – mutator.

int	size (void) const
	Returns the number of elements in the sparse matrix.

virtual void	Print (ostream &os) const override
	Polymorphic output. Produces text output on stream "os". Output is by row.

virtual string	toXML (string name="") const
	Produce XML representation of Matrix in string return value.

virtual const SparseMatrix	operator- () const

virtual const SparseMatrix	operator+ (const SparseMatrix &rhs) const

virtual const SparseMatrix	operator* (const SparseMatrix &rhs) const

Public Member Functions inherited from Matrix
virtual	~Matrix ()=default
	Virtual Destructor.

template<class Archive >
void	serialize (Archive &archive)
	Cereal serialization method.

Public Member Functions inherited from RecordableBase
template<class Archive >
void	serialize (Archive &archive)
	Cereal serialization method.

Protected Member Functions
void	clear (void)
	Frees up all dynamically allocated storage.

void	remove_lists (Element *el)

void	copy (const SparseMatrix &source)

void	alloc (void)

void	rowFromXML (TiXmlElement *rowElement)
	Reads a row of the sparse Matrix from XML.

Protected Member Functions inherited from Matrix
	Matrix (string t="", string i="", int r=0, int c=0, BGFLOAT m=0.0)

void	SetAttributes (string t, string i, int r, int c, BGFLOAT m, int d)
	Convenience mutator.

Protected Member Functions inherited from RecordableBase
	RecordableBase ()=default
	prevents any code outside this class from creating a RecordableBase object

Protected Attributes
int	dimensions
	One or two dimensional.

Protected Attributes inherited from Matrix
string	type

string	init

int	rows
	Number of rows in Matrix (>0)

int	columns
	Number of columns in Matrix (>0)

BGFLOAT	multiplier
	Constant used for initialization.

int	dimensions
	One or two dimensional.

Protected Attributes inherited from RecordableBase
std::string	basicDataType_
	the basic data type in the recorded variable

Friends
const VectorMatrix	operator* (const VectorMatrix &v, const SparseMatrix &m)

Detailed Description

An efficient implementation of a dynamically-allocated sparse 2D array.

This is a self-allocating and de-allocating 2D array that is optimized for numerical computation. It is modified from CompleteMatrix, but with a totally different, sparse implementation, including optimization of the math operations to take advantage of sparseness. More specifically, if the size of the array is NxN and the average number of non-zero entries in a row or column is M, then this implementation is intended to provide O(M) time scanning of all non-zero entries in a row or column and O(1) time access of the item at arbitrary location (i,j). The maximum number of items that a SparseMatrix can hold is sqrt(rows * columns).

This magic is accomplished by storing non-zero elements as part of three data structures simultaneously:

an element of a linked list of items in row i
an element of a linked list of items in column j
an element of a hash table with hashing function that uses both i and j. As a result, we can linearly scan a particular row or column to retrieve all of its elements, thus facilitating efficient math operations. We can also use the hash table to provide constant time random access by row and column, like a full 2D array would provide.

Definition at line 49 of file SparseMatrix.h.

Constructor & Destructor Documentation

◆ SparseMatrix() [1/4]

SparseMatrix::SparseMatrix	(	int	r,
		int	c,
		BGFLOAT	m,
		TiXmlElement *	e )

Allocate storage and initialize attributes for a sparse matrix with explicit row data. The parameter e is used as a source of data for initializing the matrix (and must be the pointer to the Matrix element in the XML).

Exceptions

Matrix_bad_alloc
Matrix_invalid_argument

Parameters

r	rows in Matrix
c	columns in Matrix
m	multiplier used for initialization
e	pointer to Matrix element in XML

@method SparseMatrix @discussion Allocate storage and initialize attributes for a sparse matrix with explicit row data. The parameter e is used as a source of data for initializing the matrix (and must be the pointer to the Matrix element in the XML).

Exceptions

Matrix_bad_alloc
Matrix_invalid_argument

Parameters

r	rows in Matrix
c	columns in Matrix
m	multiplier used for initialization
e	pointer to Matrix element in XML

Definition at line 174 of file SparseMatrix.cpp.

◆ SparseMatrix() [2/4]

SparseMatrix::SparseMatrix	(	int	r,
		int	c,
		BGFLOAT	m,
		const char *	v = nullptr )

Allocate storage and initialize attributes for a diagonal sparse matrix with explicit row data. The parameter v is used as a source of data for initializing the matrix (and must be a string of numbers equal to the number of rows or columns). If v is nullptr, then the multiplier is used to initialize the diagonal elements.

Exceptions

Matrix_bad_alloc
Matrix_invalid_argument

Parameters

r	rows in Matrix
c	columns in Matrix
m	multiplier used for initialization (and must be non-zero)
v	string of initialization values

@method SparseMatrix @discussion Allocate storage and initialize attributes for a diagonal sparse matrix with explicit row data. The parameter v is used as a source of data for initializing the matrix (and must be a string of numbers equal to the number of rows or columns).

Exceptions

Matrix_bad_alloc
Matrix_invalid_argument

Parameters

r	rows in Matrix
c	columns in Matrix
m	multiplier used for initialization
v	string of initialization values

Definition at line 215 of file SparseMatrix.cpp.

◆ SparseMatrix() [3/4]

SparseMatrix::SparseMatrix	(	int	r = 1,
		int	c = 1 )

Allocate storage and initialize attributes for an empty sparse matrix. This is also the default constructor.

Exceptions

Matrix_bad_alloc
Matrix_invalid_argument

Parameters

r	rows in Matrix
c	columns in Matrix

@method SparseMatrix @discussion Allocate storage and initialize attributes for an empty sparse matrix. This is also the default constructor.

Exceptions

Matrix_bad_alloc
Matrix_invalid_argument

Parameters

r	rows in Matrix
c	columns in Matrix

Definition at line 281 of file SparseMatrix.cpp.

◆ SparseMatrix() [4/4]

SparseMatrix::SparseMatrix ( const SparseMatrix & oldM )

Copy constructor. Performs a deep copy.

Parameters

oldM	The source SparseMatrix

Definition at line 307 of file SparseMatrix.cpp.

◆ ~SparseMatrix()

SparseMatrix::~SparseMatrix ( )

virtual

De-allocate storage.

Definition at line 335 of file SparseMatrix.cpp.

Member Function Documentation

◆ alloc()

void SparseMatrix::alloc ( void )

protected

Allocates storage for internal storage. Assumes that no storage has already been allocated (i.e., must call clear() before this if not in a constructor) and that all simple data members (specifically, rows and columns) have been correctly set.

Exceptions

Matrix_bad_alloc
MatrixException

Definition at line 475 of file SparseMatrix.cpp.

◆ clear()

void SparseMatrix::clear ( void )

protected

Frees up all dynamically allocated storage.

Definition at line 372 of file SparseMatrix.cpp.

◆ copy()

void SparseMatrix::copy ( const SparseMatrix & source )

protected

Performs a deep copy. It is assumed that the correct storage has already been allocated and all "simple" data members have already had their values copied.

Parameters

source VectorMatrix to copy from

Definition at line 414 of file SparseMatrix.cpp.

◆ operator()()

BGFLOAT & SparseMatrix::operator()	(	int	r,
		int	c )

Access value of element at (row, column) – mutator.

Constant time as long as number of items in the N x M SparseMatrix is less than 4*sqrt(N*M). If there is no element at the given location, then a zero value one is created. This is done because this method is usable as a mutator: it returns a reference to the value in the specified element. If this becomes a problem in other code, then the solution would be to add an accessor that either throws an exception if an element doesn't exist or that returns both the element value and a success/failure flag.

Parameters

r	element row
c	element column

Returns: reference to value of element at that location

@method operator() @discussion Access value of element at (row, column) – mutator. Constant time as long as number of items in the N x M SparseMatrix is less than 4*sqrt(N*M). If there is no element at the given location, then a zero value one is created.

Parameters

r	element row
c	element column

Returns: value of element at that location

Exceptions

Matrix_bad_alloc

Definition at line 549 of file SparseMatrix.cpp.

◆ operator*()

const SparseMatrix SparseMatrix::operator* ( const SparseMatrix & rhs ) const

virtual

Matrix product. Number of rows of "rhs" must equal to number of columns of this.

Exceptions

Matrix_domain_error

Parameters

rhs	right-hand argument to the product.

Returns: A SparseMatrix with number of rows equal to this and number of columns equal to "rhs".

Definition at line 601 of file SparseMatrix.cpp.

◆ operator+()

const SparseMatrix SparseMatrix::operator+ ( const SparseMatrix & rhs ) const

virtual

Compute the sum of two SparseMatrices of the same rows and columns.

Exceptions

Matrix_domain_error

Parameters

rhs	right-hand argument to the addition. Must have same dimensions as this.

Returns: A new SparseMatrix, with value equal to the sum of this one and rhs and rows and columns the same as both, returned by value.

Definition at line 594 of file SparseMatrix.cpp.

◆ operator-()

const SparseMatrix SparseMatrix::operator- ( ) const

virtual

Unary minus. Negate all elements of the SparseMatrix.

Returns: A new SparseMatrix, with same size as the current one.

Definition at line 575 of file SparseMatrix.cpp.

◆ operator=()

SparseMatrix & SparseMatrix::operator= ( const SparseMatrix & rhs )

Assignment operator.

Parameters

rhs	right-hand side of assignment

Returns: returns reference to this SparseMatrix (after assignment)

Definition at line 342 of file SparseMatrix.cpp.

◆ Print()

void SparseMatrix::Print ( ostream & os ) const

overridevirtual

Polymorphic output. Produces text output on stream "os". Output is by row.

Parameters

os	stream to output to

Implements Matrix.

Definition at line 500 of file SparseMatrix.cpp.

◆ remove_lists()

void SparseMatrix::remove_lists ( Element * el )

protected

Remove an Element from the SparseMatrix lists (but not the hash table). This is meant to be called from a HashTable method.

@method remove_lists @discussion Remove an Element from the SparseMatrix lists (but not the hash table). This is meant to be called from a HashTable method.

Definition at line 405 of file SparseMatrix.cpp.

◆ rowFromXML()

void SparseMatrix::rowFromXML ( TiXmlElement * rowElement )

protected

Reads a row of the sparse Matrix from XML.

Parameters

rowElement pointer to Row XML element

Exceptions

Matrix_invalid_argument

Definition at line 445 of file SparseMatrix.cpp.

◆ size()

int SparseMatrix::size ( void ) const

inline

Returns the number of elements in the sparse matrix.

Returns: number of elements

Definition at line 280 of file SparseMatrix.h.

◆ toXML()

string SparseMatrix::toXML ( string name = "" ) const

virtual

Produce XML representation of Matrix in string return value.

Definition at line 520 of file SparseMatrix.cpp.

Friends And Related Symbol Documentation

◆ operator*

const VectorMatrix operator*	(	const VectorMatrix &	v,
		const SparseMatrix &	m )

friend

Matrix times vector. Size of v must equal to number of rows of m. Size of resultant vector is equal to number Of columns of m.

Exceptions

Matrix_domain_error

Returns: A VectorMatrix with size equal to number of columns of m.

Definition at line 608 of file SparseMatrix.cpp.

Member Data Documentation

◆ dimensions

int Matrix::dimensions

protected

One or two dimensional.

Definition at line 83 of file Matrix.h.

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

Simulator/Utils/Matrix/SparseMatrix.h
Simulator/Utils/Matrix/SparseMatrix.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ SparseMatrix() [1/4]

◆ SparseMatrix() [2/4]

◆ SparseMatrix() [3/4]

◆ SparseMatrix() [4/4]

◆ ~SparseMatrix()

Member Function Documentation

◆ alloc()

◆ clear()

◆ copy()

◆ operator()()

◆ operator*()

◆ operator+()

◆ operator-()

◆ operator=()

◆ Print()

◆ remove_lists()

◆ rowFromXML()

◆ size()

◆ toXML()

Friends And Related Symbol Documentation

◆ operator*

Member Data Documentation

◆ dimensions