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

Cleaned up Doxygen docs for Stoichiometry Manager classes

Browse source
This commit is contained in:
Ray Speth 2013-04-12 23:06:36 +00:00
parent 41a23e44d2
commit acdf1e3900
3 changed files with 98 additions and 159 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
include/cantera/kinetics/ReactionStoichMgr.h
View file

@ -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);

179
include/cantera/kinetics/StoichManager.h
View file

@ -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<class InputIter, class Vec1, class Vec2>
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<C3> m_c3_list;
std::vector<C_AnyN> 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<size_t, size_t> 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<size_t, size_t> m_loc;

12
src/kinetics/ReactionStoichMgr.cpp
View file

@ -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<size_t>& reactants,
const std::vector<size_t>& products,
@ -67,7 +61,6 @@ add(size_t rxn, const std::vector<size_t>& 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)
{