Cantera  2.0
importKinetics.h
Go to the documentation of this file.
1 /**
2  * @file importKinetics.h
3  * Definitions of global routines for the importing
4  * of data from XML files (see \ref inputfiles).
5  *
6  * This file contains routines which are global routines, i.e.,
7  * not part of any object. These routine take as input, ctml
8  * pointers to data, and pointers to %Cantera objects. The purpose
9  * of these routines is to initialize the %Cantera objects with data
10  * from the ctml tree structures.
11  */
12 // Copyright 2002 California Institute of Technology
13 
14 
15 #ifndef CT_IMPORTCTML_H
16 #define CT_IMPORTCTML_H
17 
18 #include <string>
19 
21 #include "Kinetics.h"
22 
23 namespace Cantera
24 {
25 
26 class Kinetics;
27 class SpeciesThermoFactory;
28 class XML_Node;
29 
30 //! Rules for parsing and installing reactions
32 {
33  ReactionRules();
34  bool skipUndeclaredSpecies;
35  bool skipUndeclaredThirdBodies;
36  bool allowNegativeA;
37 };
38 
39 //!This function returns a ratio if two reactions are duplicates of
40 //!one another, and 0.0 otherwise.
41 /*!
42  * The input arguments are two
43  * maps from species number to stoichiometric coefficient, one for
44  * each reaction. The reactions are considered duplicates if their
45  * stoichiometric coefficients have the same ratio for all
46  * species.
47  *
48  * @param r1 map 1
49  * @param r2 map 2
50  *
51  * @return
52  * Returns 0.0 if the reactions are not the same.
53  * If the reactions are the same, it returns the ratio of the
54  * stoichiometric coefficients.
55  *
56  * @ingroup kineticsmgr
57  */
58 doublereal isDuplicateReaction(std::map<int, doublereal>& r1,
59  std::map<int, doublereal>& r2);
60 
61 
62 //! This function will check a specific reaction to see if the elements balance.
63 /*!
64  * @param kin Kinetics object
65  * @param rdata Object containing the information about one reaction
66  * @param errorTolerance double containing the error tolerance.
67  *
68  * @ingroup kineticsmgr
69  */
71  const ReactionData& rdata,
72  doublereal errorTolerance = 1.0e-3);
73 
74 /**
75  * Get the reactants or products of a reaction. The information
76  * is returned in the spnum, stoich, and order vectors. The
77  * length of the vectors is the number of different types of
78  * reactants or products found for the reaction.
79  *
80  * Input
81  * --------
82  * rxn -> xml node pointing to the reaction element
83  * in the xml tree.
84  * kin -> Reference to the kinetics object to install
85  * the information into.
86  * rp = 1 -> Go get the reactants for a reaction
87  * -1 -> Go get the products for a reaction
88  * default_phase = String name for the default phase
89  * to loop up species in.
90  * Output
91  * -----------
92  * spnum = vector of species numbers found.
93  * Length is number of reactants or products.
94  * stoich = stoichiometric coefficient of the reactant or product
95  * Length is number of reactants or products.
96  * order = Order of the reactant and product in the reaction rate expression
97  * @param rules If rules.skipUndeclaredSpecies is set and we fail to find a
98  * species we simply return false, allowing the calling routine to skip
99  * this reaction and continue. Otherwise, we will throw an error.
100  */
101 bool getReagents(const XML_Node& rxn, Kinetics& kin, int rp,
102  std::string default_phase,
103  std::vector<size_t>& spnum, vector_fp& stoich,
104  vector_fp& order, const ReactionRules& rule);
105 
106 //! Read the rate coefficient data from the XML file.
107 /*!
108  * Extract the rate coefficient for a reaction from the xml node, kf.
109  * kf should point to a XML element named "rateCoeff".
110  * rdata is the partially filled ReactionData object for the reaction.
111  * This function will fill in more fields in the ReactionData object.
112  *
113  * @param kf XML_Node containing information about the rate coefficients.
114  * @param kin kinetics manager
115  * @param rdata ReactionData reference
116  * @param rules Rules for parsing and installing reactions
117  *
118  * Trigger an exception for negative A unless specifically authorized.
119  *
120  * @ingroup kineticsmgr
121  */
122 void getRateCoefficient(const XML_Node& kf, Kinetics& kin, ReactionData& rdata,
123  const ReactionRules& rules);
124 
125 
126 //! Create a new ThermoPhase object and initializes it according to the XML tree database.
127 
128 
129 //! Install information about reactions into the kinetics object, kin.
130 /*!
131  * At this point, parent usually refers to the phase xml element.
132  * One of the children of this element is reactionArray,
133  * the element which determines where in the xml file to
134  * look up the reaction rate data.
135  *
136  * This is a wrapper routine around the static function installReaction()
137  *
138  * @param p parent XML phase element
139  * @param kin Kinetics object to install reactions into
140  * @param default_phase The default_phase is the default phase to assume when
141  * looking up species.
142  * @param check_for_duplicates Check for reactions with exactly the same
143  * reactants and products.
144  *
145  * @return
146  * On return, if reaction instantiation goes correctly, return true.
147  * If there is a problem, return false.
148  *
149  * @ingroup kineticsmgr
150  */
151 bool installReactionArrays(const XML_Node& p, Kinetics& kin,
152  std::string default_phase,
153  bool check_for_duplicates = false);
154 
155 //! Import a reaction mechanism for a phase or an interface.
156 /*!
157  * This routine will import a reaction mechanism into a
158  * kinetics object. The reaction
159  * mechanism may either be homogeneous or heterogeneous,
160  * involving multiple ThermoPhase objects.
161  * The hosting phase should be included as the first argument.
162  * For example, if phase I is an interface phase between bulk
163  * phases A and B. Then, the XML_Node for phase I should be
164  * the first argument.
165  * The vector of %ThermoPhase objects should consist of pointers
166  * to phases I, A, and B.
167  *
168  * @param phase This is an xml node containing a description
169  * of the owning phase for the kinetics object.
170  * Within the phase is a XML element
171  * called reactionArray containing the location
172  * of the description of the reactions that make
173  * up the kinetics object.
174  * Also within the phase is an XML element called
175  * phaseArray containing a listing of other phases
176  * that participate in the kinetics mechanism.
177  *
178  * @param th This is a list of ThermoPhase pointers which must
179  * include all of
180  * the phases that participate in the kinetics
181  * operator. All of the phases must have already
182  * been initialized and formed within Cantera.
183  * However, their pointers should not have been
184  * added to the Kinetics object; this addition
185  * is carried out here. Additional phases may
186  * be include in the list; these have no effect.
187  *
188  * @param kin This is a pointer to a kinetics manager class
189  * that will be initialized with the kinetics
190  * mechanism. Inherited Kinetics classes may be
191  * used here.
192  *
193  * @ingroup kineticsmgr
194  *
195  */
196 bool importKinetics(const XML_Node& phase, std::vector<ThermoPhase*> th,
197  Kinetics* kin);
198 
199 //!Build a single-phase ThermoPhase object with associated kinetics mechanism.
200 /*!
201  * In a single call, this routine initializes a ThermoPhase object and a
202  * homogeneous kinetics object for a phase.
203  *
204  * @param root pointer to the XML tree which will be searched to find the
205  * XML phase element.
206  *
207  * @param id Name of the phase to be searched for.
208  * @param nm Name of the XML element. Should be "phase"
209  * @param th Pointer to a bare ThermoPhase object, which will be initialized
210  * by this operation.
211  * @param k Pointer to a bare Kinetics object, which will be initialized
212  * by this operation to a homogeneous kinetics manager
213  *
214  * @return
215  * Returns true if all went well. If there are errors, it will return false.
216  *
217  * For Example
218  *
219  * @code
220  * ThermoPhase *th = new ThermoPhase();
221  * Kinetics *k = new Kinetics();
222  * XML_Node *root = get_XML_File("gri30.xml");
223  * ok = buildSolutionFromXML(root, "gri30_mix", "phase", th, k)
224  * @endcode
225  *
226  * @ingroup inputfiles
227  * @see importKinetics()
228  */
229 bool buildSolutionFromXML(XML_Node& root, std::string id, std::string nm,
230  ThermoPhase* th, Kinetics* k);
231 
232 //! Search an XML tree for species data.
233 /*!
234  *
235  * This utility routine will search the XML tree for the species
236  * named by the string, kname. It will return the XML_Node
237  * pointer.
238  * Failures of any kind return the null pointer.
239  *
240  * @param kname species Name
241  * @param phaseSpeciesData Pointer to the phase XML node pertaining to the
242  * species database for the phase to be found
243  *
244  * @return
245  * Returns a pointer to the XML node containing the species data.
246  *
247  * @ingroup inputfiles
248  */
249 //const XML_Node *speciesXML_Node(std::string kname,
250 // const XML_Node *phaseSpeciesData);
251 
252 }
253 
254 #endif
255