Cantera  3.1.0a1
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 
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
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)
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;
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  //! 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) {
216  m_composition_dependent_rate = comp_dep;
217  }
218 
219 protected:
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
233  size_t m_rate_index = npos;
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 
244 private:
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.
Definition: MultiRateBase.h:28
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.
Definition: ctexceptions.h:195
Abstract base class for reaction rate definitions; this base class is used by user-facing APIs to acc...
Definition: ReactionRate.h:49
void setCompositionDependence(bool comp_dep)
Set rate compositional dependence.
Definition: ReactionRate.h:215
virtual void setParameters(const AnyMap &node, const UnitStack &units)
Set parameters.
Definition: ReactionRate.h:101
bool compositionDependent()
Boolean indicating whether rate has compositional dependence.
Definition: ReactionRate.h:209
double eval(double T)
Evaluate reaction rate based on temperature.
Definition: ReactionRate.h:169
Units m_conversion_units
Units of the leading term in the reaction rate expression.
Definition: ReactionRate.h:242
virtual void setContext(const Reaction &rxn, const Kinetics &kin)
Set context of reaction rate evaluation.
Definition: ReactionRate.h:161
bool valid() const
Get flag indicating whether reaction rate is set up correctly.
Definition: ReactionRate.h:203
double eval(double T, const vector< double > &extra)
Evaluate reaction rate based on temperature and an extra vector parameter.
Definition: ReactionRate.h:197
virtual void setRateUnits(const UnitStack &rate_units)
Set the units of the reaction rate expression.
Definition: ReactionRate.h:132
double eval(double T, double extra)
Evaluate reaction rate based on temperature and an extra parameter.
Definition: ReactionRate.h:182
size_t rateIndex() const
Reaction rate index within kinetics evaluator.
Definition: ReactionRate.h:147
AnyMap parameters() const
Return the parameters such that an identical Reaction could be reconstructed using the newReaction() ...
Definition: ReactionRate.h:109
const Units & conversionUnits() const
Get the units for converting the leading term in the reaction rate expression.
Definition: ReactionRate.h:121
void setRateIndex(size_t idx)
Set reaction rate index within kinetics evaluator.
Definition: ReactionRate.h:152
bool m_valid
Flag indicating whether reaction rate is set up correctly.
Definition: ReactionRate.h:236
virtual const string subType() const
String identifying sub-type of reaction rate specialization.
Definition: ReactionRate.h:94
virtual unique_ptr< MultiRateBase > newMultiRate() const
Create a rate evaluator for reactions of a particular derived type.
Definition: ReactionRate.h:85
virtual void validate(const string &equation, const Kinetics &kin)
Validate the reaction rate expression.
Definition: ReactionRate.h:144
virtual void check(const string &equation)
Check basic syntax and settings of reaction rate expression.
Definition: ReactionRate.h:141
virtual const string type() const =0
String identifying reaction rate specialization.
MultiRateBase & _evaluator()
Return an object that be used to evaluate the rate by converting general input such as temperature an...
Definition: ReactionRate.h:248
bool m_composition_dependent_rate
Flag indicating composition dependent rate.
Definition: ReactionRate.h:239
AnyMap m_input
Input data used for specific models.
Definition: ReactionRate.h:230
virtual void getParameters(AnyMap &node) const
Get parameters.
Definition: ReactionRate.h:224
size_t m_rate_index
Index of reaction rate within kinetics evaluator.
Definition: ReactionRate.h:233
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