From c3fb4e41930ba3d92d5622886f04fb6907e5eeaa Mon Sep 17 00:00:00 2001 From: Harry Moffat Date: Mon, 13 Oct 2008 21:01:48 +0000 Subject: [PATCH] Doxygen update: no code changed. I tried to upgrade the description of SpeciesThermo and SpeciesThermoInterpType vs VPSSMgr and PDSS types. --- Cantera/src/thermo/GeneralSpeciesThermo.h | 4 +- Cantera/src/thermo/NasaThermo.h | 4 +- Cantera/src/thermo/PDSSFactory.cpp | 2 +- Cantera/src/thermo/PDSS_ConstVol.h | 10 +- Cantera/src/thermo/PDSS_HKFT.h | 3 +- Cantera/src/thermo/PDSS_IdealGas.h | 8 +- Cantera/src/thermo/PDSS_Water.cpp | 2 +- Cantera/src/thermo/PDSS_Water.h | 3 +- Cantera/src/thermo/ShomateThermo.h | 4 +- Cantera/src/thermo/SimpleThermo.h | 2 +- Cantera/src/thermo/SpeciesThermo.h | 94 +++++++----- Cantera/src/thermo/SpeciesThermoInterpType.h | 117 +++++++++++++- Cantera/src/thermo/SpeciesThermoMgr.h | 16 +- Cantera/src/thermo/ThermoPhase.h | 21 ++- Cantera/src/thermo/VPSSMgr.cpp | 2 +- Cantera/src/thermo/VPSSMgr.h | 151 +++++++++++++------ Cantera/src/thermo/VPSSMgrFactory.h | 6 +- Cantera/src/thermo/VPSSMgr_ConstVol.h | 2 + Cantera/src/thermo/VPSSMgr_General.h | 4 +- Cantera/src/thermo/VPSSMgr_IdealGas.h | 4 +- Cantera/src/thermo/VPSSMgr_Water_ConstVol.h | 4 +- Cantera/src/thermo/VPSSMgr_Water_HKFT.h | 4 +- 22 files changed, 343 insertions(+), 124 deletions(-) diff --git a/Cantera/src/thermo/GeneralSpeciesThermo.h b/Cantera/src/thermo/GeneralSpeciesThermo.h index 0e0134b33..57f06c76d 100644 --- a/Cantera/src/thermo/GeneralSpeciesThermo.h +++ b/Cantera/src/thermo/GeneralSpeciesThermo.h @@ -1,7 +1,7 @@ /** * @file GeneralSpeciesThermo.h * Headers for a completely general species thermodynamic property - * manager for a phase (see \ref spthermo and + * manager for a phase (see \ref mgrsrefcalc and * \link Cantera::GeneralSpeciesThermo GeneralSpeciesThermo\endlink). * * Because it is general, it is slow. @@ -33,7 +33,7 @@ namespace Cantera { * temperature needed for each species. What it does is to create * a vector of SpeciesThermoInterpType objects. * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ class GeneralSpeciesThermo : public SpeciesThermo { diff --git a/Cantera/src/thermo/NasaThermo.h b/Cantera/src/thermo/NasaThermo.h index b504ffb87..4eca544ed 100755 --- a/Cantera/src/thermo/NasaThermo.h +++ b/Cantera/src/thermo/NasaThermo.h @@ -2,7 +2,7 @@ * @file NasaThermo.h * Header for the 2 regime 7 coefficient Nasa thermodynamic * polynomials for multiple species in a phase, derived from the - * \link Cantera::SpeciesThermo SpeciesThermo\endlink base class (see \ref spthermo and + * \link Cantera::SpeciesThermo SpeciesThermo\endlink base class (see \ref mgrsrefcalc and * \link Cantera::NasaThermo NasaThermo\endlink). */ @@ -50,7 +50,7 @@ namespace Cantera { * coefficients of this parameterization. * @see importCTML * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ class NasaThermo : public SpeciesThermo { diff --git a/Cantera/src/thermo/PDSSFactory.cpp b/Cantera/src/thermo/PDSSFactory.cpp index e3439b997..b1c27f784 100644 --- a/Cantera/src/thermo/PDSSFactory.cpp +++ b/Cantera/src/thermo/PDSSFactory.cpp @@ -2,7 +2,7 @@ * @file SpeciesThermoFactory.cpp * Definitions for factory to build instances of classes that manage the * standard-state thermodynamic properties of a set of species - * (see \ref spthermo and class \link Cantera::SpeciesThermoFactory SpeciesThermoFactory\endlink); + * (see \ref pdssthermo and class \link Cantera::SpeciesThermoFactory SpeciesThermoFactory\endlink); */ /* * $Id$ diff --git a/Cantera/src/thermo/PDSS_ConstVol.h b/Cantera/src/thermo/PDSS_ConstVol.h index 8e37f8799..74fff4d7f 100644 --- a/Cantera/src/thermo/PDSS_ConstVol.h +++ b/Cantera/src/thermo/PDSS_ConstVol.h @@ -2,7 +2,7 @@ * @file PDSS_ConstVol.h * Declarations for the class PDSS_ConstVol (pressure dependent standard state) * which handles calculations for a single species with a constant molar volume in a phase - * (see class \link Cantera::PDSS_ConstVol PDSS_ConstVol\endlink). + * (see class \ref pdssthermo and \link Cantera::PDSS_ConstVol PDSS_ConstVol\endlink). */ /* * Copywrite (2006) Sandia Corporation. Under the terms of @@ -22,10 +22,12 @@ namespace Cantera { class XML_Node; class VPStandardStateTP; - /** - * Class for pressure dependent standard states. - * This class is for a single Ideal Gas species. + //! Class for pressure dependent standard states that use a constant volume model + /*! + * Class for pressure dependent standard states that use a constant volume model. * + * + * @ingroup pdssthermo */ class PDSS_ConstVol : public PDSS { diff --git a/Cantera/src/thermo/PDSS_HKFT.h b/Cantera/src/thermo/PDSS_HKFT.h index d208dc0fe..df32af0e8 100644 --- a/Cantera/src/thermo/PDSS_HKFT.h +++ b/Cantera/src/thermo/PDSS_HKFT.h @@ -3,7 +3,7 @@ * Declarations for the class PDSS_HKFT (pressure dependent standard state) * which handles calculations for a single species in a phase using the * HKFT standard state - * (see class \link Cantera::PDSS_HKFT PDSS_HKFT\endlink). + * (see \ref pdssthermo and class \link Cantera::PDSS_HKFT PDSS_HKFT\endlink). */ /* $Author$ * $Date$ @@ -52,6 +52,7 @@ namespace Cantera { * It only recalculates the standard state when the setState functions * for temperature and pressure are called * + * @ingroup pdssthermo */ class PDSS_HKFT : public PDSS { diff --git a/Cantera/src/thermo/PDSS_IdealGas.h b/Cantera/src/thermo/PDSS_IdealGas.h index 288c8e147..900e06bba 100644 --- a/Cantera/src/thermo/PDSS_IdealGas.h +++ b/Cantera/src/thermo/PDSS_IdealGas.h @@ -2,7 +2,7 @@ * @file PDSS_IdealGas.h * Declarations for the class PDSS_IdealGas (pressure dependent standard state) * which handles calculations for a single ideal gas species in a phase - * (see class \link Cantera::PDSS_IdealGas PDSS_IdealGas\endlink). + * (see \ref pdssthermo and class \link Cantera::PDSS_IdealGas PDSS_IdealGas\endlink). */ /* * Copywrite (2006) Sandia Corporation. Under the terms of @@ -23,10 +23,12 @@ namespace Cantera { class XML_Node; class VPStandardStateTP; - /** - * Derived class for pressure dependent standard states. + + //! Derived class for pressure dependent standard states of an ideal gas species + /*! * This class is for a single Ideal Gas species. * + * @ingroup pdssthermo */ class PDSS_IdealGas : public PDSS { diff --git a/Cantera/src/thermo/PDSS_Water.cpp b/Cantera/src/thermo/PDSS_Water.cpp index dd3b3a9b0..ec703bf7d 100644 --- a/Cantera/src/thermo/PDSS_Water.cpp +++ b/Cantera/src/thermo/PDSS_Water.cpp @@ -193,7 +193,7 @@ namespace Cantera { std::string inputFile, std::string id) { if (inputFile.size() == 0) { - throw CanteraError("aterTp::initThermo", + throw CanteraError("PDSS_Water::constructPDSSFile", "input file is null"); } std::string path = findInputFile(inputFile); diff --git a/Cantera/src/thermo/PDSS_Water.h b/Cantera/src/thermo/PDSS_Water.h index 6a8af1c15..b6ac06c0e 100644 --- a/Cantera/src/thermo/PDSS_Water.h +++ b/Cantera/src/thermo/PDSS_Water.h @@ -2,7 +2,7 @@ * @file PDSS_Water.h * Implementation of a pressure dependent standard state * virtual function for a Pure Water Phase - * (see class \link Cantera::PDSS_Water PDSS_Water\endlink). + * (see \ref pdssthermo and class \link Cantera::PDSS_Water PDSS_Water\endlink). */ /* * Copywrite (2006) Sandia Corporation. Under the terms of @@ -53,6 +53,7 @@ namespace Cantera { * They assume u_liq(TP) = 0.0, s_liq(TP) = 0.0, where TP is the * triple point conditions. * + * @ingroup pdssthermo */ class PDSS_Water : public PDSS { diff --git a/Cantera/src/thermo/ShomateThermo.h b/Cantera/src/thermo/ShomateThermo.h index e266d12e2..bc9d31957 100755 --- a/Cantera/src/thermo/ShomateThermo.h +++ b/Cantera/src/thermo/ShomateThermo.h @@ -2,7 +2,7 @@ * @file ShomateThermo.h * Header for the 2 regions Shomate polynomial * for multiple species in a phase, derived from the - * \link Cantera::SpeciesThermo SpeciesThermo\endlink base class (see \ref spthermo and + * \link Cantera::SpeciesThermo SpeciesThermo\endlink base class (see \ref mgrsrefcalc and * \link Cantera::ShomateThermo ShomateThermo\endlink). */ /* @@ -59,7 +59,7 @@ namespace Cantera { * the implicit integration of (t = T 1000), which provides a * multiplier of 1000 to the Enthalpy equation. * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ class ShomateThermo : public SpeciesThermo { diff --git a/Cantera/src/thermo/SimpleThermo.h b/Cantera/src/thermo/SimpleThermo.h index 8c22966cc..406f1157e 100644 --- a/Cantera/src/thermo/SimpleThermo.h +++ b/Cantera/src/thermo/SimpleThermo.h @@ -45,7 +45,7 @@ namespace Cantera { * * @see ConstCpPoly * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ class SimpleThermo : public SpeciesThermo { diff --git a/Cantera/src/thermo/SpeciesThermo.h b/Cantera/src/thermo/SpeciesThermo.h index a6ad777cb..b30e326a9 100755 --- a/Cantera/src/thermo/SpeciesThermo.h +++ b/Cantera/src/thermo/SpeciesThermo.h @@ -1,7 +1,7 @@ /** * @file SpeciesThermo.h * Virtual base class for the calculation of multiple-species thermodynamic - * reference-state property managers and text for the spthermo module (see \ref spthermo + * reference-state property managers and text for the mgrsrefcalc module (see \ref mgrsrefcalc * and class \link Cantera::SpeciesThermo SpeciesThermo\endlink). */ @@ -24,7 +24,14 @@ namespace Cantera { class SpeciesThermoInterpType; /** - * @defgroup spthermo Species Reference-State Thermodynamic Properties + * @defgroup mgrsrefcalc Managers for Calculating Reference-State Thermodynamics + * + * The ThermoPhase object relies on a set of manager classes to calculate + * the thermodynamic properties of the reference state for all + * of the species in the phase. This may be a computationally + * significant cost, so efficiency is important. + * This group describes how this is done efficiently within Cantera. + * * * To compute the thermodynamic properties of multicomponent * solutions, it is necessary to know something about the @@ -34,17 +41,8 @@ namespace Cantera { * solution. For a gaseous solution (i.e., a gas mixture), the * species properties required are usually ideal gas properties at * the mixture temperature and at a reference pressure (almost always at - * 1 bar). For other types of solutions, however, it may - * not be possible to isolate the species in a "pure" state. For - * example, the thermodynamic properties of, say, Na+ and Cl- in - * saltwater are not easily determined from data on the properties - * of solid NaCl, or solid Na metal, or chlorine gas. In this - * case, the solvation in water is fundamental to the identity of - * the species, and some other reference state must be used. One - * common convention for liquid solutions is to use thermodynamic - * data for the solutes in the limit of infinite dilution within the - * pure solvent; another convention is to reference all properties - * to unit molality. + * 1 bar). + * * * In defining these standard states for species in a phase, we make * the following definition. A reference state is a standard state @@ -54,22 +52,46 @@ namespace Cantera { * between a minimum temperature and a maximum temperature. The * reference state also specifies the molar volume of the species * as a function of temperature. The molar volume is a thermodynamic - * function. - * A full standard state does the same thing as a reference state, - * but specifies the thermodynamics functions at all pressures. + * function. By constrast, a full standard state does the same thing + * as a reference state, but specifies the thermodynamics functions + * at all pressures. * - * Whatever the conventions used by a particular solution model, - * means need to be provided to compute the species properties in - * the reference state. Class SpeciesThermo is the base class - * for a family of classes that compute properties of all - * species in a phase in their reference states, for a range of temperatures. - * Note, the pressure dependence of the species thermodynamic functions is not - * handled by this particular species thermodynamic model. %SpeciesThermo - * calculates the reference-state thermodynamic values of all species in a single - * phase during each call. + * Whatever the conventions used by a particular solution model, + * means need to be provided to compute the species properties in + * the reference state. Class SpeciesThermo is the base class + * for a family of classes that compute properties of all + * species in a phase in their reference states, for a range of temperatures. + * Note, the pressure dependence of the species thermodynamic functions is not + * handled by this particular species thermodynamic model. %SpeciesThermo + * calculates the reference-state thermodynamic values of all species in a single + * phase during each call. The vector nature of the operation leads to + * a lower operation count and better efficiency, especially if the + * individual reference state classes are known to the reference-state + * manager class so that common operations may be grouped together. * - * The following classes inherit from SpeciesThermo. Each of these classes - * handle multiple species, usually all of the species in a phas. However, + * The most important member function for the %SpeciesThermo class + * is the member function \link SpeciesThermo::update() update()\endlink. + * The function calculates the values of Cp, H, and S for all of the + * species at once at the specified temperature. + * + * Usually, all of the species in a phase are installed into a %SpeciesThermo + * class. However, there is no requirement that a %SpeciesThermo + * object handles all of the species in a phase. There are + * two member functions that are called to install each species into + * the %SpeciesThermo. + * One routine is called \link SpeciesThermo::install() install()\endlink. + * It is called with the index of the species in the phase, + * an integer type delineating + * the SpeciesThermoInterpType object, and a listing of the + * parameters for that parameterization. A factory routine is called based + * on the integer type. The other routine is called + * \link SpeciesThermo::install_STIT() install_STIT()\endlink. + * It accepts as an argument a pointer to an already formed + * SpeciesThermoInterpType object. + * + * + * The following classes inherit from %SpeciesThermo. Each of these classes + * handle multiple species, usually all of the species in a phase. However, * there is no requirement that a %SpeciesThermo object handles all of the * species in a phase. * @@ -143,12 +165,10 @@ namespace Cantera { * calculations at all and therefore is the slowest but * most general implementation. * - * @ingroup phases + * @ingroup thermoprops */ //@{ - //////////////////////// class SpeciesThermo //////////////////// - //! Pure Virtual base class for the species thermo manager classes. /*! @@ -222,8 +242,7 @@ namespace Cantera { */ virtual void install(std::string name, int index, int type, const doublereal* c, - doublereal minTemp, - doublereal maxTemp, + doublereal minTemp, doublereal maxTemp, doublereal refPressure)=0; //! Install a new species thermodynamic property @@ -250,14 +269,16 @@ namespace Cantera { * @param s_R Vector of Dimensionless entropies. * (length m_kk). */ - virtual void update(doublereal T, - doublereal* cp_R, - doublereal* h_RT, - doublereal* s_R) const=0; + virtual void update(doublereal T, doublereal* cp_R, + doublereal* h_RT, doublereal* s_R) const=0; //! Like update(), but only updates the single species k. /*! + * The default treatment is to just call update() which + * means that potentially the operation takes a m_kk*m_kk + * hit. + * * @param k species index * @param T Temperature (Kelvin) * @param cp_R Vector of Dimensionless heat capacities. @@ -266,7 +287,6 @@ namespace Cantera { * (length m_kk). * @param s_R Vector of Dimensionless entropies. * (length m_kk). - * */ virtual void update_one(int k, doublereal T, doublereal* cp_R, diff --git a/Cantera/src/thermo/SpeciesThermoInterpType.h b/Cantera/src/thermo/SpeciesThermoInterpType.h index 0d6523697..3a460d2e6 100644 --- a/Cantera/src/thermo/SpeciesThermoInterpType.h +++ b/Cantera/src/thermo/SpeciesThermoInterpType.h @@ -1,7 +1,8 @@ /** * @file SpeciesThermoInterpType.h * Pure Virtual Base class for individual species reference state - * themodynamic managers (see \ref spthermo and class \link Cantera::SpeciesThermoInterpType SpeciesThermoInterpType \endlink). + * themodynamic managers and text for the spthermo module + * (see \ref spthermo and class \link Cantera::SpeciesThermoInterpType SpeciesThermoInterpType \endlink). */ /* * $Author$ @@ -21,6 +22,120 @@ namespace Cantera { class PDSS; class VPSSMgr; + /** + * @defgroup spthermo Species Reference-State Thermodynamic Properties + * + * The %ThermoPhase object relies on classes to calculate + * the thermodynamic properties of the reference state for all + * of the species in the phase. + * This group describes the types and functionality of the classes + * that calculate the reference state thermodynamic functions + * within %Cantera. + * + * + * To compute the thermodynamic properties of multicomponent + * solutions, it is necessary to know something about the + * thermodynamic properties of the individual species present in + * the solution. Exactly what sort of species properties are + * required depends on the thermodynamic model for the + * solution. For a gaseous solution (i.e., a gas mixture), the + * species properties required are usually ideal gas properties at + * the mixture temperature and at a reference pressure (almost always at + * 1 bar). For other types of solutions, however, it may + * not be possible to isolate the species in a "pure" state. For + * example, the thermodynamic properties of, say, Na+ and Cl- in + * saltwater are not easily determined from data on the properties + * of solid NaCl, or solid Na metal, or chlorine gas. In this + * case, the solvation in water is fundamental to the identity of + * the species, and some other reference state must be used. One + * common convention for liquid solutions is to use thermodynamic + * data for the solutes in the limit of infinite dilution within the + * pure solvent; another convention is to reference all properties + * to unit molality. + * + * In defining these standard states for species in a phase, we make + * the following definition. A reference state is a standard state + * of a species in a phase limited to one particular pressure, the reference + * pressure. The reference state specifies the dependence of all + * thermodynamic functions as a function of the temperature, in + * between a minimum temperature and a maximum temperature. The + * reference state also specifies the molar volume of the species + * as a function of temperature. The molar volume is a thermodynamic + * function. + * A full standard state does the same thing as a reference state, + * but specifies the thermodynamics functions at all pressures. + * + * Whatever the conventions used by a particular solution model, + * means need to be provided to compute the species properties in + * the reference state. Class SpeciesThermo is the base class + * for a family of classes that compute properties of all + * species in a phase in their reference states, for a range of temperatures. + * Note, the pressure dependence of the species thermodynamic functions is not + * handled by this particular species thermodynamic model. %SpeciesThermo + * calculates the reference-state thermodynamic values of all species in a single + * phase during each call. + * + * The class SpeciesThermoInterpType is a pure virtual base class for + * calculation of thermodynamic functions for a single species + * in its reference state. + * The following classes inherit from %SpeciesThermoInterpType. + * + * - NasaPoly1 in file NasaPoly1.h + * - This is a one zone model, consisting of a 7 + * coefficient Nasa Polynomial format. + * . + * - NasaPoly2 in file NasaPoly2.h + * - This is a two zone model, with each zone consisting of a 7 + * coefficient Nasa Polynomial format. + * . + * - ShomatePoly in file ShomatePoly.h + * - This is a one zone model, consisting of a 7 + * coefficient Shomate Polynomial format. + * . + * - ShomatePoly2 in file ShomatePoly.h + * - This is a two zone model, with each zone consisting of a 7 + * coefficient Shomate Polynomial format. + * . + * - ConstCpPoly in file ConstCpPoly.h + * - This is a one-zone constant heat capacity model. + * . + * - Mu0Poly in file Mu0Poly.h + * - This is a multizoned model. The chemical potential is given + * at a set number of temperatures. Between each temperature + * the heat capacity is treated as a constant. + * . + * - Nasa9Poly1 in file Nasa9Poly1.h + * - This is a one zone model, consisting of the 9 + * coefficient Nasa Polynomial format. + * . + * - Nasa9PolyMultiTempRegion in file Nasa9PolyMultiTempRegion.h + * - This is a multiple zone model, consisting of the 9 + * coefficient Nasa Polynomial format in each zone. + * . + * - STITbyPDSS in file SpeciesThermoInterpType.h + * - This is an object that calculates reference state thermodynamic + * functions by relying on a pressure dependent + * standard state object (i.e., a PDSS object) to calculate + * the thermodynamic functions. + * . + * + * The most important member function for the %SpeciesThermoInterpType class + * is the member function + * \link SpeciesThermoInterpType::updatePropertiesTemp() updatePropertiesTemp()\endlink. + * The function calculates the values of Cp, H, and S for the specific + * species pertaining to this class. It takes as its arguments the + * base pointer for the vector of Cp, H, and S values for all species + * in the phase. The offset for the species is known within the + * object. + * + * A key concept for reference states is that there is a maximum and a minimum + * temperature beyond which the thermodynamic formulation isn't valid. + * Calls for temperatures outside this range will cause the + * object to throw a CanteraError. + * + * @ingroup thermoprops + */ + //! Pure Virtual Base class for the thermoydnamic manager for //! an individual species' reference state /*! diff --git a/Cantera/src/thermo/SpeciesThermoMgr.h b/Cantera/src/thermo/SpeciesThermoMgr.h index bf22b6aea..8b4bf1ff0 100755 --- a/Cantera/src/thermo/SpeciesThermoMgr.h +++ b/Cantera/src/thermo/SpeciesThermoMgr.h @@ -3,7 +3,7 @@ * This file contains descriptions of templated subclasses of * the virtual base class, SpeciesThermo, which * include SpeciesThermoDuo and SpeciesThermo1 - * (see \ref spthermo and classes + * (see \ref mgrsrefcalc and classes * \link Cantera::SpeciesThermoDuo SpeciesThermoDuo\endlink and * \link Cantera::SpeciesThermo1 SpeciesThermo1\endlink) * @@ -42,7 +42,7 @@ namespace Cantera { * @param s_R Vector of Dimensionless entropies. * (length m_kk). * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ template inline void _updateAll(InputIter begin, @@ -66,7 +66,7 @@ namespace Cantera { * @param begin Beginning iterator * @param end end iterator * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ template doublereal _minTemp(InputIter begin, InputIter end) { @@ -86,7 +86,7 @@ namespace Cantera { * @param begin Beginning iterator * @param end end iterator * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ template doublereal _maxTemp(_InputIter begin, _InputIter end) { @@ -100,7 +100,7 @@ namespace Cantera { //! Exception thrown if species reference pressures don't match. /*! - * @ingroup spthermo + * @ingroup mgrsrefcalc */ class RefPressureMismatch : public CanteraError { public: @@ -121,7 +121,7 @@ namespace Cantera { //! Unknown species thermo manager string error /*! - * @ingroup spthermo + * @ingroup mgrsrefcalc */ class UnknownSpeciesThermo : public CanteraError { public: @@ -154,7 +154,7 @@ namespace Cantera { * * Note this seems to be a slow way to do things, and it may be on its way out. * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ template class SpeciesThermoDuo : public SpeciesThermo { @@ -346,7 +346,7 @@ namespace Cantera { * * @deprecated Note this is currently unused and it may be on its way out. * - * @ingroup spthermo + * @ingroup mgrsrefcalc */ template class SpeciesThermo1 : public SpeciesThermo { diff --git a/Cantera/src/thermo/ThermoPhase.h b/Cantera/src/thermo/ThermoPhase.h index d705e1d6e..c12f6d2bf 100755 --- a/Cantera/src/thermo/ThermoPhase.h +++ b/Cantera/src/thermo/ThermoPhase.h @@ -161,6 +161,7 @@ namespace Cantera { * in the class IdealSolnGasVPSS, because at this level they look alike having * the same mixing rules with respect to the specification of the excess * thermodynamic properties. + * * The third class of objects are actually all derivatives of the MolalityVPSSTP * object. They assume that the standard states are temperature and * pressure dependent. But, they also assume that the standard states are @@ -1803,10 +1804,15 @@ namespace Cantera { void setSpeciesThermo(SpeciesThermo* spthermo) { m_spthermo = spthermo; } - /** - * @internal Return a changeable reference to the species thermodynamic property - * manager. @todo This method will fail if no species thermo - * manager has been installed. + + //! Return a changeable reference to the calculation manager + //! for species reference-state thermodynamic properties + /*! + * + * @todo This method will fail if no species thermo + * manager has been installed. + * + * @internal */ SpeciesThermo& speciesThermo() { return *m_spthermo; } @@ -1989,7 +1995,12 @@ namespace Cantera { protected: - //! Pointer to the species thermodynamic property manager + //! Pointer to the calculation manager for species + //! reference-state thermodynamic properties + /*! + * This class is called when the reference-state thermodynamic properties + * of all the species in the phase needs to be evaluated. + */ SpeciesThermo* m_spthermo; /// Pointer to the XML tree containing the species diff --git a/Cantera/src/thermo/VPSSMgr.cpp b/Cantera/src/thermo/VPSSMgr.cpp index 182852f35..743f8db7e 100644 --- a/Cantera/src/thermo/VPSSMgr.cpp +++ b/Cantera/src/thermo/VPSSMgr.cpp @@ -3,7 +3,7 @@ * Definition file for a virtual base class that manages * the calculation of standard state properties for all of the * species in a single phase, assuming a variable P and T standard state - * (see \ref thermoprops and + * (see \ref mgrpdssthermocalc and * class \link Cantera::VPSSMgr VPSSMgr\endlink). */ /* diff --git a/Cantera/src/thermo/VPSSMgr.h b/Cantera/src/thermo/VPSSMgr.h index 1f6881b5f..171018bc1 100644 --- a/Cantera/src/thermo/VPSSMgr.h +++ b/Cantera/src/thermo/VPSSMgr.h @@ -3,7 +3,7 @@ * Declaration file for a virtual base class that manages * the calculation of standard state properties for all of the * species in a single phase, assuming a variable P and T standard state - * (see \ref thermoprops and + * (see \ref mgrpdssthermocalc and * class \link Cantera::VPSSMgr VPSSMgr\endlink). */ @@ -32,7 +32,7 @@ namespace Cantera { class SpeciesThermo; class PDSS; /** - * @defgroup vpssmgrthermo Species Standard-State Thermodynamic Properties + * @defgroup mgrpdssthermocalc Managers for Calculating Standard-State Thermodynamics * * To compute the thermodynamic properties of multicomponent * solutions, it is necessary to know something about the @@ -54,58 +54,81 @@ namespace Cantera { * pure solvent; another convention is to reference all properties * to unit molality. * - * In defining these standard states for species in a phase, we make - * the following definition. A reference state is a standard state - * of a species in a phase limited to one particular pressure, the reference - * pressure. The reference state specifies the dependence of all - * thermodynamic functions as a function of the temperature, in - * between a minimum temperature and a maximum temperature. The - * reference state also specifies the molar volume of the species - * as a function of temperature. The molar volume is a thermodynamic - * function. - * A full standard state does the same thing as a reference state, - * but specifies the thermodynamics functions at all pressures. + * In defining these standard states for species in a phase, we make + * the following definition. A reference state is a standard state + * of a species in a phase limited to one particular pressure, the reference + * pressure. The reference state specifies the dependence of all + * thermodynamic functions as a function of the temperature, in + * between a minimum temperature and a maximum temperature. The + * reference state also specifies the molar volume of the species + * as a function of temperature. The molar volume is a thermodynamic + * function. + * A full standard state does the same thing as a reference state, + * but specifies the thermodynamics functions at all pressures. * - * Class VPSSMgr is the base class - * for a family of classes that compute properties of all - * species in a phase in their standard states, for a range of temperatures - * and pressures. + * Class VPSSMgr is the base class + * for a family of classes that compute properties of all + * species in a phase in their standard states, for a range of temperatures + * and pressures. * - * Phases which use the VPSSMGr class must have their respective - * ThermoPhase objects actually be derivatives of the VPStandardState - * class. These classes assume that there exists a standard state + * Phases which use the VPSSMGr class must have their respective + * ThermoPhase objects actually be derivatives of the VPStandardState + * class. These classes assume that there exists a standard state * for each species in the phase, where the Thermodynamic functions are specified - * as a function of temperature and pressure. Standard state objects for each + * as a function of temperature and pressure. Standard state thermo objects for each * species in the phase are all derived from the PDSS virtual base class. * Calculators for these - * standard state, which coordinate the calculation for all of the species + * standard state thermo , which coordinate the calculation for all of the species * in a phase, are all derived from VPSSMgr. * In turn, these standard states may employ reference state calculation to * aid in their calculations. And the VPSSMgr calculators may also employ * SimpleThermo calculators to help in calculating the properties for all of the * species in a phase. However, there are some PDSS objects which do not employ - * reference state calculations. An example of this is real equation of state for - * liquid water used within the calculation of brine thermodynamcis. - * In general, the independent variables that completely describe the state of the - * system for this class are temperature, the - * phase pressure, and N - 1 species mole or mass fractions or molalities. - * The standard state thermodynamics combined with the mixing rules yields - * the thermodynamic functions for the phase. Mixing rules are given in terms - * of specifying the molar-base activity coefficients or activities. - * Lists of phases which belong to this group are given below + * reference state calculations. An example of this is a real equation of state for + * liquid water used within the calculation of brine thermodynamcis. * + * Typically calls to calculate standard state thermo properties are virtual calls + * at the ThermoPhase level. It is left to the child classes of ThermoPhase to + * specify how these are carried out. Usually, this will involve calling the + * m_spthermo pointer to a SpeciesThermo object to calculate the reference state + * thermodynamic properties. Then, the pressure dependence is added in within the + * child ThermoPhase object to complete the specification of the standard state. + * The VPStandardStateTP class, however, redefines the calls to the calculation of + * standard state properties to use VPSSMgr class calls. A listing of + * these classes and important pointers are supplied below. + * + * + * - ThermoPhase + * - \link Cantera::ThermoPhase::m_spthermo m_spthermo\endlink + * This is a pointer to a %SpeciesThermo manager class that + * handles the reference %state Thermodynamic calculations. + * . + * - VPStandardStateTP (inherits from %ThermoPhase) + * - \link Cantera::ThermoPhase::m_spthermo m_spthermo\endlink + * %SpeciesThermo manager handling reference %state Thermodynamic calculations. + * may or may not be used by the VPSSMgr class. For species + * which don't have a reference state class defined, a default + * class, called STITbyPDSS which is installed into the SpeciesThermo + * class, actually calculates reference state + * thermo by calling a PDSS object. + * - \link Cantera::VPStandardStateTP::m_VPSS_ptr m_VPSS_ptr\endlink + * This is a pointer to a %VPSSMgr class which handles the + * standard %state thermo calculations. It may + * or may not use the pointer, m_spthermo, in its calculations. + * . + * . + * + * The following classes inherit from VPSSMgr. Each of these classes + * handle multiple species and by definition all of the species in a phase. + * It is a requirement that a VPSSMgr object handles all of the + * species in a phase. * - * The following classes inherit from VPSSMgr. Each of these classes - * handle multiple species and by definition all of the species in a phase. - * It is a requirement that a VPSSMgr object handles all of the - * species in a phase. - * * - VPSSMgr_IdealGas * - standardState model = "IdealGas" * - This model assumes that all species in the phase obey the * ideal gas law for their pressure dependence. The manager - * uses a SimpleThermo object to handle the calculation of the + * uses a SpeciesThermo object to handle the calculation of the * reference state. * . * @@ -113,7 +136,7 @@ namespace Cantera { * - standardState model = "ConstVol" * - This model assumes that all species in the phase obey the * constant partial molar volume pressure dependence. - * The manager uses a SimpleThermo object to handle the + * The manager uses a SpeciesThermo object to handle the * calculation of the reference state. * . * @@ -121,13 +144,13 @@ namespace Cantera { * - standardState model = "Water_ConstVol" * - This model assumes that all species but one in the phase obey the * constant partial molar volume pressure dependence. - * The manager uses a SimpleThermo object to handle the + * The manager uses a SpeciesThermo object to handle the * calculation of the reference state for those species. * Species 0 is assumed to be water, and a real equation * of state is used to model the T, P behavior. * . * - * - VPSSMgr_Water_HKFT. + * - VPSSMgr_Water_HKFT * - standardState model = "Water_HKFT" * - This model assumes that all species but one in the phase obey the * HKFT equation of state. @@ -140,22 +163,56 @@ namespace Cantera { * - This model is completely general. Nothing is assumed at this * level. Calls consist of loops to PDSS property evalulations. * . - * - * The choice of which VPSSMGr object to be used is implicitly made by - * Cantera by querying the XML data file for compatibility. + * . + * + * The choice of which VPSSMgr object to be used is implicitly made by + * %Cantera by querying the XML data file for compatibility. * However, each of these VPSSMgr objects may be explicitly requested in the XML file - * by adding in the following XML nodes into the thermo section of the - * phase XML Node. For example, this explicitly requests that the VPSSMgr_IdealGas - * object be used to handle the standard state calculations. + * by adding in the following XML node into the thermo section of the + * phase XML Node. For example, the code example listed below + * explicitly requests that the VPSSMgr_IdealGas + * object be used to handle the standard state thermodynamics calculations. * * @verbatim + + . . . <\thermo> + . . . + <\phase> @endverbatim * + * If it turns out that the VPSSMgr_IdealGas class can not handle the standard + * state calculation, then %Cantera will fail during the instantiation phase + * printing out an informative error message. * - * @ingroup phases + * In the source code listing above, the thermo model, VPIdealGas ,was requested. The + * thermo model specifies the type of ThermoPhase object to use. In this case + * the object IdealSolnGasVPSS (with the ideal gas suboption) is used. %IdealSolnGasVPSS + * inherits from VPStandardStateTP, so that it actually has a VPSSMgr pointer + * to be specified. Note, in addition to the IdealGas entry to the model + * parameter in standardState node, we could have also specified the "General" + * option. The general option will always work. An example of this + * usage is listed below. + * + * @verbatim + + . . . + + + <\thermo> + . . . + <\phase> + @endverbatim + * + * The "General" option will cause the VPSSMgr_General %VPSSMgr class to be used. + * In this manager, the calculations are all handled at the PDSS object + * level. This is completely general, but, may be significantly + * slower. + * + * + * @ingroup thermoprops */ //! Virtual base class for the classes that manage the calculation diff --git a/Cantera/src/thermo/VPSSMgrFactory.h b/Cantera/src/thermo/VPSSMgrFactory.h index 9330fe34f..32011fe79 100644 --- a/Cantera/src/thermo/VPSSMgrFactory.h +++ b/Cantera/src/thermo/VPSSMgrFactory.h @@ -2,7 +2,7 @@ * @file VPSSMgrFactory.h * Header for factory to build instances of classes that manage the * standard-state thermodynamic properties of a set of species - * (see \ref spthermo and class \link Cantera::VPSSMgrFactory VPSSMgrFactory\endlink); + * (see \ref mgrpdssthermocalc and class \link Cantera::VPSSMgrFactory VPSSMgrFactory\endlink); */ /* @@ -33,7 +33,7 @@ namespace Cantera { //! Throw a named error for an unknown or missing vpss species thermo model. /*! * - * @ingroup thermoprops + * @ingroup mgrpdssthermocalc */ class UnknownVPSSMgrModel: public CanteraError { public: @@ -75,7 +75,7 @@ namespace Cantera { * otherwise simply returns the pointer to the existing * instance. * - * @ingroup thermoprops + * @ingroup mgrpdssthermocalc */ class VPSSMgrFactory : public FactoryBase { diff --git a/Cantera/src/thermo/VPSSMgr_ConstVol.h b/Cantera/src/thermo/VPSSMgr_ConstVol.h index bc23f2dee..6c8c787c6 100644 --- a/Cantera/src/thermo/VPSSMgr_ConstVol.h +++ b/Cantera/src/thermo/VPSSMgr_ConstVol.h @@ -32,6 +32,8 @@ namespace Cantera { * The calculation of multiple-species thermodynamic * property managers for variable temperature and pressure standard * states assuming a constant partial molar volume assumption. + * + * @ingroup mgrpdssthermocalc */ class VPSSMgr_ConstVol : public VPSSMgr { diff --git a/Cantera/src/thermo/VPSSMgr_General.h b/Cantera/src/thermo/VPSSMgr_General.h index 7fdd6e562..107c0a4ab 100644 --- a/Cantera/src/thermo/VPSSMgr_General.h +++ b/Cantera/src/thermo/VPSSMgr_General.h @@ -3,7 +3,7 @@ * Declaration file for a derived class that handles the calculation * of standard state thermo properties for * a set of species belonging to a single phase in a completely general - * but slow way (see \ref thermoprops and + * but slow way (see \ref mgrpdssthermocalc and * class \link Cantera::VPSSMgr_General VPSSMgr_General\endlink). */ /* @@ -40,6 +40,8 @@ namespace Cantera { * but slow way. * The way this does this is to call the underlying PDSS routines one at a * time for every species. + * + * @ingroup mgrpdssthermocalc */ class VPSSMgr_General : public VPSSMgr { diff --git a/Cantera/src/thermo/VPSSMgr_IdealGas.h b/Cantera/src/thermo/VPSSMgr_IdealGas.h index 3bd2df6b9..955c24516 100644 --- a/Cantera/src/thermo/VPSSMgr_IdealGas.h +++ b/Cantera/src/thermo/VPSSMgr_IdealGas.h @@ -3,7 +3,7 @@ * Declaration file for a derived class that handles the calculation * of standard state thermo properties for * a set of species which have an Ideal Gas dependence - * (see \ref thermoprops and + * (see \ref mgrpdssthermocalc and * class \link Cantera::VPSSMgr_IdealGas VPSSMgr_IdealGas\endlink). */ /* @@ -41,6 +41,8 @@ namespace Cantera { * species in their reference state at a range of temperatures. * Note, the pressure dependence of the reference state is not * handled by this particular species standard state model. + * + * @ingroup mgrpdssthermocalc */ class VPSSMgr_IdealGas : public VPSSMgr { diff --git a/Cantera/src/thermo/VPSSMgr_Water_ConstVol.h b/Cantera/src/thermo/VPSSMgr_Water_ConstVol.h index 10916cbc1..d4ae22ab5 100644 --- a/Cantera/src/thermo/VPSSMgr_Water_ConstVol.h +++ b/Cantera/src/thermo/VPSSMgr_Water_ConstVol.h @@ -4,7 +4,7 @@ * of standard state thermo properties for real water and * a set of species which have a constant molar volume pressure * dependence - * (see \ref thermoprops and + * (see \ref mgrpdssthermocalc and * class \link Cantera::VPSSMgr_ConstVol VPSSMgr_ConstVol\endlink). */ @@ -42,6 +42,8 @@ namespace Cantera { * species in their reference state at a range of temperatures. * Note, the pressure dependence of the reference state is not * handled by this particular species standard state model. + * + * @ingroup mgrpdssthermocalc */ class VPSSMgr_Water_ConstVol : public VPSSMgr { diff --git a/Cantera/src/thermo/VPSSMgr_Water_HKFT.h b/Cantera/src/thermo/VPSSMgr_Water_HKFT.h index a174c78b8..f8c437135 100644 --- a/Cantera/src/thermo/VPSSMgr_Water_HKFT.h +++ b/Cantera/src/thermo/VPSSMgr_Water_HKFT.h @@ -3,7 +3,7 @@ * Declaration file for a derived class that handles the calculation * of standard state thermo properties for real water and * a set of species which have the HKFT equation of state - * (see \ref thermoprops and + * (see \ref mgrpdssthermocalc and * class \link Cantera::VPSSMgr_Water_HKFT VPSSMgr_Water_HKFT\endlink). */ /* @@ -40,6 +40,8 @@ namespace Cantera { * species in their reference state at a range of temperatures. * Note, the pressure dependence of the reference state is not * handled by this particular species standard state model. + * + * @ingroup mgrpdssthermocalc */ class VPSSMgr_Water_HKFT : public VPSSMgr {