Cantera 2.6.0

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/ctexceptions.h"
15
16 namespace Cantera
17{
18
19
20 class Reaction;
21
22//! Abstract base class for reaction rate definitions; this base class is used by
23//! user-facing APIs to access reaction rate objects
24//!
25//! In addition to the pure virtual methods declared in this class, complete derived
26//! classes must implement the method `evalFromStruct(const DataType& shared_data)`,
27//! where `DataType` is a container for parameters needed to evaluate reactions of that
28//! type. In addition, derived classes may also implement the method
29//! `updateFromStruct(const DataType& shared_data)` to update buffered data that
30//! is specific to a given reaction rate.
31//!
32//! The calculation of derivatives (or Jacobians) relies on the following methods:
33//! - Derived classes may implement the method
34//! `ddTScaledFromStruct(const DataType& shared_data)` for an analytical derivative
35//! with respect to temperature.
36//! - Associated `DataType` containers may overload the method
37//! `perturbTemperature(double deltaT)`, which is used for the calculation of
38//! numerical derivatives with respect to temperature if an analytic implementation
39//! is not available.
40//! - For reaction rate constants that depend on pressure or third-body collision
41//! partners, associated `DataType` containers should implement the methods
42//! `perturbPressure(double deltaP)` and/or `perturbThirdBodies(double deltaM)`,
43//! which allow for the calculation of numerical derivatives.
44 class ReactionRate
45{
46 public:
47 ReactionRate() : m_rate_index(npos) {}
48
49 // Copy constructor and assignment operator need to be defined because of the
50 // #m_evaluator member that can't (and shouldn't) be copied.
51 ReactionRate(const ReactionRate& other)
52 : m_input(other.m_input)
53 , m_rate_index(other.m_rate_index)
54 {}
55
56 ReactionRate& operator=(const ReactionRate& other) {
57 if (this == &other) {
58 return *this;
59 }
60 m_input = other.m_input;
61 m_rate_index = other.m_rate_index;
62 return *this;
63 }
64
65 virtual ~ReactionRate() = default;
66
67 //! Create a rate evaluator for reactions of a particular derived type.
68 //! Derived classes usually implement this as:
69 //!
70 //! ```.cpp
71 //! unique_ptr<MultiRateBase> newMultiRate() const override {
72 //! return unique_ptr<MultiRateBase>(new MultiRate<RateType, DataType>);
73 //! ```
74 //!
75 //! where `RateType` is the derived class name and `DataType` is the corresponding
76 //! container for parameters needed to evaluate reactions of that type.
77 virtual unique_ptr<MultiRateBase> newMultiRate() const {
78 throw NotImplementedError("ReactionRate::newMultiRate",
79 "Not implemented by '{}' object.", type());
80 }
81
82 //! String identifying reaction rate specialization
83 virtual const std::string type() const = 0;
84
85 //! Set parameters
86 //! @param node AnyMap object containing reaction rate specification
87 //! @param units unit definitions specific to rate information
88 virtual void setParameters(const AnyMap& node, const UnitStack& units) {
89 m_input = node;
90 }
91
92 //! Return the parameters such that an identical Reaction could be reconstructed
93 //! using the newReaction() function. Behavior specific to derived classes is
94 //! handled by the getParameters() method.
95 AnyMap parameters() const {
96 AnyMap out;
97 getParameters(out);
98 return out;
99 }
100
101 //! Check basic syntax and settings of reaction rate expression
102 virtual void check(const std::string& equation, const AnyMap& node) {}
103
104 //! Validate the reaction rate expression
105 virtual void validate(const std::string& equation, const Kinetics& kin) {}
106
107 //! Validate the reaction rate expression (legacy call)
108 //! @todo deprecate in favor of two-parameter version
109 virtual void validate(const std::string& equation) {}
110
111 //! Reaction rate index within kinetics evaluator
112 size_t rateIndex() const {
113 return m_rate_index;
114 }
115
116 //! Set reaction rate index within kinetics evaluator
117 void setRateIndex(size_t idx) {
118 m_rate_index = idx;
119 }
120
121 //! Set context of reaction rate evaluation
122 //! @param rxn Reaction object associated with rate
123 //! @param kin Kinetics object used for rate evaluation
124 //! This method allows for passing of information specific to the associated
125 //! reaction when a ReactionRate object is added a MultiRate reaction evaluator.
126 virtual void setContext(const Reaction& rxn, const Kinetics& kin) {
127 }
128
129 //! Evaluate reaction rate based on temperature
130 //! @param T temperature [K]
131 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
132 //! This method allows for testing of a reaction rate expression outside of
133 //! Kinetics reaction rate evaluators.
134 double eval(double T) {
135 _evaluator().update(T);
136 return _evaluator().evalSingle(*this);
137 }
138
139 //! Evaluate reaction rate based on temperature and an extra parameter.
140 //! Specific rate parameterizations may require an additional parameter, which
141 //! is specific to the derived ReactionRate object.
142 //! @param T temperature [K]
143 //! @param extra extra parameter used by parameterization
144 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
145 //! This method allows for testing of a reaction rate expression outside of
146 //! Kinetics reaction rate evaluators.
147 double eval(double T, double extra) {
148 _evaluator().update(T, extra);
149 return _evaluator().evalSingle(*this);
150 }
151
152 //! Evaluate reaction rate based on temperature and an extra vector parameter.
153 //! Specific rate parameterizations may require additional parameters, which
154 //! are specific to the derived ReactionRate object.
155 //! @param T temperature [K]
156 //! @param extra extra vector parameter used by parameterization
157 //! Used in conjunction with MultiRateBase::evalSingle / ReactionRate::eval.
158 //! This method allows for testing of a reaction rate expression outside of
159 //! Kinetics reaction rate evaluators.
160 //! @warning This method is an experimental part of the %Cantera API and
161 //! may be changed or removed without notice.
162 double eval(double T, const std::vector<double>& extra) {
163 _evaluator().update(T, extra);
164 return _evaluator().evalSingle(*this);
165 }
166
167 protected:
168 //! Get parameters
169 //! @param node AnyMap containing rate information
170 //! Store the parameters of a ReactionRate needed to reconstruct an identical
171 //! object. Does not include user-defined fields available in the #m_input map.
172 virtual void getParameters(AnyMap& node) const {
173 throw NotImplementedError("ReactionRate::getParameters",
174 "Not implemented by '{}' object.", type());
175 }
176
177 //! Input data used for specific models
178 AnyMap m_input;
179
180 //! Index of reaction rate within kinetics evaluator
181 size_t m_rate_index;
182
183 private:
184 //! Return an object that be used to evaluate the rate by converting general input
185 //! such as temperature and pressure into the `DataType` struct that is particular
186 //! to the rate model.
187 MultiRateBase& _evaluator() {
188 if (!m_evaluator) {
189 m_evaluator = newMultiRate();
190 }
191 return *m_evaluator;
192 }
193
194 unique_ptr<MultiRateBase> m_evaluator;
195};
196
197}
198
199#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:399
Cantera::Kinetics
Public interface for kinetics managers.
Definition: Kinetics.h:114
Cantera::MultiRateBase
An abstract base class for evaluating all reactions of a particular type.
Definition: MultiRateBase.h:27
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:187
Cantera::ReactionRate
Abstract base class for reaction rate definitions; this base class is used by user-facing APIs to acc...
Definition: ReactionRate.h:45
Cantera::ReactionRate::setParameters
virtual void setParameters(const AnyMap &node, const UnitStack &units)
Set parameters.
Definition: ReactionRate.h:88
Cantera::ReactionRate::check
virtual void check(const std::string &equation, const AnyMap &node)
Check basic syntax and settings of reaction rate expression.
Definition: ReactionRate.h:102
Cantera::ReactionRate::type
virtual const std::string type() const =0
String identifying reaction rate specialization.
Cantera::ReactionRate::eval
double eval(double T)
Evaluate reaction rate based on temperature.
Definition: ReactionRate.h:134
Cantera::ReactionRate::setContext
virtual void setContext(const Reaction &rxn, const Kinetics &kin)
Set context of reaction rate evaluation.
Definition: ReactionRate.h:126
Cantera::ReactionRate::validate
virtual void validate(const std::string &equation, const Kinetics &kin)
Validate the reaction rate expression.
Definition: ReactionRate.h:105
Cantera::ReactionRate::eval
double eval(double T, double extra)
Evaluate reaction rate based on temperature and an extra parameter.
Definition: ReactionRate.h:147
Cantera::ReactionRate::rateIndex
size_t rateIndex() const
Reaction rate index within kinetics evaluator.
Definition: ReactionRate.h:112
Cantera::ReactionRate::parameters
AnyMap parameters() const
Return the parameters such that an identical Reaction could be reconstructed using the newReaction() ...
Definition: ReactionRate.h:95
Cantera::ReactionRate::setRateIndex
void setRateIndex(size_t idx)
Set reaction rate index within kinetics evaluator.
Definition: ReactionRate.h:117
Cantera::ReactionRate::newMultiRate
virtual unique_ptr< MultiRateBase > newMultiRate() const
Create a rate evaluator for reactions of a particular derived type.
Definition: ReactionRate.h:77
Cantera::ReactionRate::validate
virtual void validate(const std::string &equation)
Validate the reaction rate expression (legacy call)
Definition: ReactionRate.h:109
Cantera::ReactionRate::m_input
AnyMap m_input
Input data used for specific models.
Definition: ReactionRate.h:178
Cantera::ReactionRate::getParameters
virtual void getParameters(AnyMap &node) const
Get parameters.
Definition: ReactionRate.h:172
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:187
Cantera::ReactionRate::m_rate_index
size_t m_rate_index
Index of reaction rate within kinetics evaluator.
Definition: ReactionRate.h:181
Cantera::ReactionRate::eval
double eval(double T, const std::vector< double > &extra)
Evaluate reaction rate based on temperature and an extra vector parameter.
Definition: ReactionRate.h:162
Cantera::Reaction
Abstract base class which stores data about a reaction and its rate parameterization so that it can b...
Definition: Reaction.h:33
ctexceptions.h
Definitions for the classes that are thrown when Cantera experiences an error condition (also contain...
Cantera
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:557
Cantera::npos
const size_t npos
index returned by functions to indicate "no position"
Definition: ct_defs.h:192
Cantera::UnitStack
Unit aggregation utility.
Definition: Units.h:99