Cantera  2.2.1
GeneralMatrix.h
Go to the documentation of this file.
1 /**
2  * @file GeneralMatrix.h
3  * Declarations for the class GeneralMatrix which is a virtual base class for matrices handled by solvers
5  */
6
7 /*
8  * Copyright 2004 Sandia Corporation. Under the terms of Contract
9  * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
10  * retains certain rights in this software.
11  * See file License.txt for licensing information.
12  */
13
14 #ifndef CT_GENERALMATRIX_H
15 #define CT_GENERALMATRIX_H
16
17 #include "cantera/base/ct_defs.h"
19
20 namespace Cantera
21 {
22
23 //! Generic matrix
25 {
26 public:
27  //! Base Constructor
28  /*!
29  * @param matType Matrix type
30  * 0 full
31  * 1 banded
32  */
33  GeneralMatrix(int matType);
34
35  //! Copy Constructor
36  GeneralMatrix(const GeneralMatrix& right);
37
38  //! Assignment operator
39  GeneralMatrix& operator=(const GeneralMatrix& right);
40
41  //! Destructor. Does nothing.
42  virtual ~GeneralMatrix() {}
43
44  //! Duplicator member function
45  /*!
46  * This function will duplicate the matrix given a generic GeneralMatrix
47  *
48  * @return Returns a pointer to the malloced object
49  */
50  virtual GeneralMatrix* duplMyselfAsGeneralMatrix() const = 0;
51
52  //! Zero the matrix elements
53  virtual void zero() = 0;
54
55  //! Multiply A*b and write result to prod.
56  /*!
57  * @param b Vector to do the rh multiplication
58  * @param prod OUTPUT vector to receive the result
59  */
60  virtual void mult(const doublereal* b, doublereal* prod) const = 0;
61
62  //! Multiply b*A and write result to prod.
63  /*!
64  * @param b Vector to do the lh multiplication
65  * @param prod OUTPUT vector to receive the result
66  */
67  virtual void leftMult(const doublereal* const b, doublereal* const prod) const = 0;
68
69  //! Factors the A matrix, overwriting A.
70  /*
71  * We flip m_factored boolean to indicate that the matrix is now A-1.
72  */
73  virtual int factor() = 0;
74
75  //! Factors the A matrix using the QR algorithm, overwriting A
76  /*!
77  * we set m_factored to 2 to indicate the matrix is now QR factored
78  *
79  * @return Returns the info variable from LAPACK
80  */
81  virtual int factorQR() {
82  throw NotImplementedError("GeneralMatrix::factorQR");
83  }
84
85  //! Returns an estimate of the inverse of the condition number for the matrix
86  /*!
87  * The matrix must have been previously factored using the QR algorithm
88  *
89  * @return returns the inverse of the condition number
90  */
91  virtual doublereal rcondQR() {
92  throw NotImplementedError("GeneralMatrix::rcondQR");
93  }
94
95  //! Returns an estimate of the inverse of the condition number for the matrix
96  /*!
97  * The matrix must have been previously factored using the LU algorithm
98  *
99  * @param a1norm Norm of the matrix
100  *
101  * @return returns the inverse of the condition number
102  */
103  virtual doublereal rcond(doublereal a1norm) = 0;
104
105  //! Change the way the matrix is factored
106  /*!
107  * @param fAlgorithm integer
108  * 0 LU factorization
109  * 1 QR factorization
110  */
111  virtual void useFactorAlgorithm(int fAlgorithm) {
112  throw NotImplementedError("GeneralMatrix::useFactorAlgorithm");
113  };
114
115  //! Return the factor algorithm used
116  virtual int factorAlgorithm() const = 0;
117
118  //! Calculate the one norm of the matrix
119  virtual doublereal oneNorm() const = 0;
120
121  //! Return the number of rows in the matrix
122  virtual size_t nRows() const = 0;
123
124  //! Return the size and structure of the matrix
125  /*!
126  * @param iStruct OUTPUT Pointer to a vector of ints that describe the structure of the matrix.
127  *
128  * @return returns the number of rows and columns in the matrix.
129  */
130  virtual size_t nRowsAndStruct(size_t* const iStruct = 0) const = 0;
131
132  //! clear the factored flag
133  virtual void clearFactorFlag() {
134  m_factored = 0;
135  };
136
137  //! Solves the Ax = b system returning x in the b spot.
138  /*!
139  * @param b Vector for the RHS of the equation system
140  * @param nrhs Number of right-hand sides to solve, default 1
141  * @param ldb Leading dimension of the right-hand side array.
142  * Defaults to nRows()
143  */
144  virtual int solve(doublereal* b, size_t nrhs=1, size_t ldb=0) = 0;
145
146  //! true if the current factorization is up to date with the matrix
147  virtual bool factored() const {
148  return (m_factored != 0);
149  }
150
151  //! Return a pointer to the top of column j, columns are assumed to be contiguous in memory
152  /*!
153  * @param j Value of the column
154  *
155  * @return Returns a pointer to the top of the column
156  */
157  virtual doublereal* ptrColumn(size_t j) = 0;
158
159  //! Index into the (i,j) element
160  /*!
161  * @param i row
162  * @param j column
163  *
164  * Returns a changeable reference to the matrix entry
165  */
166  virtual doublereal& operator()(size_t i, size_t j) = 0;
167
168  //! Constant Index into the (i,j) element
169  /*!
170  * @param i row
171  * @param j column
172  *
173  * Returns an unchangeable reference to the matrix entry
174  */
175  virtual doublereal operator()(size_t i, size_t j) const = 0;
176
177  //! Copy the data from one array into another without doing any checking
178  /*!
179  * This differs from the assignment operator as no resizing is done and memcpy() is used.
180  * @param y Array to be copied
181  * @deprecated To be removed after Cantera 2.2.
182  */
183  virtual void copyData(const GeneralMatrix& y) = 0;
184
185  //! Return an iterator pointing to the first element
186  /*!
187  * We might drop this later
188  */
189  virtual vector_fp::iterator begin() = 0;
190
191  //! Return a const iterator pointing to the first element
192  /*!
193  * We might drop this later
194  */
195  virtual vector_fp::const_iterator begin() const = 0;
196
197  //! Return a vector of const pointers to the columns
198  /*!
199  * Note the value of the pointers are protected by their being const.
200  * However, the value of the matrix is open to being changed.
201  *
202  * @return returns a vector of pointers to the top of the columns
203  * of the matrices.
204  */
205  virtual doublereal* const* colPts() = 0;
206
207  //! Check to see if we have any zero rows in the Jacobian
208  /*!
209  * This utility routine checks to see if any rows are zero.
210  * The smallest row is returned along with the largest coefficient in that row
211  *
212  * @param valueSmall OUTPUT value of the largest coefficient in the smallest row
213  *
214  * @return index of the row that is most nearly zero
215  */
216  virtual size_t checkRows(doublereal& valueSmall) const = 0;
217
218  //! Check to see if we have any zero columns in the Jacobian
219  /*!
220  * This utility routine checks to see if any columns are zero.
221  * The smallest column is returned along with the largest coefficient in that column
222  *
223  * @param valueSmall OUTPUT value of the largest coefficient in the smallest column
224  *
225  * @return index of the column that is most nearly zero
226  */
227  virtual size_t checkColumns(doublereal& valueSmall) const = 0;
228
229  //! Matrix type
230  /*!
231  * 0 Square
232  * 1 Banded
233  */
235
236 protected:
237  //! Indicates whether the matrix is factored. 0 for unfactored; Non-zero values
238  //! indicate a particular factorization (LU=1, QR=2).
240 };
241
242 }
243 #endif
virtual doublereal * ptrColumn(size_t j)=0
Return a pointer to the top of column j, columns are assumed to be contiguous in memory.
int matrixType_
Matrix type.
An error indicating that an unimplemented function has been called.
Definition: ctexceptions.h:213
virtual GeneralMatrix * duplMyselfAsGeneralMatrix() const =0
Duplicator member function.
int m_factored
Indicates whether the matrix is factored.
virtual doublereal oneNorm() const =0
Calculate the one norm of the matrix.
virtual void clearFactorFlag()
clear the factored flag
virtual size_t nRows() const =0
Return the number of rows in the matrix.
virtual doublereal rcond(doublereal a1norm)=0
Returns an estimate of the inverse of the condition number for the matrix.
GeneralMatrix(int matType)
Base Constructor.
virtual vector_fp::iterator begin()=0
Return an iterator pointing to the first element.
This file contains definitions of terms that are used in internal routines and are unlikely to need m...
Generic matrix.
Definition: GeneralMatrix.h:24
virtual int factorQR()
Factors the A matrix using the QR algorithm, overwriting A.
Definition: GeneralMatrix.h:81
virtual int factorAlgorithm() const =0
Return the factor algorithm used.
virtual ~GeneralMatrix()
Destructor. Does nothing.
Definition: GeneralMatrix.h:42
virtual int factor()=0
Factors the A matrix, overwriting A.
virtual void zero()=0
Zero the matrix elements.
virtual doublereal & operator()(size_t i, size_t j)=0
Index into the (i,j) element.
virtual size_t checkRows(doublereal &valueSmall) const =0
Check to see if we have any zero rows in the Jacobian.
virtual void leftMult(const doublereal *const b, doublereal *const prod) const =0
Multiply b*A and write result to prod.
virtual void mult(const doublereal *b, doublereal *prod) const =0
Multiply A*b and write result to prod.
virtual bool factored() const
true if the current factorization is up to date with the matrix
virtual int solve(doublereal *b, size_t nrhs=1, size_t ldb=0)=0
Solves the Ax = b system returning x in the b spot.
virtual size_t nRowsAndStruct(size_t *const iStruct=0) const =0
Return the size and structure of the matrix.
virtual void copyData(const GeneralMatrix &y)=0
Copy the data from one array into another without doing any checking.
virtual size_t checkColumns(doublereal &valueSmall) const =0
Check to see if we have any zero columns in the Jacobian.
virtual doublereal *const * colPts()=0
Return a vector of const pointers to the columns.
GeneralMatrix & operator=(const GeneralMatrix &right)
Assignment operator.
virtual doublereal rcondQR()
Returns an estimate of the inverse of the condition number for the matrix.
Definition: GeneralMatrix.h:91
Definitions for the classes that are thrown when Cantera experiences an error condition (also contain...
virtual void useFactorAlgorithm(int fAlgorithm)
Change the way the matrix is factored.