Abstract matrix base class interface definition. More...

#include <GMatrixBase.hpp>

Inheritance diagram for GMatrixBase:

Public Member Functions
	GMatrixBase (void)
	Void constructor. More...

	GMatrixBase (const GMatrixBase &matrix)
	Copy constructor. More...

virtual	~GMatrixBase (void)
	Destructor. More...

virtual double &	operator() (const int &row, const int &column)=0

virtual const double &	operator() (const int &row, const int &column) const =0

virtual GVector	operator* (const GVector &vector) const =0

virtual GMatrixBase &	operator= (const GMatrixBase &matrix)
	Assignment operator. More...

virtual bool	operator== (const GMatrixBase &matrix) const
	Equalty operator. More...

virtual bool	operator!= (const GMatrixBase &matrix) const
	Non-equality operator. More...

virtual void	clear (void)=0
	Clear object. More...

virtual GMatrixBase *	clone (void) const =0
	Clones object. More...

virtual std::string	classname (void) const =0
	Return class name. More...

virtual double &	at (const int &row, const int &column)=0

virtual const double &	at (const int &row, const int &column) const =0

virtual GVector	row (const int &row) const =0

virtual void	row (const int &row, const GVector &vector)=0

virtual GVector	column (const int &column) const =0

virtual void	column (const int &column, const GVector &vector)=0

virtual void	add_to_row (const int &row, const GVector &vector)=0

virtual void	add_to_column (const int &column, const GVector &vector)=0

virtual double	fill (void) const =0

virtual double	min (void) const =0

virtual double	max (void) const =0

virtual double	sum (void) const =0

virtual std::string	print (const GChatter &chatter=NORMAL) const =0
	Print content of object. More...

bool	is_empty (void) const
	Check if matrix is empty. More...

const int &	size (void) const
	Return number of matrix elements. More...

const int &	columns (void) const
	Return number of matrix columns. More...

const int &	rows (void) const
	Return number of matrix rows. More...

Public Member Functions inherited from GBase
virtual	~GBase (void)
	Destructor. More...

Protected Member Functions
void	init_members (void)
	Initialise class members. More...

void	copy_members (const GMatrixBase &matrix)
	Copy class members. More...

void	free_members (void)
	Delete class members. More...

void	select_non_zero (void)
	Setup compressed matrix factorisation. More...

void	scale_elements (const double &scalar)
	Scale all matrix elements with a scalar. More...

void	set_all_elements (const double &value)
	Set all elements to a specific value. More...

double	get_min_element (void) const
	Return minimum matrix element. More...

double	get_max_element (void) const
	Returns maximum matrix element. More...

double	get_element_sum (void) const
	Returns sum over all matrix elements. More...

std::string	print_elements (const GChatter &chatter=NORMAL, const int &num=15) const
	Print all matrix elements. More...

std::string	print_row_compression (const GChatter &chatter=NORMAL) const
	Print row compression scheme if it exists. More...

std::string	print_col_compression (const GChatter &chatter=NORMAL) const
	Print column compression scheme if it exists. More...

Protected Attributes
int	m_rows
	Number of rows. More...

int	m_cols
	Number of columns. More...

int	m_elements
	Number of elements stored in matrix. More...

int	m_alloc
	Size of allocated matrix memory. More...

int	m_num_rowsel
	Number of selected rows (for compressed decomposition) More...

int	m_num_colsel
	Number of selected columns (for compressed decomposition) More...

int *	m_colstart
	Column start indices (m_cols+1) More...

int *	m_rowsel
	Row selection (for compressed decomposition) More...

int *	m_colsel
	Column selection (for compressed decomposition) More...

double *	m_data
	Matrix data. More...

Detailed Description

Abstract matrix base class interface definition.

This class provides the abstract interface for all matrix classes. A GammaLib matrix is a two dimensional array of double precision values that is commonly used for linear algebra computations.

The matrix classes were designed in a manner so that matrices can be used in a natural syntax that is comparable to the syntax used for scalar values. In particular, the following matrix operations are available:

assigned_matrix     = matrix;
assigned_matrix     = value;
added_matrix        = matrix1 + matrix2;
added_matrix       += matrix;
subtracted_matrix   = matrix1 - matrix2;
subtracted_matrix  -= matrix;
multiplied_matrix   = matrix1 * matrix2;
multiplied_matrix  *= matrix;
scaled_matrix       = matrix * scale;
scaled_matrix       = scale * matrix;
scaled_matrix      *= scale;
divided_matrix      = matrix / factor;
divided_matrix     /= factor;
negated_matrix      = -matrix;

