GammaLib  2.1.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GMatrixBase.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GMatrixBase.hpp - Abstract matrix base class *
3  * ----------------------------------------------------------------------- *
4  * copyright (C) 2006-2021 by Juergen Knoedlseder *
5  * ----------------------------------------------------------------------- *
6  * *
7  * This program is free software: you can redistribute it and/or modify *
8  * it under the terms of the GNU General Public License as published by *
9  * the Free Software Foundation, either version 3 of the License, or *
10  * (at your option) any later version. *
11  * *
12  * This program is distributed in the hope that it will be useful, *
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
15  * GNU General Public License for more details. *
16  * *
17  * You should have received a copy of the GNU General Public License *
18  * along with this program. If not, see <http://www.gnu.org/licenses/>. *
19  * *
20  ***************************************************************************/
21 /**
22  * @file GMatrixBase.hpp
23  * @brief Abstract matrix base class definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GMATRIXBASE_HPP
28 #define GMATRIXBASE_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <string>
32 #include "GBase.hpp"
33 #include "GVector.hpp"
34 
35 
36 /***********************************************************************//**
37  * @class GMatrixBase
38  *
39  * @brief Abstract matrix base class interface definition
40  *
41  * This class provides the abstract interface for all matrix classes. A
42  * GammaLib matrix is a two dimensional array of double precision values
43  * that is commonly used for linear algebra computations.
44  *
45  * The matrix classes were designed in a manner so that matrices can be used
46  * in a natural syntax that is comparable to the syntax used for scalar
47  * values. In particular, the following matrix operations are available:
48  *
49  * assigned_matrix = matrix;
50  * assigned_matrix = value;
51  * added_matrix = matrix1 + matrix2;
52  * added_matrix += matrix;
53  * subtracted_matrix = matrix1 - matrix2;
54  * subtracted_matrix -= matrix;
55  * multiplied_matrix = matrix1 * matrix2;
56  * multiplied_matrix *= matrix;
57  * scaled_matrix = matrix * scale;
58  * scaled_matrix = scale * matrix;
59  * scaled_matrix *= scale;
60  * divided_matrix = matrix / factor;
61  * divided_matrix /= factor;
62  * negated_matrix = -matrix;
63  *
64  * where @p matrix, @p matrix1 and @p matrix2 are matrices, and
65  * @p value, @p scale and @p factor are double precision values. For the
66  * value assignment operator, each matrix element is assigned the specified
67  * value. For the scaling and division operators, every matrix element is
68  * multiplied or divided by the specified value.
69  *
70  * Matrices can also be compared using
71  *
72  * if (matrix == another_matrix) ...
73  * if (matrix != another_matrix) ...
74  *
75  * where identify is defined as having the same number of rows and columns
76  * and every element having the same value.
77  *
78  * Matrix elements are accessed using the access operators or the at() methods
79  *
80  * double element = matrix(row, column);
81  * double element = matrix.at(row, column);
82  *
83  * the difference being that the access operators do NOT but the at()
84  * methods do perform validity checking of the @p row and @p column
85  * arguments. Access operators and at() methods exist for non-const and
86  * const references.
87  *
88  * For more efficient matrix access, methods operating on matrix rows and
89  * columns are available. The
90  *
91  * GVector row = matrix.row(index);
92  * GVector column = matrix.column(index);
93  *
94  * methods return a row or a column in a GVector object, while the
95  *
96  * GVector row;
97  * GVector column;
98  * ...
99  * matrix.row(index, row);
100  * matrix.column(index, column);
101  *
102  * store a row or a column provided by a GVector object into the matrix.
103  * Obviously, the vector needs to be of the same size as the number of rows
104  * or columns available in the matrix. Adding of matrix elements row-by-row
105  * or column-by-column is done using the
106  *
107  * matrix.add_to_row(index, row);
108  * matrix.add_to_column(index, column);
109  *
110  * methods.
111  *
112  * Matrix multiplication with a vector is done using
113  *
114  * GVector vector;
115  * ...
116  * GVector product = matrix * vector;
117  *
118  * where the size of @p vector needs to be identical to the number of
119  * columns in the matrix.
120  *
121  * Furthermore, the following methods exist for matrix transformations:
122  *
123  * new_matrix = matrix.transpose(); // Transposes matrix
124  * new_matrix = matrix.invert(); // Inverts matrix
125  * new_vector = matrix.solve(vector); // Solves linear matrix equation
126  * new_matrix = matrix.abs(); // Returns matrix with all elements replaced by their absolute values
127  *
128  * The following methods allow to access matrix attributes:
129  *
130  * matrix.fill(); // Percentage of non-zero elements in matrix [0,1]
131  * matrix.min(); // Minimum matrix element
132  * matrix.max(); // Maximum matrix element
133  * matrix.sum(); // Sum of all matrix elements
134  * matrix.rows(); // Number of rows in matrix
135  * matrix.columns(); // Number of columns in matrix
136  * matrix.size(); // Number of elements in matrix
137  ***************************************************************************/
138 class GMatrixBase : public GBase {
139 
140 public:
141  // Constructors and destructors
142  GMatrixBase(void);
143  GMatrixBase(const GMatrixBase& matrix);
144  virtual ~GMatrixBase(void);
145 
146  // Pure virtual operators
147  virtual double& operator()(const int& row, const int& column) = 0;
148  virtual const double& operator()(const int& row, const int& column) const = 0;
149  virtual GVector operator*(const GVector& vector) const = 0;
150 
151  // Base class operators
152  virtual GMatrixBase& operator=(const GMatrixBase& matrix);
153  virtual bool operator==(const GMatrixBase& matrix) const;
154  virtual bool operator!=(const GMatrixBase& matrix) const;
155 
156  // Pure virtual methods
157  virtual void clear(void) = 0;
158  virtual GMatrixBase* clone(void) const = 0;
159  virtual std::string classname(void) const = 0;
160  virtual double& at(const int& row, const int& column) = 0;
161  virtual const double& at(const int& row, const int& column) const = 0;
162  virtual GVector row(const int& row) const = 0;
163  virtual void row(const int& row, const GVector& vector) = 0;
164  virtual GVector column(const int& column) const = 0;
165  virtual void column(const int& column, const GVector& vector) = 0;
166  virtual void add_to_row(const int& row, const GVector& vector) = 0;
167  virtual void add_to_column(const int& column, const GVector& vector) = 0;
168  virtual double fill(void) const = 0;
169  virtual double min(void) const = 0;
170  virtual double max(void) const = 0;
171  virtual double sum(void) const = 0;
172  virtual std::string print(const GChatter& chatter = NORMAL) const = 0;
173 
174  // Base class methods
175  bool is_empty(void) const;
176  const int& size(void) const;
177  const int& columns(void) const;
178  const int& rows(void) const;
179 
180 protected:
181  // Protected methods
182  void init_members(void);
183  void copy_members(const GMatrixBase& matrix);
184  void free_members(void);
185  void select_non_zero(void);
186  void scale_elements(const double& scalar);
187  void set_all_elements(const double& value);
188  double get_min_element(void) const;
189  double get_max_element(void) const;
190  double get_element_sum(void) const;
191  std::string print_elements(const GChatter& chatter = NORMAL,
192  const int& num = 15) const;
193  std::string print_row_compression(const GChatter& chatter = NORMAL) const;
194  std::string print_col_compression(const GChatter& chatter = NORMAL) const;
195 
196  // Protected data area
197  int m_rows; //!< Number of rows
198  int m_cols; //!< Number of columns
199  int m_elements; //!< Number of elements stored in matrix
200  int m_alloc; //!< Size of allocated matrix memory
201  int m_num_rowsel; //!< Number of selected rows (for compressed decomposition)
202  int m_num_colsel; //!< Number of selected columns (for compressed decomposition)
203  int* m_colstart; //!< Column start indices (m_cols+1)
204  int* m_rowsel; //!< Row selection (for compressed decomposition)
205  int* m_colsel; //!< Column selection (for compressed decomposition)
206  double* m_data; //!< Matrix data
207 };
208 
209 
210 /***********************************************************************//**
211  * @brief Check if matrix is empty
212  *
213  * @return True if matrix has no rows or columns.
214  *
215  * Checks if the matrix has no rows or columns.
216  ***************************************************************************/
217 inline
218 bool GMatrixBase::is_empty(void) const
219 {
220  return (m_rows == 0 || m_cols == 0);
221 }
222 
223 
224 /***********************************************************************//**
225  * @brief Return number of matrix elements
226  *
227  * @return Number of matrix elements.
228  *
229  * Returns the number of matrix elements that are stored in the matrix.
230  ***************************************************************************/
231 inline
232 const int& GMatrixBase::size(void) const
233 {
234  return (m_elements);
235 }
236 
237 
238 /***********************************************************************//**
239  * @brief Return number of matrix columns
240  *
241  * @return Number of matrix columns.
242  *
243  * Returns the number of matrix columns.
244  ***************************************************************************/
245 inline
246 const int& GMatrixBase::columns(void) const
247 {
248  return (m_cols);
249 }
250 
251 
252 /***********************************************************************//**
253  * @brief Return number of matrix rows
254  *
255  * @return Number of matrix rows.
256  *
257  * Returns the number of matrix rows.
258  ***************************************************************************/
259 inline
260 const int& GMatrixBase::rows(void) const
261 {
262  return (m_rows);
263 }
264 
265 #endif /* GMATRIXBASE_HPP */
double get_min_element(void) const
Return minimum matrix element.
virtual std::string print(const GChatter &chatter=NORMAL) const =0
Print content of object.
void scale_elements(const double &scalar)
Scale all matrix elements with a scalar.
Abstract matrix base class interface definition.
std::string print_row_compression(const GChatter &chatter=NORMAL) const
Print row compression scheme if it exists.
void init_members(void)
Initialise class members.
const int & size(void) const
Return number of matrix elements.
virtual void add_to_row(const int &row, const GVector &vector)=0
double get_element_sum(void) const
Returns sum over all matrix elements.
virtual GVector row(const int &row) const =0
Definition of interface for all GammaLib classes.
int m_rows
Number of rows.
virtual double sum(void) const =0
virtual std::string classname(void) const =0
Return class name.
int m_num_colsel
Number of selected columns (for compressed decomposition)
virtual double & at(const int &row, const int &column)=0
virtual double & operator()(const int &row, const int &column)=0
void set_all_elements(const double &value)
Set all elements to a specific value.
virtual void clear(void)=0
Clear object.
std::string print_elements(const GChatter &chatter=NORMAL, const int &num=15) const
Print all matrix elements.
double * m_data
Matrix data.
const int & rows(void) const
Return number of matrix rows.
Interface class for all GammaLib classes.
Definition: GBase.hpp:52
void copy_members(const GMatrixBase &matrix)
Copy class members.
int m_cols
Number of columns.
double get_max_element(void) const
Returns maximum matrix element.
virtual GVector column(const int &column) const =0
GChatter
Definition: GTypemaps.hpp:33
virtual double max(void) const =0
int m_alloc
Size of allocated matrix memory.
virtual bool operator==(const GMatrixBase &matrix) const
Equalty operator.
std::string print_col_compression(const GChatter &chatter=NORMAL) const
Print column compression scheme if it exists.
Vector class interface definition.
virtual ~GMatrixBase(void)
Destructor.
Definition: GMatrixBase.cpp:86
virtual GMatrixBase * clone(void) const =0
Clones object.
int m_elements
Number of elements stored in matrix.
GMatrixBase(void)
Void constructor.
Definition: GMatrixBase.cpp:51
virtual GVector operator*(const GVector &vector) const =0
virtual bool operator!=(const GMatrixBase &matrix) const
Non-equality operator.
virtual double min(void) const =0
virtual GMatrixBase & operator=(const GMatrixBase &matrix)
Assignment operator.
virtual void add_to_column(const int &column, const GVector &vector)=0
void free_members(void)
Delete class members.
Vector class.
Definition: GVector.hpp:46
int m_num_rowsel
Number of selected rows (for compressed decomposition)
int * m_colstart
Column start indices (m_cols+1)
int * m_rowsel
Row selection (for compressed decomposition)
void select_non_zero(void)
Setup compressed matrix factorisation.
virtual double fill(void) const =0
const int & columns(void) const
Return number of matrix columns.
int * m_colsel
Column selection (for compressed decomposition)
bool is_empty(void) const
Check if matrix is empty.