research/cantera
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Cleaned up Doxygen docs for KineticsFactory and ImportKinetics

Browse source
This commit is contained in:
Ray Speth 2013-04-12 23:06:20 +00:00
parent 0b0bbcf88f
commit c43b02e130
4 changed files with 86 additions and 229 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
include/cantera/kinetics/KineticsFactory.h
View file

@ -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<ThermoPhase*> 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

125
include/cantera/kinetics/importKinetics.h
View file

@ -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<int, doublereal>& r1,
std::map<int, doublereal>& 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<size_t>& 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

28
src/kinetics/KineticsFactory.cpp
View file

@ -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<ThermoPhase*> th)
{
@ -114,10 +91,6 @@ newKinetics(XML_Node& phaseData, vector<ThermoPhase*> 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)
}
}

134
src/kinetics/importKinetics.cpp
View file

@ -73,14 +73,29 @@ public:
//! Used to speed up duplicate reaction checks.
std::map<std::vector<char>, std::vector<size_t> > 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<size_t>& 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
<falloff type="Troe"> 0.5 73.2 5000. 9999. </falloff>
@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<int, doublereal>& r1,
std::map<int, doublereal>& 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<ThermoPhase*> th,
Kinetics* k)
{
@ -1120,10 +1026,6 @@ bool importKinetics(const XML_Node& phase, std::vector<ThermoPhase*> 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)
{