| Cantera 3.0.0

Loading...
Searching...
No Matches
ReactionRate.h
Go to the documentation of this file.
1/**
2 * @file ReactionRate.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_REACTIONRATE_H
9#define CT_REACTIONRATE_H
10
11#include "MultiRateBase.h"
12#include "cantera/base/AnyMap.h"
13#include "cantera/base/Units.h"
14#include "cantera/base/global.h"
15#include "cantera/base/ctexceptions.h"
16
17 namespace Cantera
18{
19
20
21 class Reaction;
22
23//! Abstract base class for reaction rate definitions; this base class is used by
24//! user-facing APIs to access reaction rate objects
25//!
26//! In addition to the pure virtual methods declared in this class, complete derived
27//! classes must implement the method `evalFromStruct(const DataType& shared_data)`,
28//! where `DataType` is a container for parameters needed to evaluate reactions of that
29//! type. In addition, derived classes may also implement the method
30//! `updateFromStruct(const DataType& shared_data)` to update buffered data that
31//! is specific to a given reaction rate.
32//!
33//! The calculation of derivatives (or Jacobians) relies on the following methods:
34//! - Derived classes may implement the method
35//! `ddTScaledFromStruct(const DataType& shared_data)` for an analytical derivative
36//! with respect to temperature.
37//! - Associated `DataType` containers may overload the method
38//! `perturbTemperature(double deltaT)`, which is used for the calculation of
39//! numerical derivatives with respect to temperature if an analytic implementation
40//! is not available.
41//! - For reaction rate constants that depend on pressure or third-body collision
42//! partners, associated `DataType` containers should implement the methods
43//! `perturbPressure(double deltaP)` and/or `perturbThirdBodies(double deltaM)`,
44//! which allow for the calculation of numerical derivatives.
45//! - For additional information, refer to the @ref kinDerivs "Kinetics Derivatives"
46//! documentation.
47//! @ingroup reactionGroup
48 class ReactionRate
49{
50 public:
51 ReactionRate() {}
52
53 // Copy constructor and assignment operator need to be defined because of the
54 // #m_evaluator member that can't (and shouldn't) be copied.
55 ReactionRate(const ReactionRate& other)
56 : m_input(other.m_input)
57 , m_rate_index(other.m_rate_index)
58 , m_valid(other.m_valid)
59 , m_conversion_units(other.m_conversion_units)
60 {}
61
62 ReactionRate& operator=(const ReactionRate& other) {
63 if (this == &other) {
64 return *this;
65 }
66 m_input = other.m_input;
67 m_rate_index = other.m_rate_index;
68 m_valid = other.m_valid;
69 m_conversion_units = other.m_conversion_units;
70 return *this;
71 }
72
73 virtual ~ReactionRate() = default;
74
75 //! Create a rate evaluator for reactions of a particular derived type.
76 //! Derived classes usually implement this as:
77 //!
78 //! ```.cpp
79 //! unique_ptr<MultiRateBase> newMultiRate() const override {
80 //! return make_unique<MultiRate<RateType, DataType>>();
81 //! ```
82 //!
83 //! where `RateType` is the derived class name and `DataType` is the corresponding
84 //! container for parameters needed to evaluate reactions of that type.
85 virtual unique_ptr<MultiRateBase> newMultiRate() const {
86 throw NotImplementedError("ReactionRate::newMultiRate",
87 "Not implemented by '{}' object.", type());
88 }
89
90 //! String identifying reaction rate specialization
91 virtual const string type() const = 0;
92
93 //! String identifying sub-type of reaction rate specialization
94 virtual const string subType() const {
95 return "";
96 }
97
98 //! Set parameters
99 //! @param node AnyMap object containing reaction rate specification
100 //! @param units unit definitions specific to rate information
101 virtual void setParameters(const AnyMap& node, const UnitStack& units) {
102 setRateUnits(units);
103 m_input = node;
104 }
105
106 //! Return the parameters such that an identical Reaction could be reconstructed
107 //! using the newReaction() function. Behavior specific to derived classes is
108 //! handled by the getParameters() method.
109 AnyMap parameters() const {
110 AnyMap out;
111 out["type"] = type();
112 getParameters(out);
113 return out;
114 }
115
116 //! Get the units for converting the leading term in the reaction rate expression.
117 //!
118 //! These units are often the same as the units of the rate expression itself, but
119 //! not always; sticking coefficients are a notable exception.
120 //! @since New in %Cantera 3.0
121 const Units& conversionUnits() const {
122 return m_conversion_units;
123 }
124
125 //! Set the units of the reaction rate expression
126 //!
127 //! Used to determine the units that should be used for converting terms in the
128 //! reaction rate expression, which often have the same units (for example, the
129 //! Arrhenius pre-exponential) but may also be different (for example, sticking
130 //! coefficients).
131 //! @since New in %Cantera 3.0
132 virtual void setRateUnits(const UnitStack& rate_units) {
133 if (rate_units.size() > 1) {
134 m_conversion_units = rate_units.product();
135 } else {
136 m_conversion_units = rate_units.standardUnits();
137 }
138 }
139
140 //! Check basic syntax and settings of reaction rate expression
141 virtual void check(const string& equation) {}
142
143 //! Check basic syntax and settings of reaction rate expression
144 //! @deprecated To be removed after %Cantera 3.0.
145 //! Superseded by single-parameter version
146 void check(const string& equation, const AnyMap& node) {
147 warn_deprecated("ReactionRate::check",
148 "To be removed after Cantera 3.0; superseded by single-parameter version.");
149 check(equation);
150 }
151
152 //! Validate the reaction rate expression
153 virtual void validate(const string& equation, const Kinetics& kin) {}
154
155 //! Validate the reaction rate expression (legacy call)
156 //! @deprecated To be removed after %Cantera 3.0.
157 //! Superseded by two-parameter version
158 virtual void validate(const string& equation) {
159 warn_deprecated("ReactionRate::validate",
160 "To be removed after Cantera 3.0; superseded by two-parameter version.");
161 }
162
163 //! Reaction rate index within kinetics evaluator
164 size_t rateIndex() const {
165 return m_rate_index;
166 }
167
168 //! Set reaction rate index within kinetics evaluator
169 void setRateIndex(size_t idx) {
170 m_rate_index = idx;
171 }
172
173 //! Set context of reaction rate evaluation
174 //! @param rxn Reaction object associated with rate
175 //! @param kin Kinetics object used for rate evaluation
176 //! This method allows for passing of information specific to the associated
177 //! reaction when a ReactionRate object is added a MultiRate reaction evaluator.
178 virtual void setContext(const Reaction& rxn, const Kinetics& kin) {
179 }
180
181 //! Evaluate reaction rate based on temperature
182 //! @param T temperature [K]
183 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
184 //! This method allows for testing of a reaction rate expression outside of
185 //! Kinetics reaction rate evaluators.
186 double eval(double T) {
187 _evaluator().update(T);
188 return _evaluator().evalSingle(*this);
189 }
190
191 //! Evaluate reaction rate based on temperature and an extra parameter.
192 //! Specific rate parameterizations may require an additional parameter, which
193 //! is specific to the derived ReactionRate object.
194 //! @param T temperature [K]
195 //! @param extra extra parameter used by parameterization
196 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
197 //! This method allows for testing of a reaction rate expression outside of
198 //! Kinetics reaction rate evaluators.
199 double eval(double T, double extra) {
200 _evaluator().update(T, extra);
201 return _evaluator().evalSingle(*this);
202 }
203
204 //! Evaluate reaction rate based on temperature and an extra vector parameter.
205 //! Specific rate parameterizations may require additional parameters, which
206 //! are specific to the derived ReactionRate object.
207 //! @param T temperature [K]
208 //! @param extra extra vector parameter used by parameterization
209 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
210 //! This method allows for testing of a reaction rate expression outside of
211 //! Kinetics reaction rate evaluators.
212 //! @warning This method is an experimental part of the %Cantera API and
213 //! may be changed or removed without notice.
214 double eval(double T, const vector<double>& extra) {
215 _evaluator().update(T, extra);
216 return _evaluator().evalSingle(*this);
217 }
218
219 //! Get flag indicating whether reaction rate is set up correctly
220 bool valid() const {
221 return m_valid;
222 }
223
224 //! Boolean indicating whether rate has compositional dependence
225 //! @since New in %Cantera 3.0
226 bool compositionDependent() {
227 return m_composition_dependent_rate;
228 }
229
230 //! Set rate compositional dependence
231 //! @since New in %Cantera 3.0
232 void setCompositionDependence(bool comp_dep) {
233 m_composition_dependent_rate = comp_dep;
234 }
235
236 protected:
237 //! Get parameters
238 //! @param node AnyMap containing rate information
239 //! Store the parameters of a ReactionRate needed to reconstruct an identical
240 //! object. Does not include user-defined fields available in the #m_input map.
241 virtual void getParameters(AnyMap& node) const {
242 throw NotImplementedError("ReactionRate::getParameters",
243 "Not implemented by '{}' object.", type());
244 }
245
246 //! Input data used for specific models
247 AnyMap m_input;
248
249 //! Index of reaction rate within kinetics evaluator
250 size_t m_rate_index = npos;
251
252 //! Flag indicating whether reaction rate is set up correctly
253 bool m_valid = false;
254
255 //! Flag indicating composition dependent rate
256 bool m_composition_dependent_rate = false;
257
258 //! Units of the leading term in the reaction rate expression
259 Units m_conversion_units{0.};
260
261 private:
262 //! Return an object that be used to evaluate the rate by converting general input
263 //! such as temperature and pressure into the `DataType` struct that is particular
264 //! to the rate model.
265 MultiRateBase& _evaluator() {
266 if (!m_evaluator) {
267 m_evaluator = newMultiRate();
268 }
269 return *m_evaluator;
270 }
271
272 unique_ptr<MultiRateBase> m_evaluator;
273};
274
275}
276
277#endif
AnyMap.h
MultiRateBase.h
Units.h
Header for unit conversion utilities, which are used to translate user input from input files (See In...
Cantera::AnyMap
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:427
Cantera::Kinetics
Public interface for kinetics managers.
Definition Kinetics.h:126
Cantera::MultiRateBase
An abstract base class for evaluating all reactions of a particular type.
Definition MultiRateBase.h:28
Cantera::MultiRateBase::evalSingle
virtual double evalSingle(ReactionRate &rate)=0
Get the rate for a single reaction.
Cantera::MultiRateBase::update
virtual void update(double T)=0
Update common reaction rate data based on temperature.
Cantera::NotImplementedError
An error indicating that an unimplemented function has been called.
Definition ctexceptions.h:195
Cantera::ReactionRate
Abstract base class for reaction rate definitions; this base class is used by user-facing APIs to acc...
Definition ReactionRate.h:49
Cantera::ReactionRate::setCompositionDependence
void setCompositionDependence(bool comp_dep)
Set rate compositional dependence.
Definition ReactionRate.h:232
Cantera::ReactionRate::setParameters
virtual void setParameters(const AnyMap &node, const UnitStack &units)
Set parameters.
Definition ReactionRate.h:101
Cantera::ReactionRate::compositionDependent
bool compositionDependent()
Boolean indicating whether rate has compositional dependence.
Definition ReactionRate.h:226
Cantera::ReactionRate::eval
double eval(double T)
Evaluate reaction rate based on temperature.
Definition ReactionRate.h:186
Cantera::ReactionRate::m_conversion_units
Units m_conversion_units
Units of the leading term in the reaction rate expression.
Definition ReactionRate.h:259
Cantera::ReactionRate::setContext
virtual void setContext(const Reaction &rxn, const Kinetics &kin)
Set context of reaction rate evaluation.
Definition ReactionRate.h:178
Cantera::ReactionRate::conversionUnits
const Units & conversionUnits() const
Get the units for converting the leading term in the reaction rate expression.
Definition ReactionRate.h:121
Cantera::ReactionRate::valid
bool valid() const
Get flag indicating whether reaction rate is set up correctly.
Definition ReactionRate.h:220
Cantera::ReactionRate::eval
double eval(double T, const vector< double > &extra)
Evaluate reaction rate based on temperature and an extra vector parameter.
Definition ReactionRate.h:214
Cantera::ReactionRate::setRateUnits
virtual void setRateUnits(const UnitStack &rate_units)
Set the units of the reaction rate expression.
Definition ReactionRate.h:132
Cantera::ReactionRate::eval
double eval(double T, double extra)
Evaluate reaction rate based on temperature and an extra parameter.
Definition ReactionRate.h:199
Cantera::ReactionRate::rateIndex
size_t rateIndex() const
Reaction rate index within kinetics evaluator.
Definition ReactionRate.h:164
Cantera::ReactionRate::parameters
AnyMap parameters() const
Return the parameters such that an identical Reaction could be reconstructed using the newReaction() ...
Definition ReactionRate.h:109
Cantera::ReactionRate::setRateIndex
void setRateIndex(size_t idx)
Set reaction rate index within kinetics evaluator.
Definition ReactionRate.h:169
Cantera::ReactionRate::m_valid
bool m_valid
Flag indicating whether reaction rate is set up correctly.
Definition ReactionRate.h:253
Cantera::ReactionRate::newMultiRate
virtual unique_ptr< MultiRateBase > newMultiRate() const
Create a rate evaluator for reactions of a particular derived type.
Definition ReactionRate.h:85
Cantera::ReactionRate::subType
virtual const string subType() const
String identifying sub-type of reaction rate specialization.
Definition ReactionRate.h:94
Cantera::ReactionRate::check
void check(const string &equation, const AnyMap &node)
Check basic syntax and settings of reaction rate expression.
Definition ReactionRate.h:146
Cantera::ReactionRate::validate
virtual void validate(const string &equation, const Kinetics &kin)
Validate the reaction rate expression.
Definition ReactionRate.h:153
Cantera::ReactionRate::check
virtual void check(const string &equation)
Check basic syntax and settings of reaction rate expression.
Definition ReactionRate.h:141
Cantera::ReactionRate::type
virtual const string type() const =0
String identifying reaction rate specialization.
Cantera::ReactionRate::m_composition_dependent_rate
bool m_composition_dependent_rate
Flag indicating composition dependent rate.
Definition ReactionRate.h:256
Cantera::ReactionRate::m_input
AnyMap m_input
Input data used for specific models.
Definition ReactionRate.h:247
Cantera::ReactionRate::getParameters
virtual void getParameters(AnyMap &node) const
Get parameters.
Definition ReactionRate.h:241
Cantera::ReactionRate::_evaluator
MultiRateBase & _evaluator()
Return an object that be used to evaluate the rate by converting general input such as temperature an...
Definition ReactionRate.h:265
Cantera::ReactionRate::m_rate_index
size_t m_rate_index
Index of reaction rate within kinetics evaluator.
Definition ReactionRate.h:250
Cantera::ReactionRate::validate
virtual void validate(const string &equation)
Validate the reaction rate expression (legacy call)
Definition ReactionRate.h:158
Cantera::Reaction
Abstract base class which stores data about a reaction and its rate parameterization so that it can b...
Definition Reaction.h:27
Cantera::Units
A representation of the units associated with a dimensional quantity.
Definition Units.h:35
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
Cantera::npos
const size_t npos
index returned by functions to indicate "no position"
Definition ct_defs.h:195
Cantera::warn_deprecated
void warn_deprecated(const string &source, const AnyBase &node, const string &message)
A deprecation warning for syntax in an input file.
Definition AnyMap.cpp:1926
Cantera::UnitStack
Unit aggregation utility.
Definition Units.h:105
Cantera::UnitStack::size
size_t size() const
Size of UnitStack.
Definition Units.h:118
Cantera::UnitStack::standardUnits
Units standardUnits() const
Get standard unit used by UnitStack.
Definition Units.cpp:323
Cantera::UnitStack::product
Units product() const
Calculate product of units-exponent stack.
Definition Units.cpp:377