Cantera  3.1.0a1
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
15namespace Cantera
16{
17
18class Kinetics;
19class ThirdBody;
20
21//! Abstract base class which stores data about a reaction and its rate
22//! parameterization so that it can be added to a Kinetics object.
23//! @ingroup reactionGroup
25{
26public:
27 Reaction() {}
29 shared_ptr<ReactionRate> rate, shared_ptr<ThirdBody> tbody=nullptr);
30 Reaction(const string& equation,
31 shared_ptr<ReactionRate> rate, shared_ptr<ThirdBody> tbody=nullptr);
32
33 //! Construct a Reaction and corresponding ReactionRate based on AnyMap (YAML)
34 //! input.
35 Reaction(const AnyMap& node, const Kinetics& kin);
36
37 virtual ~Reaction() {}
38
39 //! The reactant side of the chemical equation for this reaction
40 string reactantString() const;
41
42 //! The product side of the chemical equation for this reaction
43 string productString() const;
44
45 //! The chemical equation for this reaction
46 string equation() const;
47
48 //! Set the reactants and products based on the reaction equation. If a Kinetics
49 //! object is provided, it is used to check that all reactants and products exist.
50 void setEquation(const string& equation, const Kinetics* kin=0);
51
52 //! The type of reaction, including reaction rate information
53 string type() const;
54
55 //! Calculate the units of the rate constant. These are determined by the units
56 //! of the standard concentration of the reactant species' phases and the phase
57 //! where the reaction occurs. Sets the value of #rate_units.
59
60 //! Ensure that the rate constant and other parameters for this reaction are valid.
61 //! @since New in %Cantera 3.0.
62 void check();
63
64 //! Perform validation checks that need access to a complete Kinetics objects, for
65 // example to retrieve information about reactant / product species.
66 void validate(Kinetics& kin) {
67 if (m_rate) {
68 m_rate->validate(equation(), kin);
69 }
70 }
71
72 //! Return the parameters such that an identical Reaction could be reconstructed
73 //! using the newReaction() function. Behavior specific to derived classes is
74 //! handled by the getParameters() method.
75 //! @param withInput If true, include additional input data fields associated
76 //! with the object, such as user-defined fields from a YAML input file, as
77 //! contained in the #input attribute.
78 AnyMap parameters(bool withInput=true) const;
79
80 //! Set up reaction based on AnyMap *node*
81 void setParameters(const AnyMap& node, const Kinetics& kin);
82
83 //! Get validity flag of reaction
84 bool valid() const {
85 return m_valid;
86 }
87
88 //! Set validity flag of reaction
89 void setValid(bool valid) {
90 m_valid = valid;
91 }
92
93 //! Check that the specified reaction is balanced (same number of atoms for
94 //! each element in the reactants and products). Raises an exception if the
95 //! reaction is not balanced. Used by checkSpecies.
96 //! @param kin Kinetics object
97 void checkBalance(const Kinetics& kin) const;
98
99 //! Verify that all species involved in the reaction are defined in the Kinetics
100 //! object. The function returns true if all species are found, and raises an
101 //! exception unless the kinetics object is configured to skip undeclared species,
102 //! in which case false is returned.
103 //! @param kin Kinetics object
104 bool checkSpecies(const Kinetics& kin) const;
105
106 //! Check whether reaction uses electrochemistry
107 //! @param kin Kinetics object
108 bool usesElectrochemistry(const Kinetics& kin) const;
109
110 //! Reactant species and stoichiometric coefficients
112
113 //! Product species and stoichiometric coefficients
115
116 //! Forward reaction order with respect to specific species. By default,
117 //! mass-action kinetics is assumed, with the reaction order equal to each
118 //! reactant's stoichiometric coefficient.
120
121 //! An identification string for the reaction, used in some filtering
122 //! operations
123 string id;
124
125 //! True if the current reaction is reversible. False otherwise
126 bool reversible = true;
127
128 //! True if the current reaction is marked as duplicate
129 bool duplicate = false;
130
131 //! True if reaction orders can be specified for non-reactant species.
132 //! Default is `false`.
134
135 //! True if negative reaction orders are allowed. Default is `false`.
137
138 //! Input data used for specific models
140
141 //! The units of the rate constant. These are determined by the units of the
142 //! standard concentration of the reactant species' phases of the phase
143 //! where the reaction occurs.
145
146 //! Get reaction rate pointer
147 shared_ptr<ReactionRate> rate() {
148 return m_rate;
149 }
150
151 //! Set reaction rate pointer
152 void setRate(shared_ptr<ReactionRate> rate);
153
154 //! Get pointer to third-body handler
155 shared_ptr<ThirdBody> thirdBody() {
156 return m_third_body;
157 }
158
159 //! Check whether reaction involves third body collider
160 //! @since New in %Cantera 3.0.
161 bool usesThirdBody() const {
162 return bool(m_third_body);
163 }
164
165protected:
166 //! Store the parameters of a Reaction needed to reconstruct an identical
167 //! object using the newReaction(AnyMap&, Kinetics&) function. Does not
168 //! include user-defined fields available in the #input map.
169 void getParameters(AnyMap& reactionNode) const;
170
171 //! Flag indicating whether reaction is set up correctly
172 bool m_valid = true;
173
174 //! Flag indicating that serialization uses explicit type
175 bool m_explicit_type = false;
176
177 //! Flag indicating that object was instantiated from reactant/product compositions
178 bool m_from_composition = false;
179
180 //! Reaction rate used by generic reactions
181 shared_ptr<ReactionRate> m_rate;
182
183 //! Relative efficiencies of third-body species in enhancing the reaction rate
184 //! (if applicable)
185 shared_ptr<ThirdBody> m_third_body;
186};
187
188
189//! A class for managing third-body efficiencies, including default values
190//! @ingroup reactionGroup
192{
193public:
194 explicit ThirdBody() {};
195 ThirdBody(const string& third_body);
196 ThirdBody(const AnyMap& node);
197
198 //! Name of the third body collider
199 //! @since New in %Cantera 3.0
200 string name() const {
201 return m_name;
202 }
203
204 //! Set name of the third body collider
205 //! @since New in %Cantera 3.0
206 void setName(const string& third_body);
207
208 //! Set third-body efficiencies from AnyMap *node*
209 //! @since New in %Cantera 3.0
210 void setParameters(const AnyMap& node);
211
212 //! Get third-body efficiencies from AnyMap *node*
213 //! @param node AnyMap receiving serialized parameters
214 //! @since New in %Cantera 3.0
215 void getParameters(AnyMap& node) const;
216
217 //! Get the third-body efficiency for species *k*
218 double efficiency(const string& k) const;
219
220 //! Suffix representing the third body collider in reaction equation, for example
221 //! `+ M` or `(+M)`
222 //! @since New in %Cantera 3.0
223 string collider() const;
224
225 //! Verify that all species involved in collision efficiencies are defined in the
226 //! Kinetics object. The function returns true if all species are found, and raises
227 //! an exception unless the Kinetics object is configured to skip undeclared
228 //! species, in which case false is returned.
229 //! @param rxn Reaction object
230 //! @param kin Kinetics object
231 //! @since New in %Cantera 3.0
232 bool checkSpecies(const Reaction& rxn, const Kinetics& kin) const;
233
234 //! Map of species to third body efficiency
236
237 //! The default third body efficiency for species not listed in #efficiencies.
239
240 //! Third body is used by law of mass action
241 //! (`true` for three-body reactions, `false` for falloff reactions)
242 bool mass_action = true;
243
244 //! Flag indicating whether third body requires explicit serialization
245 bool explicit_3rd = false;
246
247protected:
248 //! Name of the third body collider
249 string m_name = "M";
250};
251
252
253//! Create a new empty Reaction object
254/*!
255 * @param type string identifying type of reaction.
256 */
257unique_ptr<Reaction> newReaction(const string& type);
258
259//! Create a new Reaction object using the specified parameters
260/*!
261 * @param rxn_node AnyMap node describing reaction.
262 * @param kin kinetics manager
263 */
264unique_ptr<Reaction> newReaction(const AnyMap& rxn_node,
265 const Kinetics& kin);
266
267//! Create Reaction objects for each item (an AnyMap) in `items`. The species
268//! involved in these reactions must exist in the phases associated with the
269//! Kinetics object `kinetics`.
270vector<shared_ptr<Reaction>> getReactions(const AnyValue& items, Kinetics& kinetics);
271
272//! Parse reaction equation
273void parseReactionEquation(Reaction& R, const string& equation,
274 const AnyBase& reactionNode, const Kinetics* kin);
275
276}
277#endif
Header for unit conversion utilities, which are used to translate user input from input files (See In...
Base class defining common data possessed by both AnyMap and AnyValue objects.
Definition AnyMap.h:34
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:427
A wrapper for a variable whose type is determined at runtime.
Definition AnyMap.h:86
Public interface for kinetics managers.
Definition Kinetics.h:125
Abstract base class which stores data about a reaction and its rate parameterization so that it can b...
Definition Reaction.h:25
void setParameters(const AnyMap &node, const Kinetics &kin)
Set up reaction based on AnyMap node
Definition Reaction.cpp:229
UnitStack calculateRateCoeffUnits(const Kinetics &kin)
Calculate the units of the rate constant.
Definition Reaction.cpp:523
bool m_from_composition
Flag indicating that object was instantiated from reactant/product compositions.
Definition Reaction.h:178
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:576
Units rate_units
The units of the rate constant.
Definition Reaction.h:144
bool valid() const
Get validity flag of reaction.
Definition Reaction.h:84
shared_ptr< ReactionRate > rate()
Get reaction rate pointer.
Definition Reaction.h:147
Composition orders
Forward reaction order with respect to specific species.
Definition Reaction.h:119
bool checkSpecies(const Kinetics &kin) const
Verify that all species involved in the reaction are defined in the Kinetics object.
Definition Reaction.cpp:643
void setRate(shared_ptr< ReactionRate > rate)
Set reaction rate pointer.
Definition Reaction.cpp:267
shared_ptr< ThirdBody > m_third_body
Relative efficiencies of third-body species in enhancing the reaction rate (if applicable)
Definition Reaction.h:185
AnyMap parameters(bool withInput=true) const
Return the parameters such that an identical Reaction could be reconstructed using the newReaction() ...
Definition Reaction.cpp:159
bool m_explicit_type
Flag indicating that serialization uses explicit type.
Definition Reaction.h:175
bool usesThirdBody() const
Check whether reaction involves third body collider.
Definition Reaction.h:161
string reactantString() const
The reactant side of the chemical equation for this reaction.
Definition Reaction.cpp:309
string productString() const
The product side of the chemical equation for this reaction.
Definition Reaction.cpp:327
shared_ptr< ThirdBody > thirdBody()
Get pointer to third-body handler.
Definition Reaction.h:155
void check()
Ensure that the rate constant and other parameters for this reaction are valid.
Definition Reaction.cpp:123
bool m_valid
Flag indicating whether reaction is set up correctly.
Definition Reaction.h:172
bool reversible
True if the current reaction is reversible. False otherwise.
Definition Reaction.h:126
bool allow_nonreactant_orders
True if reaction orders can be specified for non-reactant species.
Definition Reaction.h:133
shared_ptr< ReactionRate > m_rate
Reaction rate used by generic reactions.
Definition Reaction.h:181
string type() const
The type of reaction, including reaction rate information.
Definition Reaction.cpp:504
string equation() const
The chemical equation for this reaction.
Definition Reaction.cpp:345
void setEquation(const string &equation, const Kinetics *kin=0)
Set the reactants and products based on the reaction equation.
Definition Reaction.cpp:354
bool usesElectrochemistry(const Kinetics &kin) const
Check whether reaction uses electrochemistry.
Definition Reaction.cpp:687
void getParameters(AnyMap &reactionNode) const
Store the parameters of a Reaction needed to reconstruct an identical object using the newReaction(An...
Definition Reaction.cpp:181
bool allow_negative_orders
True if negative reaction orders are allowed. Default is false.
Definition Reaction.h:136
Composition products
Product species and stoichiometric coefficients.
Definition Reaction.h:114
Composition reactants
Reactant species and stoichiometric coefficients.
Definition Reaction.h:111
string id
An identification string for the reaction, used in some filtering operations.
Definition Reaction.h:123
void validate(Kinetics &kin)
Perform validation checks that need access to a complete Kinetics objects, for.
Definition Reaction.h:66
AnyMap input
Input data used for specific models.
Definition Reaction.h:139
bool duplicate
True if the current reaction is marked as duplicate.
Definition Reaction.h:129
void setValid(bool valid)
Set validity flag of reaction.
Definition Reaction.h:89
A class for managing third-body efficiencies, including default values.
Definition Reaction.h:192
bool explicit_3rd
Flag indicating whether third body requires explicit serialization.
Definition Reaction.h:245
void setParameters(const AnyMap &node)
Set third-body efficiencies from AnyMap node
Definition Reaction.cpp:757
double efficiency(const string &k) const
Get the third-body efficiency for species k
Definition Reaction.cpp:792
double default_efficiency
The default third body efficiency for species not listed in efficiencies.
Definition Reaction.h:238
Composition efficiencies
Map of species to third body efficiency.
Definition Reaction.h:235
string collider() const
Suffix representing the third body collider in reaction equation, for example + M or (+M)
Definition Reaction.cpp:797
bool mass_action
Third body is used by law of mass action (true for three-body reactions, false for falloff reactions)
Definition Reaction.h:242
string m_name
Name of the third body collider.
Definition Reaction.h:249
void getParameters(AnyMap &node) const
Get third-body efficiencies from AnyMap node
Definition Reaction.cpp:779
void setName(const string &third_body)
Set name of the third body collider.
Definition Reaction.cpp:724
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:805
string name() const
Name of the third body collider.
Definition Reaction.h:200
A representation of the units associated with a dimensional quantity.
Definition Units.h:35
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
void parseReactionEquation(Reaction &R, const string &equation, const AnyBase &reactionNode, const Kinetics *kin)
Parse reaction equation.
Definition Reaction.cpp:842
vector< shared_ptr< Reaction > > getReactions(const AnyValue &items, Kinetics &kinetics)
Create Reaction objects for each item (an AnyMap) in items.
Definition Reaction.cpp:912
map< string, double > Composition
Map from string names to doubles.
Definition ct_defs.h:177
unique_ptr< Reaction > newReaction(const string &type)
Create a new empty Reaction object.
Definition Reaction.cpp:832
Unit aggregation utility.
Definition Units.h:105