where matrix, matrix1 and matrix2 are matrices, and value, scale and factor are double precision values. For the value assignment operator, each matrix element is assigned the specified value. For the scaling and division operators, every matrix element is multiplied or divided by the specified value.

Matrices can also be compared using

if (matrix == another_matrix) ...
if (matrix != another_matrix) ...

where identify is defined as having the same number of rows and columns and every element having the same value.

Matrix elements are accessed using the access operators or the at() methods

double element = matrix(row, column);
double element = matrix.at(row, column);

the difference being that the access operators do NOT but the at() methods do perform validity checking of the row and column arguments. Access operators and at() methods exist for non-const and const references.

For more efficient matrix access, methods operating on matrix rows and columns are available. The

GVector row    = matrix.row(index);
GVector column = matrix.column(index);

methods return a row or a column in a GVector object, while the

GVector row;
GVector column;
...
matrix.row(index, row);
matrix.column(index, column);

store a row or a column provided by a GVector object into the matrix. Obviously, the vector needs to be of the same size as the number of rows or columns available in the matrix. Adding of matrix elements row-by-row or column-by-column is done using the

matrix.add_to_row(index, row);
matrix.add_to_column(index, column);

methods.

Matrix multiplication with a vector is done using

GVector vector;
...
GVector product = matrix * vector;

where the size of vector needs to be identical to the number of columns in the matrix.

Furthermore, the following methods exist for matrix transformations:

new_matrix = matrix.transpose();    // Transposes matrix
new_matrix = matrix.invert();       // Inverts matrix
new_vector = matrix.solve(vector);  // Solves linear matrix equation
new_matrix = matrix.abs();          // Returns matrix with all elements replaced by their absolute values

The following methods allow to access matrix attributes:

matrix.fill();     // Percentage of non-zero elements in matrix [0,1]
matrix.min();      // Minimum matrix element
matrix.max();      // Maximum matrix element
matrix.sum();      // Sum of all matrix elements
matrix.rows();     // Number of rows in matrix
matrix.columns();  // Number of columns in matrix
matrix.size();     // Number of elements in matrix

Definition at line 138 of file GMatrixBase.hpp.

Constructor & Destructor Documentation

GMatrixBase::GMatrixBase ( void )

Void constructor.

Definition at line 51 of file GMatrixBase.cpp.

References init_members().

GMatrixBase::GMatrixBase ( const GMatrixBase & matrix )

Copy constructor.

Parameters

[in] matrix Matrix.

Constructs matrix by copying information from another matrix. The constructor is sufficiently generic to provide the base constructor for all derived classes, including sparse matrices.

Definition at line 70 of file GMatrixBase.cpp.

References copy_members(), and init_members().

GMatrixBase::~GMatrixBase ( void )

virtual

Destructor.

Definition at line 86 of file GMatrixBase.cpp.

References free_members().

Member Function Documentation

virtual void GMatrixBase::add_to_column	(	const int &	column,
		const GVector &	vector
	)

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual void GMatrixBase::add_to_row	(	const int &	row,
		const GVector &	vector
	)

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual double& GMatrixBase::at	(	const int &	row,
		const int &	column
	)

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual const double& GMatrixBase::at	(	const int &	row,
		const int &	column
	)		const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual std::string GMatrixBase::classname ( void ) const

pure virtual

Return class name.

Returns: String containing the class name.

Returns the class name for non-abstract classes in a human readable way.

Implements GBase.

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual void GMatrixBase::clear ( void )

pure virtual

Clear object.

Sets the object to a clean initial state. After calling the method the object will be in the same state as it were if an empty instance of the object would have been created.

Implements GBase.

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual GMatrixBase* GMatrixBase::clone ( void ) const

pure virtual

Clones object.

Returns: Pointer to deep copy of object.

Creates a deep copy of the object and returns a pointer to the object.

Implements GBase.

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual GVector GMatrixBase::column ( const int & column ) const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual void GMatrixBase::column	(	const int &	column,
		const GVector &	vector
	)

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

const int & GMatrixBase::columns ( void ) const

inline

Return number of matrix columns.

Returns: Number of matrix columns.

Returns the number of matrix columns.

Definition at line 246 of file GMatrixBase.hpp.

References m_cols.

