From 723cc0a7098685f0df4fe970b2a623cfe4511800 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 18 Apr 2013 22:07:49 +0000 Subject: [PATCH] Cleaned up Doxygen docs for class MultiPhaseEquil --- include/cantera/equil/MultiPhaseEquil.h | 87 ++++++++++++++++++------- src/equil/MultiPhaseEquil.cpp | 77 +++------------------- 2 files changed, 72 insertions(+), 92 deletions(-) diff --git a/include/cantera/equil/MultiPhaseEquil.h b/include/cantera/equil/MultiPhaseEquil.h index 343513df5..1c8be64f0 100644 --- a/include/cantera/equil/MultiPhaseEquil.h +++ b/include/cantera/equil/MultiPhaseEquil.h @@ -7,32 +7,32 @@ namespace Cantera { -/** - * Multiphase chemical equilibrium solver. Class MultiPhaseEquil - * is designed to be used to set a mixture containing one or more - * phases to a state of chemical equilibrium. It implements the - * VCS algorithm, described in Smith and Missen, "Chemical - * Reaction Equilibrium." +/*! + * Multiphase chemical equilibrium solver. Class MultiPhaseEquil is designed + * to be used to set a mixture containing one or more phases to a state of + * chemical equilibrium. It implements the VCS algorithm, described in Smith + * and Missen, "Chemical Reaction Equilibrium." * - * This class only handles chemical equilibrium at a specified - * temperature and pressure. To compute equilibrium holding other - * properties fixed, it is necessary to iterate on T and P in an - * "outer" loop, until the specified properties have the desired - * values. This is done, for example, in method equilibrate of - * class MultiPhase. + * This class only handles chemical equilibrium at a specified temperature and + * pressure. To compute equilibrium holding other properties fixed, it is + * necessary to iterate on T and P in an "outer" loop, until the specified + * properties have the desired values. This is done, for example, in method + * equilibrate of class MultiPhase. * - * This class is primarily meant to be used internally by the - * equilibrate method of class MultiPhase, although there is no - * reason it cannot be used directly in application programs if - * desired. + * This class is primarily meant to be used internally by the equilibrate + * method of class MultiPhase, although there is no reason it cannot be used + * directly in application programs if desired. * * @ingroup equil */ - class MultiPhaseEquil { - public: + //! Construct a multiphase equilibrium manager for a multiphase mixture. + //! @param mix Pointer to a multiphase mixture object. + //! @param start If true, the initial composition will be determined by a + //! linear Gibbs minimization, otherwise the initial mixture + //! composition will be used. MultiPhaseEquil(MultiPhase* mix, bool start=true, int loglevel = 0); virtual ~MultiPhaseEquil() {} @@ -65,6 +65,7 @@ public: doublereal error(); #if defined(WITH_HTML_LOGS) + //! Return a string specifying the jth reaction. std::string reactionString(size_t j); void printInfo(int loglevel); #else @@ -88,16 +89,56 @@ public: double phaseMoles(size_t iph) const; protected: - + //! This method finds a set of component species and a complete set of + //! formation reactions for the non-components in terms of the components. + //! In most cases, many different component sets are possible, and + //! therefore neither the components returned by this method nor the + //! formation reactions are unique. The algorithm used here is described + //! in Smith and Missen, Chemical Reaction Equilibrium Analysis. + //! + //! The component species are taken to be the first M species in array + //! 'species' that have linearly-independent compositions. + //! + //! @param order On entry, vector \a order should contain species index + //! numbers in the order of decreasing desirability as a component. + //! For example, if it is desired to choose the components from among + //! the major species, this array might list species index numbers in + //! decreasing order of mole fraction. If array 'species' does not + //! have length = nSpecies(), then the species will be considered as + //! candidates to be components in declaration order, beginning with + //! the first phase added. void getComponents(const std::vector& order); + + //! Estimate the initial mole numbers. This is done by running each + //! reaction as far forward or backward as possible, subject to the + //! constraint that all mole numbers remain non-negative. Reactions for + //! which \f$ \Delta \mu^0 \f$ are positive are run in reverse, and ones + //! for which it is negative are run in the forward direction. The end + //! result is equivalent to solving the linear programming problem of + //! minimizing the linear Gibbs function subject to the element and non- + //! negativity constraints. int setInitialMoles(int loglevel = 0); + void computeN(); + + //! Take one step in composition, given the gradient of G at the starting + //! point, and a vector of reaction steps dxi. doublereal stepComposition(int loglevel = 0); - //void sort(vector_fp& x); + + //! Re-arrange a vector of species properties in sorted form + //! (components first) into unsorted, sequential form. void unsort(vector_fp& x); + void step(doublereal omega, vector_fp& deltaN, int loglevel = 0); + + //! Compute the change in extent of reaction for each reaction. doublereal computeReactionSteps(vector_fp& dxi); + void updateMixMoles(); + + //! Clean up the composition. The solution algorithm can leave some + //! species in stoichiometric condensed phases with very small negative + //! mole numbers. This method simply sets these to zero. void finish(); // moles of the species with sorted index ns @@ -143,9 +184,8 @@ protected: vector_int m_dsoln; vector_int m_incl_element, m_incl_species; - // Vector of indices for species that are included in the - // calculation. This is used to exclude pure-phase species - // with invalid thermo data + // Vector of indices for species that are included in the calculation. + // This is used to exclude pure-phase species with invalid thermo data std::vector m_species; std::vector m_element; std::vector m_solnrxn; @@ -154,5 +194,4 @@ protected: } - #endif diff --git a/src/equil/MultiPhaseEquil.cpp b/src/equil/MultiPhaseEquil.cpp index 116195c7f..f7ef72e9c 100644 --- a/src/equil/MultiPhaseEquil.cpp +++ b/src/equil/MultiPhaseEquil.cpp @@ -17,15 +17,15 @@ namespace Cantera { #if defined(WITH_HTML_LOGS) -/// Used to print reaction equations. Given a stoichiometric -/// coefficient 'nu' and a chemical symbol 'sym', return a string -/// for this species in the reaction. -/// @param first if this is false, then a " + " string will be -/// added to the beginning of the string. -/// @param nu Stoichiometric coefficient. May be positive or negative. The -/// absolute value will be used in the string. -/// @param sym Species chemical symbol. -/// + +//! Used to print reaction equations. Given a stoichiometric coefficient 'nu' +//! and a chemical symbol 'sym', return a string for this species in the +//! reaction. +//! @param first if this is false, then a " + " string will be added to the +//! beginning of the string. +//! @param nu Stoichiometric coefficient. May be positive or negative. The +//! absolute value will be used in the string. +//! @param sym Species chemical symbol. static string coeffString(bool first, doublereal nu, string sym) { if (nu == 0.0) { @@ -43,12 +43,6 @@ static string coeffString(bool first, doublereal nu, string sym) } #endif -/// Constructor. Construct a multiphase equilibrium manager for a -/// multiphase mixture. -/// @param mix Pointer to a multiphase mixture object. -/// @param start If true, the initial composition will be -/// determined by a linear Gibbs minimization, otherwise the -/// initial mixture composition will be used. MultiPhaseEquil::MultiPhaseEquil(MultiPhase* mix, bool start, int loglevel) : m_mix(mix) { // the multi-phase mixture @@ -209,7 +203,6 @@ MultiPhaseEquil::MultiPhaseEquil(MultiPhase* mix, bool start, int loglevel) : m_ // numbers for the included species. } - doublereal MultiPhaseEquil::equilibrate(int XY, doublereal err, int maxsteps, int loglevel) { @@ -264,10 +257,6 @@ void MultiPhaseEquil::updateMixMoles() m_mix->setMoles(DATA_PTR(m_work3)); } -/// Clean up the composition. The solution algorithm can leave -/// some species in stoichiometric condensed phases with very -/// small negative mole numbers. This method simply sets these to -/// zero. void MultiPhaseEquil::finish() { fill(m_work3.begin(), m_work3.end(), 0.0); @@ -278,16 +267,6 @@ void MultiPhaseEquil::finish() m_mix->setMoles(DATA_PTR(m_work3)); } - -/// Estimate the initial mole numbers. This is done by running -/// each reaction as far forward or backward as possible, subject -/// to the constraint that all mole numbers remain -/// non-negative. Reactions for which \f$ \Delta \mu^0 \f$ are -/// positive are run in reverse, and ones for which it is negative -/// are run in the forward direction. The end result is equivalent -/// to solving the linear programming problem of minimizing the -/// linear Gibbs function subject to the element and -/// non-negativity constraints. int MultiPhaseEquil::setInitialMoles(int loglevel) { size_t ik, j; @@ -372,28 +351,6 @@ int MultiPhaseEquil::setInitialMoles(int loglevel) return 0; } - -/// This method finds a set of component species and a complete -/// set of formation reactions for the non-components in terms of -/// the components. Note that in most cases, many different -/// component sets are possible, and therefore neither the -/// components returned by this method nor the formation -/// reactions are unique. The algorithm used here is described in -/// Smith and Missen, Chemical Reaction Equilibrium Analysis. -/// -/// The component species are taken to be the first M species -/// in array 'species' that have linearly-independent compositions. -/// -/// @param order On entry, vector \a order should contain species -/// index numbers in the order of decreasing desirability as a -/// component. For example, if it is desired to choose the -/// components from among the major species, this array might -/// list species index numbers in decreasing order of mole -/// fraction. If array 'species' does not have length = -/// nSpecies(), then the species will be considered as candidates -/// to be components in declaration order, beginning with the -/// first phase added. -/// void MultiPhaseEquil::getComponents(const std::vector& order) { size_t m, k, j; @@ -545,11 +502,6 @@ void MultiPhaseEquil::getComponents(const std::vector& order) } } - - - -/// Re-arrange a vector of species properties in sorted form -/// (components first) into unsorted, sequential form. void MultiPhaseEquil::unsort(vector_fp& x) { copy(x.begin(), x.end(), m_work2.begin()); @@ -601,7 +553,6 @@ void MultiPhaseEquil::printInfo(int loglevel) } } -/// Return a string specifying the jth reaction. string MultiPhaseEquil::reactionString(size_t j) { string sr = "", sp = ""; @@ -664,9 +615,6 @@ void MultiPhaseEquil::step(doublereal omega, vector_fp& deltaN, } } - -/// Take one step in composition, given the gradient of G at the -/// starting point, and a vector of reaction steps dxi. doublereal MultiPhaseEquil:: stepComposition(int loglevel) { @@ -774,12 +722,8 @@ stepComposition(int loglevel) return omega; } - -/// Compute the change in extent of reaction for each reaction. - doublereal MultiPhaseEquil::computeReactionSteps(vector_fp& dxi) { - size_t j, k, ik, kc, ip; doublereal stoich, nmoles, csum, term1, fctr, rfctr; vector_fp nu; @@ -1098,7 +1042,4 @@ void MultiPhaseEquil::reportCSV(const std::string& reportFile) fclose(FP); } - - - }