Cantera  2.4.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 
13 // This file is part of Cantera. See License.txt in the top-level directory or
14 // at http://www.cantera.org/license.txt for license and copyright information.
15 
16 #ifndef CT_IMPORTKINETICS_H
17 #define CT_IMPORTKINETICS_H
18 
19 #include "Kinetics.h"
20 
21 namespace Cantera
22 {
23 
24 //! Install information about reactions into the kinetics object, kin.
25 /*!
26  * At this point, parent usually refers to the phase XML element. One of the
27  * children of this element is reactionArray, the element which determines
28  * where in the XML file to look up the reaction rate data.
29  *
30  * @param p parent XML phase element
31  * @param kin Kinetics object to install reactions into
32  * @param default_phase The default_phase is the default phase to assume when
33  * looking up species.
34  * @param check_for_duplicates Check for reactions with exactly the same
35  * reactants and products.
36  *
37  * @return
38  * On return, if reaction instantiation goes correctly, return true.
39  * If there is a problem, return false.
40  *
41  * @ingroup kineticsmgr
42  */
43 bool installReactionArrays(const XML_Node& p, Kinetics& kin,
44  std::string default_phase,
45  bool check_for_duplicates = false);
46 
47 //! Import a reaction mechanism for a phase or an interface.
48 /*!
49  * This routine will import a reaction mechanism into a kinetics object. The
50  * reaction mechanism may either be homogeneous or heterogeneous, involving
51  * multiple ThermoPhase objects. The hosting phase should be included as the
52  * first argument. For example, if phase I is an interface phase between bulk
53  * phases A and B. Then, the XML_Node for phase I should be the first
54  * argument. The vector of ThermoPhase objects should consist of pointers to
55  * phases I, A, and B.
56  *
57  * @param phase This is an XML node containing a description of the owning
58  * phase for the kinetics object. Within the phase is a XML
59  * element called reactionArray containing the location of the
60  * description of the reactions that make up the kinetics object.
61  * Also within the phase is an XML element called phaseArray
62  * containing a listing of other phases that participate in the
63  * kinetics mechanism.
64  *
65  * @param th This is a list of ThermoPhase pointers which must include all
66  * of the phases that participate in the kinetics operator. All
67  * of the phases must have already been initialized and formed
68  * within Cantera. However, their pointers should not have been
69  * added to the Kinetics object; this addition is carried out
70  * here. Additional phases may be include in the list; these have
71  * no effect.
72  *
73  * @param kin This is a pointer to a kinetics manager class that will be
74  * initialized with the kinetics mechanism. Inherited Kinetics
75  * classes should be used here.
76  *
77  * @ingroup kineticsmgr
78  */
79 bool importKinetics(const XML_Node& phase, std::vector<ThermoPhase*> th,
80  Kinetics* kin);
81 
82 //! Build a single-phase ThermoPhase object with associated kinetics mechanism.
83 /*!
84  * In a single call, this routine initializes a ThermoPhase object and a
85  * homogeneous kinetics object for a phase. It returns the fully initialized
86  * ThermoPhase object pointer and kinetics pointer.
87  *
88  * @param root pointer to the XML tree which will be searched to find the
89  * XML phase element.
90  * @param id Name of the phase to be searched for.
91  * @param nm Name of the XML element. Should be "phase"
92  * @param th Pointer to a bare ThermoPhase object, which will be initialized
93  * by this operation.
94  * @param kin Pointer to a bare Kinetics object, which will be initialized
95  * by this operation to a homogeneous kinetics manager
96  * @return
97  * Returns true if all went well. If there are errors, it will return false.
98  *
99  * For Example
100  *
101  * @code
102  * ThermoPhase *th = new ThermoPhase();
103  * Kinetics *kin = new Kinetics();
104  * XML_Node *root = get_XML_File("gri30.xml");
105  * ok = buildSolutionFromXML(root, "gri30_mix", "phase", th, kin)
106  * @endcode
107  *
108  * @ingroup inputfiles
109  * @see importKinetics()
110  */
111 bool buildSolutionFromXML(XML_Node& root, const std::string& id,
112  const std::string& nm, ThermoPhase* th, Kinetics* kin);
113 
114 //! Check to ensure that all electrochemical reactions are specified correctly
115 /*!
116  * This function ensures the user has correctly specified all electrochemical
117  * reactions. The routine counts the amount of charge (i.e. number of electron
118  * elements specified for each species in each phase) for both reactants and
119  * products. If net charge transfer phases during a reaction, the reaction is
120  * electrochemical. If not already specified as such, the function defines the
121  * reaction as electrochemical, corrects the reaction attributes, and sets
122  * beta = 0.5.
123  *
124  * @param p This is an XML node containing a description of the owning
125  * phase for the kinetics object.
126  * @param kin This is a pointer to a kinetics manager class.
127  * @param r This is the reaction node that is being evaluated
128  * @return The function always returns true.
129 */
130 bool checkElectrochemReaction(const XML_Node& p, Kinetics& kin, const XML_Node& r);
131 
132 
133 }
134 
135 #endif
bool installReactionArrays(const XML_Node &p, Kinetics &kin, std::string default_phase, bool check_for_duplicates)
Install information about reactions into the kinetics object, kin.
bool importKinetics(const XML_Node &phase, std::vector< ThermoPhase *> th, Kinetics *k)
Import a reaction mechanism for a phase or an interface.
bool checkElectrochemReaction(const XML_Node &p, Kinetics &kin, const XML_Node &r)
Check to ensure that all electrochemical reactions are specified correctly.
Base class for kinetics managers and also contains the kineticsmgr module documentation (see Kinetics...
bool buildSolutionFromXML(XML_Node &root, const std::string &id, const std::string &nm, ThermoPhase *th, Kinetics *kin)
Build a single-phase ThermoPhase object with associated kinetics mechanism.
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:8