Referenced by GMatrixSymmetric::alloc_members(), GMatrix::alloc_members(), GMatrixSparse::alloc_members(), GResponse::convolve(), GObservations::likelihood::covariance(), GRmf::emeasured(), GModelData::eval(), GMatrix::GMatrix(), GMatrixSparse::GMatrixSparse(), GMatrixSymmetric::GMatrixSymmetric(), GCTAResponseCube::irf_radial(), GObservation::model(), GRmf::nmeasured(), GCTAEdispRmf::set_max_edisp(), and GRmf::size().

void GMatrixBase::copy_members ( const GMatrixBase & matrix )

protected

Copy class members.

Parameters

[in] matrix Matrix.

Definition at line 217 of file GMatrixBase.cpp.

References m_alloc, m_cols, m_colsel, m_colstart, m_data, m_elements, m_num_colsel, m_num_rowsel, m_rows, and m_rowsel.

Referenced by GMatrixBase(), and operator=().

virtual double GMatrixBase::fill ( void ) const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

void GMatrixBase::free_members ( void )

protected

Delete class members.

Definition at line 282 of file GMatrixBase.cpp.

References m_colsel, m_colstart, m_data, and m_rowsel.

Referenced by GMatrix::eulerx(), GMatrix::eulery(), GMatrix::eulerz(), operator=(), and ~GMatrixBase().

double GMatrixBase::get_element_sum ( void ) const

protected

Returns sum over all matrix elements.

Definition at line 481 of file GMatrixBase.cpp.

References m_data, and m_elements.

Referenced by GMatrix::sum().

double GMatrixBase::get_max_element ( void ) const

protected

Returns maximum matrix element.

Returns: Maximum element in matrix.

Returns the maximum matrix element. If the matrix is empty, returns 0.

Definition at line 453 of file GMatrixBase.cpp.

References m_data, and m_elements.

Referenced by GMatrixSymmetric::max(), and GMatrix::max().

double GMatrixBase::get_min_element ( void ) const

protected

Return minimum matrix element.

Returns: Minimum element in matrix.

Returns the minimum matrix element. If the matrix is empty, returns 0.

Definition at line 421 of file GMatrixBase.cpp.

References m_data, and m_elements.

Referenced by GMatrixSymmetric::min(), and GMatrix::min().

void GMatrixBase::init_members ( void )

protected

Initialise class members.

Definition at line 193 of file GMatrixBase.cpp.

References m_alloc, m_cols, m_colsel, m_colstart, m_data, m_elements, m_num_colsel, m_num_rowsel, m_rows, and m_rowsel.

Referenced by GMatrix::eulerx(), GMatrix::eulery(), GMatrix::eulerz(), GMatrixBase(), and operator=().

bool GMatrixBase::is_empty ( void ) const

inline

Check if matrix is empty.

Returns: True if matrix has no rows or columns.

Checks if the matrix has no rows or columns.

Definition at line 218 of file GMatrixBase.hpp.

References m_cols, and m_rows.

Referenced by cs_transpose(), GMatrixSparse::operator=(), GMatrixSparse::solve(), and GMatrixSparse::stack_flush().

virtual double GMatrixBase::max ( void ) const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual double GMatrixBase::min ( void ) const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

bool GMatrixBase::operator!= ( const GMatrixBase & matrix ) const

virtual

Non-equality operator.

Parameters

[in] matrix Matrix.

Returns: True if both matrices are different.

Checks if two matrices are different. Two matrices are considered different if they either have different dimensions or at least one element that differs.

Definition at line 174 of file GMatrixBase.cpp.

References operator==().

virtual double& GMatrixBase::operator()	(	const int &	row,
		const int &	column
	)

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual const double& GMatrixBase::operator()	(	const int &	row,
		const int &	column
	)		const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

virtual GVector GMatrixBase::operator* ( const GVector & vector ) const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

GMatrixBase & GMatrixBase::operator= ( const GMatrixBase & matrix )

virtual

Assignment operator.

Parameters

[in] matrix Matrix.

Returns: Matrix.

Definition at line 108 of file GMatrixBase.cpp.

References copy_members(), free_members(), and init_members().

Referenced by GMatrixSymmetric::operator=(), GMatrix::operator=(), and GMatrixSparse::operator=().

bool GMatrixBase::operator== ( const GMatrixBase & matrix ) const

virtual

Equalty operator.

Parameters

[in] matrix Matrix.

Returns: True if both matrices are identical.

Checks if two matrices are identical. Two matrices are considered identical if they have the same dimensions and identical elements.

Definition at line 138 of file GMatrixBase.cpp.

References m_cols, m_data, m_elements, and m_rows.

