diff --git a/Cantera/src/Kinetics.h b/Cantera/src/Kinetics.h index 92d6e9093..501bebb4f 100755 --- a/Cantera/src/Kinetics.h +++ b/Cantera/src/Kinetics.h @@ -202,11 +202,23 @@ namespace Cantera { /** - * Get the nth Phase object. - */ - //phase_t& phase(int n=0) { return *m_phase[n]; } - //const phase_t& phase(int n=0) const { return *m_phase[n]; } + * Return the number of phases defined within the kinetics + * object. + */ int nPhases() const { return m_thermo.size(); } + /** + * Return the phase index of a phase in the list of phases + * defined within the object. + * + * Input + * ---------- + * ph = string name of the phase + * + * If a -1 is returned, then the phase is not defined in + * the Kinetics object. + * (HKM -> unfound object will create another entry in the + * map, suggest rewriting this function) + */ int phaseIndex(string ph) { return m_phaseindex[ph] - 1; } /** @@ -223,32 +235,68 @@ namespace Cantera { m_thermo.push_back(&thermo); m_phaseindex[m_thermo.back()->id()] = nPhases(); } + + /** + * This method returns a reference to the nth ThermoPhase + * defined in this kinetics mechanism. + * It is typically used so that member functions of the the + * ThermoPhase may be called. + */ thermo_t& thermo(int n=0) { return *m_thermo[n]; } const thermo_t& thermo(int n=0) const { return *m_thermo[n]; } + + /** + * This method returns a reference to the nth thermophase + * defined in this kinetics mechanism. + * It is typically used so that member functions of the + * ThermoPhase may be called. + */ thermo_t& phase(int n=0) { return *m_thermo[n]; } const thermo_t& phase(int n=0) const { return *m_thermo[n]; } + /** + * This method returns the index of a species in the source + * term vector for this kinetics object. + * + * @param k species index + * @param n phase index for the species + */ int kineticsSpeciesIndex(int k, int n) { return m_start[n] + k; } - + /** + * This routine will look up a species number based on + * the input string nm. The lookup of species will + * occur for all phases listed in the kinetics obect, + * unless the string ph refers to a specific phase of + * the object. + * + * return + * If a match is found, the position in the species list + * is returned. + * If no match is found, the value -2 is returned. + */ int kineticsSpeciesIndex(string nm, string ph = "") { - int np = m_thermo.size(); - int k; - string id; - for (int n = 0; n < np; n++) { - id = thermo(n).id(); - if (ph == id) { - k = thermo(n).speciesIndex(nm); - if (k < 0) return -1; - return k + m_start[n]; - } - else if (ph == "") { - k = thermo(n).speciesIndex(nm); - if (k >= 0) return k + m_start[n]; - } - } - return -2; + int np = m_thermo.size(); + int k; + string id; + for (int n = 0; n < np; n++) { + id = thermo(n).id(); + if (ph == id) { + k = thermo(n).speciesIndex(nm); + if (k < 0) return -1; + return k + m_start[n]; + } + else if (ph == "") { + /* + * Call the speciesIndex() member function of the + * ThermoPhase object to find a match. + */ + k = thermo(n).speciesIndex(nm); + if (k >= 0) return k + m_start[n]; + } + } + return -2; } thermo_t& speciesPhase(string nm) { @@ -264,11 +312,17 @@ namespace Cantera { /** - * Prepare to add reactions. + * Prepare the class for the addition of reactions. This function + * must be called after instantiation of the class, but before + * any reactions are actually added to the mechanism. */ virtual void init() {err("init");} - /// Finished adding reactions. Prepare for use. + /** + * Finish adding reactions and prepare for use. This function + * must be called after all reactions are entered into the mechanism + * and before the mechanism is used to calculate reaction rates. + */ virtual void finalize() {err("finalize");} virtual void addReaction(const ReactionData& r) {err("addReaction");} @@ -278,12 +332,17 @@ namespace Cantera { } - virtual const vector& reactantGroups(int i) - { err("reactantGroups"); return m_dummygroups; } + virtual const vector& reactantGroups(int i) { + err("reactantGroups"); + return m_dummygroups; + } - virtual const vector& productGroups(int i) - { err("productGroups"); return m_dummygroups; } + virtual const vector& productGroups(int i) { + err("productGroups"); + return m_dummygroups; + } + //@} /** * @name Altering Reaction Rates * @@ -299,19 +358,72 @@ namespace Cantera { void setMultiplier(int i, doublereal f) {m_perturb[i] = f;} //@} - + /** + * Increment the number of reactions in the mechanism by one. + */ void incrementRxnCount() { m_ii++; m_perturb.push_back(1.0); } - virtual bool ready() const {return false;} + /** + * + */ + virtual bool ready() const { + err("ready()"); + return false; + } protected: + /** + * m_ii is the number of reactions in the mechanism + */ int m_ii; + + /** + * m_perturb is a vector of perturbation factors for each + * reaction's rate of progress vector. It is initialized to one. + */ vector_fp m_perturb; + + /** + * This is a vector of vectors containing the reactants for each + * reaction. The outer vector is over the number of reactions, m_ii. + * The inner vector is a list of species indecises. If the stoichiometric + * coefficient for a reactant is greater than one, then the + * reactant is listed contiguously in the vector a number of + * times equal to its stoichiometric coefficient. + */ vector m_reactants; + + /** + * This is a vector of vectors containing the products for each + * reaction. The outer vector is over the number of reactions, m_ii. + * The inner vector is a list of species indecises. If the stoichiometric + * coefficient for a product is greater than one, then the + * reactant is listed contiguously in the vector a number of + * times equal to its stoichiometric coefficient. + */ + vector m_products; + + /** + * m_thermo is a vector of pointers to ThermoPhase objects. For + * homogeneous kinetics applications, this vector will only + * consist of one entry. For interfacial reactions, this vector + * will consist of multiple entries; some of them will be surface + * phases, and the other ones will be bulk phases. + * The order that the objects are listed determines the order in + * which the species comprising each phase are listed in the + * source term vector, originating from the reaction mechanism. + */ vector m_thermo; + + /** + * m_start is a vector of integers specifying the beginning position + * for the species vector for the n'th phase in the kinetics + * class. + */ vector_int m_start; + // XML_Node* m_xml; map m_phaseindex; int m_index; @@ -320,7 +432,9 @@ namespace Cantera { vector m_dummygroups; void err(string m) const { - throw CanteraError("Kinetics::"+m,"Base class method called."); + throw CanteraError("Kinetics::" + m, + "The default Base class method was called, when " + "the inherited class's method should have been called"); } };