| Cantera 3.0.0

Loading...
Searching...
No Matches
Reaction.h
Go to the documentation of this file.
1/**
2 * @file Reaction.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_REACTION_H
9#define CT_REACTION_H
10
11#include "cantera/base/AnyMap.h"
12#include "cantera/base/Units.h"
13#include "ReactionRate.h"
14
15 namespace Cantera
16{
17
18 class Kinetics;
19 class ThirdBody;
20 class ArrheniusRate; // @todo Remove after Cantera 3.0
21 class FalloffRate; // @todo Remove after Cantera 3.0
22
23//! Abstract base class which stores data about a reaction and its rate
24//! parameterization so that it can be added to a Kinetics object.
25//! @ingroup reactionGroup
26 class Reaction
27{
28 public:
29 Reaction() {}
30 Reaction(const Composition& reactants, const Composition& products,
31 shared_ptr<ReactionRate> rate, shared_ptr<ThirdBody> tbody=nullptr);
32 Reaction(const string& equation,
33 shared_ptr<ReactionRate> rate, shared_ptr<ThirdBody> tbody=nullptr);
34
35 //! Construct a Reaction and corresponding ReactionRate based on AnyMap (YAML)
36 //! input.
37 Reaction(const AnyMap& node, const Kinetics& kin);
38
39 virtual ~Reaction() {}
40
41 //! The reactant side of the chemical equation for this reaction
42 string reactantString() const;
43
44 //! The product side of the chemical equation for this reaction
45 string productString() const;
46
47 //! The chemical equation for this reaction
48 string equation() const;
49
50 //! Set the reactants and products based on the reaction equation. If a Kinetics
51 //! object is provided, it is used to check that all reactants and products exist.
52 void setEquation(const string& equation, const Kinetics* kin=0);
53
54 //! The type of reaction, including reaction rate information
55 string type() const;
56
57 //! Calculate the units of the rate constant. These are determined by the units
58 //! of the standard concentration of the reactant species' phases and the phase
59 //! where the reaction occurs. Sets the value of #rate_units.
60 UnitStack calculateRateCoeffUnits(const Kinetics& kin);
61
62 //! Calculate the units of the rate constant.
63 //! @deprecated To be removed after %Cantera 3.0. Replaceable by
64 //! calculateRateCoeffUnits.
65 UnitStack calculateRateCoeffUnits3(const Kinetics& kin) {
66 warn_deprecated("Reaction::calculateRateCoeffUnits3",
67 "Deprecated in Cantera 3.0 and to be removed thereafter; replaceable "
68 "by calculateRateCoeffUnits.");
69 return calculateRateCoeffUnits(kin);
70 }
71
72 //! Ensure that the rate constant and other parameters for this reaction are valid.
73 //! @since New in %Cantera 3.0.
74 void check();
75
76 //! Ensure that the rate constant and other parameters for this reaction are valid.
77 //! @deprecated To be removed after %Cantera 3.0. Replaceable by check.
78 void validate() {
79 warn_deprecated("Reaction::validate",
80 "Deprecated in Cantera 3.0 and to be removed thereafter; replaceable "
81 "by Reaction::check.");
82 check();
83 }
84
85 //! Perform validation checks that need access to a complete Kinetics objects, for
86 // example to retrieve information about reactant / product species.
87 void validate(Kinetics& kin) {
88 if (m_rate) {
89 m_rate->validate(equation(), kin);
90 }
91 }
92
93 //! Return the parameters such that an identical Reaction could be reconstructed
94 //! using the newReaction() function. Behavior specific to derived classes is
95 //! handled by the getParameters() method.
96 //! @param withInput If true, include additional input data fields associated
97 //! with the object, such as user-defined fields from a YAML input file, as
98 //! contained in the #input attribute.
99 AnyMap parameters(bool withInput=true) const;
100
101 //! Set up reaction based on AnyMap *node*
102 void setParameters(const AnyMap& node, const Kinetics& kin);
103
104 //! Get validity flag of reaction
105 bool valid() const {
106 return m_valid;
107 }
108
109 //! Set validity flag of reaction
110 void setValid(bool valid) {
111 m_valid = valid;
112 }
113
114 //! Check that the specified reaction is balanced (same number of atoms for
115 //! each element in the reactants and products). Raises an exception if the
116 //! reaction is not balanced. Used by checkSpecies.
117 //! @param kin Kinetics object
118 void checkBalance(const Kinetics& kin) const;
119
120 //! Verify that all species involved in the reaction are defined in the Kinetics
121 //! object. The function returns true if all species are found, and raises an
122 //! exception unless the kinetics object is configured to skip undeclared species,
123 //! in which case false is returned.
124 //! @param kin Kinetics object
125 bool checkSpecies(const Kinetics& kin) const;
126
127 //! Check whether reaction uses electrochemistry
128 //! @param kin Kinetics object
129 bool usesElectrochemistry(const Kinetics& kin) const;
130
131 //! Reactant species and stoichiometric coefficients
132 Composition reactants;
133
134 //! Product species and stoichiometric coefficients
135 Composition products;
136
137 //! Forward reaction order with respect to specific species. By default,
138 //! mass-action kinetics is assumed, with the reaction order equal to each
139 //! reactant's stoichiometric coefficient.
140 Composition orders;
141
142 //! An identification string for the reaction, used in some filtering
143 //! operations
144 string id;
145
146 //! True if the current reaction is reversible. False otherwise
147 bool reversible = true;
148
149 //! True if the current reaction is marked as duplicate
150 bool duplicate = false;
151
152 //! True if reaction orders can be specified for non-reactant species.
153 //! Default is `false`.
154 bool allow_nonreactant_orders = false;
155
156 //! True if negative reaction orders are allowed. Default is `false`.
157 bool allow_negative_orders = false;
158
159 //! Input data used for specific models
160 AnyMap input;
161
162 //! The units of the rate constant. These are determined by the units of the
163 //! standard concentration of the reactant species' phases of the phase
164 //! where the reaction occurs.
165 Units rate_units{0.0};
166
167 //! Get reaction rate pointer
168 shared_ptr<ReactionRate> rate() {
169 return m_rate;
170 }
171
172 //! Set reaction rate pointer
173 void setRate(shared_ptr<ReactionRate> rate);
174
175 //! Get pointer to third-body handler
176 shared_ptr<ThirdBody> thirdBody() {
177 return m_third_body;
178 }
179
180 //! Check whether reaction involves third body collider
181 //! @since New in %Cantera 3.0.
182 bool usesThirdBody() const {
183 return bool(m_third_body);
184 }
185
186 protected:
187 //! Store the parameters of a Reaction needed to reconstruct an identical
188 //! object using the newReaction(AnyMap&, Kinetics&) function. Does not
189 //! include user-defined fields available in the #input map.
190 void getParameters(AnyMap& reactionNode) const;
191
192 //! Flag indicating whether reaction is set up correctly
193 bool m_valid = true;
194
195 //! Flag indicating that serialization uses explicit type
196 bool m_explicit_type = false;
197
198 //! Flag indicating that object was instantiated from reactant/product compositions
199 bool m_from_composition = false;
200
201 //! Reaction rate used by generic reactions
202 shared_ptr<ReactionRate> m_rate;
203
204 //! Relative efficiencies of third-body species in enhancing the reaction rate
205 //! (if applicable)
206 shared_ptr<ThirdBody> m_third_body;
207};
208
209
210//! A class for managing third-body efficiencies, including default values
211//! @ingroup reactionGroup
212 class ThirdBody
213{
214 public:
215 explicit ThirdBody() {};
216 ThirdBody(const string& third_body);
217 ThirdBody(const AnyMap& node);
218
219 //! @deprecated To be removed after %Cantera 3.0; instantiate using string instead
220 ThirdBody(double default_efficiency);
221
222 //! Name of the third body collider
223 //! @since New in %Cantera 3.0
224 string name() const {
225 return m_name;
226 }
227
228 //! Set name of the third body collider
229 //! @since New in %Cantera 3.0
230 void setName(const string& third_body);
231
232 //! Set third-body efficiencies from AnyMap *node*
233 //! @deprecated To be removed after %Cantera 3.0; renamed to setParameters
234 void setEfficiencies(const AnyMap& node);
235
236 //! Set third-body efficiencies from AnyMap *node*
237 //! @since New in %Cantera 3.0
238 void setParameters(const AnyMap& node);
239
240 //! Get third-body efficiencies from AnyMap *node*
241 //! @param node AnyMap receiving serialized parameters
242 //! @since New in %Cantera 3.0
243 void getParameters(AnyMap& node) const;
244
245 //! Get the third-body efficiency for species *k*
246 double efficiency(const string& k) const;
247
248 //! Suffix representing the third body collider in reaction equation, for example
249 //! `+ M` or `(+M)`
250 //! @since New in %Cantera 3.0
251 string collider() const;
252
253 //! Verify that all species involved in collision efficiencies are defined in the
254 //! Kinetics object. The function returns true if all species are found, and raises
255 //! an exception unless the Kinetics object is configured to skip undeclared
256 //! species, in which case false is returned.
257 //! @param rxn Reaction object
258 //! @param kin Kinetics object
259 //! @since New in %Cantera 3.0
260 bool checkSpecies(const Reaction& rxn, const Kinetics& kin) const;
261
262 //! Map of species to third body efficiency
263 Composition efficiencies;
264
265 //! The default third body efficiency for species not listed in #efficiencies.
266 double default_efficiency = 1.;
267
268 //! Third body is used by law of mass action
269 //! (`true` for three-body reactions, `false` for falloff reactions)
270 bool mass_action = true;
271
272 //! Flag indicating whether third body requires explicit serialization
273 bool explicit_3rd = false;
274
275 protected:
276 //! Name of the third body collider
277 string m_name = "M";
278};
279
280
281//! A reaction with a non-reacting third body "M" that acts to add or remove
282//! energy from the reacting species
283//! @deprecated To be removed after %Cantera 3.0. Merged with Reaction
284 class ThreeBodyReaction : public Reaction
285{
286 public:
287 ThreeBodyReaction();
288 ThreeBodyReaction(const Composition& reactants, const Composition& products,
289 const ArrheniusRate& rate, const ThirdBody& tbody);
290
291 ThreeBodyReaction(const AnyMap& node, const Kinetics& kin);
292};
293
294
295//! A falloff reaction that is first-order in [M] at low pressure, like a third-body
296//! reaction, but zeroth-order in [M] as pressure increases.
297//! In addition, the class supports chemically-activated reactions where the rate
298//! decreases as pressure increases due to collisional stabilization of a reaction
299//! intermediate; in this case, the forward rate constant is written as being
300//! proportional to the low-pressure rate constant.
301//! @deprecated To be removed after %Cantera 3.0. Merged with Reaction
302 class FalloffReaction : public Reaction
303{
304 public:
305 FalloffReaction();
306 FalloffReaction(const Composition& reactants, const Composition& products,
307 const FalloffRate& rate, const ThirdBody& tbody);
308
309 FalloffReaction(const AnyMap& node, const Kinetics& kin);
310};
311
312
313//! Create a new empty Reaction object
314/*!
315 * @param type string identifying type of reaction.
316 */
317unique_ptr<Reaction> newReaction(const string& type);
318
319//! Create a new Reaction object using the specified parameters
320/*!
321 * @param rxn_node AnyMap node describing reaction.
322 * @param kin kinetics manager
323 */
324unique_ptr<Reaction> newReaction(const AnyMap& rxn_node,
325 const Kinetics& kin);
326
327//! Create Reaction objects for each item (an AnyMap) in `items`. The species
328//! involved in these reactions must exist in the phases associated with the
329//! Kinetics object `kinetics`.
330 vector<shared_ptr<Reaction>> getReactions(const AnyValue& items, Kinetics& kinetics);
331
332//! Parse reaction equation
333 void parseReactionEquation(Reaction& R, const string& equation,
334 const AnyBase& reactionNode, const Kinetics* kin);
335
336 using ThreeBodyReaction3 = ThreeBodyReaction; // @todo: remove after Cantera 3.0
337 using FalloffReaction3 = FalloffReaction; // @todo: remove after Cantera 3.0
338
339}
340#endif
AnyMap.h
ReactionRate.h
Units.h
Header for unit conversion utilities, which are used to translate user input from input files (See In...
Cantera::AnyBase
Base class defining common data possessed by both AnyMap and AnyValue objects.
Definition AnyMap.h:34
Cantera::AnyMap
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:427
Cantera::AnyValue
A wrapper for a variable whose type is determined at runtime.
Definition AnyMap.h:86
Cantera::ArrheniusRate
Arrhenius reaction rate type depends only on temperature.
Definition Arrhenius.h:170
Cantera::FalloffRate
Base class for falloff rate calculators.
Definition Falloff.h:83
Cantera::FalloffReaction
A falloff reaction that is first-order in [M] at low pressure, like a third-body reaction,...
Definition Reaction.h:303
Cantera::Kinetics
Public interface for kinetics managers.
Definition Kinetics.h:126
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::Reaction::setParameters
void setParameters(const AnyMap &node, const Kinetics &kin)
Set up reaction based on AnyMap node
Definition Reaction.cpp:231
Cantera::Reaction::calculateRateCoeffUnits
UnitStack calculateRateCoeffUnits(const Kinetics &kin)
Calculate the units of the rate constant.
Definition Reaction.cpp:525
Cantera::Reaction::m_from_composition
bool m_from_composition
Flag indicating that object was instantiated from reactant/product compositions.
Definition Reaction.h:199
Cantera::Reaction::checkBalance
void checkBalance(const Kinetics &kin) const
Check that the specified reaction is balanced (same number of atoms for each element in the reactants...
Definition Reaction.cpp:579
Cantera::Reaction::rate_units
Units rate_units
The units of the rate constant.
Definition Reaction.h:165
Cantera::Reaction::valid
bool valid() const
Get validity flag of reaction.
Definition Reaction.h:105
Cantera::Reaction::rate
shared_ptr< ReactionRate > rate()
Get reaction rate pointer.
Definition Reaction.h:168
Cantera::Reaction::orders
Composition orders
Forward reaction order with respect to specific species.
Definition Reaction.h:140
Cantera::Reaction::validate
void validate()
Ensure that the rate constant and other parameters for this reaction are valid.
Definition Reaction.h:78
Cantera::Reaction::checkSpecies
bool checkSpecies(const Kinetics &kin) const
Verify that all species involved in the reaction are defined in the Kinetics object.
Definition Reaction.cpp:646
Cantera::Reaction::setRate
void setRate(shared_ptr< ReactionRate > rate)
Set reaction rate pointer.
Definition Reaction.cpp:269
Cantera::Reaction::m_third_body
shared_ptr< ThirdBody > m_third_body
Relative efficiencies of third-body species in enhancing the reaction rate (if applicable)
Definition Reaction.h:206
Cantera::Reaction::parameters
AnyMap parameters(bool withInput=true) const
Return the parameters such that an identical Reaction could be reconstructed using the newReaction() ...
Definition Reaction.cpp:161
Cantera::Reaction::m_explicit_type
bool m_explicit_type
Flag indicating that serialization uses explicit type.
Definition Reaction.h:196
Cantera::Reaction::usesThirdBody
bool usesThirdBody() const
Check whether reaction involves third body collider.
Definition Reaction.h:182
Cantera::Reaction::reactantString
string reactantString() const
The reactant side of the chemical equation for this reaction.
Definition Reaction.cpp:311
Cantera::Reaction::productString
string productString() const
The product side of the chemical equation for this reaction.
Definition Reaction.cpp:329
Cantera::Reaction::thirdBody
shared_ptr< ThirdBody > thirdBody()
Get pointer to third-body handler.
Definition Reaction.h:176
Cantera::Reaction::check
void check()
Ensure that the rate constant and other parameters for this reaction are valid.
Definition Reaction.cpp:125
Cantera::Reaction::m_valid
bool m_valid
Flag indicating whether reaction is set up correctly.
Definition Reaction.h:193
Cantera::Reaction::reversible
bool reversible
True if the current reaction is reversible. False otherwise.
Definition Reaction.h:147
Cantera::Reaction::allow_nonreactant_orders
bool allow_nonreactant_orders
True if reaction orders can be specified for non-reactant species.
Definition Reaction.h:154
Cantera::Reaction::m_rate
shared_ptr< ReactionRate > m_rate
Reaction rate used by generic reactions.
Definition Reaction.h:202
Cantera::Reaction::type
string type() const
The type of reaction, including reaction rate information.
Definition Reaction.cpp:506
Cantera::Reaction::equation
string equation() const
The chemical equation for this reaction.
Definition Reaction.cpp:347
Cantera::Reaction::setEquation
void setEquation(const string &equation, const Kinetics *kin=0)
Set the reactants and products based on the reaction equation.
Definition Reaction.cpp:356
Cantera::Reaction::usesElectrochemistry
bool usesElectrochemistry(const Kinetics &kin) const
Check whether reaction uses electrochemistry.
Definition Reaction.cpp:690
Cantera::Reaction::getParameters
void getParameters(AnyMap &reactionNode) const
Store the parameters of a Reaction needed to reconstruct an identical object using the newReaction(An...
Definition Reaction.cpp:183
Cantera::Reaction::allow_negative_orders
bool allow_negative_orders
True if negative reaction orders are allowed. Default is false.
Definition Reaction.h:157
Cantera::Reaction::products
Composition products
Product species and stoichiometric coefficients.
Definition Reaction.h:135
Cantera::Reaction::reactants
Composition reactants
Reactant species and stoichiometric coefficients.
Definition Reaction.h:132
Cantera::Reaction::id
string id
An identification string for the reaction, used in some filtering operations.
Definition Reaction.h:144
Cantera::Reaction::validate
void validate(Kinetics &kin)
Perform validation checks that need access to a complete Kinetics objects, for.
Definition Reaction.h:87
Cantera::Reaction::input
AnyMap input
Input data used for specific models.
Definition Reaction.h:160
Cantera::Reaction::duplicate
bool duplicate
True if the current reaction is marked as duplicate.
Definition Reaction.h:150
Cantera::Reaction::calculateRateCoeffUnits3
UnitStack calculateRateCoeffUnits3(const Kinetics &kin)
Calculate the units of the rate constant.
Definition Reaction.h:65
Cantera::Reaction::setValid
void setValid(bool valid)
Set validity flag of reaction.
Definition Reaction.h:110
Cantera::ThirdBody
A class for managing third-body efficiencies, including default values.
Definition Reaction.h:213
Cantera::ThirdBody::explicit_3rd
bool explicit_3rd
Flag indicating whether third body requires explicit serialization.
Definition Reaction.h:273
Cantera::ThirdBody::setParameters
void setParameters(const AnyMap &node)
Set third-body efficiencies from AnyMap node
Definition Reaction.cpp:774
Cantera::ThirdBody::setEfficiencies
void setEfficiencies(const AnyMap &node)
Set third-body efficiencies from AnyMap node
Definition Reaction.cpp:767
Cantera::ThirdBody::efficiency
double efficiency(const string &k) const
Get the third-body efficiency for species k
Definition Reaction.cpp:809
Cantera::ThirdBody::default_efficiency
double default_efficiency
The default third body efficiency for species not listed in efficiencies.
Definition Reaction.h:266
Cantera::ThirdBody::efficiencies
Composition efficiencies
Map of species to third body efficiency.
Definition Reaction.h:263
Cantera::ThirdBody::collider
string collider() const
Suffix representing the third body collider in reaction equation, for example + M or (+M)
Definition Reaction.cpp:814
Cantera::ThirdBody::mass_action
bool mass_action
Third body is used by law of mass action (true for three-body reactions, false for falloff reactions)
Definition Reaction.h:270
Cantera::ThirdBody::m_name
string m_name
Name of the third body collider.
Definition Reaction.h:277
Cantera::ThirdBody::getParameters
void getParameters(AnyMap &node) const
Get third-body efficiencies from AnyMap node
Definition Reaction.cpp:796
Cantera::ThirdBody::setName
void setName(const string &third_body)
Set name of the third body collider.
Definition Reaction.cpp:734
Cantera::ThirdBody::checkSpecies
bool checkSpecies(const Reaction &rxn, const Kinetics &kin) const
Verify that all species involved in collision efficiencies are defined in the Kinetics object.
Definition Reaction.cpp:822
Cantera::ThirdBody::name
string name() const
Name of the third body collider.
Definition Reaction.h:224
Cantera::ThreeBodyReaction
A reaction with a non-reacting third body "M" that acts to add or remove energy from the reacting spe...
Definition Reaction.h:285
Cantera::Units
A representation of the units associated with a dimensional quantity.
Definition Units.h:35
Cantera
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
Cantera::parseReactionEquation
void parseReactionEquation(Reaction &R, const string &equation, const AnyBase &reactionNode, const Kinetics *kin)
Parse reaction equation.
Definition Reaction.cpp:922
Cantera::getReactions
vector< shared_ptr< Reaction > > getReactions(const AnyValue &items, Kinetics &kinetics)
Create Reaction objects for each item (an AnyMap) in items.
Definition Reaction.cpp:992
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::Composition
map< string, double > Composition
Map from string names to doubles.
Definition ct_defs.h:184
Cantera::newReaction
unique_ptr< Reaction > newReaction(const string &type)
Create a new empty Reaction object.
Definition Reaction.cpp:912
Cantera::UnitStack
Unit aggregation utility.
Definition Units.h:105