Cantera  3.1.0a1
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"
16
17namespace Cantera
18{
19
20
21class 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
49{
50public:
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)
58 , m_valid(other.m_valid)
60 {}
61
62 ReactionRate& operator=(const ReactionRate& other) {
63 if (this == &other) {
64 return *this;
65 }
66 m_input = other.m_input;
68 m_valid = other.m_valid;
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.
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 //! Validate the reaction rate expression
144 virtual void validate(const string& equation, const Kinetics& kin) {}
145
146 //! Reaction rate index within kinetics evaluator
147 size_t rateIndex() const {
148 return m_rate_index;
149 }
150
151 //! Set reaction rate index within kinetics evaluator
152 void setRateIndex(size_t idx) {
153 m_rate_index = idx;
154 }
155
156 //! Set context of reaction rate evaluation
157 //! @param rxn Reaction object associated with rate
158 //! @param kin Kinetics object used for rate evaluation
159 //! This method allows for passing of information specific to the associated
160 //! reaction when a ReactionRate object is added a MultiRate reaction evaluator.
161 virtual void setContext(const Reaction& rxn, const Kinetics& kin) {
162 }
163
164 //! Evaluate reaction rate based on temperature
165 //! @param T temperature [K]
166 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
167 //! This method allows for testing of a reaction rate expression outside of
168 //! Kinetics reaction rate evaluators.
169 double eval(double T) {
170 _evaluator().update(T);
171 return _evaluator().evalSingle(*this);
172 }
173
174 //! Evaluate reaction rate based on temperature and an extra parameter.
175 //! Specific rate parameterizations may require an additional parameter, which
176 //! is specific to the derived ReactionRate object.
177 //! @param T temperature [K]
178 //! @param extra extra parameter used by parameterization
179 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
180 //! This method allows for testing of a reaction rate expression outside of
181 //! Kinetics reaction rate evaluators.
182 double eval(double T, double extra) {
183 _evaluator().update(T, extra);
184 return _evaluator().evalSingle(*this);
185 }
186
187 //! Evaluate reaction rate based on temperature and an extra vector parameter.
188 //! Specific rate parameterizations may require additional parameters, which
189 //! are specific to the derived ReactionRate object.
190 //! @param T temperature [K]
191 //! @param extra extra vector parameter used by parameterization
192 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
193 //! This method allows for testing of a reaction rate expression outside of
194 //! Kinetics reaction rate evaluators.
195 //! @warning This method is an experimental part of the %Cantera API and
196 //! may be changed or removed without notice.
197 double eval(double T, const vector<double>& extra) {
198 _evaluator().update(T, extra);
199 return _evaluator().evalSingle(*this);
200 }
201
202 //! Get flag indicating whether reaction rate is set up correctly
203 bool valid() const {
204 return m_valid;
205 }
206
207 //! Boolean indicating whether rate has compositional dependence
208 //! @since New in %Cantera 3.0
211 }
212
213 //! Set rate compositional dependence
214 //! @since New in %Cantera 3.0
215 void setCompositionDependence(bool comp_dep) {
217 }
218
219protected:
220 //! Get parameters
221 //! @param node AnyMap containing rate information
222 //! Store the parameters of a ReactionRate needed to reconstruct an identical
223 //! object. Does not include user-defined fields available in the #m_input map.
224 virtual void getParameters(AnyMap& node) const {
225 throw NotImplementedError("ReactionRate::getParameters",
226 "Not implemented by '{}' object.", type());
227 }
228
229 //! Input data used for specific models
231
232 //! Index of reaction rate within kinetics evaluator
234
235 //! Flag indicating whether reaction rate is set up correctly
236 bool m_valid = false;
237
238 //! Flag indicating composition dependent rate
240
241 //! Units of the leading term in the reaction rate expression
243
244private:
245 //! Return an object that be used to evaluate the rate by converting general input
246 //! such as temperature and pressure into the `DataType` struct that is particular
247 //! to the rate model.
249 if (!m_evaluator) {
250 m_evaluator = newMultiRate();
251 }
252 return *m_evaluator;
253 }
254
255 unique_ptr<MultiRateBase> m_evaluator;
256};
257
258}
259
260#endif
Header for unit conversion utilities, which are used to translate user input from input files (See In...
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:427
Public interface for kinetics managers.
Definition Kinetics.h:125
An abstract base class for evaluating all reactions of a particular type.
virtual double evalSingle(ReactionRate &rate)=0
Get the rate for a single reaction.
virtual void update(double T)=0
Update common reaction rate data based on temperature.
An error indicating that an unimplemented function has been called.
Abstract base class for reaction rate definitions; this base class is used by user-facing APIs to acc...
void setCompositionDependence(bool comp_dep)
Set rate compositional dependence.
virtual void setParameters(const AnyMap &node, const UnitStack &units)
Set parameters.
bool compositionDependent()
Boolean indicating whether rate has compositional dependence.
double eval(double T)
Evaluate reaction rate based on temperature.
Units m_conversion_units
Units of the leading term in the reaction rate expression.
virtual void setContext(const Reaction &rxn, const Kinetics &kin)
Set context of reaction rate evaluation.
const Units & conversionUnits() const
Get the units for converting the leading term in the reaction rate expression.
bool valid() const
Get flag indicating whether reaction rate is set up correctly.
double eval(double T, const vector< double > &extra)
Evaluate reaction rate based on temperature and an extra vector parameter.
virtual void setRateUnits(const UnitStack &rate_units)
Set the units of the reaction rate expression.
double eval(double T, double extra)
Evaluate reaction rate based on temperature and an extra parameter.
size_t rateIndex() const
Reaction rate index within kinetics evaluator.
AnyMap parameters() const
Return the parameters such that an identical Reaction could be reconstructed using the newReaction() ...
void setRateIndex(size_t idx)
Set reaction rate index within kinetics evaluator.
bool m_valid
Flag indicating whether reaction rate is set up correctly.
virtual unique_ptr< MultiRateBase > newMultiRate() const
Create a rate evaluator for reactions of a particular derived type.
virtual const string subType() const
String identifying sub-type of reaction rate specialization.
virtual void validate(const string &equation, const Kinetics &kin)
Validate the reaction rate expression.
virtual void check(const string &equation)
Check basic syntax and settings of reaction rate expression.
virtual const string type() const =0
String identifying reaction rate specialization.
bool m_composition_dependent_rate
Flag indicating composition dependent rate.
AnyMap m_input
Input data used for specific models.
virtual void getParameters(AnyMap &node) const
Get parameters.
MultiRateBase & _evaluator()
Return an object that be used to evaluate the rate by converting general input such as temperature an...
size_t m_rate_index
Index of reaction rate within kinetics evaluator.
Abstract base class which stores data about a reaction and its rate parameterization so that it can b...
Definition Reaction.h:25
A representation of the units associated with a dimensional quantity.
Definition Units.h:35
Definitions for the classes that are thrown when Cantera experiences an error condition (also contain...
This file contains definitions for utility functions and text for modules, inputfiles and logging,...
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
const size_t npos
index returned by functions to indicate "no position"
Definition ct_defs.h:180
Unit aggregation utility.
Definition Units.h:105
size_t size() const
Size of UnitStack.
Definition Units.h:118
Units standardUnits() const
Get standard unit used by UnitStack.
Definition Units.cpp:323
Units product() const
Calculate product of units-exponent stack.
Definition Units.cpp:377