| Cantera 3.0.0

Loading...
Searching...
No Matches
FuncEval.h
Go to the documentation of this file.
1/**
2 * @file FuncEval.h
3 */
4
5// This file is part of Cantera. See License.txt in the top-level directory or
6// at https://cantera.org/license.txt for license and copyright information.
7
8#ifndef CT_FUNCEVAL_H
9#define CT_FUNCEVAL_H
10
11#include "cantera/base/ct_defs.h"
12#include "cantera/base/ctexceptions.h"
13#include "cantera/base/global.h"
14
15 namespace Cantera
16{
17
18/**
19 * @defgroup odeGroup ODE and DAE Function Utilities
20*/
21
22/**
23 * Virtual base class for ODE/DAE right-hand-side function evaluators.
24 * Classes derived from FuncEval evaluate the right-hand-side function
25 * @f$ \vec{F}(t,\vec{y}) @f$ in
26 * @f[
27 * \dot{\vec{y}} = \vec{F}(t,\vec{y}).
28 * @f]
29 * @ingroup odeGroup
30 */
31 class FuncEval
32{
33 public:
34 FuncEval() = default;
35 virtual ~FuncEval() = default;
36
37 /**
38 * Evaluate the right-hand-side ODE function. Called by the integrator.
39 * @param[in] t time.
40 * @param[in] y solution vector, length neq()
41 * @param[out] ydot rate of change of solution vector, length neq()
42 * @param[in] p sensitivity parameter vector, length nparams()
43 */
44 virtual void eval(double t, double* y, double* ydot, double* p) {
45 throw NotImplementedError("FuncEval::eval");
46 }
47
48 /**
49 * Evaluate the right-hand-side DAE function. Called by the integrator.
50 * @param[in] t time.
51 * @param[in] y solution vector, length neq()
52 * @param[out] ydot rate of change of solution vector, length neq()
53 * @param[in] p sensitivity parameter vector, length nparams()
54 * @param[out] residual the DAE residuals, length nparams()
55 */
56 virtual void evalDae(double t, double* y, double* ydot, double* p,
57 double* residual) {
58 throw NotImplementedError("FuncEval::evalDae");
59 }
60
61 //! Given a vector of length neq(), mark which variables should be
62 //! considered algebraic constraints
63 virtual void getConstraints(double* constraints) {
64 throw NotImplementedError("FuncEval::getConstraints");
65 }
66
67 //! Evaluate the right-hand side using return code to indicate status.
68 /*!
69 * Errors are indicated using the return value, rather than by throwing
70 * exceptions. This method is used when calling from a C-based integrator
71 * such as CVODES. Exceptions may either be stored or printed, based on the
72 * setting of suppressErrors().
73 * @returns 0 for a successful evaluation; 1 after a potentially-
74 * recoverable error; -1 after an unrecoverable error.
75 */
76 int evalNoThrow(double t, double* y, double* ydot);
77
78 //! Evaluate the right-hand side using return code to indicate status.
79 /*!
80 * Errors are indicated using the return value, rather than by throwing
81 * exceptions. This method is used when calling from a C-based integrator
82 * such as CVODES. Exceptions may either be stored or printed, based on the
83 * setting of suppressErrors().
84 * @returns 0 for a successful evaluation; 1 after a potentially-
85 * recoverable error; -1 after an unrecoverable error.
86 */
87 int evalDaeNoThrow(double t, double* y, double* ydot, double* residual);
88
89 /**
90 * Evaluate the setup processes for the Jacobian preconditioner.
91 * @param[in] t time.
92 * @param[in] y solution vector, length neq()
93 * @param gamma the gamma in M=I-gamma*J
94 * @warning This function is an experimental part of the %Cantera API and may be
95 * changed or removed without notice.
96 */
97 virtual void preconditionerSetup(double t, double* y, double gamma) {
98 throw NotImplementedError("FuncEval::preconditionerSetup");
99 }
100
101 /**
102 * Evaluate the linear system Ax=b where A is the preconditioner.
103 * @param[in] rhs right hand side vector used in linear system
104 * @param[out] output output vector for solution
105 * @warning This function is an experimental part of the %Cantera API and may be
106 * changed or removed without notice.
107 */
108 virtual void preconditionerSolve(double* rhs, double* output) {
109 throw NotImplementedError("FuncEval::preconditionerSolve");
110 }
111
112 //! Update the preconditioner based on already computed jacobian values
113 virtual void updatePreconditioner(double gamma) {
114 throw NotImplementedError("FuncEval::updatePreconditioner");
115 }
116
117 /**
118 * Preconditioner setup that doesn't throw an error but returns a
119 * CVODES flag. It also helps as a first level of polymorphism
120 * which identifies the specific FuncEval, e.g., ReactorNet.
121 * @param[in] t time.
122 * @param[in] y solution vector, length neq()
123 * @param gamma the gamma in M=I-gamma*J
124 * @warning This function is an experimental part of the %Cantera API and may be
125 * changed or removed without notice.
126 */
127 int preconditioner_setup_nothrow(double t, double* y, double gamma);
128
129 /**
130 * Preconditioner solve that doesn't throw an error but returns a
131 * CVODES flag. It also helps as a first level of polymorphism
132 * which identifies the specific FuncEval, e.g., ReactorNet.
133 * @param[in] rhs right hand side vector used in linear system
134 * @param[out] output output vector for solution
135 * @warning This function is an experimental part of the %Cantera API and may be
136 * changed or removed without notice.
137 */
138 int preconditioner_solve_nothrow(double* rhs, double* output);
139
140 //! Fill in the vector *y* with the current state of the system.
141 //! Used for getting the initial state for ODE systems.
142 virtual void getState(double* y) {
143 throw NotImplementedError("FuncEval::getState");
144 }
145
146 //! Fill in the vectors *y* and *ydot* with the current state of the system.
147 //! Used for getting the initial state for DAE systems.
148 virtual void getStateDae(double* y, double* ydot) {
149 throw NotImplementedError("FuncEval::getStateDae");
150 }
151
152 //! Number of equations.
153 virtual size_t neq() const = 0;
154
155 //! Number of sensitivity parameters.
156 virtual size_t nparams() const {
157 return m_sens_params.size();
158 }
159
160 //! Enable or disable suppression of errors when calling eval()
161 void suppressErrors(bool suppress) {
162 m_suppress_errors = suppress;
163 }
164
165 //! Get current state of error suppression
166 bool suppressErrors() const {
167 return m_suppress_errors;
168 };
169
170 //! Return a string containing the text of any suppressed errors
171 string getErrors() const;
172
173 //! Clear any previously-stored suppressed errors
174 void clearErrors() {
175 m_errors.clear();
176 };
177
178 //! Values for the problem parameters for which sensitivities are computed
179 //! This is the array which is perturbed and passed back as the fourth
180 //! argument to eval().
181 vector<double> m_sens_params;
182
183 //! Scaling factors for each sensitivity parameter
184 vector<double> m_paramScales;
185
186 protected:
187 // If true, errors are accumulated in m_errors. Otherwise, they are printed
188 bool m_suppress_errors = false;
189
190 //! Errors occurring during function evaluations
191 vector<string> m_errors;
192};
193
194}
195
196#endif
Cantera::FuncEval
Virtual base class for ODE/DAE right-hand-side function evaluators.
Definition FuncEval.h:32
Cantera::FuncEval::evalDae
virtual void evalDae(double t, double *y, double *ydot, double *p, double *residual)
Evaluate the right-hand-side DAE function.
Definition FuncEval.h:56
Cantera::FuncEval::suppressErrors
void suppressErrors(bool suppress)
Enable or disable suppression of errors when calling eval()
Definition FuncEval.h:161
Cantera::FuncEval::preconditioner_solve_nothrow
int preconditioner_solve_nothrow(double *rhs, double *output)
Preconditioner solve that doesn't throw an error but returns a CVODES flag.
Definition FuncEval.cpp:113
Cantera::FuncEval::getStateDae
virtual void getStateDae(double *y, double *ydot)
Fill in the vectors y and ydot with the current state of the system.
Definition FuncEval.h:148
Cantera::FuncEval::m_paramScales
vector< double > m_paramScales
Scaling factors for each sensitivity parameter.
Definition FuncEval.h:184
Cantera::FuncEval::preconditioner_setup_nothrow
int preconditioner_setup_nothrow(double t, double *y, double gamma)
Preconditioner setup that doesn't throw an error but returns a CVODES flag.
Definition FuncEval.cpp:80
Cantera::FuncEval::evalDaeNoThrow
int evalDaeNoThrow(double t, double *y, double *ydot, double *residual)
Evaluate the right-hand side using return code to indicate status.
Definition FuncEval.cpp:39
Cantera::FuncEval::clearErrors
void clearErrors()
Clear any previously-stored suppressed errors.
Definition FuncEval.h:174
Cantera::FuncEval::evalNoThrow
int evalNoThrow(double t, double *y, double *ydot)
Evaluate the right-hand side using return code to indicate status.
Definition FuncEval.cpp:7
Cantera::FuncEval::updatePreconditioner
virtual void updatePreconditioner(double gamma)
Update the preconditioner based on already computed jacobian values.
Definition FuncEval.h:113
Cantera::FuncEval::suppressErrors
bool suppressErrors() const
Get current state of error suppression.
Definition FuncEval.h:166
Cantera::FuncEval::eval
virtual void eval(double t, double *y, double *ydot, double *p)
Evaluate the right-hand-side ODE function.
Definition FuncEval.h:44
Cantera::FuncEval::neq
virtual size_t neq() const =0
Number of equations.
Cantera::FuncEval::m_errors
vector< string > m_errors
Errors occurring during function evaluations.
Definition FuncEval.h:191
Cantera::FuncEval::getConstraints
virtual void getConstraints(double *constraints)
Given a vector of length neq(), mark which variables should be considered algebraic constraints.
Definition FuncEval.h:63
Cantera::FuncEval::nparams
virtual size_t nparams() const
Number of sensitivity parameters.
Definition FuncEval.h:156
Cantera::FuncEval::getErrors
string getErrors() const
Return a string containing the text of any suppressed errors.
Definition FuncEval.cpp:71
Cantera::FuncEval::m_sens_params
vector< double > m_sens_params
Values for the problem parameters for which sensitivities are computed This is the array which is per...
Definition FuncEval.h:181
Cantera::FuncEval::getState
virtual void getState(double *y)
Fill in the vector y with the current state of the system.
Definition FuncEval.h:142
Cantera::FuncEval::preconditionerSolve
virtual void preconditionerSolve(double *rhs, double *output)
Evaluate the linear system Ax=b where A is the preconditioner.
Definition FuncEval.h:108
Cantera::FuncEval::preconditionerSetup
virtual void preconditionerSetup(double t, double *y, double gamma)
Evaluate the setup processes for the Jacobian preconditioner.
Definition FuncEval.h:97
Cantera::NotImplementedError
An error indicating that an unimplemented function has been called.
Definition ctexceptions.h:195
ct_defs.h
This file contains definitions of constants, types and terms that are used in internal routines and a...
ctexceptions.h
Definitions for the classes that are thrown when Cantera experiences an error condition (also contain...
global.h
This file contains definitions for utility functions and text for modules, inputfiles and logging,...
Cantera
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564