Referenced by operator!=().

virtual std::string GMatrixBase::print ( const GChatter & chatter = NORMAL ) const

pure virtual

Print content of object.

Parameters

[in] chatter Chattiness (defaults to NORMAL).

Returns: String containing the content of the object.

Formats the content in a standard way and puts this content in a C++ string that is returned.

Implements GBase.

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

std::string GMatrixBase::print_col_compression ( const GChatter & chatter = NORMAL ) const

protected

Print column compression scheme if it exists.

Parameters

[in] chatter Chattiness (defaults to NORMAL).

Definition at line 613 of file GMatrixBase.cpp.

References m_colsel, m_num_colsel, gammalib::parformat(), and gammalib::str().

Referenced by GMatrixSymmetric::print(), GMatrix::print(), and GMatrixSparse::print().

std::string GMatrixBase::print_elements	(	const GChatter &	chatter = `NORMAL`,
		const int &	num = `15`
	)		const

protected

Print all matrix elements.

Parameters

[in]	chatter	Chattiness (defaults to NORMAL).
[in]	num	Maximum number of rows and columns to print (default: 10)

Prints all matrix elements into a string. The parameter max_elements allows to control the maximum number of matrix elements that should be printed. If set to 0, all elements will be printed. Otherwise, the number of rows and columns will be limited by ommitting the central values.

Definition at line 507 of file GMatrixBase.cpp.

References m_cols, m_rows, row(), and gammalib::str().

Referenced by GMatrixSymmetric::print(), GMatrix::print(), and GMatrixSparse::print().

std::string GMatrixBase::print_row_compression ( const GChatter & chatter = NORMAL ) const

protected

Print row compression scheme if it exists.

Parameters

[in] chatter Chattiness (defaults to NORMAL).

Definition at line 589 of file GMatrixBase.cpp.

References m_num_rowsel, m_rowsel, gammalib::parformat(), row(), and gammalib::str().

Referenced by GMatrixSymmetric::print(), GMatrix::print(), and GMatrixSparse::print().

virtual GVector GMatrixBase::row ( const int & row ) const

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

Referenced by print_elements(), print_row_compression(), and select_non_zero().

virtual void GMatrixBase::row	(	const int &	row,
		const GVector &	vector
	)

pure virtual

Implemented in GMatrixSparse, GMatrix, and GMatrixSymmetric.

const int & GMatrixBase::rows ( void ) const

inline

Return number of matrix rows.

Returns: Number of matrix rows.

Returns the number of matrix rows.

Definition at line 260 of file GMatrixBase.hpp.

References m_rows.

Referenced by GMatrixSymmetric::alloc_members(), GMatrix::alloc_members(), GMatrixSparse::alloc_members(), GResponse::convolve(), GObservations::likelihood::covariance(), GRmf::etrue(), GModelData::eval(), GMatrix::GMatrix(), GMatrixSparse::GMatrixSparse(), GMatrixSymmetric::GMatrixSymmetric(), GMatrixSparse::insert_zero_row_col(), GCTAResponseCube::irf_radial(), GObservation::model(), GRmf::ntrue(), GCTAEdispRmf::set_max_edisp(), and GRmf::size().

void GMatrixBase::scale_elements ( const double & scalar )

protected

Scale all matrix elements with a scalar.

Parameters

[in] scalar Scalar.

Multiply all matrix elements with a scalar. There are three cases:

the multiplier is 0, then reset all elements to 0,
the multiplier is +/-1, then do nothing or negate,
in any other case, multiply by multiplier.

Definition at line 367 of file GMatrixBase.cpp.

References abs(), m_data, and m_elements.

Referenced by GMatrixSymmetric::operator*=(), GMatrix::operator*=(), and GMatrixSparse::operator*=().

void GMatrixBase::select_non_zero ( void )

protected

Setup compressed matrix factorisation.

Determines the non-zero rows and columns in matrix and set up index arrays that point to these rows/columns. These arrays are used for compressed matrix factorisations.

Definition at line 308 of file GMatrixBase.cpp.

References m_cols, m_colsel, m_num_colsel, m_num_rowsel, m_rows, m_rowsel, and row().

Referenced by GMatrixSparse::remove_zero_row_col().

void GMatrixBase::set_all_elements ( const double & value )

protected

Set all elements to a specific value.

Parameters

[in] value Value.

Sets all matrix elements to a specific value.

Definition at line 402 of file GMatrixBase.cpp.

References m_data, and m_elements.

const int & GMatrixBase::size ( void ) const