| Cantera 3.0.0

Loading...
Searching...
No Matches
ResidJacEval.h
Go to the documentation of this file.
1/**
2 * @file ResidJacEval.h
3 *
4 * Dense, Square (not sparse) matrices.
5 */
6
7// This file is part of Cantera. See License.txt in the top-level directory or
8// at https://cantera.org/license.txt for license and copyright information.
9
10#ifndef CT_RESIDJACEVAL_H
11#define CT_RESIDJACEVAL_H
12
13#include "ResidEval.h"
14#include "DenseMatrix.h"
15
16#ifndef CT_SKIP_DEPRECATION_WARNINGS
17#pragma message("warning: ResidJacEval.h and class ResidJacEval are deprecated and " \
18 "will be removed after Cantera 3.0.")
19#endif
20
21 namespace Cantera
22{
23
24//! Differentiates the type of residual evaluations according to functionality
25 enum ResidEval_Type_Enum {
26 //! Base residual calculation for the time-stepping function
27 Base_ResidEval = 0,
28 //! Base residual calculation for the Jacobian calculation
29 JacBase_ResidEval,
30 //! Delta residual calculation for the Jacobian calculation
31 JacDelta_ResidEval,
32 //! Base residual calculation for the showSolution routine
33 /*!
34 * We calculate this when we want to display a solution
35 */
36 Base_ShowSolution,
37 //! Base residual calculation containing any lagged components
38 /*!
39 * We use this to calculate residuals when doing line searches along
40 * directions determined by Jacobians that are missing contributions from
41 * lagged entries.
42 */
43 Base_LaggedSolutionComponents
44};
45
46//! Wrappers for the function evaluators for Nonlinear solvers and Time steppers
47/*!
48 * @attention This class currently does not have any test cases or examples. Its
49 * implementation may be incomplete, and future changes to %Cantera may
50 * unexpectedly cause this class to stop working. If you use this class,
51 * please consider contributing examples or test cases. In the absence of
52 * new tests or examples, this class may be deprecated and removed in a
53 * future version of %Cantera. See
54 * https://github.com/Cantera/cantera/issues/267 for additional information.
55 *
56 * A class for full (non-sparse dense matrices with Fortran-compatible data
57 * storage. The class adds support for identifying what types of calls are made
58 * to the residual evaluator by adding the ResidEval_Type_Enum class.
59 *
60 * @deprecated Unused. To be removed after %Cantera 3.0.
61 */
62 class ResidJacEval : public ResidEval
63{
64 public:
65 //!Default constructor
66 /*!
67 * @param atol Initial value of the global tolerance (defaults to 1.0E-13)
68 */
69 ResidJacEval(double atol = 1.0e-13);
70
71 //! Return the number of equations in the equation system
72 int nEquations() const override;
73
74 //! Evaluate the residual function
75 /*!
76 * @param t Time (input)
77 * @param delta_t The current value of the time step (input)
78 * @param y Solution vector (input, do not modify)
79 * @param ydot Rate of change of solution vector. (input, do not modify)
80 * @param resid Value of the residual that is computed (output)
81 * @param evalType Type of the residual being computed (defaults to Base_ResidEval)
82 * @param id_x Index of the variable that is being numerically differenced to find
83 * the Jacobian (defaults to -1, which indicates that no variable is being
84 * differenced or that the residual doesn't take this issue into account)
85 * @param delta_x Value of the delta used in the numerical differencing
86 *
87 * @returns a flag to indicate that operation is successful.
88 * 1 Means a successful operation
89 * -0 or neg value Means an unsuccessful operation
90 */
91 virtual int evalResidNJ(const double t, const double delta_t,
92 const double* const y,
93 const double* const ydot,
94 double* const resid,
95 const ResidEval_Type_Enum evalType = Base_ResidEval,
96 const int id_x = -1,
97 const double delta_x = 0.0);
98
99 int eval(const double t, const double* const y, const double* const ydot,
100 double* const r) override;
101
102 int getInitialConditions(const double t0, double* const y, double* const ydot) override;
103
104 //! Filter the solution predictions
105 /*!
106 * Codes might provide a predicted step change. This routine filters the
107 * predicted solution vector eliminating illegal directions.
108 *
109 * @param t Time (input)
110 * @param ybase Solution vector (input, output)
111 * @param step Proposed step in the solution that will be cropped
112 * @returns the norm of the amount of filtering
113 */
114 virtual double filterNewStep(const double t, const double* const ybase,
115 double* const step);
116
117 //! Filter the solution predictions
118 /*!
119 * Codes might provide a predicted solution vector. This routine filters the
120 * predicted solution vector.
121 *
122 * @param t Time (input)
123 * @param y Solution vector (input, output)
124 * @returns the norm of the amount of filtering
125 */
126 virtual double filterSolnPrediction(const double t, double* const y);
127
128 //! Set a global value of the absolute tolerance
129 /*!
130 * @param atol Value of atol
131 */
132 void setAtol(double atol);
133
134 //! Evaluate the time tracking equations, if any
135 /*!
136 * Evaluate time integrated quantities that are calculated at the end of
137 * every successful time step. This call is made once at the end of every
138 * successful time step that advances the time. It's also made once at the
139 * start of the time stepping.
140 *
141 * @param t Time (input)
142 * @param delta_t The current value of the time step (input)
143 * @param y Solution vector (input, do not modify)
144 * @param ydot Rate of change of solution vector. (input, do not modify)
145 * @returns a flag to indicate that operation is successful.
146 * 1 Means a successful operation
147 * -0 or neg value Means an unsuccessful operation
148 */
149 virtual int evalTimeTrackingEqns(const double t, const double delta_t, const double* const y,
150 const double* const ydot);
151
152 //! Evaluate any stopping criteria other than a final time limit
153 /*!
154 * If we are to stop the time integration for any reason other than reaching
155 * a final time limit, tout, provide a test here. This call is made at the
156 * end of every successful time step iteration
157 *
158 * @return If true, the the time stepping is stopped. If false, then time
159 * stepping is stopped if t >= tout Defaults to false.
160 * @param t Time (input)
161 * @param delta_t The current value of the time step (input)
162 * @param y Solution vector (input, do not modify)
163 * @param ydot Rate of change of solution vector. (input, do not modify)
164 */
165 virtual bool evalStoppingCritera(const double t,
166 const double delta_t,
167 const double* const y,
168 const double* const ydot);
169
170 //! Return a vector of delta y's for calculation of the numerical Jacobian
171 /*!
172 * There is a default algorithm provided.
173 *
174 * delta_y[i] = atol[i] + 1.0E-6 ysoln[i]
175 * delta_y[i] = atol[i] + MAX(1.0E-6 ysoln[i] * 0.01 * solnWeights[i])
176 *
177 * @param t Time (input)
178 * @param y Solution vector (input, do not modify)
179 * @param ydot Rate of change of solution vector. (input, do not modify)
180 * @param delta_y Value of the delta to be used in calculating the numerical Jacobian
181 * @param solnWeights Value of the solution weights that are used in determining convergence (default = 0)
182 * @returns a flag to indicate that operation is successful.
183 * 1 Means a successful operation
184 * -0 or neg value Means an unsuccessful operation
185 */
186 virtual int
187 calcDeltaSolnVariables(const double t,
188 const double* const y,
189 const double* const ydot,
190 double* const delta_y,
191 const double* const solnWeights = 0);
192
193 //! Returns a vector of column scale factors that can be used to column
194 //! scale Jacobians.
195 /*!
196 * Default to yScales[] = 1.0
197 *
198 * @param t Time (input)
199 * @param y Solution vector (input, do not modify)
200 * @param y_old Old Solution vector (input, do not modify)
201 * @param yScales Value of the column scales
202 */
203 virtual void calcSolnScales(const double t, const double* const y,
204 const double* const y_old, double* const yScales);
205
206 //! This function may be used to create output at various points in the
207 //! execution of an application.
208 /*!
209 * @param ifunc identity of the call
210 * 0 Initial call
211 * 1 Called at the end of every successful time step
212 * -1 Called at the end of every unsuccessful time step
213 * 2 Called at the end of every call to integrateRJE()
214 * @param t Time (input)
215 * @param delta_t The current value of the time step (input)
216 * @param y Solution vector (input, do not modify)
217 * @param ydot Rate of change of solution vector. (input)
218 */
219 virtual void user_out2(const int ifunc, const double t,
220 const double delta_t,
221 const double* const y,
222 const double* const ydot);
223
224 //! This function may be used to create output at various points in the
225 //! execution of an application.
226 /*!
227 * This routine calls user_out2().
228 *
229 * @param ifunc identity of the call
230 * @param t Time (input)
231 * @param y Solution vector (input, do not modify)
232 * @param ydot Rate of change of solution vector. (input)
233 */
234 virtual void user_out(const int ifunc, const double t,
235 const double* y,
236 const double* ydot);
237
238 //! Multiply the matrix by another matrix that leads to better conditioning
239 /*!
240 * Provide a left sided matrix that will multiply the current Jacobian,
241 * after scaling and lead to a better conditioned system. This routine is
242 * called just before the matrix is factored.
243 *
244 * Original Problem:
245 * J delta_x = - Resid
246 *
247 * New problem:
248 * M (J delta_x) = - M Resid
249 *
250 * @param matrix Pointer to the current Jacobian (if zero, it's already been factored)
251 * @param nrows offsets for the matrix
252 * @param rhs residual vector. This also needs to be LHS multiplied by M
253 * @returns a flag to indicate that operation is successful.
254 * 1 Means a successful operation
255 * -0 or neg value Means an unsuccessful operation
256 */
257 virtual int matrixConditioning(double* const matrix, const int nrows,
258 double* const rhs);
259
260 //! Calculate an analytical Jacobian and the residual at the current time
261 //! and values.
262 /*!
263 * Only called if the jacFormation method is set to analytical
264 *
265 * @param t Time (input)
266 * @param delta_t The current value of the time step (input)
267 * @param cj Coefficient of yprime used in the evaluation of the Jacobian
268 * @param y Solution vector (input, do not modify)
269 * @param ydot Rate of change of solution vector. (input, do not modify)
270 * @param J Reference to the DenseMatrix object to be calculated (output)
271 * @param resid Value of the residual that is computed (output)
272 * @returns a flag to indicate that operation is successful.
273 * 1 Means a successful operation
274 * -0 or neg value Means an unsuccessful operation
275 */
276 virtual int evalJacobian(const double t, const double delta_t, double cj,
277 const double* const y, const double* const ydot,
278 DenseMatrix& J, double* const resid);
279
280 //! Calculate an analytical Jacobian and the residual at the current time and values.
281 /*!
282 * Only called if the jacFormation method is set to analytical
283 *
284 * @param t Time (input)
285 * @param delta_t The current value of the time step (input)
286 * @param cj Coefficient of yprime used in the evaluation of the Jacobian
287 * @param y Solution vector (input, do not modify)
288 * @param ydot Rate of change of solution vector. (input, do not modify)
289 * @param jacobianColPts Pointer to the vector of pts to columns of the DenseMatrix
290 * object to be calculated (output)
291 * @param resid Value of the residual that is computed (output)
292 * @returns a flag to indicate that operation is successful.
293 * 1 Means a successful operation
294 * -0 or neg value Means an unsuccessful operation
295 */
296 virtual int evalJacobianDP(const double t, const double delta_t, double cj,
297 const double* const y,
298 const double* const ydot,
299 double* const* jacobianColPts,
300 double* const resid);
301
302 protected:
303 //! constant value of atol
304 double m_atol;
305
306 //! Number of equations
307 int neq_;
308};
309}
310
311#endif
DenseMatrix.h
Headers for the DenseMatrix object, which deals with dense rectangular matrices and description of th...
ResidEval.h
Cantera::DenseMatrix
A class for full (non-sparse) matrices with Fortran-compatible data storage, which adds matrix operat...
Definition DenseMatrix.h:55
Cantera::ResidEval
Virtual base class for DAE residual function evaluators.
Definition ResidEval.h:39
Cantera::ResidJacEval
Wrappers for the function evaluators for Nonlinear solvers and Time steppers.
Definition ResidJacEval.h:63
Cantera::ResidJacEval::filterNewStep
virtual double filterNewStep(const double t, const double *const ybase, double *const step)
Filter the solution predictions.
Definition ResidJacEval.cpp:96
Cantera::ResidJacEval::evalTimeTrackingEqns
virtual int evalTimeTrackingEqns(const double t, const double delta_t, const double *const y, const double *const ydot)
Evaluate the time tracking equations, if any.
Definition ResidJacEval.cpp:58
Cantera::ResidJacEval::evalResidNJ
virtual int evalResidNJ(const double t, const double delta_t, const double *const y, const double *const ydot, double *const resid, const ResidEval_Type_Enum evalType=Base_ResidEval, const int id_x=-1, const double delta_x=0.0)
Evaluate the residual function.
Definition ResidJacEval.cpp:120
Cantera::ResidJacEval::setAtol
void setAtol(double atol)
Set a global value of the absolute tolerance.
Definition ResidJacEval.cpp:23
Cantera::ResidJacEval::nEquations
int nEquations() const override
Return the number of equations in the equation system.
Definition ResidJacEval.cpp:18
Cantera::ResidJacEval::user_out
virtual void user_out(const int ifunc, const double t, const double *y, const double *ydot)
This function may be used to create output at various points in the execution of an application.
Definition ResidJacEval.cpp:52
Cantera::ResidJacEval::matrixConditioning
virtual int matrixConditioning(double *const matrix, const int nrows, double *const rhs)
Multiply the matrix by another matrix that leads to better conditioning.
Definition ResidJacEval.cpp:114
Cantera::ResidJacEval::calcDeltaSolnVariables
virtual int calcDeltaSolnVariables(const double t, const double *const y, const double *const ydot, double *const delta_y, const double *const solnWeights=0)
Return a vector of delta y's for calculation of the numerical Jacobian.
Definition ResidJacEval.cpp:66
Cantera::ResidJacEval::evalStoppingCritera
virtual bool evalStoppingCritera(const double t, const double delta_t, const double *const y, const double *const ydot)
Evaluate any stopping criteria other than a final time limit.
Definition ResidJacEval.cpp:106
Cantera::ResidJacEval::user_out2
virtual void user_out2(const int ifunc, const double t, const double delta_t, const double *const y, const double *const ydot)
This function may be used to create output at various points in the execution of an application.
Definition ResidJacEval.cpp:46
Cantera::ResidJacEval::filterSolnPrediction
virtual double filterSolnPrediction(const double t, double *const y)
Filter the solution predictions.
Definition ResidJacEval.cpp:101
Cantera::ResidJacEval::eval
int eval(const double t, const double *const y, const double *const ydot, double *const r) override
Evaluate the residual function.
Definition ResidJacEval.cpp:129
Cantera::ResidJacEval::evalJacobian
virtual int evalJacobian(const double t, const double delta_t, double cj, const double *const y, const double *const ydot, DenseMatrix &J, double *const resid)
Calculate an analytical Jacobian and the residual at the current time and values.
Definition ResidJacEval.cpp:136
Cantera::ResidJacEval::getInitialConditions
int getInitialConditions(const double t0, double *const y, double *const ydot) override
Fill in the initial conditions.
Definition ResidJacEval.cpp:32
Cantera::ResidJacEval::neq_
int neq_
Number of equations.
Definition ResidJacEval.h:307
Cantera::ResidJacEval::m_atol
double m_atol
constant value of atol
Definition ResidJacEval.h:304
Cantera::ResidJacEval::calcSolnScales
virtual void calcSolnScales(const double t, const double *const y, const double *const y_old, double *const yScales)
Returns a vector of column scale factors that can be used to column scale Jacobians.
Definition ResidJacEval.cpp:84
Cantera::ResidJacEval::evalJacobianDP
virtual int evalJacobianDP(const double t, const double delta_t, double cj, const double *const y, const double *const ydot, double *const *jacobianColPts, double *const resid)
Calculate an analytical Jacobian and the residual at the current time and values.
Definition ResidJacEval.cpp:145
Cantera
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
Cantera::ResidEval_Type_Enum
ResidEval_Type_Enum
Differentiates the type of residual evaluations according to functionality.
Definition ResidJacEval.h:25
Cantera::JacDelta_ResidEval
@ JacDelta_ResidEval
Delta residual calculation for the Jacobian calculation.
Definition ResidJacEval.h:31
Cantera::Base_ShowSolution
@ Base_ShowSolution
Base residual calculation for the showSolution routine.
Definition ResidJacEval.h:36
Cantera::Base_ResidEval
@ Base_ResidEval
Base residual calculation for the time-stepping function.
Definition ResidJacEval.h:27
Cantera::Base_LaggedSolutionComponents
@ Base_LaggedSolutionComponents
Base residual calculation containing any lagged components.
Definition ResidJacEval.h:43
Cantera::JacBase_ResidEval
@ JacBase_ResidEval
Base residual calculation for the Jacobian calculation.
Definition ResidJacEval.h:29