From c43b02e1309594525b2d8c1c27393f7df82af125 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 12 Apr 2013 23:06:20 +0000 Subject: [PATCH] Cleaned up Doxygen docs for KineticsFactory and ImportKinetics --- include/cantera/kinetics/KineticsFactory.h | 28 +++-- include/cantera/kinetics/importKinetics.h | 125 ++++++++----------- src/kinetics/KineticsFactory.cpp | 28 ----- src/kinetics/importKinetics.cpp | 134 +++------------------ 4 files changed, 86 insertions(+), 229 deletions(-) diff --git a/include/cantera/kinetics/KineticsFactory.h b/include/cantera/kinetics/KineticsFactory.h index b2cde1b89..2768be267 100644 --- a/include/cantera/kinetics/KineticsFactory.h +++ b/include/cantera/kinetics/KineticsFactory.h @@ -15,7 +15,6 @@ namespace Cantera { - class UnknownKineticsModel : public CanteraError { public: @@ -26,15 +25,12 @@ public: virtual ~UnknownKineticsModel() throw() {} }; - /** * Factory for kinetics managers. */ class KineticsFactory : public FactoryBase { - public: - static KineticsFactory* factory() { ScopedLock lock(kinetics_mutex); if (!s_factory) { @@ -57,21 +53,36 @@ public: } /** - * Create a new kinetics manager. + * Return a new kinetics manager that implements a reaction mechanism + * specified in a CTML file. In other words, the kinetics manager, given + * the rate constants and formulation of the reactions that make up a + * kinetics mechanism, is responsible for calculating the rates of + * progress of the reactions and for calculating the source terms for + * species. + * + * @param phase An XML_Node that contains the xml data describing the + * phase. Of particular note to this routine is the child xml + * element called "kinetics". The element has one attribute + * called "model", with a string value. The value of this + * string is used to decide which kinetics manager is used to + * calculate the reaction mechanism. + * + * @return Pointer to the new kinetics manager. */ virtual Kinetics* newKinetics(XML_Node& phase, std::vector th); + /** + * Return a new, empty kinetics manager. + */ virtual Kinetics* newKinetics(const std::string& model); private: - static KineticsFactory* s_factory; KineticsFactory() {} static mutex_t kinetics_mutex; }; - /** * Create a new kinetics manager. */ @@ -97,6 +108,3 @@ inline Kinetics* newKineticsMgr(const std::string& model, KineticsFactory* f=0) } #endif - - - diff --git a/include/cantera/kinetics/importKinetics.h b/include/cantera/kinetics/importKinetics.h index 3f37bdbd7..9044c931c 100644 --- a/include/cantera/kinetics/importKinetics.h +++ b/include/cantera/kinetics/importKinetics.h @@ -38,11 +38,9 @@ struct ReactionRules { //!This function returns a ratio if two reactions are duplicates of //!one another, and 0.0 otherwise. /*! - * The input arguments are two - * maps from species number to stoichiometric coefficient, one for - * each reaction. The reactions are considered duplicates if their - * stoichiometric coefficients have the same ratio for all - * species. + * The input arguments are two maps from species number to stoichiometric + * coefficient, one for each reaction. The reactions are considered duplicates + * if their stoichiometric coefficients have the same ratio for all species. * * @param r1 map 1 * @param r2 map 2 @@ -57,7 +55,6 @@ struct ReactionRules { doublereal isDuplicateReaction(std::map& r1, std::map& r2); - //! This function will check a specific reaction to see if the elements balance. /*! * @param kin Kinetics object @@ -71,36 +68,31 @@ void checkRxnElementBalance(Kinetics& kin, doublereal errorTolerance = 1.0e-3); /** - * Get the reactants or products of a reaction. The information - * is returned in the spnum, stoich, and order vectors. The - * length of the vectors is the number of different types of - * reactants or products found for the reaction. + * Get the reactants or products of a reaction. The information is returned in + * the spnum, stoich, and order vectors. The length of the vectors is the + * number of different types of reactants or products found for the reaction. * - * Input - * -------- - * rxn -> xml node pointing to the reaction element - * in the xml tree. - * kin -> Reference to the kinetics object to install - * the information into. - * rp = 1 -> Go get the reactants for a reaction - * -1 -> Go get the products for a reaction - * default_phase = String name for the default phase - * to loop up species in. - * Output - * ----------- - * spnum = vector of species numbers found. - * Length is number of reactants or products. - * stoich = stoichiometric coefficient of the reactant or product - * Length is number of reactants or products. - * order = Order of the reactant and product in the reaction rate expression - * @param rules If rules.skipUndeclaredSpecies is set and we fail to find a - * species we simply return false, allowing the calling routine to skip - * this reaction and continue. Otherwise, we will throw an error. + * @param[in] rxn xml node pointing to the reaction element in the xml tree. + * @param[in] kin Reference to the kinetics object to install the information + * into. + * @param[in] rp 1 -> Go get the reactants for a reaction; -1 -> Go get the + * products for a reaction + * @param[in] default_phase Name for the default phase to loop up species in. + * @param[out] spnum vector of species numbers found. Length is number of + * reactants or products. + * @param[out] stoich stoichiometric coefficient of the reactant or product. + * Length is number of reactants or products. + * @param[out] order Order of the reactant and product in the reaction rate + * expression. + * @param[in] rules If rules.skipUndeclaredSpecies is set and we fail to find + * a species we simply return false, allowing the calling + * routine to skip this reaction and continue. Otherwise, we + * will throw an error. */ bool getReagents(const XML_Node& rxn, Kinetics& kin, int rp, std::string default_phase, std::vector& spnum, vector_fp& stoich, - vector_fp& order, const ReactionRules& rule); + vector_fp& order, const ReactionRules& rules); //! Read the rate coefficient data from the XML file. /*! @@ -121,10 +113,6 @@ bool getReagents(const XML_Node& rxn, Kinetics& kin, int rp, void getRateCoefficient(const XML_Node& kf, Kinetics& kin, ReactionData& rdata, const ReactionRules& rules); - -//! Create a new ThermoPhase object and initializes it according to the XML tree database. - - //! Install information about reactions into the kinetics object, kin. /*! * At this point, parent usually refers to the phase xml element. @@ -132,8 +120,6 @@ void getRateCoefficient(const XML_Node& kf, Kinetics& kin, ReactionData& rdata, * the element which determines where in the xml file to * look up the reaction rate data. * - * This is a wrapper routine around the static function installReaction() - * * @param p parent XML phase element * @param kin Kinetics object to install reactions into * @param default_phase The default_phase is the default phase to assume when @@ -153,41 +139,33 @@ bool installReactionArrays(const XML_Node& p, Kinetics& kin, //! Import a reaction mechanism for a phase or an interface. /*! - * This routine will import a reaction mechanism into a - * kinetics object. The reaction - * mechanism may either be homogeneous or heterogeneous, - * involving multiple ThermoPhase objects. - * The hosting phase should be included as the first argument. - * For example, if phase I is an interface phase between bulk - * phases A and B. Then, the XML_Node for phase I should be - * the first argument. - * The vector of %ThermoPhase objects should consist of pointers - * to phases I, A, and B. + * This routine will import a reaction mechanism into a kinetics object. The + * reaction mechanism may either be homogeneous or heterogeneous, involving + * multiple ThermoPhase objects. The hosting phase should be included as the + * first argument. For example, if phase I is an interface phase between bulk + * phases A and B. Then, the XML_Node for phase I should be the first + * argument. The vector of ThermoPhase objects should consist of pointers to + * phases I, A, and B. * - * @param phase This is an xml node containing a description - * of the owning phase for the kinetics object. - * Within the phase is a XML element - * called reactionArray containing the location - * of the description of the reactions that make - * up the kinetics object. - * Also within the phase is an XML element called - * phaseArray containing a listing of other phases - * that participate in the kinetics mechanism. + * @param phase This is an xml node containing a description of the owning + * phase for the kinetics object. Within the phase is a XML + * element called reactionArray containing the location of the + * description of the reactions that make up the kinetics object. + * Also within the phase is an XML element called phaseArray + * containing a listing of other phases that participate in the + * kinetics mechanism. * - * @param th This is a list of ThermoPhase pointers which must - * include all of - * the phases that participate in the kinetics - * operator. All of the phases must have already - * been initialized and formed within Cantera. - * However, their pointers should not have been - * added to the Kinetics object; this addition - * is carried out here. Additional phases may - * be include in the list; these have no effect. + * @param th This is a list of ThermoPhase pointers which must include all + * of the phases that participate in the kinetics operator. All + * of the phases must have already been initialized and formed + * within Cantera. However, their pointers should not have been + * added to the Kinetics object; this addition is carried out + * here. Additional phases may be include in the list; these have + * no effect. * - * @param kin This is a pointer to a kinetics manager class - * that will be initialized with the kinetics - * mechanism. Inherited Kinetics classes may be - * used here. + * @param kin This is a pointer to a kinetics manager class that will be + * initialized with the kinetics mechanism. Inherited Kinetics + * classes may be used here. * * @ingroup kineticsmgr * @@ -230,11 +208,9 @@ bool buildSolutionFromXML(XML_Node& root, const std::string& id, //! Search an XML tree for species data. /*! - * - * This utility routine will search the XML tree for the species - * named by the string, kname. It will return the XML_Node - * pointer. - * Failures of any kind return the null pointer. + * This utility routine will search the XML tree for the species named by + * the string, kname. It will return the XML_Node pointer. Failures of any + * kind return the null pointer. * * @param kname species Name * @param phaseSpeciesData Pointer to the phase XML node pertaining to the @@ -251,4 +227,3 @@ bool buildSolutionFromXML(XML_Node& root, const std::string& id, } #endif - diff --git a/src/kinetics/KineticsFactory.cpp b/src/kinetics/KineticsFactory.cpp index f9f43c0c0..d490b9d2f 100644 --- a/src/kinetics/KineticsFactory.cpp +++ b/src/kinetics/KineticsFactory.cpp @@ -24,29 +24,6 @@ static int ntypes = 6; static string _types[] = {"none", "GasKinetics", "GRI30", "Interface", "Edge", "AqueousKinetics"}; static int _itypes[] = {0, cGasKinetics, cGRI30, cInterfaceKinetics, cEdgeKinetics, cAqueousKinetics}; -/** - * Return a new kinetics manager that implements a reaction - * mechanism specified in a CTML file. In other words, the - * kinetics manager, given the rate constants and formulation of the - * reactions that make up a kinetics mechanism, is responsible for - * calculating the rates of progress of the reactions and for - * calculating the source terms for species. - * - * Input - * ------ - * phaseData = This is an XML_Node that contains the xml data - * describing the phase. Of particular note to this - * routine is the child xml element called "kinetics". - * The element has one attribute called "model", - * with a string value. The value of this string - * is used to decide which kinetics manager is used - * to calculate the reaction mechanism. - * - * Return - * --------- - * Pointer to the new kinetics manager. - */ - Kinetics* KineticsFactory:: newKinetics(XML_Node& phaseData, vector th) { @@ -114,10 +91,6 @@ newKinetics(XML_Node& phaseData, vector th) return k; } - -/** - * Return a new, empty kinetics manager. - */ Kinetics* KineticsFactory::newKinetics(const string& model) { @@ -151,4 +124,3 @@ Kinetics* KineticsFactory::newKinetics(const string& model) } } - diff --git a/src/kinetics/importKinetics.cpp b/src/kinetics/importKinetics.cpp index 69377bc43..6e6bbcea7 100644 --- a/src/kinetics/importKinetics.cpp +++ b/src/kinetics/importKinetics.cpp @@ -73,14 +73,29 @@ public: //! Used to speed up duplicate reaction checks. std::map, std::vector > m_participants; + /** + * Install an individual reaction into a kinetics manager. The + * data for the reaction is in the xml_node r. In other words, r + * points directly to a ctml element named "reaction". i refers + * to the number id of the reaction in the kinetics object. + * + * @param iRxn Reaction number. + * @param r XML_Node containing reaction data. + * @param kin Kinetics manager to which reaction will be added. + * @param default_phase Default phase for locating a species + * @param rules Rule for handling reactions with missing species + * (skip or flag as error) + * @param validate_rxn If true, check that this reaction is not a + * duplicate of one already entered, and check that + * the reaction balances. + * + * @ingroup kineticsmgr + */ bool installReaction(int i, const XML_Node& r, Kinetics& kin, std::string default_phase, ReactionRules& rule, bool validate_rxn) ; }; -/* - * Check a reaction to see if the elements balance. - */ void checkRxnElementBalance(Kinetics& kin, const ReactionData& rdata, doublereal errorTolerance) { @@ -144,36 +159,6 @@ void checkRxnElementBalance(Kinetics& kin, } } - -/** - * Get the reactants or products of a reaction. The information - * is returned in the spnum, stoich, and order vectors. The - * length of the vectors is the number of different types of - * reactants or products found for the reaction. - * - * Input - * -------- - * rxn -> xml node pointing to the reaction element - * in the xml tree. - * kin -> Reference to the kinetics object to install - * the information into. - * rp = 1 -> Go get the reactants for a reaction - * -1 -> Go get the products for a reaction - * default_phase = String name for the default phase - * to loop up species in. - * Output - * ----------- - * spnum = vector of species numbers found. - * Length is number of reactants or products. - * stoich = stoichiometric coefficient of the reactant or product - * Length is number of reactants or products. - * order = Order of the reactant and product in the reaction - * rate expression - * rules = If we fail to find a species, we will throw an error - * if rule != 1. If rule = 1, we simply return false, - * allowing the calling routine to skip this reaction - * and continue. - */ bool getReagents(const XML_Node& rxn, Kinetics& kin, int rp, std::string default_phase, std::vector& spnum, vector_fp& stoich, vector_fp& order, @@ -277,7 +262,6 @@ bool getReagents(const XML_Node& rxn, Kinetics& kin, int rp, return true; } - /** * getArrhenius() parses the xml element called Arrhenius. * The Arrhenius expression is @@ -415,13 +399,11 @@ static void getCoverageDependence(const XML_Node& node, } } - //! Get falloff parameters for a reaction. /*! * This routine reads the falloff XML node and extracts parameters into a * vector of doubles * - * * @verbatim 0.5 73.2 5000. 9999. @endverbatim @@ -495,14 +477,6 @@ static void getEfficiencies(const XML_Node& eff, Kinetics& kin, } } -/* - * Extract the rate coefficient for a reaction from the xml node, kf. - * kf should point to a XML element named "rateCoeff". - * rdata is the partially filled ReactionData object for the reaction. - * This function will fill in more fields in the ReactionData object. - * - * @param kf Reference to the XML Node named rateCoeff - */ void getRateCoefficient(const XML_Node& kf, Kinetics& kin, ReactionData& rdata, const ReactionRules& rules) { @@ -605,14 +579,6 @@ void getRateCoefficient(const XML_Node& kf, Kinetics& kin, } } -/* - * This function returns true if two reactions are duplicates of - * one another, and false otherwise. The input arguments are two - * maps from species number to stoichiometric coefficient, one for - * each reaction. The reactions are considered duplicates if their - * stoichiometric coefficients have the same ratio for all - * species. - */ doublereal isDuplicateReaction(std::map& r1, std::map& r2) { @@ -656,25 +622,6 @@ next: return ratio; } - -/** - * Install an individual reaction into a kinetics manager. The - * data for the reaction is in the xml_node r. In other words, r - * points directly to a ctml element named "reaction". i refers - * to the number id of the reaction in the kinetics object. - * - * @param iRxn Reaction number. - * @param r XML_Node containing reaction data. - * @param kin Kinetics manager to which reaction will be added. - * @param default_phase Default phase for locating a species - * @param rules Rule for handling reactions with missing species - * (skip or flag as error) - * @param validate_rxn If true, check that this reaction is not a - * duplicate of one already entered, and check that the reaction - * balances. - * - * @ingroup kineticsmgr - */ bool rxninfo::installReaction(int iRxn, const XML_Node& r, Kinetics& kin, string default_phase, ReactionRules& rules, bool validate_rxn) @@ -870,20 +817,6 @@ bool rxninfo::installReaction(int iRxn, const XML_Node& r, Kinetics& kin, return true; } -/* - * Take information from the XML tree, p, about reactions - * and install them into the kinetics object, kin. - * default_phase is the default phase to assume when - * looking up species. - * - * At this point, p usually refers to the phase xml element. - * One of the children of this element is reactionArray, - * the element which determines where in the xml file to - * look up the reaction rate data pertaining to the phase. - * - * On return, if reaction instantiation goes correctly, return true. - * If there is a problem, return false. - */ bool installReactionArrays(const XML_Node& p, Kinetics& kin, std::string default_phase, bool check_for_duplicates) { @@ -1016,33 +949,6 @@ bool installReactionArrays(const XML_Node& p, Kinetics& kin, return true; } - -/* - * Import a reaction mechanism for a phase or an interface. - * - * @param phase This is an xml node containing a description - * of a phase. Within the phase is a XML element - * called reactionArray containing the location - * of the description of the reactions that make - * up the kinetics object. - * Also within the phase is an XML element called - * phaseArray containing a listing of other phases - * that participate in the kinetics mechanism. - * - * @param th This is a list of ThermoPhase pointers which must - * include all of - * the phases that participate in the kinetics - * operator. All of the phases must have already - * been initialized and formed within Cantera. - * However, their pointers should not have been - * added to the Kinetics object; this addition - * is carried out here. Additional phases may - * be include; these have no effect. - * - * @param k This is a pointer to the kinetics manager class - * that will be initialized with a kinetics - * mechanism. - */ bool importKinetics(const XML_Node& phase, std::vector th, Kinetics* k) { @@ -1120,10 +1026,6 @@ bool importKinetics(const XML_Node& phase, std::vector th, return installReactionArrays(phase, kin, owning_phase, check_for_duplicates); } -/* - * Build a single-phase ThermoPhase object with associated kinetics - * mechanism. - */ bool buildSolutionFromXML(XML_Node& root, const std::string& id, const std::string& nm, ThermoPhase* th, Kinetics* k) {