diff --git a/include/cantera/kinetics/ReactionStoichMgr.h b/include/cantera/kinetics/ReactionStoichMgr.h index fdde35466..efd66831b 100644 --- a/include/cantera/kinetics/ReactionStoichMgr.h +++ b/include/cantera/kinetics/ReactionStoichMgr.h @@ -27,7 +27,7 @@ class ReactionData; * - the change in molar species properties in the reactions * - concentration products * - * To use this class, method 'add' is first used to add each reaction. + * To use this class, method add() is first used to add each reaction. * Once all reactions have been added, the methods that compute various * quantities may be called. * @@ -55,9 +55,7 @@ class ReactionData; */ class ReactionStoichMgr { - public: - /// Constructor. ReactionStoichMgr(); @@ -105,9 +103,8 @@ public: virtual void add(size_t rxn, const ReactionData& r); /** - * Species creation rates. - * Given the arrays of the forward and reverse rates of - * progress for all reactions, compute the species creation + * Species creation rates. Given the arrays of the forward and reverse + * rates of progress for all reactions, compute the species creation * rates, given by * \f[ * C = N_p Q_f + N_r Q_r. @@ -118,11 +115,9 @@ public: const doublereal* revRatesOfProgress, doublereal* creationRates); - /** - * Species destruction rates. - * Given the arrays of the forward and reverse rates of - * progress for all reactions, compute the species destruction + * Species destruction rates. Given the arrays of the forward and reverse + * rates of progress for all reactions, compute the species destruction * rates, given by * \f[ * D = N_r Q_f + N_p Q_r, @@ -135,33 +130,22 @@ public: const doublereal* revRatesOfProgress, doublereal* destructionRates); - /** - * Given the array of the net rates of progress for all - * reactions, compute the species net production rates and - * return them in array w. - */ - /** - * Species net production rates. - * Given the array of the net rates of - * progress for all reactions, compute the species net production - * rates, given by + * Species net production rates. Given the array of the net rates of + * progress for all reactions, compute the species net production rates, + * given by * \f[ * W = (N_r - N_p) Q_{\rm net}, * \f] */ virtual void getNetProductionRates(size_t nsp, const doublereal* ropnet, doublereal* w); - - //! Calculates the change of a molar species property in a reaction. /*! - * Given an - * array of species properties 'g', return in array 'dg' the - * change in this quantity in the reactions. Array 'g' must - * have a length at least as great as the number of species, - * and array 'dg' must have a length as great as the total - * number of reactions. + * Given an array of species properties 'g', return in array 'dg' the + * change in this quantity in the reactions. Array 'g' must have a length + * at least as great as the number of species, and array 'dg' must have a + * length as great as the total number of reactions. * \f[ * \delta g_i = \sum_k{\nu_{i,k} g_k } * \f] @@ -178,25 +162,21 @@ public: const doublereal* g, doublereal* dg); - /** - * Given an array of species properties 'g', return in array - * 'dg' the change in this quantity in the reversible - * reactions. Array 'g' must have a length at least as great - * as the number of species, and array 'dg' must have a length - * as great as the total number of reactions. This method - * only computes 'dg' for the reversible reactions, and the - * entries of 'dg' for the irreversible reactions are - * unaltered. This is primarily designed for use in - * calculating reverse rate coefficients from thermochemistry - * for reversible reactions. + * Given an array of species properties 'g', return in array 'dg' the + * change in this quantity in the reversible reactions. Array 'g' must + * have a length at least as great as the number of species, and array + * 'dg' must have a length as great as the total number of reactions. + * This method only computes 'dg' for the reversible reactions, and the + * entries of 'dg' for the irreversible reactions are unaltered. This is + * primarily designed for use in calculating reverse rate coefficients + * from thermochemistry for reversible reactions. */ virtual void getRevReactionDelta(size_t nr, const doublereal* g, doublereal* dg); - /** * Given an array of concentrations C, multiply the entries in array R by - * the concentration products for the reactants: + * the concentration products for the reactants. * \f[ * R_i = R_i * \prod_k C_k^{o_{k,i}} * \f] @@ -205,10 +185,9 @@ public: */ virtual void multiplyReactants(const doublereal* C, doublereal* R); - /** * Given an array of concentrations C, multiply the entries in array R by - * the concentration products for the products: + * the concentration products for the products. * \f[ * R_i = R_i * \prod_k C_k^{\nu^{(p)}_{k,i}} * \f] @@ -220,7 +199,6 @@ public: virtual void write(const std::string& filename); protected: - void writeCreationRates(std::ostream& f); void writeDestructionRates(std::ostream& f); void writeNetProductionRates(std::ostream& f); diff --git a/include/cantera/kinetics/StoichManager.h b/include/cantera/kinetics/StoichManager.h index 2c7f75a55..b93bf644d 100644 --- a/include/cantera/kinetics/StoichManager.h +++ b/include/cantera/kinetics/StoichManager.h @@ -18,76 +18,65 @@ namespace Cantera * Note: these classes are designed for internal use in class * ReactionStoichManager. * - * The classes defined here implement simple operations that are - * used by class ReactionStoichManager to compute things like - * rates of progress, species production rates, etc. In general, a - * reaction mechanism may involve many species and many reactions, - * but any given reaction typically only involves a few species as - * reactants, and a few as products. Therefore, the matrix of - * stoichiometric coefficients is very sparse. Not only is it - * sparse, but the non-zero matrix elements often have the value - * 1, and in many cases no more than three coefficients are - * non-zero for the reactants and/or the products. + * The classes defined here implement simple operations that are used by class + * ReactionStoichManager to compute things like rates of progress, species + * production rates, etc. In general, a reaction mechanism may involve many + * species and many reactions, but any given reaction typically only involves + * a few species as reactants, and a few as products. Therefore, the matrix of + * stoichiometric coefficients is very sparse. Not only is it sparse, but the + * non-zero matrix elements often have the value 1, and in many cases no more + * than three coefficients are non-zero for the reactants and/or the products. * - * For the present purposes, we will consider each direction of a - * reversible reaction to be a separate reaction. We often need to - * compute quantities that can formally be written as a matrix - * product of a stoichiometric coefficient matrix and a vector of - * reaction rates. For example, the species creation rates are - * given by + * For the present purposes, we will consider each direction of a reversible + * reaction to be a separate reaction. We often need to compute quantities + * that can formally be written as a matrix product of a stoichiometric + * coefficient matrix and a vector of reaction rates. For example, the species + * creation rates are given by * * \f[ * \dot C_k = \sum_k \nu^{(p)}_{k,i} R_i * \f] * * where \f$ \nu^{(p)_{k,i}} \f$ is the product-side stoichiometric - * coefficient of species \a k in reaction \a i. - * This could be done be straightforward matrix multiplication, - * but would be inefficient, since most of the matrix elements - * of \f$ \nu^{(p)}_{k,i} \f$ are zero. We could do better by - * using sparse-matrix algorithms to compute this product. + * coefficient of species \a k in reaction \a i. This could be done be + * straightforward matrix multiplication, but would be inefficient, since most + * of the matrix elements of \f$ \nu^{(p)}_{k,i} \f$ are zero. We could do + * better by using sparse-matrix algorithms to compute this product. * * If the reactions are general ones, with non-integral stoichiometric - * coefficients, this is about as good as we can do. But we are - * particularly concerned here with the performance for very large - * reaction mechanisms, which are usually composed of elementary - * reactions, which have integral stoichiometric - * coefficients. Furthermore, very few elementary reactions involve more - * than 3 product or reactant molecules. This means that instead of - - - But we can do even better if we take account of the special structure - of this matrix for elementary reactions. - - involve three or fewer product molecules (or reactant molecules). - - * To take advantage of this structure, reactions are divided into - * four groups. - These classes are - * designed to take advantage of this sparse structure when - * computing quantities that can be written as matrix multiplies - + * coefficients, this is about as good as we can do. But we are particularly + * concerned here with the performance for very large reaction mechanisms, + * which are usually composed of elementary reactions, which have integral + * stoichiometric coefficients. Furthermore, very few elementary reactions + * involve more than 3 product or reactant molecules. + * + * But we can do even better if we take account of the special structure of + * this matrix for elementary reactions involving three or fewer product + * molecules (or reactant molecules). + * + * To take advantage of this structure, reactions are divided into four + * groups. These classes are designed to take advantage of this sparse + * structure when computing quantities that can be written as matrix + * multiplies. + * * They are designed to explicitly unroll loops over species or reactions for - * Operations on reactions that require knowing the reaction - * stoichiometry. - * This module consists of class StoichManager, and - * classes C1, C2, and C3. Classes C1, C2, and C3 handle operations - * involving one, two, or three species, respectively, in a - * reaction. Instances are instantiated with a reaction number, and n - * species numbers (n = 1 for C1, etc.). All three classes have the - * same interface. + * Operations on reactions that require knowing the reaction stoichiometry. * - * These classes are designed for use by StoichManager, and the - * operations implemented are those needed to efficiently compute - * quantities such as rates of progress, species production rates, - * reaction thermochemistry, etc. The compiler will inline these - * methods into the body of the corresponding StoichManager method, - * and so there is no performance penalty (unless inlining is turned - * off). + * This module consists of class StoichManager, and classes C1, C2, and C3. + * Classes C1, C2, and C3 handle operations involving one, two, or three + * species, respectively, in a reaction. Instances are instantiated with a + * reaction number, and n species numbers (n = 1 for C1, etc.). All three + * classes have the same interface. * - * To describe the methods, consider class C3 and suppose an instance - * is created with reaction number irxn and species numbers k0, k1, - * and k2. + * These classes are designed for use by StoichManager, and the operations + * implemented are those needed to efficiently compute quantities such as + * rates of progress, species production rates, reaction thermochemistry, etc. + * The compiler will inline these methods into the body of the corresponding + * StoichManager method, and so there is no performance penalty (unless + * inlining is turned off). + * + * To describe the methods, consider class C3 and suppose an instance is + * created with reaction number irxn and species numbers k0, k1, and k2. * * - multiply(in, out) : out[irxn] is multiplied by * in[k0] * in[k1] * in[k2] @@ -107,32 +96,27 @@ namespace Cantera * - decrementSpecies(in, out) : out[k0], out[k1], and out[k2] * are all decremented by in[irxn] * - * The function multiply() is usually used when evaluating the - * forward and reverse rates of progress of reactions. - * The rate constants are usually loaded into out[]. Then - * multiply() is called to add in the dependence of the - * species concentrations to yield a forward and reverse rop. + * The function multiply() is usually used when evaluating the forward and + * reverse rates of progress of reactions. The rate constants are usually + * loaded into out[]. Then multiply() is called to add in the dependence of + * the species concentrations to yield a forward and reverse rop. * - * The function incrementSpecies() and its cousin decrementSpecies() - * is used to translate from rates of progress to species production - * rates. The vector in[] is preloaded with the rates of progress of - * all reactions. Then incrementSpecies() is called to - * increment the species production vector, out[], with the rates - * of progress. + * The function incrementSpecies() and its cousin decrementSpecies() is used + * to translate from rates of progress to species production rates. The vector + * in[] is preloaded with the rates of progress of all reactions. Then + * incrementSpecies() is called to increment the species production vector, + * out[], with the rates of progress. * - * The functions incrementReaction() and decrementReaction() are - * used to find the standard state equilibrium constant for - * a reaction. Here, output[] is a vector of length - * number of reactions, usually the standard gibbs free energies - * of reaction, while input, usually the standard state - * gibbs free energies of species, is a vector of length number of - * species. + * The functions incrementReaction() and decrementReaction() are used to find + * the standard state equilibrium constant for a reaction. Here, output[] is a + * vector of length number of reactions, usually the standard gibbs free + * energies of reaction, while input, usually the standard state gibbs free + * energies of species, is a vector of length number of species. * - * Note the stoichiometric coefficient for a species in a reaction - * is handled by always assuming it is equal to one and then - * treating reactants and products for a reaction separately. - * Bimolecular reactions involving the identical species are - * treated as involving separate species. + * Note the stoichiometric coefficient for a species in a reaction is handled + * by always assuming it is equal to one and then treating reactants and + * products for a reaction separately. Bimolecular reactions involving the + * identical species are treated as involving separate species. * * @internal This class should be upgraded to include cases where * real stoichiometric coefficients are used. Shouldn't be that @@ -155,17 +139,15 @@ inline static std::string fmt(const std::string& r, size_t n) return r + "[" + int2str(n) + "]"; } - /** * Handles one species in a reaction. + * See @ref Stoichiometry * @ingroup Stoichiometry * @internal */ class C1 { - public: - C1(size_t rxn = 0, size_t ic0 = 0) : m_rxn(rxn), m_ic0(ic0) { @@ -245,10 +227,9 @@ private: size_t m_ic0; }; - - /** * Handles two species in a single reaction. + * See @ref Stoichiometry * @ingroup Stoichiometry */ class C2 @@ -333,22 +314,16 @@ public: } private: - - /** - * Reaction index -> index into the ROP vector - */ + //! Reaction index -> index into the ROP vector size_t m_rxn; - /** - * Species index -> index into the species vector for the - * two species. - */ + //! Species index -> index into the species vector for the two species. size_t m_ic0, m_ic1; }; - /** * Handles three species in a reaction. + * See @ref Stoichiometry * @ingroup Stoichiometry */ class C3 @@ -444,16 +419,15 @@ private: size_t m_ic2; }; - /** * Handles any number of species in a reaction, including fractional * stoichiometric coefficients, and arbitrary reaction orders. + * See @ref Stoichiometry * @ingroup Stoichiometry */ class C_AnyN { public: - C_AnyN() : m_n(0), m_rxn(npos) { @@ -586,7 +560,6 @@ public: } private: - //! Length of the m_ic vector /*! * This is the number of species which have non-zero entries in either the @@ -611,7 +584,6 @@ private: vector_fp m_stoich; }; - template inline static void _multiply(InputIter begin, InputIter end, const Vec1& input, Vec2& output) @@ -740,12 +712,12 @@ inline static void _writeMultiply(InputIter begin, InputIter end, * S_k = R_{i1} + \dots + R_{iM} * \f] * where M is the number of molecules, and $\f i(m) \f$ is the + * See @ref Stoichiometry * @ingroup Stoichiometry */ class StoichManagerN { public: - /** * Constructor for the StoichManagerN class. * @@ -769,8 +741,6 @@ public: m_cn_list(right.m_cn_list), m_n(right.m_n), m_loc(right.m_loc) { - - } StoichManagerN& operator=(const StoichManagerN& right) { @@ -804,7 +774,6 @@ public: add(rxn, k, order, stoich); } - //! Add a single reaction to the list of reactions that this //! stoichiometric manager object handles. /*! @@ -932,12 +901,12 @@ private: std::vector m_c3_list; std::vector m_cn_list; /** - * Std::Mapping with the Reaction Number as key and the Number of species + * Map with the Reaction Number as key and the Number of species * as the value. */ std::map m_n; /** - * Std::Mapping with the Reaction Number as key and the placement in the + * Map with the Reaction Number as key and the placement in the * vector of reactions list( i.e., m_c1_list[]) as key */ std::map m_loc; diff --git a/src/kinetics/ReactionStoichMgr.cpp b/src/kinetics/ReactionStoichMgr.cpp index 205e1ef43..df0e87cbc 100644 --- a/src/kinetics/ReactionStoichMgr.cpp +++ b/src/kinetics/ReactionStoichMgr.cpp @@ -17,20 +17,15 @@ using namespace std; namespace Cantera { -//==================================================================================================================== -// create stoichiometry managers for the reactants of all reactions, -// for the products of the reversible reactions, and for the -// products of the irreversible reactions. ReactionStoichMgr::ReactionStoichMgr() { m_dummy.resize(10,1.0); } -//==================================================================================================================== + ReactionStoichMgr::~ReactionStoichMgr() { } -//==================================================================================================================== ReactionStoichMgr::ReactionStoichMgr(const ReactionStoichMgr& right) : m_reactants(right.m_reactants), m_revproducts(right.m_revproducts), @@ -39,7 +34,6 @@ ReactionStoichMgr::ReactionStoichMgr(const ReactionStoichMgr& right) : { } -//==================================================================================================================== ReactionStoichMgr& ReactionStoichMgr::operator=(const ReactionStoichMgr& right) { if (this != &right) { @@ -51,7 +45,7 @@ ReactionStoichMgr& ReactionStoichMgr::operator=(const ReactionStoichMgr& right) } return *this; } -//==================================================================================================================== + void ReactionStoichMgr:: add(size_t rxn, const std::vector& reactants, const std::vector& products, @@ -67,7 +61,6 @@ add(size_t rxn, const std::vector& reactants, } } - void ReactionStoichMgr:: add(size_t rxn, const ReactionData& r) { @@ -193,7 +186,6 @@ multiplyRevProducts(const doublereal* c, doublereal* r) m_revproducts.multiply(c, r); } - void ReactionStoichMgr:: write(const string& filename) {