From 88a7ac3da9915139b55937d7b54277d39b413077 Mon Sep 17 00:00:00 2001 From: Harry Moffat Date: Thu, 1 Feb 2007 01:14:56 +0000 Subject: [PATCH] doxygen update. This commit doesn't change any code. Only the doxygen related documentation has been updated. The warning levels from doxygen have been increased, so that undocumented parameters now cause a warning to be issued. This commit eliminates these warning messages. --- Cantera/src/Constituents.cpp | 90 +- Cantera/src/Constituents.h | 255 +++-- Cantera/src/Elements.cpp | 165 ++-- Cantera/src/Elements.h | 224 +++-- Cantera/src/Kinetics.h | 510 ++++++---- Cantera/src/Phase.cpp | 18 +- Cantera/src/Phase.h | 259 +++-- Cantera/src/State.h | 178 ++-- Cantera/src/ThermoPhase.h | 1117 +++++++++++++--------- Cantera/src/ct_defs.h | 19 +- Cantera/src/global.h | 41 +- Cantera/src/logger.h | 54 +- Cantera/src/thermo/IdealMolalSoln.cpp | 81 +- Cantera/src/thermo/IdealMolalSoln.h | 400 ++++++-- Cantera/src/thermo/IdealSolidSolnPhase.h | 103 +- Cantera/src/thermo/MolalityVPSSTP.cpp | 12 +- Cantera/src/thermo/MolalityVPSSTP.h | 167 +++- Cantera/src/thermo/VPStandardStateTP.h | 77 +- Cantera/src/units.h | 2 + Cantera/src/utilities.h | 777 ++++++++++----- tools/doc/Cantera.cfg.in | 15 +- 21 files changed, 2992 insertions(+), 1572 deletions(-) diff --git a/Cantera/src/Constituents.cpp b/Cantera/src/Constituents.cpp index 0ca0d0904..2089ae6db 100755 --- a/Cantera/src/Constituents.cpp +++ b/Cantera/src/Constituents.cpp @@ -23,7 +23,7 @@ using namespace std; namespace Cantera { - /** + /* * Constructor sets all base variable types to zero. Also, it * sets the pointer to the Elements object for this object to the * default value of BaseElements. If the BaseElements Elements @@ -125,7 +125,7 @@ namespace Cantera { * */ void Constituents:: - addElement(const string& symbol, doublereal weight) + addElement(const std::string& symbol, doublereal weight) { m_Elements->addElement(symbol, weight); } @@ -136,8 +136,7 @@ namespace Cantera { m_Elements->addElement(e); } - - /** + /* * Add a unique element to the set. A check on the symbol is made * If the symbol is already an element, then a new element is * not created. @@ -151,7 +150,7 @@ namespace Cantera { * -> Passthrough to the Element lvl. */ void Constituents:: - addUniqueElement(const string& symbol, doublereal weight) + addUniqueElement(const std::string& symbol, doublereal weight) { m_Elements->addUniqueElement(symbol, weight); } @@ -166,7 +165,7 @@ namespace Cantera { m_Elements->addElementsFromXML(phase); } - /** + /* * -> Passthrough to the Element lvl. */ void Constituents::freezeElements() { @@ -190,7 +189,7 @@ namespace Cantera { * * -> Passthrough to the Element class. */ - int Constituents::elementIndex(string name) const { + int Constituents::elementIndex(std::string name) const { return (m_Elements->elementIndex(name)); } @@ -266,7 +265,7 @@ namespace Cantera { return m_speciesCharge[k]; } - /********************************************************************** + /* * * addSpecies() * @@ -285,7 +284,7 @@ namespace Cantera { * and it need not be supplied on the command line. */ void Constituents:: - addSpecies(const string& name, const doublereal* comp, + addSpecies(const std::string& name, const doublereal* comp, doublereal charge, doublereal size) { m_Elements->freezeElements(); m_speciesNames.push_back(name); @@ -302,7 +301,7 @@ namespace Cantera { m_kk++; } - /********************************************************************** + /* * * addUniqueSpecies(): * @@ -312,7 +311,7 @@ namespace Cantera { * existing species in the phase. */ void Constituents:: - addUniqueSpecies(const string& name, const doublereal* comp, + addUniqueSpecies(const std::string& name, const doublereal* comp, doublereal charge, doublereal size) { vector::const_iterator it = m_speciesNames.begin(); for (int k = 0; k < m_kk; k++) { @@ -347,7 +346,7 @@ namespace Cantera { addSpecies(name, comp, charge, size); } - /******************************************************************* + /* * * freezeSpecies() * Set the boolean indicating that we are no longer allowing @@ -357,7 +356,7 @@ namespace Cantera { m_speciesFrozen = true; } - /********************************************************************** + /* * * speciesIndex() * @@ -369,7 +368,7 @@ namespace Cantera { * * If name isn't in the list, then a -1 is returned. */ - int Constituents::speciesIndex(string name) const { + int Constituents::speciesIndex(std::string name) const { vector::const_iterator it = m_speciesNames.begin(); for (int k = 0; k < m_kk; k++) { if (*it == name) { @@ -383,7 +382,7 @@ namespace Cantera { return -1; } - /********************************************************************** + /* * * speciesName() * @@ -395,7 +394,8 @@ namespace Cantera { k, nSpecies()); return m_speciesNames[k]; } - /********************************************************************** + + /* * * speciesNames() * @@ -405,8 +405,7 @@ namespace Cantera { return m_speciesNames; } - - /** + /* * * ready(): * True if both elements and species have been frozen @@ -415,37 +414,34 @@ namespace Cantera { return (m_Elements->elementsFrozen() && m_speciesFrozen); } - /** - * - * nAtoms() - * - * Returns the number of atoms of element \c m in species \c k. - */ - doublereal Constituents::nAtoms(int k, int m) const - { - const int m_mm = m_Elements->nElements(); - if (m < 0 || m >=m_mm) - throw ElementRangeError("Constituents::nAtoms",m,nElements()); - if (k < 0 || k >= nSpecies()) - throw SpeciesRangeError("Constituents::nAtoms",k,nSpecies()); - return m_speciesComp[m_mm * k + m]; - } + /* + * Returns the number of atoms of element \c m in species \c k. + */ + doublereal Constituents::nAtoms(int k, int m) const + { + const int m_mm = m_Elements->nElements(); + if (m < 0 || m >=m_mm) + throw ElementRangeError("Constituents::nAtoms",m,nElements()); + if (k < 0 || k >= nSpecies()) + throw SpeciesRangeError("Constituents::nAtoms",k,nSpecies()); + return m_speciesComp[m_mm * k + m]; + } - /** - * - * getAtoms() - * - * Get a vector containing the atomic composition - * of species k - */ - void Constituents::getAtoms(int k, double *atomArray) const - { - const int m_mm = m_Elements->nElements(); - for (int m = 0; m < m_mm; m++) { - atomArray[m] = (double) m_speciesComp[m_mm * k + m]; - } + /* + * + * getAtoms() + * + * Get a vector containing the atomic composition + * of species k + */ + void Constituents::getAtoms(int k, double *atomArray) const + { + const int m_mm = m_Elements->nElements(); + for (int m = 0; m < m_mm; m++) { + atomArray[m] = (double) m_speciesComp[m_mm * k + m]; } - + } + /** * This copy constructor just calls the assignment operator * for this class. diff --git a/Cantera/src/Constituents.h b/Cantera/src/Constituents.h index 485b82633..3cb4f3bdb 100755 --- a/Cantera/src/Constituents.h +++ b/Cantera/src/Constituents.h @@ -67,18 +67,36 @@ namespace Cantera { public: - /// Constructor. - Constituents(Elements* ptr_Elements = 0); + //! Constructor. + /*! + * Constructor sets all base variable types to zero. Also, it + * sets the pointer to the Elements object for this object. + * + * @param ptr_Elements + * The default is that a new Elements object is created, so this + * Constituents object is independent of any other object. But if + * ptr_Elements is supplied, it will be used. This way, a class + * implementing a multi-phase mixture is responsible for + * maintaining the global elements list for the mixture, and no + * static global element list is required. + */ + Constituents(Elements* ptr_Elements = 0); + + /// Destructor. + ~Constituents(); - /// Destructor. - ~Constituents(); + /// This copy constructor just calls the assignment operator + /// for this class. + /*! + * @param right reference to the object to be copied. + */ + Constituents(const Constituents& right); - /// This copy constructor just calls the assignment operator - /// for this class. - Constituents(const Constituents& right); - - /// Assignment operator - Constituents& operator=(const Constituents& right); + /// Assignment operator + /*! + * @param right Reference to the object to be copied. + */ + Constituents& operator=(const Constituents& right); /// @name Element Information // @{ @@ -103,24 +121,29 @@ namespace Cantera { int elementIndex(std::string name) const; - /// Atomic weight of element m. - doublereal atomicWeight(int m) const; + /// Atomic weight of element m. + /*! + * @param m Element index + */ + doublereal atomicWeight(int m) const; - /// Atomic number of element m. - int atomicNumber(int m) const; + /// Atomic number of element m. + /*! + * @param m Element index + */ + int atomicNumber(int m) const; - /// Return a read-only reference to the vector of element names. - const std::vector& elementNames() const; + /// Return a read-only reference to the vector of element names. + const std::vector& elementNames() const; + + /// Return a read-only reference to the vector of atomic weights. + const vector_fp& atomicWeights() const; - /// Return a read-only reference to the vector of atomic weights. - const vector_fp& atomicWeights() const; - - - /// Number of elements. - int nElements() const; + /// Number of elements. + int nElements() const; - // @} + // @} @@ -134,22 +157,45 @@ namespace Cantera { //@{ - /// Add an element. - /// @param symbol Atomic symbol std::string. - /// @param weight Atomic mass in amu. + //! Add an element. + /*! + * @param symbol Atomic symbol std::string. + * @param weight Atomic mass in amu. + */ void addElement(const std::string& symbol, doublereal weight); - - /// Add an element from an XML specification. + + //! Add an element from an XML specification. + /*! + * @param e Reference to the XML_Node where the element is described. + */ void addElement(const XML_Node& e); + //! Adde an element, checking for uniqueness + /*! + * The uniqueness is checked by comparing the string symbol. If + * not unique, nothing is done. + * + * @param symbol String symbol of the element + * @param weight Atomic weight of the element (kg kmol-1). + */ void addUniqueElement(const std::string& symbol, doublereal weight); + //! Adde an element, checking for uniqueness + /*! + * The uniqueness is checked by comparing the string symbol. If + * not unique, nothing is done. + * + * @param e Reference to the XML_Node where the element is described. + */ void addUniqueElement(const XML_Node& e); + //! Add all elements referenced in an XML_Node tree + /*! + * @param phase Reference to the top XML_Node of a phase + */ void addElementsFromXML(const XML_Node& phase); - /// Prohibit addition of more elements, and prepare to add - /// species. + /// Prohibit addition of more elements, and prepare to add species. void freezeElements(); /// True if freezeElements has been called. @@ -157,55 +203,95 @@ namespace Cantera { //@} - /// Returns the number of species in the phase - int nSpecies() const { return m_kk; } + /// Returns the number of species in the phase + int nSpecies() const { return m_kk; } - /// Molecular weight of species k. - doublereal molecularWeight(int k) const; + //! Molecular weight of species \c k. + /*! + * @param k index of species \c k + * @return + * Returns the molecular weight of species \c k. + */ + doublereal molecularWeight(int k) const; - /// Molar mass. Preferred name for molecular weight. - doublereal molarMass(int k) const { - return molecularWeight(k); - } + //! Return the Molar mass of species \c k + /*! + * Preferred name for molecular weight. + * + * @param k index for species + * @return + * Return the molar mass of species k kg/kmol. + */ + doublereal molarMass(int k) const { + return molecularWeight(k); + } - /** - * Return a const reference to the vector of molecular weights - * of the species - */ - const vector_fp& molecularWeights() const; + /** + * Return a const reference to the vector of molecular weights + * of the species + */ + const vector_fp& molecularWeights() const; + + /*! + * Electrical charge of one species k molecule, divided by + * the magnitude of the electron charge ( \f$ e = 1.602 + * \times 10^{-19}\f$ Coulombs). Dimensionless. + * + * @param k species index + */ + doublereal charge(int k) const; - - /// Electrical charge of one species k molecule, divided by - /// the magnitude of the electron charge ( \f$ e = 1.602 - /// \times 10^{-19}\f$ Coulombs). Dimensionless. - doublereal charge(int k) const; + /** + * @name Adding Species + * These methods are used to add new species. + * They are not usually called by user programs. + */ + //@{ + void addSpecies(const std::string& name, const doublereal* comp, + doublereal charge = 0.0, doublereal size = 1.0); - /** - * @name Adding Species - * These methods are used to add new species. - * They are not usually called by user programs. - */ - //@{ - void addSpecies(const std::string& name, const doublereal* comp, - doublereal charge = 0.0, doublereal size = 1.0); + //! Add a species to the phase, checking for uniqueness of the name + /*! + * This routine checks for uniqueness of the string name. It only + * adds the species if it is unique. + * + * @param name String name of the species + * @param comp Double vector containing the elemental composition of the + * species. + * @param charge Charge of the species. Defaults to zero. + * @param size Size of the species (meters). Defaults to 1 meter. + */ + void addUniqueSpecies(const std::string& name, const doublereal* comp, + doublereal charge = 0.0, + doublereal size = 1.0); + + //! Index of species named 'name' + /*! + * The first species added + * will have index 0, and the last one index nSpecies() - 1. + * + * @param name String name of the species + * @return + * Returns the index of the species. + */ + int speciesIndex(std::string name) const; - void addUniqueSpecies(const std::string& name, const doublereal* comp, - doublereal charge = 0.0, - doublereal size = 1.0); - /** - * Index of species named 'name'. The first species added - * will have index 0, and the last one index nSpecies() - 1. - */ - int speciesIndex(std::string name) const; - /// Name of the species with index k - std::string speciesName(int k) const; - /// Return a const referernce to the vector of species names - const std::vector& speciesNames() const; - /** - * size(): - * This routine returns the size of species k - */ - doublereal size(int k) const { return m_speciesSize[k]; } + //! Name of the species with index k + /*! + * @param k index of the species + */ + std::string speciesName(int k) const; + + /// Return a const referernce to the vector of species names + const std::vector& speciesNames() const; + + //! This routine returns the size of species k + /*! + * @param k index of the species + * @return + * Returns the size of the species. Units are meters. + */ + doublereal size(int k) const { return m_speciesSize[k]; } /** * Prohibit addition of more species, and prepare for @@ -224,19 +310,26 @@ namespace Cantera { /// True if both elements and species have been frozen bool ready() const; - /// Number of atoms of element m in species k. - doublereal nAtoms(int k, int m) const; + //! Number of atoms of element \c m in species \c k. + /*! + * @param k species index + * @param m element index + */ + doublereal nAtoms(int k, int m) const; - /** - * Get a vector containing the atomic composition - * of species k - */ - void getAtoms(int k, double *atomArray) const; + + //! Get a vector containing the atomic composition of species k + /*! + * @param k species index + * @param atomArray vector containing the atomic number in the species. + * Length: m_mm + */ + void getAtoms(int k, double *atomArray) const; protected: - //! Number of species in the phase. + //! Number of species in the phase. int m_kk; //! Vector of molecular weights of the species /*! diff --git a/Cantera/src/Elements.cpp b/Cantera/src/Elements.cpp index 768f06d6c..871161619 100644 --- a/Cantera/src/Elements.cpp +++ b/Cantera/src/Elements.cpp @@ -161,55 +161,60 @@ namespace Cantera { {"Pu", 244.0482 } }; - /* LookupWtElements(): */ - /** Static function to look up an atomic weight - * - * This static function looks up the argument string in the - * database above and returns the associated molecular weight. - * The data are from the periodic table. - * - * Note: The idea behind this function is to provide a unified - * source for the element atomic weights. This helps to - * ensure that mass is conserved. - * - * @param - * ElemName String. Only the first 3 characters are significant - * - * @return - * Return value contains the atomic weight of the element - * If a match for the string is not found, a value of -1.0 is - * returned. - * - * @exception CanteraError - * If a match is not found, a CanteraError is thrown as well - */ - double Elements::LookupWtElements(const string& s) { - int num = sizeof(aWTable) / sizeof(struct awData); - string s3 = s.substr(0,3); - for (int i = 0; i < num; i++) { - //if (!std::strncmp(s.c_str(), aWTable[i].name, 3)) { - if (s3 == aWTable[i].name) { - return (aWTable[i].atomicWeight); - } + + //! Static function to look up an atomic weight + /*! + * + * This static function looks up the argument string in the + * database above and returns the associated molecular weight. + * The data are from the periodic table. + * + * Note: The idea behind this function is to provide a unified + * source for the element atomic weights. This helps to + * ensure that mass is conserved. + * + * @param + * ElemName String. Only the first 3 characters are significant + * + * @return + * Return value contains the atomic weight of the element + * If a match for the string is not found, a value of -1.0 is + * returned. + * + * @exception CanteraError + * If a match is not found, a CanteraError is thrown as well + */ + double Elements::LookupWtElements(const std::string& s) { + int num = sizeof(aWTable) / sizeof(struct awData); + string s3 = s.substr(0,3); + for (int i = 0; i < num; i++) { + //if (!std::strncmp(s.c_str(), aWTable[i].name, 3)) { + if (s3 == aWTable[i].name) { + return (aWTable[i].atomicWeight); } - throw CanteraError("LookupWtElements", "element not found"); - return -1.0; } - - /*! - * Exception class to indicate a fixed set of elements. - * - * This class is used to warn the user when the number of elements - * are changed after at least one species is defined. - */ - class ElementsFrozen : public CanteraError { - public: - ElementsFrozen(string func) - : CanteraError(func, - "elements cannot be added after species.") {} - }; - + throw CanteraError("LookupWtElements", "element not found"); + return -1.0; + } + + + //! Exception class to indicate a fixed set of elements. + /*! + * This class is used to warn the user when the number of elements + * are changed after at least one species is defined. + */ + class ElementsFrozen : public CanteraError { + public: + //! Constructor for class /*! + * @param func Function where the error occurred. + */ + ElementsFrozen(string func) + : CanteraError(func, + "elements cannot be added after species.") {} + }; + + /* * Elements Class Constructor * We initialize all internal variables to zero here. */ @@ -220,7 +225,7 @@ namespace Cantera { { } - /*! + /* * Elements Class Destructor * If the number of subscribers is not zero, through an error. * A logic problem has occurred. @@ -234,7 +239,7 @@ namespace Cantera { } } - /*! + /* * freezeElements(): * * Set the freeze flag. This is a prerequesite to other @@ -245,7 +250,7 @@ namespace Cantera { } #ifdef INCL_DEPRECATED_METHODS - /*! + /* * * Returns an ElementData struct that contains the parameters * for element index m. @@ -257,7 +262,7 @@ namespace Cantera { return e; } #endif - /*********************************************************************** + /* * elementIndex(): * * Index of element named \c name. The index is an integer @@ -268,7 +273,7 @@ namespace Cantera { * */ #ifdef USE_DGG_CODE - int Elements::elementIndex(string name) const{ + int Elements::elementIndex(std::string name) const{ map::const_iterator it; it = m_definedElements.find(name); if (it != m_definedElements.end()) { @@ -277,7 +282,7 @@ namespace Cantera { return -1; } #else - int Elements::elementIndex(string name) const { + int Elements::elementIndex(std::string name) const { for (int i = 0; i < m_mm; i++) { if (m_elementNames[i] == name) return i; } @@ -285,7 +290,7 @@ namespace Cantera { } #endif - /*! + /* * * Name of the element with index \c m. @param m Element * index. If m < 0 or m >= nElements() an exception is thrown. @@ -297,7 +302,7 @@ namespace Cantera { throw ElementRangeError("Elements::elementName",m,nElements()); } - /*! + /* * * Add an element to the current set of elements in the current object. * @param symbol symbol string @@ -311,7 +316,7 @@ namespace Cantera { * and then calls the base routine. */ void Elements:: - addElement(const string& symbol, doublereal weight) + addElement(const std::string& symbol, doublereal weight) { if (weight == -12345.0) { weight = LookupWtElements(symbol); @@ -338,7 +343,7 @@ namespace Cantera { addElement(symbol, weight); } - /*********************************************************************** + /* * addUniqueElement(): * * Add a unique element to the set. This routine will not allow @@ -353,7 +358,7 @@ namespace Cantera { */ #ifdef USE_DGG_CODE void Elements:: - addUniqueElement(const string& symbol, doublereal weight, int atomicNumber) + addUniqueElement(const std::string& symbol, doublereal weight, int atomicNumber) { if (m_elementsFrozen) throw ElementsFrozen("addElement"); @@ -385,7 +390,7 @@ namespace Cantera { #else void Elements:: - addUniqueElement(const string& symbol, + addUniqueElement(const std::string& symbol, doublereal weight, int atomicNumber) { if (weight == -12345.0) { @@ -428,26 +433,26 @@ namespace Cantera { #endif - /** - * @todo call addUniqueElement(symbol, weight) instead of - * addElement. - */ - void Elements:: - addUniqueElement(const XML_Node& e) { - doublereal weight = 0.0; - if (e.hasAttrib("atomicWt")) - weight = atof(stripws(e["atomicWt"]).c_str()); - int anum = 0; - if (e.hasAttrib("atomicNumber")) - anum = atoi(stripws(e["atomicNumber"]).c_str()); - string symbol = e["name"]; - if (weight != 0.0) - addUniqueElement(symbol, weight, anum); - else - addUniqueElement(symbol); + /* + * @todo call addUniqueElement(symbol, weight) instead of + * addElement. + */ + void Elements:: + addUniqueElement(const XML_Node& e) { + doublereal weight = 0.0; + if (e.hasAttrib("atomicWt")) + weight = atof(stripws(e["atomicWt"]).c_str()); + int anum = 0; + if (e.hasAttrib("atomicNumber")) + anum = atoi(stripws(e["atomicNumber"]).c_str()); + string symbol = e["name"]; + if (weight != 0.0) + addUniqueElement(symbol, weight, anum); + else + addUniqueElement(symbol); } - /*********************************************************************** + /* * clear() * * Remove all elements from the structure. @@ -459,7 +464,7 @@ namespace Cantera { m_elementsFrozen = false; } - /*********************************************************************** + /* * ready(): * * True if the elements have been frozen @@ -468,7 +473,7 @@ namespace Cantera { return (m_elementsFrozen); } - /*********************************************************************** + /* * Elements(const Elements&) - copy constructor: * * This copy constructor just calls the assignment operator for this @@ -483,7 +488,7 @@ namespace Cantera { numSubscribers = 0; } - /*********************************************************************** + /* * Elements& Elements::operator=(const Elements& right): * * (assignment operator) @@ -566,7 +571,7 @@ namespace Cantera { } - /*********************************************************************** + /* * subscribe(), unsubscribe(), and reportSubscriptions(): * * Handles setting and reporting the number of subscriptions to this diff --git a/Cantera/src/Elements.h b/Cantera/src/Elements.h index f1376a56c..195e6882d 100644 --- a/Cantera/src/Elements.h +++ b/Cantera/src/Elements.h @@ -25,7 +25,8 @@ namespace Cantera { class XML_Node; class ElementRangeError; - /** Elements Class: Object contains the elements that make up species. + /*! + * Elements Class: Object contains the elements that make up species. * * Class Elements manages the elements that are part of a * chemistry specification. This class may support calculations @@ -40,106 +41,175 @@ namespace Cantera { class Elements { public: - /// Default constructor for the elements class - Elements(); - ~Elements(); - static double LookupWtElements(const std::string &); + /// Default constructor for the elements class + Elements(); - /// Atomic weight of element m. - doublereal atomicWeight(int m) const { return m_atomicWeights[m]; } + //! Default destructor for the elements class + ~Elements(); - /// Atomic number of element m. - int atomicNumber(int m) const { return m_atomicNumbers[m]; } + //! Function to lookup the atomic weight of an element + /*! + * @param ename Element symbol name. + */ + static double LookupWtElements(const std::string &ename); - /// vector of element atomic weights - const vector_fp& atomicWeights() const { return m_atomicWeights; } + /// Atomic weight of element m. + /*! + * @param m element index + */ + doublereal atomicWeight(int m) const { return m_atomicWeights[m]; } - /** - * Inline function that returns the number of elements in the object. - * - * @return - * \c int: The number of elements in the object. - */ - int nElements() const { return m_mm; } + /// Atomic number of element m. + /*! + * @param m element index + */ + int atomicNumber(int m) const { return m_atomicNumbers[m]; } - /** Function that returns the index of an element. - * - * Index of element named \c name. The index is an integer - * assigned to each element in the order it was added, - * beginning with 0 for the first element. If \c name is not - * the name of an element in the set, then the value -1 is - * returned. - * - * @param name String containing the index. - */ - int elementIndex(std::string name) const; + /// vector of element atomic weights + const vector_fp& atomicWeights() const { return m_atomicWeights; } - /* - * Name of the element with index \c m. @param m Element 11111 - * index. If m < 0 or m >= nElements() an exception is thrown. - */ - std::string elementName(int m) const; + /** + * Inline function that returns the number of elements in the object. + * + * @return + * \c int: The number of elements in the object. + */ + int nElements() const { return m_mm; } - /* elementNames() */ - /** Returns a string vector containing the element names - * - * Returns a read-only reference to the vector of element names. - * @return const vector& : The vector contains - * the element names in their indexed order. - */ - const std::vector& elementNames() const { - return m_elementNames; - } + //! Function that returns the index of an element. + /*! + * Index of element named \c name. The index is an integer + * assigned to each element in the order it was added, + * beginning with 0 for the first element. If \c name is not + * the name of an element in the set, then the value -1 is + * returned. + * + * @param name String containing the index. + */ + int elementIndex(std::string name) const; + + //! Name of the element with index \c m. + /*! + * @param m Element index. If m < 0 or m >= nElements() an exception is thrown. + */ + std::string elementName(int m) const; + + //! Returns a string vector containing the element names + /*! + * Returns a read-only reference to the vector of element names. + * @return const vector& : The vector contains + * the element names in their indexed order. + */ + const std::vector& elementNames() const { + return m_elementNames; + } - /// Add an element. - void addElement(const std::string& symbol, - doublereal weight = -12345.0); - void addElement(const XML_Node& e); + //! Add an element to the current set of elements in the current object. + /*! + * The default weight is a special value, which will cause the + * routine to look up the actual weight via a string lookup. + * + * There are two interfaces to this routine. The XML interface + * looks up the required parameters for the regular interface + * and then calls the base routine. + * + * @param symbol string symbol for the element. + * @param weight Atomic weight of the element. If no argument + * is provided, a lookup is attempted. + */ + void addElement(const std::string& symbol, + doublereal weight = -12345.0); - /* - * Add an element only if the element hasn't been added before. - * This is accomplished via a string match on symbol. - */ - void addUniqueElement(const std::string& symbol, - doublereal weight = -12345.0, int atomicNumber = 0); - void addUniqueElement(const XML_Node& e); + //! Add an element to the current set of elements in the current object. + /*! + * @param e Reference to the XML_Node containing the element information + * The node name is the element symbol and the atomWt attribute + * is used as the atomic weight. + */ + void addElement(const XML_Node& e); - void addElementsFromXML(const XML_Node& phase); + //! Add an element only if the element hasn't been added before. + /*! + * This is accomplished via a string match on symbol. + * + * @param symbol string symbol for the element. + * @param weight Atomic weight of the element. If no argument + * is provided, a lookup is attempted. + * @param atomicNumber defaults to 0 + */ + void addUniqueElement(const std::string& symbol, + doublereal weight = -12345.0, int atomicNumber = 0); - /** - * Prohibit addition of more elements, and prepare to add - * species. - */ - void freezeElements(); + //! Add an element to the current set of elements in the current object. + /*! + * @param e Reference to the XML_Node containing the element information + * The node name is the element symbol and the atomWt attribute + * is used as the atomic weight. + */ + void addUniqueElement(const XML_Node& e); + + //! Add multiple elements from a XML_Node phase description + /*! + * @param phase XML_Node reference to a phase + */ + void addElementsFromXML(const XML_Node& phase); + + //! Prohibit addition of more elements, and prepare to add species. + void freezeElements(); - /// True if freezeElements has been called. - bool elementsFrozen() { return m_elementsFrozen; } + /// True if freezeElements has been called. + bool elementsFrozen() { return m_elementsFrozen; } - /// Remove all elements - void clear(); + /// Remove all elements + void clear(); - /// True if both elements and species have been frozen - bool ready() const; + /// True if both elements and species have been frozen + bool ready() const; - Elements(const Elements& right); - Elements& operator=(const Elements& right); + //! copy constructor + /*! + * This copy constructor just calls the assignment operator for this + * class. It sets the number of subscribers to zer0. + * + * @param right Reference to the object to be copied. + */ + Elements(const Elements& right); + //! Assigntment operator + /*! + * This is the assignment operator for the Elements class. + * Right now we pretty much do a straight uncomplicated + * assignment. However, subscribers are not mucked with, as they + * have to do with the address of the object to be subscribed to + * + * @param right Reference to the object to be copied. + */ + Elements& operator=(const Elements& right); - void subscribe(); - int unsubscribe(); - int reportSubscriptions() const; + //! subscribe to this object + /*! + * Increment by one the number of subscriptions to this object. + */ + void subscribe(); + + //! unsubscribe to this object + /*! + * decrement by one the number of subscriptions to this object. + */ + int unsubscribe(); + + //! report the number of subscriptions + int reportSubscriptions() const; protected: /******************************************************************/ /* Description of DATA in the Object */ /******************************************************************/ - /* n_mm: */ - /** Number of elements. - * - */ - int m_mm; + + //! Number of elements. + int m_mm; /* m_elementsFrozen: */ /** boolean indicating completion of object diff --git a/Cantera/src/Kinetics.h b/Cantera/src/Kinetics.h index 31be27e88..092d40f76 100755 --- a/Cantera/src/Kinetics.h +++ b/Cantera/src/Kinetics.h @@ -215,6 +215,8 @@ namespace Cantera { * be called. For homogeneous mechanisms, there is only one * object, and this method can be called without an argument * to access it. + * + * @param n Index of the ThermoPhase being sought. */ thermo_t& thermo(int n=0) { return *m_thermo[n]; } const thermo_t& thermo(int n=0) const { return *m_thermo[n]; } @@ -224,11 +226,21 @@ namespace Cantera { * defined in this kinetics mechanism. * It is typically used so that member functions of the * ThermoPhase may be called. @deprecated This method is redundant. + * + * @param n Index of the ThermoPhase being sought. */ thermo_t& phase(int n=0) { deprecatedMethod("Kinetics","phase","thermo"); 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. @deprecated This method is redundant. + * + * @param n Index of the ThermoPhase being sought. + */ const thermo_t& phase(int n=0) const { deprecatedMethod("Kinetics","phase","thermo"); return *m_thermo[n]; @@ -293,115 +305,144 @@ namespace Cantera { * sum of the number of species in all phases participating in * the kinetics manager. If k is out of bounds, the std::string * "" is returned. + * + * @param k species index */ std::string kineticsSpeciesName(int k) const; - /** - * This routine will look up a species number based on - * the input std::string nm. The lookup of species will - * occur for all phases listed in the kinetics object, - * unless the std::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 a specific phase is specified and no match is found, - * the value -1 is returned. - * - If no match is found in any phase, the value -2 is returned. - */ - int kineticsSpeciesIndex(std::string nm, std::string ph = "") const; + /** + * This routine will look up a species number based on + * the input std::string nm. The lookup of species will + * occur for all phases listed in the kinetics object, + * unless the std::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 a specific phase is specified and no match is found, + * the value -1 is returned. + * - If no match is found in any phase, the value -2 is returned. + * + * @param nm Input string name of the species + * @param ph Input string name of the phase. Defaults to "" + */ + int kineticsSpeciesIndex(std::string nm, std::string ph = "") const; - /** - * This function looks up the std::string name of a species and - * returns a reference to the ThermoPhase object of the - * phase where the species resides. - * Will throw an error if the species std::string doesn't match. - */ - thermo_t& speciesPhase(std::string nm); - - /** - * This function takes as an argument the kineticsSpecies index - * (i.e., the list index in the list of species in the kinetics - * manager) and returns the species' owning ThermoPhase object. - */ - thermo_t& speciesPhase(int k) { - return thermo(speciesPhaseIndex(k)); - } - - /** - * This function takes as an argument the kineticsSpecies index - * (i.e., the list index in the list of species in the kinetics - * manager) and returns the index of the phase owning the - * species. - */ - int speciesPhaseIndex(int k); - - //@} + /** + * This function looks up the std::string name of a species and + * returns a reference to the ThermoPhase object of the + * phase where the species resides. + * Will throw an error if the species std::string doesn't match. + * + * @param nm String containing the name of the species. + */ + thermo_t& speciesPhase(std::string nm); + + /** + * This function takes as an argument the kineticsSpecies index + * (i.e., the list index in the list of species in the kinetics + * manager) and returns the species' owning ThermoPhase object. + * + * @param k Species index + */ + thermo_t& speciesPhase(int k) { + return thermo(speciesPhaseIndex(k)); + } + /** + * This function takes as an argument the kineticsSpecies index + * (i.e., the list index in the list of species in the kinetics + * manager) and returns the index of the phase owning the + * species. + * + * @param k Species index + */ + int speciesPhaseIndex(int k); + + //@} + /** * @name Reaction Rates Of Progress */ //@{ + + //! Return the forward rates of progress of the reactions + /*! + * Forward rates of progress. Return the forward rates of + * progress in array fwdROP, which must be dimensioned at + * least as large as the total number of reactions. + * + * @param fwdROP Output vector containing forward rates + * of progress of the reactions. Length: m_ii. + */ + virtual void getFwdRatesOfProgress(doublereal* fwdROP) { + err("getFwdRatesOfProgress"); + } + + //! Return the Reverse rates of progress of the reactions + /*! + * Return the reverse rates of + * progress in array revROP, which must be dimensioned at + * least as large as the total number of reactions. + * + * @param revROP Output vector containing reverse rates + * of progress of the reactions. Length: m_ii. + */ + virtual void getRevRatesOfProgress(doublereal* revROP) { + err("getRevRatesOfProgress"); + } - /** - * Forward rates of progress. Return the forward rates of - * progress in array fwdROP, which must be dimensioned at - * least as large as the total number of reactions. - */ - virtual void getFwdRatesOfProgress(doublereal* fwdROP) { - err("getFwdRatesOfProgress"); - } - - /** - * Reverse rates of progress. Return the reverse rates of - * progress in array revROP, which must be dimensioned at - * least as large as the total number of reactions. - */ - virtual void getRevRatesOfProgress(doublereal* revROP) { - err("getRevRatesOfProgress"); - } + /** + * Net rates of progress. Return the net (forward - reverse) + * rates of progress in array netROP, which must be + * dimensioned at least as large as the total number of + * reactions. + * + * @param netROP Output vector of the net ROP. Length: m_ii. + */ + virtual void getNetRatesOfProgress(doublereal* netROP) { + err("getNetRatesOfProgress"); + } + - /** - * Net rates of progress. Return the net (forward - reverse) - * rates of progress in array netROP, which must be - * dimensioned at least as large as the total number of - * reactions. - */ - virtual void getNetRatesOfProgress(doublereal* netROP) { - err("getNetRatesOfProgress"); - } + + //! Return a vector of Equilibrium constants. + /*! + * Return the equilibrium constants of + * the reactions in concentration units in array kc, which + * must be dimensioned at least as large as the total number + * of reactions. + * + * @param kc Output vector containing the equilibrium constants. + * Length: m_ii. + */ + virtual void getEquilibriumConstants(doublereal* kc) { + err("getEquilibriumConstants"); + } - - /** - * Equilibrium constants. Return the equilibrium constants of - * the reactions in concentration units in array kc, which - * must be dimensioned at least as large as the total number - * of reactions. - */ - virtual void getEquilibriumConstants(doublereal* kc) { - err("getEquilibriumConstants"); - } - - /** - * Change in species properties. Given an array of molar species - * property values \f$ z_k, k = 1, \dots, K \f$, return the - * array of reaction values - * \f[ - * \Delta Z_i = \sum_k \nu_{k,i} z_k, i = 1, \dots, I. - * \f] - * For example, if this method is called with the array of - * standard-state molar Gibbs free energies for the species, - * then the values returned in array \c deltaProperty would be - * the standard-state Gibbs free energies of reaction for each - * reaction. - */ - virtual void getReactionDelta(const doublereal* property, - doublereal* deltaProperty) { - err("getReactionDelta"); - } + /** + * Change in species properties. Given an array of molar species + * property values \f$ z_k, k = 1, \dots, K \f$, return the + * array of reaction values + * \f[ + * \Delta Z_i = \sum_k \nu_{k,i} z_k, i = 1, \dots, I. + * \f] + * For example, if this method is called with the array of + * standard-state molar Gibbs free energies for the species, + * then the values returned in array \c deltaProperty would be + * the standard-state Gibbs free energies of reaction for each + * reaction. + * + * @param property Input vector of property value. Length: m_kk. + * @param deltaProperty Output vector of deltaRxn. Length: m_ii. + */ + virtual void getReactionDelta(const doublereal* property, + doublereal* deltaProperty) { + err("getReactionDelta"); + } /** * Return the vector of values for the reaction gibbs free @@ -409,6 +450,9 @@ namespace Cantera { * of the solution. * * units = J kmol-1 + * + * @param deltaG Output vector of deltaG's for reactions + * Length: m_ii. */ virtual void getDeltaGibbs( doublereal* deltaG) { err("getDeltaGibbs"); @@ -420,6 +464,9 @@ namespace Cantera { * the solution. * * units = J kmol-1 + * + * @param deltaH Output vector of deltaH's for reactions + * Length: m_ii. */ virtual void getDeltaEnthalpy( doublereal* deltaH) { err("getDeltaEnthalpy"); @@ -431,6 +478,9 @@ namespace Cantera { * solution. * * units = J kmol-1 Kelvin-1 + * + * @param deltaS Output vector of deltaS's for reactions + * Length: m_ii. */ virtual void getDeltaEntropy( doublereal* deltaS) { err("getDeltaEntropy"); @@ -442,6 +492,9 @@ namespace Cantera { * the concentration of the solution. * * units = J kmol-1 + * + * @param deltaG Output vector of ss deltaG's for reactions + * Length: m_ii. */ virtual void getDeltaSSGibbs( doublereal* deltaG) { err("getDeltaSSGibbs"); @@ -453,6 +506,9 @@ namespace Cantera { * upon the concentration of the solution. * * units = J kmol-1 + * + * @param deltaH Output vector of ss deltaH's for reactions + * Length: m_ii. */ virtual void getDeltaSSEnthalpy( doublereal* deltaH) { err("getDeltaSSEnthalpy"); @@ -464,6 +520,9 @@ namespace Cantera { * depend upon the concentration of the solution. * * units = J kmol-1 Kelvin-1 + * + * @param deltaS Output vector of ss deltaS's for reactions + * Length: m_ii. */ virtual void getDeltaSSEntropy( doublereal* deltaS) { err("getDeltaSSEntropy"); @@ -481,7 +540,9 @@ namespace Cantera { * species creation rates in array cdot, which must be * dimensioned at least as large as the total number of * species in all phases. @see nTotalSpecies. - * + * + * @param cdot Output vector of creation rates. + * Length: m_kk. */ virtual void getCreationRates(doublereal* cdot) { err("getCreationRates"); @@ -493,6 +554,8 @@ namespace Cantera { * dimensioned at least as large as the total number of * species. @see nTotalSpecies. * + * @param ddot Output vector of destruction rates. + * Length: m_kk. */ virtual void getDestructionRates(doublereal* ddot) { err("getDestructionRates"); @@ -503,94 +566,123 @@ namespace Cantera { * the species net production rates (creation - destruction) * in array wdot, which must be dimensioned at least as large * as the total number of species. @see nTotalSpecies. + * + * @param wdot Output vector of net production rates. + * Length: m_kk. */ virtual void getNetProductionRates(doublereal* wdot) { err("getNetProductionRates"); } - //@} + //@} - /** - * @name Reaction Mechanism Informational Query Routines - */ - //@{ + /** + * @name Reaction Mechanism Informational Query Routines + */ + //@{ + + /** + * Stoichiometric coefficient of species k as a reactant in + * reaction i. + * + * @param k species index + * @param i reaction index + */ + virtual doublereal reactantStoichCoeff(int k, int i) const { + err("reactantStoichCoeff"); + return -1.0; + } - /** - * Stoichiometric coefficient of species k as a reactant in - * reaction i. - */ - virtual doublereal reactantStoichCoeff(int k, int i) const { - err("reactantStoichCoeff"); - return -1.0; - } - /** - * Stoichiometric coefficient of species k as a product in - * reaction i. - */ - virtual doublereal productStoichCoeff(int k, int i) const { - err("productStoichCoeff"); - return -1.0; - } + /** + * Stoichiometric coefficient of species k as a product in + * reaction i. + * + * @param k species index + * @param i reaction index + */ + virtual doublereal productStoichCoeff(int k, int i) const { + err("productStoichCoeff"); + return -1.0; + } - virtual doublereal reactantOrder(int k, int i) const { + /** + * reactant Order of species k in reaction i. + * + * @param k species index + * @param i reaction index + */ + virtual doublereal reactantOrder(int k, int i) const { err("reactantOrder"); return -1.0; - } + } - /** - * Returns a read-only reference to the vector of reactant - * index numbers for reaction i. - */ - virtual const vector_int& reactants(int i) const { - return m_reactants[i]; - } + /** + * Returns a read-only reference to the vector of reactant + * index numbers for reaction i. + * + * @param i reaction index + */ + virtual const vector_int& reactants(int i) const { + return m_reactants[i]; + } - /** - * Returns a read-only reference to the vector of product - * index numbers for reaction i. - */ - virtual const vector_int& products(int i) const { - return m_products[i]; - } + /** + * Returns a read-only reference to the vector of product + * index numbers for reaction i. + * + * @param i reaction index + */ + virtual const vector_int& products(int i) const { + return m_products[i]; + } - /** - * Flag specifying the type of reaction. The legal values and - * their meaning are specific to the particular kinetics - * manager. - */ - virtual int reactionType(int i) const { - err("reactionType"); - return -1; - } + /** + * Flag specifying the type of reaction. The legal values and + * their meaning are specific to the particular kinetics + * manager. + * + * @param i reaction index + */ + virtual int reactionType(int i) const { + err("reactionType"); + return -1; + } - /** - * True if reaction i has been declared to be reversible. If - * isReversible(i) is false, then the reverse rate of progress - * for reaction i is always zero. - */ - virtual bool isReversible(int i){ - err("isReversible"); + /** + * True if reaction i has been declared to be reversible. If + * isReversible(i) is false, then the reverse rate of progress + * for reaction i is always zero. + * + * @param i reaction index + */ + virtual bool isReversible(int i){ + err("isReversible"); return false; - } - - /** - * Return a std::string representing the reaction. - */ - virtual std::string reactionString(int i) const { - err("reactionStd::String"); return ""; - } - - /** - * Return the forward rate constants - * - * length is the number of reactions. units depends - * on many issues. @todo DGG: recommend changing name to - * getFwdRateCoefficients. - */ - virtual void getFwdRateConstants(doublereal *kfwd) { - err("getFwdRateConstants"); - } + } + + /** + * Return a std::string representing the reaction. + * + * @param i reaction index + */ + virtual std::string reactionString(int i) const { + err("reactionStd::String"); return ""; + } + + /** + * Return the forward rate constants + * + * length is the number of reactions. units depends + * on many issues. @todo DGG: recommend changing name to + * getFwdRateCoefficients. + * + * @param kfwd Output vector containing the foward reaction rate constants. + * Length: m_ii. + */ + virtual void getFwdRateConstants(doublereal *kfwd) { + err("getFwdRateConstants"); + } /** * Return the reverse rate constants. @@ -600,6 +692,10 @@ namespace Cantera { * for irreversible reactions if the default for * doIrreversible is overridden. @todo DGG: recommend changing name to * getRevRateCoefficients. + * + * @param krev Output vector of reverse rate constants. + * @param doIrreversible boolean indicating whether irreversible reactions + * should be included. */ virtual void getRevRateConstants(doublereal *krev, bool doIrreversible = false) { @@ -611,6 +707,9 @@ namespace Cantera { * Return the activation energies in Kelvin. * * length is the number of reactions + * + * @param E Ouptut vector of activation energies. + * Length: m_ii. */ virtual void getActivationEnergies(doublereal *E) { err("getActivationEnergies"); @@ -639,6 +738,8 @@ namespace Cantera { * ThermoPhase phase as a key and the * index of the phase within the kinetics * manager object as the value. + * + * @param thermo Reference to the ThermoPhase to be added. */ void addPhase(thermo_t& thermo); @@ -667,6 +768,9 @@ namespace Cantera { /** * Add a single reaction to the mechanism. This routine * must be called after init() and before finalize(). + * + * @param r Reference to the ReactionRate object for the reaction + * to be added. */ virtual void addReaction(const ReactionData& r) { err("addReaction"); @@ -683,25 +787,32 @@ namespace Cantera { } - //@} - /** - * @name Altering Reaction Rates - * - * These methods alter reaction rates. They are designed - * primarily for carrying out sensitivity analysis, but may be - * used for any purpose requiring dynamic alteration of rate - * constants. For each reaction, a real-valued multiplier may - * be defined that multiplies the reaction rate - * coefficient. The multiplier may be set to zero to - * completely remove a reaction from the mechanism. - */ - //@{ + //@} + /** + * @name Altering Reaction Rates + * + * These methods alter reaction rates. They are designed + * primarily for carrying out sensitivity analysis, but may be + * used for any purpose requiring dynamic alteration of rate + * constants. For each reaction, a real-valued multiplier may + * be defined that multiplies the reaction rate + * coefficient. The multiplier may be set to zero to + * completely remove a reaction from the mechanism. + */ + //@{ + + /// The current value of the multiplier for reaction i. + /*! + * @param i index of the reaction + */ + doublereal multiplier(int i) const {return m_perturb[i];} - /// The current value of the multiplier for reaction i. - doublereal multiplier(int i) const {return m_perturb[i];} - - /// Set the multiplier for reaction i to f. - void setMultiplier(int i, doublereal f) {m_perturb[i] = f;} + /// Set the multiplier for reaction i to f. + /*! + * @param i index of the reaction + * @param f value of the multiplier. + */ + void setMultiplier(int i, doublereal f) {m_perturb[i] = f;} //@} @@ -720,24 +831,31 @@ namespace Cantera { } - /** - * Extract from array \c data the portion pertaining to phase \c phase. - */ - void selectPhase(const doublereal* data, const thermo_t* phase, - doublereal* phase_data); + /** + * Extract from array \c data the portion pertaining to phase \c phase. + * + * @param data data + * @param phase phase + * @param phase_data phase_data + */ + void selectPhase(const doublereal* data, const thermo_t* phase, + doublereal* phase_data); + /// For internal use. May be removed in a future release. + int index(){ return m_index; } - /// For internal use. May be removed in a future release. - int index(){ return m_index; } //! Set the index of the Kinetics Manager - void setIndex(int index) { m_index = index; } + /*! + * @param index input index + */ + void setIndex(int index) { m_index = index; } protected: - /// Number of reactions in the mechanism - int m_ii; + //! Number of reactions in the mechanism + int m_ii; /// Vector of perturbation factors for each reaction's rate of /// progress vector. It is initialized to one. diff --git a/Cantera/src/Phase.cpp b/Cantera/src/Phase.cpp index ca0209704..fc9f400cd 100755 --- a/Cantera/src/Phase.cpp +++ b/Cantera/src/Phase.cpp @@ -116,7 +116,7 @@ namespace Cantera { setMoleFractions(&mf[0]); } - void Phase::setMoleFractionsByName(const string& x) { + void Phase::setMoleFractionsByName(const std::string& x) { compositionMap xx; int kk = nSpecies(); for (int k = 0; k < kk; k++) { @@ -143,7 +143,7 @@ namespace Cantera { setMassFractions(&mf[0]); } - void Phase::setMassFractionsByName(const string& y) { + void Phase::setMassFractionsByName(const std::string& y) { compositionMap yy; int kk = nSpecies(); for (int k = 0; k < kk; k++) { @@ -207,7 +207,7 @@ namespace Cantera { setMassFractions(y); setDensity(rho); } - /** + /* * Copy the vector of molecular weights into vector weights. */ void Phase::getMolecularWeights(vector_fp& weights) { @@ -216,7 +216,7 @@ namespace Cantera { copy(mw.begin(), mw.end(), weights.begin()); } - /** + /* * Copy the vector of molecular weights into array weights. * @deprecated */ @@ -225,9 +225,9 @@ namespace Cantera { copy(mw.begin(), mw.end(), weights); } - /** - * Copy the vector of molecular weights into array weights. - */ + /* + * Copy the vector of molecular weights into array weights. + */ void Phase::getMolecularWeights(doublereal* weights) { const array_fp& mw = Constituents::molecularWeights(); copy(mw.begin(), mw.end(), weights); @@ -257,7 +257,7 @@ namespace Cantera { return State::moleFraction(k); } - doublereal Phase::moleFraction(string name) const { + doublereal Phase::moleFraction(std::string name) const { int iloc = speciesIndex(name); if (iloc >= 0) return State::moleFraction(iloc); else return 0.0; @@ -267,7 +267,7 @@ namespace Cantera { return State::massFraction(k); } - doublereal Phase::massFraction(string name) const { + doublereal Phase::massFraction(std::string name) const { int iloc = speciesIndex(name); if (iloc >= 0) return massFractions()[iloc]; else return 0.0; diff --git a/Cantera/src/Phase.h b/Cantera/src/Phase.h index bac26e862..0ea2cacf1 100755 --- a/Cantera/src/Phase.h +++ b/Cantera/src/Phase.h @@ -52,15 +52,19 @@ namespace Cantera { m_xml = 0; } - /** - * Copy Constructor - */ - Phase(const Phase &c); - - /** - * Assignment operator - */ - const Phase &operator=(const Phase &c); + /** + * Copy Constructor + * + * @param c Reference to the class to be used in the copy + */ + Phase(const Phase &c); + + /** + * Assignment operator + * + * @param c Reference to the class to be used in the copy + */ + const Phase &operator=(const Phase &c); //! Returns a reference to the XML_Node storred for the phase /*! @@ -73,38 +77,50 @@ namespace Cantera { std::string id() const { return m_id; } //! Set the string id for the phase - void setID(std::string id) {m_id = id;} + /*! + * @param id String id of the phase + */ + void setID(std::string id) {m_id = id;} //! Return the name of the phase std::string name() const { return m_name; } //! Sets the string name for the phase - void setName(std::string nm) { m_name = nm; } + /*! + * @param nm String name of the phase + */ + void setName(std::string nm) { m_name = nm; } //! Returns the index of the phase int index() const { return m_index; } + //! Sets the index of the phase - void setIndex(int m) { m_index = m; } + /*! + * @param m Integer index of the phase + */ + void setIndex(int m) { m_index = m; } - /** - * Write to vector 'state' the current internal state. - * @param state output vector. Will be resized to nSpecies() + 2 on - * return. - */ - void saveState(vector_fp& state) const; - - /** - * Write to array 'state' the current internal state. - * @param lenstate length of the state array. Must be >= nSpecies() + 2 - * @param state output vector. Must be of length nSpecies() + 2 or - * greater. - */ - void saveState(int lenstate, doublereal* state) const; - - /** - * Restore a state saved on a previous call to saveState. - */ - void restoreState(const vector_fp& state); + //! Save the current internal state of the phase + /*! + * Write to vector 'state' the current internal state. + * + * @param state output vector. Will be resized to nSpecies() + 2 on return. + */ + void saveState(vector_fp& state) const; + + //! Write to array 'state' the current internal state. + /*! + * @param lenstate length of the state array. Must be >= nSpecies() + 2 + * @param state output vector. Must be of length nSpecies() + 2 or + * greater. + */ + void saveState(int lenstate, doublereal* state) const; + + //!Restore a state saved on a previous call to saveState. + /*! + * @param state State vector containing the previously saved state. + */ + void restoreState(const vector_fp& state); //! Restore the state of the phase from a previously saved state vector. /*! @@ -144,63 +160,142 @@ namespace Cantera { * * @param x String containing a composition map */ - void setMassFractionsByName(const std::string& x); + void setMassFractionsByName(const std::string& x); - /** Set the temperature (K), density (kg/m^3), and mole fractions. */ - void setState_TRX(doublereal t, doublereal dens, const doublereal* x); + //! Set the internally storred temperature (K), density, and mole fractions. + /*! + * Note, the mole fractions are always set first, before the density + * + * @param t Temperature in kelvin + * @param dens Density (kg/m^3) + * @param x vector of species mole fractions. + * Length is equal to m_kk + */ + void setState_TRX(doublereal t, doublereal dens, const doublereal* x); - /** Set the temperature (K), density (kg/m^3), and mole fractions. */ - void setState_TRX(doublereal t, doublereal dens, compositionMap& x); - /** Set the temperature (K), density (kg/m^3), and mass fractions. */ - void setState_TRY(doublereal t, doublereal dens, const doublereal* y); + //! Set the internally storred temperature (K), density, and mole fractions. + /*! + * Note, the mole fractions are always set first, before the density + * + * @param t Temperature in kelvin + * @param dens Density (kg/m^3) + * @param x Composition Map containing the mole fractions. + * Species not included in the map are assumed to have + * a zero mole fraction. + */ + void setState_TRX(doublereal t, doublereal dens, compositionMap& x); - /** Set the temperature (K), density (kg/m^3), and mass fractions. */ - void setState_TRY(doublereal t, doublereal dens, compositionMap& y); + //! Set the internally storred temperature (K), density, and mass fractions. + /*! + * Note, the mass fractions are always set first, before the density + * + * @param t Temperature in kelvin + * @param dens Density (kg/m^3) + * @param y vector of species mass fractions. + * Length is equal to m_kk + */ + void setState_TRY(doublereal t, doublereal dens, const doublereal* y); - /** Set the temperature (K), molar density (kmol/m^3), and mole fractions. */ - void setState_TNX(doublereal t, doublereal n, const doublereal* x); + //! Set the internally storred temperature (K), density, and mass fractions. + /*! + * Note, the mass fractions are always set first, before the density + * + * @param t Temperature in kelvin + * @param dens Density (kg/m^3) + * @param y Composition Map containing the mass fractions. + * Species not included in the map are assumed to have + * a zero mass fraction. + */ + void setState_TRY(doublereal t, doublereal dens, compositionMap& y); + + //! Set the internally storred temperature (K), molar density (kmol/m^3), and mole fractions. + /*! + * Note, the mole fractions are always set first, before the molar density + * + * @param t Temperature in kelvin + * @param n molar density (kmol/m^3) + * @param x vector of species mole fractions. + * Length is equal to m_kk + */ + void setState_TNX(doublereal t, doublereal n, const doublereal* x); - /** Set the temperature (K) and density (kg/m^3) */ - void setState_TR(doublereal t, doublereal rho); - - /** Set the temperature (K) and mole fractions. */ - void setState_TX(doublereal t, doublereal* x); + //! Set the internally storred temperature (K) and density (kg/m^3) + /*! + * @param t Temperature in kelvin + * @param rho Density (kg/m^3) + */ + void setState_TR(doublereal t, doublereal rho); + + //! Set the internally storred temperature (K) and mole fractions. + /*! + * @param t Temperature in kelvin + * @param x vector of species mole fractions. + * Length is equal to m_kk + */ + void setState_TX(doublereal t, doublereal* x); - /** Set the temperature (K) and mass fractions. */ - void setState_TY(doublereal t, doublereal* y); + //! Set the internally storred temperature (K) and mass fractions. + /*! + * @param t Temperature in kelvin + * @param y vector of species mass fractions. + * Length is equal to m_kk + */ + void setState_TY(doublereal t, doublereal* y); - /** Set the density (kg/m^3) and mole fractions. */ - void setState_RX(doublereal rho, doublereal* x); + //! Set the density (kg/m^3) and mole fractions. + /*! + * @param rho Density (kg/m^3) + * @param x vector of species mole fractions. + * Length is equal to m_kk + */ + void setState_RX(doublereal rho, doublereal* x); - /** Set the density (kg/m^3) and mass fractions. */ - void setState_RY(doublereal rho, doublereal* y); + //! Set the density (kg/m^3) and mass fractions. + /*! + * @param rho Density (kg/m^3) + * @param y vector of species mass fractions. + * Length is equal to m_kk + */ + void setState_RY(doublereal rho, doublereal* y); - /** - * Copy the vector of molecular weights into vector weights. - */ - void getMolecularWeights(vector_fp& weights); + /** + * Copy the vector of molecular weights into vector weights. + * + * @param weights Output vector of molecular weights (kg/kmol) + */ + void getMolecularWeights(vector_fp& weights); - /** - * Copy the vector of molecular weights into array weights. - */ - void getMolecularWeights(int iwt, doublereal* weights); + /** + * Copy the vector of molecular weights into array weights. + * + * @param iwt Unused. + * @param weights Output array of molecular weights (kg/kmol) + * + * @deprecated + */ + void getMolecularWeights(int iwt, doublereal* weights); - /** - * Copy the vector of molecular weights into array weights. - */ - void getMolecularWeights(doublereal* weights); + /** + * Copy the vector of molecular weights into array weights. + * + * @param weights Output array of molecular weights (kg/kmol) + */ + void getMolecularWeights(doublereal* weights); - /** - * Return a const reference to the internal vector of - * molecular weights. - */ - const array_fp& molecularWeights(); + /** + * Return a const reference to the internal vector of + * molecular weights. + */ + const array_fp& molecularWeights(); - /** - * Get the mole fractions by name. - */ - void getMoleFractionsByName(compositionMap& x); + /** + * Get the mole fractions by name. + * + * @param x Output composition map containing the + * species mole fractions. + */ + void getMoleFractionsByName(compositionMap& x); //! Return the mole fraction of a single species /*! @@ -208,7 +303,7 @@ namespace Cantera { * * @return Mole fraction of the species */ - doublereal moleFraction(int k) const; + doublereal moleFraction(int k) const; //! Return the mole fraction of a single species /*! @@ -216,7 +311,7 @@ namespace Cantera { * * @return Mole fraction of the species */ - doublereal moleFraction(std::string name) const; + doublereal moleFraction(std::string name) const; //! Return the mass fraction of a single species /*! @@ -224,7 +319,7 @@ namespace Cantera { * * @return Mass Fraction of the species */ - doublereal massFraction(int k) const; + doublereal massFraction(int k) const; //! Return the mass fraction of a single species /*! @@ -232,22 +327,24 @@ namespace Cantera { * * @return Mass Fraction of the species */ - doublereal massFraction(std::string name) const; + doublereal massFraction(std::string name) const; /** * Charge density [C/m^3]. */ doublereal chargeDensity() const; - /// Number of spatial dimensions (1, 2, or 3) - int nDim() {return m_ndim;} + /// Returns the number of spatial dimensions (1, 2, or 3) + int nDim() {return m_ndim;} //! Set the number of spatial dimensions (1, 2, or 3) /*! * The number of spatial dimensions is used for vector involving * directions. + * + * @param ndim Input number of dimensions. */ - void setNDim(int ndim) {m_ndim = ndim;} + void setNDim(int ndim) {m_ndim = ndim;} /** * Finished adding species, prepare to use them for calculation diff --git a/Cantera/src/State.h b/Cantera/src/State.h index dd3ddc968..5ecb85b89 100755 --- a/Cantera/src/State.h +++ b/Cantera/src/State.h @@ -60,11 +60,15 @@ namespace Cantera { /** * Copy Constructor for the State Class + * + * @param right Reference to the class to be copied. */ State(const State& right); /** * Assignment operator for the state class. + * + * @param right Reference to the class to be copied. */ State& operator=(const State& right); @@ -84,19 +88,24 @@ namespace Cantera { /// @name Composition //@{ - /** - * Get the species mole fractions. - * @param x On return, x contains the mole fractions. Must have a - * length greater than or equal to the number of species. - */ - void getMoleFractions(doublereal* x) const; + + //! Get the species mole fraction vector. + /*! + * @param x On return, x contains the mole fractions. Must have a + * length greater than or equal to the number of species. + */ + void getMoleFractions(doublereal* x) const; - /// The mole fraction of species k. If k is ouside the valid - /// range, an exception will be thrown. Note that it is - /// somewhat more efficent to call getMoleFractions if the - /// mole fractions of all species are desired. - doublereal moleFraction(int k) const; + //! The mole fraction of species k. + /*! + * If k is ouside the valid + * range, an exception will be thrown. Note that it is + * somewhat more efficent to call getMoleFractions if the + * mole fractions of all species are desired. + * @param k species index + */ + doublereal moleFraction(int k) const; /** * Set the mole fractions to the specified values, and then @@ -104,6 +113,9 @@ namespace Cantera { * @param x Array of unnormalized mole fraction values (input). * Must have a length greater than or equal to the number of * species. + * + * @param x Input vector of mole fractions. + * Length is m_kk. */ virtual void setMoleFractions(const doublereal* x); @@ -113,6 +125,9 @@ namespace Cantera { * condition is being handled by some other means, for example * by a constraint equation as part of a larger set of * equations. + * + * @param x Input vector of mole fractions. + * Length is m_kk. */ virtual void setMoleFractions_NoNorm(const doublereal* x); @@ -120,15 +135,23 @@ namespace Cantera { * Get the species mass fractions. * @param y On return, y * contains the mass fractions. Array \a y must have a length - * greater than or equal to the number of species. + * greater than or equal to the number of species. + * + * @param y Output vector of mass fractions. + * Length is m_kk. */ void getMassFractions(doublereal* y) const; - /// Mass fraction of species k. If k is outside the valid - /// range, an exception will be thrown. Note that it is - /// somewhat more efficent to call getMassFractions if the - /// mass fractions of all species are desired. - doublereal massFraction(int k) const; + //! Mass fraction of species k. + /*! + * If k is outside the valid + * range, an exception will be thrown. Note that it is + * somewhat more efficent to call getMassFractions if the + * mass fractions of all species are desired. + * + * @param k species index + */ + doublereal massFraction(int k) const; /** * Set the mass fractions to the specified values, and then @@ -136,6 +159,9 @@ namespace Cantera { * @param y Array of unnormalized mass fraction values (input). * Must have a length greater than or equal to the number of * species. + * + * @param y Input vector of mass fractions. + * Length is m_kk. */ virtual void setMassFractions(const doublereal* y); @@ -144,7 +170,10 @@ namespace Cantera { * normalizing. This is useful when the normalization * condition is being handled by some other means, for example * by a constraint equation as part of a larger set of - * equations. + * equations. + * + * @param y Input vector of mass fractions. + * Length is m_kk. */ virtual void setMassFractions_NoNorm(const doublereal* y); @@ -159,6 +188,8 @@ namespace Cantera { /** * Concentration of species k. If k is outside the valid * range, an exception will be thrown. + * + * @param k Index of species */ doublereal concentration(int k) const; @@ -198,18 +229,24 @@ namespace Cantera { * \f[ \sum_k X_k Q_k. \f] * Array Q should contain pure-species molar property * values. + * + * @param Q input vector of length m_kk that is to be averaged. + * @return + * mole-freaction-weighted mean of Q */ doublereal mean_X(const doublereal* Q) const { return m_mmw*std::inner_product(m_ym.begin(), m_ym.end(), Q, 0.0); } - /** - * Evaluate the mass-fraction-weighted mean of Q: - * \f[ \sum_k Y_k Q_k \f] - * Array Q should contain pure-species property - * values in mass units. - */ - doublereal mean_Y(const doublereal* Q) const; + /** + * Evaluate the mass-fraction-weighted mean of Q: + * \f[ \sum_k Y_k Q_k \f] + * + * @param Q Array Q contains a vector of species property values in mass units. + * @return + * Return value containing the mass-fraction-weighted mean of Q. + */ + doublereal mean_Y(const doublereal* Q) const; /** * The mean molecular weight. Units: (kg/kmol) @@ -218,12 +255,20 @@ namespace Cantera { return m_mmw; } - /// Evaluate \f$ \sum_k X_k \log X_k \f$. - doublereal sum_xlogx() const; + //! Evaluate \f$ \sum_k X_k \log X_k \f$. + /*! + * @return + * returns the indicated sum. units are dimensionless. + */ + doublereal sum_xlogx() const; - /// Evaluate \f$ \sum_k X_k \log Q_k \f$. - doublereal sum_xlogQ(doublereal* Q) const; - //@} + //! Evaluate \f$ \sum_k X_k \log Q_k \f$. + /*! + * @param Q Vector of length m_kk to take the log average of + * @return Returns the indicated sum. + */ + doublereal sum_xlogQ(doublereal* Q) const; + //@} /// @name Thermodynamic Properties /// Class State only stores enough thermodynamic data to @@ -243,43 +288,56 @@ namespace Cantera { return m_dens/meanMolecularWeight(); } - /// Set the density (kg/m^3). - virtual void setDensity(doublereal density) { - m_dens = density; - } + //! Set the internally storred density (kg/m^3) of the phase + /*! + * Note the density of a phase is an indepedent variable. + * + * @param density Input density (kg/m^3). + */ + virtual void setDensity(doublereal density) { + m_dens = density; + } - /// Set the molar density (kmol/m^3). - virtual void setMolarDensity(doublereal molarDensity) { - m_dens = molarDensity*meanMolecularWeight(); - } + //! Set the internally storred molar density (kmol/m^3) of the phase. + /*! + * @param molarDensity Input molar density (kmol/m^3). + */ + virtual void setMolarDensity(doublereal molarDensity) { + m_dens = molarDensity*meanMolecularWeight(); + } - /// Set the temperature (K). - void setTemperature(doublereal temp) { - m_temp = temp; - } - //@} - - /// True if species - bool ready() const { return (m_kk > 0); } + //! Set the temperature (K). + /*! + * This function sets the internally storred temperature of the phase. + * + * @param temp Temperature in kelvin + */ + void setTemperature(doublereal temp) { + m_temp = temp; + } + //@} + /// True if the number species has been set + bool ready() const { return (m_kk > 0); } protected: - /** - * @internal - * Initialize. Make a local copy of the vector of - * molecular weights, and resize the composition arrays to - * the appropriate size. The only information an instance of - * State has about the species is their molecular weights. - * - */ - void init(const array_fp& mw); //, density_is_independent = true); - - /** - * m_kk is the number of species in the mixture - */ - int m_kk; + /** + * @internal + * Initialize. Make a local copy of the vector of + * molecular weights, and resize the composition arrays to + * the appropriate size. The only information an instance of + * State has about the species is their molecular weights. + * + * @param mw Vector of molecular weights of the species. + */ + void init(const array_fp& mw); //, density_is_independent = true); + + /** + * m_kk is the number of species in the phase + */ + int m_kk; //! Set the molecular weight of a single species to a given value /*! diff --git a/Cantera/src/ThermoPhase.h b/Cantera/src/ThermoPhase.h index 106dece94..9ff27c3d3 100755 --- a/Cantera/src/ThermoPhase.h +++ b/Cantera/src/ThermoPhase.h @@ -98,12 +98,15 @@ namespace Cantera { */ ThermoPhase(const ThermoPhase &); - /** - * Assignment operator - * - * This is NOT a virtual function. - */ - ThermoPhase& operator=(const ThermoPhase &right); + + //! Assignment operator + /*! + * This is NOT a virtual function. + * + * @param right Reference to %ThermoPhase object to be copied into the + * current one. + */ + ThermoPhase& operator=(const ThermoPhase &right); /** * Duplication routine for objects which inherit from @@ -141,36 +144,42 @@ namespace Cantera { return m_spthermo->refPressure(); } - /** - * Minimum temperature for which the thermodynamic data for - * the species are valid. If no argument is supplied, the - * value returned will be the lowest temperature at which the - * data for \e all species are valid. Otherwise, the value - * will be only for species \a k. This function is a wrapper - * that calls the species thermo minTemp function. - */ - doublereal minTemp(int k = -1) { - return m_spthermo->minTemp(k); - } - - /** - * Maximum temperature for which the thermodynamic data for - * the species are valid. If no argument is supplied, the - * value returned will be the highest temperature at which the - * data for \e all species are valid. Otherwise, the value - * will be only for species \a k. This function is a wrapper - * that calls the species thermo maxTemp function. - */ - doublereal maxTemp(int k = -1) { - return m_spthermo->maxTemp(k); - } - - /** - * @} - * @name Molar Thermodynamic Properties of the Solution - * @{ - */ + //! Minimum temperature for which the thermodynamic data for the species or phase are valid. + /*! + * If no argument is supplied, the + * value returned will be the lowest temperature at which the + * data for \e all species are valid. Otherwise, the value + * will be only for species \a k. This function is a wrapper + * that calls the species thermo minTemp function. + * + * @param k index of the species. Default is -1, which will return the max of the min value + * over all species. + */ + doublereal minTemp(int k = -1) { + return m_spthermo->minTemp(k); + } + + //! Maximum temperature for which the thermodynamic data for the species are valid. + /*! + * If no argument is supplied, the + * value returned will be the highest temperature at which the + * data for \e all species are valid. Otherwise, the value + * will be only for species \a k. This function is a wrapper + * that calls the species thermo maxTemp function. + * + * @param k index of the species. Default is -1, which will return the min of the max value + * over all species. + */ + doublereal maxTemp(int k = -1) { + return m_spthermo->maxTemp(k); + } + + /** + * @} + * @name Molar Thermodynamic Properties of the Solution + * @{ + */ /// Molar enthalpy. Units: J/kmol. virtual doublereal enthalpy_mole() const { @@ -222,26 +231,34 @@ namespace Cantera { } - /** - * Set the pressure (Pa). This method must be reimplemented - * in derived classes. - */ - virtual void setPressure(doublereal p) { - err("setPressure"); - } - - /** - * The isothermal compressibility. Units: 1/Pa. - * The isothermal compressibility is defined as - * \f[ - * \kappa_T = -\frac{1}{v}\left(\frac{\partial v}{\partial P}\right)_T - * \f] - * This method may optionally be defined in derived classes. - */ - virtual doublereal isothermalCompressibility() const { - err("isothermalCompressibility"); return -1.0; - } - + //! Set the internally storred pressure (Pa) + /*! + * This method must be reimplemented in derived classes, where it + * may involve the solution of a nonlinear equation. Within %Cantera, + * the independent variable is the density. Therefore, this function + * solves for the density that will yield the desired input pressure. + * The temperature and composition iare held constant during this process. + * + * This base class function will print an error, if not overwritten. + * + * @param p input Pressure (Pa) + */ + virtual void setPressure(doublereal p) { + err("setPressure"); + } + + /** + * The isothermal compressibility. Units: 1/Pa. + * The isothermal compressibility is defined as + * \f[ + * \kappa_T = -\frac{1}{v}\left(\frac{\partial v}{\partial P}\right)_T + * \f] + * This method may optionally be defined in derived classes. + */ + virtual doublereal isothermalCompressibility() const { + err("isothermalCompressibility"); return -1.0; + } + /** * The volumetric thermal expansion coefficient. Units: 1/K. * The thermal expansion coefficient is defined as @@ -259,30 +276,29 @@ namespace Cantera { deprecatedMethod("ThermoPhase","updateDensity",""); } - /** - * @} - * @name Electric Potential - * - * The phase may be at some non-zero electrical - * potential. These methods set or get the value of the - * electric potential. - //@{ - */ - - - /** - * Set the electric potential of this phase (V). - * This is used by classes InterfaceKinetics and EdgeKinetics to - * compute the rates of charge-transfer reactions, and in computing - * the electrochemical potentials of the species. - * - * Each phase may have its own electric potential. - * - * ¶m v Value of the electric potential in Volts - */ - void setElectricPotential(doublereal v) { - m_phi = v; - } + /** + * @} + * @name Electric Potential + * + * The phase may be at some non-zero electrical + * potential. These methods set or get the value of the + * electric potential. + */ + //@{ + + //! Set the electric potential of this phase (V). + /*! + * This is used by classes InterfaceKinetics and EdgeKinetics to + * compute the rates of charge-transfer reactions, and in computing + * the electrochemical potentials of the species. + * + * Each phase may have its own electric potential. + * + * @param v Input value of the electric potential in Volts + */ + void setElectricPotential(doublereal v) { + m_phi = v; + } //! Returns the electric potential of this phase (V). /*! @@ -355,282 +371,356 @@ namespace Cantera { * concentration is species-specific (e.g. surface species of * different sizes), this method may be called with an * optional parameter indicating the species. + * + * @param k Optional parameter indicating the species. The default + * is to assume this refers to species 0. + * @return + * Returns the standard Concentration in units of m3 kmol-1. */ virtual doublereal standardConcentration(int k=0) const { err("standardConcentration"); return -1.0; } - /** - * Natural logarithm of the standard - * concentration of the kth species. - */ - virtual doublereal logStandardConc(int k=0) const { - err("logStandardConc"); - return -1.0; - } + + //! Natural logarithm of the standard concentration of the kth species. + /*! + * @param k index of the species + */ + virtual doublereal logStandardConc(int k=0) const { + err("logStandardConc"); + return -1.0; + } + + /** + * Returns the units of the standard and generalized + * concentrations. Note they have the same units, as their + * ratio is defined to be equal to the activity of the kth + * species in the solution, which is unitless. + * + * This routine is used in print out applications where the + * units are needed. Usually, MKS units are assumed throughout + * the program and in the XML input files. + * + * @param uA Output vector containing the units + * uA[0] = kmol units - default = 1 + * uA[1] = m units - default = -nDim(), the number of spatial + * dimensions in the Phase class. + * uA[2] = kg units - default = 0; + * uA[3] = Pa(pressure) units - default = 0; + * uA[4] = Temperature units - default = 0; + * uA[5] = time units - default = 0 + * @param k species index. Defaults to 0. + * @param sizeUA output int containing the size of the vector. + * Currently, this is equal to 6. + */ + virtual void getUnitsStandardConc(double *uA, int k = 0, + int sizeUA = 6); - /** - * Returns the units of the standard and generalized - * concentrations. Note they have the same units, as their - * ratio is defined to be equal to the activity of the kth - * species in the solution, which is unitless. - * - * This routine is used in print out applications where the - * units are needed. Usually, MKS units are assumed throughout - * the program and in the XML input files. - * - * uA[0] = kmol units - default = 1 - * uA[1] = m units - default = -nDim(), the number of spatial - * dimensions in the Phase class. - * uA[2] = kg units - default = 0; - * uA[3] = Pa(pressure) units - default = 0; - * uA[4] = Temperature units - default = 0; - * uA[5] = time units - default = 0 - */ - virtual void getUnitsStandardConc(double *uA, int k = 0, - int sizeUA = 6); + /** + * Get the array of non-dimensional activities at + * the current solution temperature, pressure, and + * solution concentration. + * + * We resolve this function at this level by calling + * on the activityConcentration function. However, + * derived classes may want to override this default + * implementation. + * + * @param a Output vector of activities. Length: m_kk. + */ + virtual void getActivities(doublereal* a); - /* - * Get the array of non-dimensional activities at - * the current solution temperature, pressure, and - * solution concentration. - * - * We resolve this function at this level by calling - * on the activityConcentration function. However, - * derived classes may want to override this default - * implementation. - */ - virtual void getActivities(doublereal* a); + /** + * Get the array of non-dimensional molar-based + * activity coefficients at + * the current solution temperature, pressure, and + * solution concentration. + * + * @param ac Output vector of activity coefficients. Length: m_kk. + */ + virtual void getActivityCoefficients(doublereal* ac) const { + if (m_kk == 1) { + ac[0] = 1.0; + } else { + err("getActivityCoefficients"); + } + } + + //@} + /// @name Partial Molar Properties of the Solution + //@{ + + /** + * Get the array of non-dimensional species chemical potentials + * These are partial molar Gibbs free energies. + * \f$ \mu_k / \hat R T \f$. + * Units: unitless + * + * @param mu Output vector of dimensionless chemical potentials. + * Length: m_kk. + */ + virtual void getChemPotentials_RT(doublereal* mu) const { + err("getChemPotentials_RT"); + } + + /** + * Get the species chemical potentials in the solution + * These are partial molar Gibbs free energies. + * Units: J/kmol. + * + * @param mu Output vector of species chemical + * potentials. Length: m_kk. Units: J/kmol + */ + virtual void getChemPotentials(doublereal* mu) const { + err("getChemPotentials"); + } + + //! Get the species electrochemical potentials. + /*! + * These are partial molar quantities. This method adds a term \f$ Fz_k + * \phi_k \f$ to each chemical potential. + * + * @param mu Output vector of species electrochemical + * potentials. Length: m_kk. Units: J/kmol + */ + void getElectrochemPotentials(doublereal* mu) const { + getChemPotentials(mu); + double ve = Faraday * electricPotential(); + for (int k = 0; k < m_kk; k++) { + mu[k] += ve*charge(k); + } + } - /** - * Get the array of non-dimensional molar-based - * activity coefficients at - * the current solution temperature, pressure, and - * solution concentration. - */ - virtual void getActivityCoefficients(doublereal* ac) const { - if (m_kk == 1) { - ac[0] = 1.0; - } else { - err("getActivityCoefficients"); - } - } + //! Get the species partial molar enthalpies. Units: J/kmol. + /*! + * @param hbar Output vector of species partial molar enthalpies. + * Length: m_kk. units are J/kmol. + */ + virtual void getPartialMolarEnthalpies(doublereal* hbar) const { + err("getPartialMolarEnthalpies"); + } + + //! Get the species partial molar entropies. Units: J/kmol/K. + /*! + * @param sbar Output vector of species partial molar entropies. + * Length = m_kk. units are J/kmol/K. + */ + virtual void getPartialMolarEntropies(doublereal* sbar) const { + err("getPartialMolarEntropies"); + } - //@} - /// @name Partial Molar Properties of the Solution - //@{ + //! Get the species partial molar enthalpies. Units: J/kmol. + /*! + * @param ubar Output vector of speciar partial molar internal energies. + * Length = m_kk. units are J/kmol. + */ + virtual void getPartialMolarIntEnergies(doublereal* ubar) const { + err("getPartialMolarIntEnergies"); + } - /** - * Get the array of non-dimensional species chemical potentials - * These are partial molar Gibbs free energies. - * \f$ \mu_k / \hat R T \f$. - * Units: unitless - */ - virtual void getChemPotentials_RT(doublereal* mu) const { - err("getChemPotentials_RT"); - } - - /** - * Get the species chemical potentials in the solution - * These are partial molar Gibbs free energies. - * Units: J/kmol. - */ - virtual void getChemPotentials(doublereal* mu) const { - err("getChemPotentials"); - } - - /** - * Get the species electrochemical potentials. These are - * partial molar quantities. This method adds a term \f$ Fz_k - * \phi_k \f$ to each chemical potential. - * - * Units: J/kmol - */ - void getElectrochemPotentials(doublereal* mu) const { - getChemPotentials(mu); - double ve = Faraday * electricPotential(); - for (int k = 0; k < m_kk; k++) { - mu[k] += ve*charge(k); - } - } - - /** - * Get the species partial molar enthalpies. Units: J/kmol. - */ - virtual void getPartialMolarEnthalpies(doublereal* hbar) const { - err("getPartialMolarEnthalpies"); - } - - /** - * Get the species partial molar entropies. Units: J/kmol. - */ - virtual void getPartialMolarEntropies(doublereal* sbar) const { - err("getPartialMolarEntropies"); - } - - /** - * Get the species partial molar enthalpies. Units: J/kmol. - */ - virtual void getPartialMolarIntEnergies(doublereal* ubar) const { - err("getPartialMolarIntEnergies"); - } - - /** - * Get the partial molar heat capacities Units: J/kmol/K - */ - virtual void getPartialMolarCp(doublereal* cpbar) const { - err("getPartialMolarCp"); - } - - /** - * Get the species partial molar volumes. Units: m^3/kmol. - */ - virtual void getPartialMolarVolumes(doublereal* vbar) const { - err("getPartialMolarVolumes"); - } + //! Get the partial molar heat capacities Units: J/kmol/K + /*! + * @param cpbar Output vector of species partial molar heat capacities at constant pressure. + * Length = m_kk. units are J/kmol/K. + */ + virtual void getPartialMolarCp(doublereal* cpbar) const { + err("getPartialMolarCp"); + } + + //! Get the species partial molar volumes. Units: m^3/kmol. + /*! + * @param vbar Output vector of speciar partial molar volumes. + * Length = m_kk. units are m^3/kmol. + */ + virtual void getPartialMolarVolumes(doublereal* vbar) const { + err("getPartialMolarVolumes"); + } //@} /// @name Properties of the Standard State of the Species in the Solution //@{ - /** - * Get the array of chemical potentials at unit activity. - * These - * are the standard state chemical potentials \f$ \mu^0_k(T,P) - * \f$.. The values are evaluated at the current - * temperature and pressure. - */ - virtual void getStandardChemPotentials(doublereal* mu) const { - err("getStandardChemPotentials"); - } + + //! Get the array of chemical potentials at unit activity. + /*! + * These are the standard state chemical potentials \f$ \mu^0_k(T,P) + * \f$. The values are evaluated at the current + * temperature and pressure of the solution + * + * @param mu Output vector of chemical potentials. + * Length: m_kk. + */ + virtual void getStandardChemPotentials(doublereal* mu) const { + err("getStandardChemPotentials"); + } - /** - * Get the nondimensional Enthalpy functions for the species - * at their standard states at the current - * T and P of the solution. - */ - virtual void getEnthalpy_RT(doublereal* hrt) const { - err("getEnthalpy_RT"); - } + + //! Get the nondimensional Enthalpy functions for the species + //! at their standard states at the current + //! T and P of the solution. + /*! + * @param hrt Output vector of nondimensional standard state enthalpies. + * Length: m_kk. + */ + virtual void getEnthalpy_RT(doublereal* hrt) const { + err("getEnthalpy_RT"); + } - /** - * Get the array of nondimensional Enthalpy functions for the - * standard state species - * at the current T and P of the solution. - */ - virtual void getEntropy_R(doublereal* sr) const { - err("getEntropy_R"); - } + /*! + * Get the array of nondimensional Enthalpy functions for the + * standard state species + * at the current T and P of the solution. + * + * @param sr Output vector of nondimensional standard state entropies. + * Length: m_kk. + */ + virtual void getEntropy_R(doublereal* sr) const { + err("getEntropy_R"); + } - /** - * Get the nondimensional Gibbs functions for the species - * at their standard states of solution at the current T and P - * of the solution. - */ - virtual void getGibbs_RT(doublereal* grt) const { - err("getGibbs_RT"); - } + /*! + * Get the nondimensional Gibbs functions for the species + * at their standard states of solution at the current T and P + * of the solution. + * + * @param grt Output vector of nondimensional standard state gibbs free energies + * Length: m_kk. + */ + virtual void getGibbs_RT(doublereal* grt) const { + err("getGibbs_RT"); + } + + /** + * Get the nondimensional Gibbs functions for the standard + * state of the species at the current T and P. + * + * @param gpure Output vector of standard state gibbs free energies + * Length: m_kk. + */ + virtual void getPureGibbs(doublereal* gpure) const { + err("getPureGibbs"); + } + + /*! + * Returns the vector of nondimensional + * Internal Energies of the standard state at the current temperature + * and pressure of the solution for each species. + * + * @param urt output vector of nondimensional standard state internal energies + * of the species. Length: m_kk. + */ + virtual void getIntEnergy_RT(doublereal *urt) const { + err("getIntEnergy_RT"); + } + + /** + * Get the nondimensional Heat Capacities at constant + * pressure for the standard state of the species + * at the current T and P. + * + * @param cpr Output vector of nondimensional standard state heat capacities + * Length: m_kk. + */ + virtual void getCp_R(doublereal* cpr) const { + err("getCp_R"); + } + + //! Get the molar volumes of each species in their standard states at the current + //! T and P of the solution. + /*! + * units = m^3 / kmol + * + * @param vol Output vector containing the standard state volumes. + * Length: m_kk. + */ + virtual void getStandardVolumes(doublereal *vol) const { + err("getStandardVolumes"); + } - /** - * Get the nondimensional Gibbs functions for the standard - * state of the species at the current T and P. - */ - virtual void getPureGibbs(doublereal* gpure) const { - err("getPureGibbs"); - } + //@} + /// @name Thermodynamic Values for the Species Reference States + //@{ - /** - * Returns the vector of nondimensional - * internal Energies of the standard state at the current temperature - * and pressure of the solution for each species. - */ - virtual void getIntEnergy_RT(doublereal *urt) const { - err("getIntEnergy_RT"); - } - - /** - * Get the nondimensional Heat Capacities at constant - * pressure for the standard state of the species - * at the current T and P. - */ - virtual void getCp_R(doublereal* cpr) const { - err("getCp_R"); - } - - /** - * Get the molar volumes of each species in their standard - * states at the current - * T and P of the solution. - * units = m^3 / kmol - */ - virtual void getStandardVolumes(doublereal *vol) const { - err("getStandardVolumes"); - } - - //@} - /// @name Thermodynamic Values for the Species Reference States - //@{ - - /** - * Returns the vector of nondimensional - * enthalpies of the reference state at the current temperature - * of the solution and the reference pressure for the species. - * - * This base function will throw a CanteraException unless - * it is overwritten in a derived class. - */ - virtual void getEnthalpy_RT_ref(doublereal *hrt) const { + /*! + * Returns the vector of nondimensional + * enthalpies of the reference state at the current temperature + * of the solution and the reference pressure for the species. + * + * This base function will throw a CanteraException unless + * it is overwritten in a derived class. + * + * @param hrt Output vector containing the nondimensional reference state enthalpies + * Length: m_kk. + */ + virtual void getEnthalpy_RT_ref(doublereal *hrt) const { err("getEnthalpy_RT_ref"); } - /** - * Returns the vector of nondimensional - * enthalpies of the reference state at the current temperature - * of the solution and the reference pressure for the species. - */ - virtual void getGibbs_RT_ref(doublereal *grt) const { - err("getGibbs_RT_ref"); - } + /*! + * Returns the vector of nondimensional + * enthalpies of the reference state at the current temperature + * of the solution and the reference pressure for the species. + * + * @param grt Output vector containing the nondimensional reference state + * Gibbs Free energies. Length: m_kk. + */ + virtual void getGibbs_RT_ref(doublereal *grt) const { + err("getGibbs_RT_ref"); + } - /** - * Returns the vector of the - * gibbs function of the reference state at the current temperature - * of the solution and the reference pressure for the species. - * units = J/kmol - */ - virtual void getGibbs_ref(doublereal *g) const { - err("getGibbs_ref"); - } + /*! + * Returns the vector of the + * gibbs function of the reference state at the current temperature + * of the solution and the reference pressure for the species. + * units = J/kmol + * + * @param g Output vector containing the reference state + * Gibbs Free energies. Length: m_kk. Units: J/kmol. + */ + virtual void getGibbs_ref(doublereal *g) const { + err("getGibbs_ref"); + } - /** - * Returns the vector of nondimensional - * entropies of the reference state at the current temperature - * of the solution and the reference pressure for each species. - */ - virtual void getEntropy_R_ref(doublereal *er) const { - err("getEntropy_R_ref"); - } - - /** - * Returns the vector of nondimensional - * internal Energies of the reference state at the current temperature - * of the solution and the reference pressure for each species. - */ - virtual void getIntEnergy_RT_ref(doublereal *urt) const { - err("getIntEnergy_RT_ref"); - } - - /** - * Returns the vector of nondimensional - * constant pressure heat capacities of the reference state - * at the current temperature of the solution - * and reference pressure for each species. - */ - virtual void getCp_R_ref(doublereal *cprt) const { - err("getCp_R_ref()"); - } + /*! + * Returns the vector of nondimensional + * entropies of the reference state at the current temperature + * of the solution and the reference pressure for each species. + * + * @param er Output vector containing the nondimensional reference state + * entropies. Length: m_kk. + */ + virtual void getEntropy_R_ref(doublereal *er) const { + err("getEntropy_R_ref"); + } + /*! + * Returns the vector of nondimensional + * internal Energies of the reference state at the current temperature + * of the solution and the reference pressure for each species. + * + * @param urt Output vector of nondimensional reference state + * internal energies of the species. + * Length: m_kk + */ + virtual void getIntEnergy_RT_ref(doublereal *urt) const { + err("getIntEnergy_RT_ref"); + } + + /*! + * Returns the vector of nondimensional + * constant pressure heat capacities of the reference state + * at the current temperature of the solution + * and reference pressure for each species. + * + * @param cprt Output vector of nondimensional reference state + * heat capacities at constant pressure for the species. + * Length: m_kk + */ + virtual void getCp_R_ref(doublereal *cprt) const { + err("getCp_R_ref()"); + } + /////////////////////////////////////////////////////// // @@ -696,108 +786,223 @@ namespace Cantera { return temperature() * GasConstant; } - /** - * @name Setting the State - * - * These methods set all or part of the thermodynamic - * state. - * @{ - */ - /** Set the temperature (K), pressure (Pa), and mole fractions. */ - void setState_TPX(doublereal t, doublereal p, const doublereal* x); + /** + * @name Setting the State + * + * These methods set all or part of the thermodynamic + * state. + * @{ + */ - /** Set the temperature (K), pressure (Pa), and mole fractions. */ - void setState_TPX(doublereal t, doublereal p, compositionMap& x); + //! Set the temperature (K), pressure (Pa), and mole fractions. + /*! + * Note, the mole fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param x Vector of mole fractions. + * Length is equal to m_kk. + */ + void setState_TPX(doublereal t, doublereal p, const doublereal* x); - /** Set the temperature (K), pressure (Pa), and mole fractions. */ - void setState_TPX(doublereal t, doublereal p, const std::string& x); + //! Set the temperature (K), pressure (Pa), and mole fractions. + /*! + * Note, the mole fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param x Composition map of mole fractions. Species not in + * the composition map are assumed to have zero mole fraction + */ + void setState_TPX(doublereal t, doublereal p, compositionMap& x); - /** Set the temperature (K), pressure (Pa), and mass fractions. */ - void setState_TPY(doublereal t, doublereal p, const doublereal* y); + //! Set the temperature (K), pressure (Pa), and mole fractions. + /*! + * Note, the mole fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param x String containing a composition map of the mole fractions. Species not in + * the composition map are assumed to have zero mole fraction + */ + void setState_TPX(doublereal t, doublereal p, const std::string& x); - /** Set the temperature (K), pressure (Pa), and mass fractions. */ - void setState_TPY(doublereal t, doublereal p, compositionMap& y); + //! Set the internally storred temperature (K), pressure (Pa), and mass fractions of the phase. + /*! + * Note, the mass fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param y Vector of mass fractions. + * Length is equal to m_kk. + */ + void setState_TPY(doublereal t, doublereal p, const doublereal* y); + + //! Set the internally storred temperature (K), pressure (Pa), and mass fractions of the phase + /*! + * Note, the mass fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param y Composition map of mass fractions. Species not in + * the composition map are assumed to have zero mass fraction + */ + void setState_TPY(doublereal t, doublereal p, compositionMap& y); - /** Set the temperature (K), pressure (Pa), and mass fractions. */ - void setState_TPY(doublereal t, doublereal p, const std::string& y); + //! Set the internally storred temperature (K), pressure (Pa), and mass fractions of the phase + /*! + * Note, the mass fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param y String containing a composition map of the mass fractions. Species not in + * the composition map are assumed to have zero mass fraction + */ + void setState_TPY(doublereal t, doublereal p, const std::string& y); - /** Set the temperature (K) and pressure (Pa) */ - void setState_TP(doublereal t, doublereal p); + //! Set the temperature (K) and pressure (Pa) + /*! + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param t Temperature (K) + * @param p Pressure (Pa) + */ + void setState_TP(doublereal t, doublereal p); - /** Set the pressure (Pa) and mole fractions. */ - void setState_PX(doublereal p, doublereal* x); - - /** Set the pressure (Pa) and mass fractions. */ - void setState_PY(doublereal p, doublereal* y); + //! Set the pressure (Pa) and mole fractions. + /*! + * Note, the mole fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param p Pressure (Pa) + * @param x Vector of mole fractions. + * Length is equal to m_kk. + */ + void setState_PX(doublereal p, doublereal* x); - /** Set the specific enthalpy (J/kg) and pressure (Pa). */ - virtual void setState_HP(doublereal h, doublereal p, - doublereal tol = 1.e-4); + //! Set the internally storred pressure (Pa) and mass fractions. + /*! + * Note, the temperature is held constant during this operation. + * Note, the mass fractions are set first before the pressure is set. + * Setting the pressure may involve the solution of a nonlinear equation. + * + * @param p Pressure (Pa) + * @param y Vector of mass fractions. + * Length is equal to m_kk. + */ + void setState_PY(doublereal p, doublereal* y); - /** Set the specific enthalpy (J/kg) and specific volume (m^3/kg). */ - virtual void setState_UV(doublereal u, doublereal v, - doublereal tol = 1.e-4); + //! Set the internally storred specific enthalpy (J/kg) and pressure (Pa) of the phase. + /*! + * @param h Specific enthalpy (J/kg) + * @param p Pressure (Pa) + * @param tol Optional parameter setting the tolerance of the + * calculation. + */ + virtual void setState_HP(doublereal h, doublereal p, + doublereal tol = 1.e-4); - /** Set the specific entropy (J/kg/K) and pressure (Pa). */ - virtual void setState_SP(doublereal s, doublereal p, - doublereal tol = 1.e-4); + //! Set the specific internal energy (J/kg) and specific volume (m^3/kg). + /*! + * This function fixes the internal state of the phase so that + * the specific internal energy and specific volume have the value of the input parameters. + * + * @param u specific internal energy (J/kg) + * @param v specific volume (m^3/kg). + * @param tol Optional parameter setting the tolerance of the + * calculation. + */ + virtual void setState_UV(doublereal u, doublereal v, + doublereal tol = 1.e-4); - /** Set the specific entropy (J/kg/K) and specific volume (m^3/kg). */ - virtual void setState_SV(doublereal s, doublereal v, - doublereal tol = 1.e-4); + //! Set the specific entropy (J/kg/K) and pressure (Pa). + /*! + * This function fixes the internal state of the phase so that + * the specific entropy and the pressure have the value of the input parameters. + * + * @param s specific entropy (J/kg/K) + * @param p specific pressure (Pa). + * @param tol Optional parameter setting the tolerance of the + * calculation. + */ + virtual void setState_SP(doublereal s, doublereal p, + doublereal tol = 1.e-4); - //@} + //! Set the specific entropy (J/kg/K) and specific volume (m^3/kg). + /*! + * This function fixes the internal state of the phase so that + * the specific entropy and specific volume have the value of the input parameters. + * + * @param s specific entropy (J/kg/K) + * @param v specific volume (m^3/kg). + * @param tol Optional parameter setting the tolerance of the + * calculation. + */ + virtual void setState_SV(doublereal s, doublereal v, doublereal tol = 1.e-4); - /** - * @name Chemical Equilibrium - * Chemical equilibrium. - * @{ - */ + //@} + + /** + * @name Chemical Equilibrium + * Chemical equilibrium. + * @{ + */ + + + //!This method is used by the ChemEquil equilibrium solver. + /*! + * It sets the state such that the chemical potentials satisfy + * \f[ \frac{\mu_k}{\hat R T} = \sum_m A_{k,m} + * \left(\frac{\lambda_m} {\hat R T}\right) \f] where + * \f$ \lambda_m \f$ is the element potential of element m. The + * temperature is unchanged. Any phase (ideal or not) that + * implements this method can be equilibrated by ChemEquil. + * + * @param lambda_RT Input vector of dimensionless element potentials + * The length is equal to nElements(). + */ + virtual void setToEquilState(const doublereal* lambda_RT) { + err("setToEquilState"); + } - /** - * This method is used by the ChemEquil equilibrium solver. - * It sets the state such that the chemical potentials satisfy - * \f[ \frac{\mu_k}{\hat R T} = \sum_m A_{k,m} - * \left(\frac{\lambda_m} {\hat R T}\right) \f] where - * \f$ \lambda_m \f$ is the element potential of element m. The - * temperature is unchanged. Any phase (ideal or not) that - * implements this method can be equilibrated by ChemEquil. - */ - virtual void setToEquilState(const doublereal* lambda_RT) { - err("setToEquilState"); - } - - //! Stores the element potentials in the ThermoPhase object - /*! - * Called by function 'equilibrate' in ChemEquil.h to transfer - * the element potentials to this object after every successful - * equilibration routine. - * The element potentials are storred in their dimensionless - * forms, calculated by dividing by RT. - * @param lambda Input vector containing the element potentials. - * Length = nElements. Units are Joules/kmol. - */ - void setElementPotentials(const vector_fp& lambda); + //! Stores the element potentials in the ThermoPhase object + /*! + * Called by function 'equilibrate' in ChemEquil.h to transfer + * the element potentials to this object after every successful + * equilibration routine. + * The element potentials are storred in their dimensionless + * forms, calculated by dividing by RT. + * + * @param lambda Input vector containing the element potentials. + * Length = nElements. Units are Joules/kmol. + */ + void setElementPotentials(const vector_fp& lambda); - //! Returns the element potentials storred in the ThermoPhase object - /*! - * Returns the storred element potentials. - * The element potentials are retrieved from their storred - * dimensionless forms by multiplying by RT. - * @param lambda Output vector containing the element potentials. - * Length = nElements. Units are Joules/kmol. - * @return bool indicating whether thare are any valid storred element - * potentials. The calling routine should check this - * bool. In the case that there aren't any, lambda is not - * touched. - */ - bool getElementPotentials(doublereal* lambda) const; + //! Returns the element potentials storred in the ThermoPhase object + /*! + * Returns the storred element potentials. + * The element potentials are retrieved from their storred + * dimensionless forms by multiplying by RT. + * @param lambda Output vector containing the element potentials. + * Length = nElements. Units are Joules/kmol. + * @return bool indicating whether thare are any valid storred element + * potentials. The calling routine should check this + * bool. In the case that there aren't any, lambda is not + * touched. + */ + bool getElementPotentials(doublereal* lambda) const; //@} - /* + //--------------------------------------------------------- /// @name Critical State Properties. /// These methods are only implemented by some subclasses, and may @@ -846,7 +1051,7 @@ namespace Cantera { virtual void setState_Psat(doublereal p, doublereal x) { err("setState_sat"); } - */ + //@} @@ -860,14 +1065,18 @@ namespace Cantera { /// ThermoFactory.cpp. //@{ - /// Store a reference to the XML tree containing the species - /// data for this phase. This is used to access data needed to - /// construct transport manager later. - /// @internal - void saveSpeciesData(const XML_Node* data) { - m_speciesData = data; - } - + //! Store a reference to the XML tree containing the species data for this phase. + /*! + * This is used to access data needed to construct transport manager later. + * @internal + * + * @param data Pointer to the XML_Node data containing + * information about the species in the phase. + */ + void saveSpeciesData(const XML_Node* data) { + m_speciesData = data; + } + /// Return a pointer to the XML tree containing the species /// data for this phase. const XML_Node* speciesData() { @@ -886,7 +1095,10 @@ namespace Cantera { * constructing solution properties. It is meant for internal * use, and some classes derived from ThermoPhase may not use * any species thermodynamic property manager. This method is - * called by function importPhase in importCTML.cpp. + * called by function importPhase() in importCTML.cpp. + * + * @param spthermo input pointer to the species thermodynamic property + * manager. */ void setSpeciesThermo(SpeciesThermo* spthermo) { m_spthermo = spthermo; } @@ -978,15 +1190,17 @@ namespace Cantera { int index() { return m_index; } - /** - * @internal Set the index number. The Cantera interface - * library uses this method to set the index number to the - * location of the pointer to this object in the pointer array - * it maintains. Using this method for any other purpose will - * lead to unpredictable results if used in conjunction with - * the interface library. - */ - void setIndex(int m) { m_index = m; } + /** + * @internal Set the index number. The Cantera interface + * library uses this method to set the index number to the + * location of the pointer to this object in the pointer array + * it maintains. Using this method for any other purpose will + * lead to unpredictable results if used in conjunction with + * the interface library. + * + * @param m Input the index number. + */ + void setIndex(int m) { m_index = m; } /** @@ -1014,27 +1228,27 @@ namespace Cantera { */ virtual void setParametersFromXML(const XML_Node& eosdata) {} - /** - * Set the initial state of the phase to the conditions - * specified in the state XML element. - * - * This method sets the temperature, pressure, and mole - * fraction vector to a set default value. - * - *@ param state AN XML_Node object corresponding to - * the "state" entry for this phase in the - * input file. - */ - virtual void setStateFromXML(const XML_Node& state); + /** + * Set the initial state of the phase to the conditions + * specified in the state XML element. + * + * This method sets the temperature, pressure, and mole + * fraction vector to a set default value. + * + * @param state AN XML_Node object corresponding to + * the "state" entry for this phase in the + * input file. + */ + virtual void setStateFromXML(const XML_Node& state); - //@} + //@} protected: - /// Pointer to the species thermodynamic property manager - SpeciesThermo* m_spthermo; + //! Pointer to the species thermodynamic property manager + SpeciesThermo* m_spthermo; /// Pointer to the XML tree containing the species /// data for this phase. This is used to access data needed to @@ -1042,13 +1256,22 @@ namespace Cantera { /// later in the initialization process. const XML_Node* m_speciesData; - /// Index number - int m_index; + //! Index number of the phase + /*! + * The Cantera interface library uses this member to set the index number to the + * location of the pointer to this object in the pointer array of ThermoPhase's + * it maintains. Using this member for any other purpose will + * lead to unpredictable results if used in conjunction with + * the interface library. + */ + int m_index; + //! Storred value of the electric potential for this phase /*! * Units are Volts */ - doublereal m_phi; + doublereal m_phi; + /// Vector of element potentials. /// -> length equal to number of elements vector_fp m_lambdaRRT; diff --git a/Cantera/src/ct_defs.h b/Cantera/src/ct_defs.h index aa77fbf95..019847244 100755 --- a/Cantera/src/ct_defs.h +++ b/Cantera/src/ct_defs.h @@ -156,12 +156,21 @@ namespace Cantera { //! Small number to compare differences of mole fractions against. const doublereal Tiny = 1.e-20; //! inline function to return the max value of two doubles. - inline doublereal fmaxx(doublereal x, doublereal y) - { return (x > y) ? x : y; } - //! inline function to return the min value of two doubles. - inline doublereal fminn(doublereal x, doublereal y) - { return (x < y) ? x : y; } + /*! + * @param x double value + * @param y second double value + */ + inline doublereal fmaxx(doublereal x, doublereal y) + { return (x > y) ? x : y; } + //! inline function to return the min value of two doubles. + /*! + * @param x double value + * @param y second double value + */ + inline doublereal fminn(doublereal x, doublereal y) + { return (x < y) ? x : y; } + //! Map connecting a string name with a double. /*! diff --git a/Cantera/src/global.h b/Cantera/src/global.h index f9c5f1e0a..00a821bc3 100755 --- a/Cantera/src/global.h +++ b/Cantera/src/global.h @@ -156,6 +156,8 @@ namespace Cantera { //! Add a directory to the input file search path. /*! * @ingroup inputfiles + * + * @param dir String name for the directory to be added to the search path */ void addDirectory(std::string dir); @@ -188,6 +190,8 @@ namespace Cantera { * place to put temporary files. * * @ingroup inputfiles + * + * @param tmp String name for the temporary directory */ void setTmpDir(std::string tmp); @@ -279,19 +283,30 @@ namespace Cantera { */ void setLogger(Logger* logwriter); - /// Return the conversion factor to convert unit std::string 'unit' to - /// SI units. - doublereal toSI(std::string unit); - - /// Return the conversion factor to convert activation energy unit - /// std::string 'unit' to Kelvin. - doublereal actEnergyToSI(std::string unit); - - /// Return a pointer to the XML tree for a Cantera input file. - XML_Node* get_XML_File(std::string file); - - /// Close a Cantera input file. - void close_XML_File(std::string file); + /// Return the conversion factor to convert unit std::string 'unit' to SI units. + /*! + * @param unit String containing the units + */ + doublereal toSI(std::string unit); + + /// Return the conversion factor to convert activation energy unit + /// std::string 'unit' to Kelvin. + /*! + * @param unit String containing the activation energy units + */ + doublereal actEnergyToSI(std::string unit); + + /// Return a pointer to the XML tree for a Cantera input file. + /*! + * @param file String containing the relative or absolute file name + */ + XML_Node* get_XML_File(std::string file); + + /// Close a Cantera input file. + /*! + * @param file String containing the relative or absolute file name + */ + void close_XML_File(std::string file); #ifdef WITH_HTML_LOGS diff --git a/Cantera/src/logger.h b/Cantera/src/logger.h index 561627c11..0857dfee6 100644 --- a/Cantera/src/logger.h +++ b/Cantera/src/logger.h @@ -38,33 +38,43 @@ namespace Cantera { //! Constructor - empty Logger() {} + //! Destructor - empty virtual ~Logger() {} - /// Write a log message. The default behavior is to write to - /// the standard output. Note that no end-of-line character is - /// appended to the message, and so if one is desired it must - /// be included in the string. - - virtual void write(const std::string& msg) { - std::cout << msg; - } + //! Write a log message. + /*! + * The default behavior is to write to + * the standard output. Note that no end-of-line character is + * appended to the message, and so if one is desired it must + * be included in the string. + * + * @param msg String message to be written to cout + */ + virtual void write(const std::string& msg) { + std::cout << msg; + } - /// Write an error message and quit. The default behavior is - /// to write to the standard eror stream, and then call - /// exit(). Note that no end-of-line character is appended to - /// the message, and so if one is desired it must be included - /// in the string. Note that this default behavior will - /// terminate the application Cantera is invoked from (MATLAB, - /// Excel, etc.) If this is not desired, then derive a class - /// and reimplement this method. - virtual void error(const std::string& msg) { - std::cerr << msg << std::endl; - std::exit(-1); - } + //! Write an error message and quit. + /*! + * The default behavior is + * to write to the standard eror stream, and then call + * exit(). Note that no end-of-line character is appended to + * the message, and so if one is desired it must be included + * in the string. Note that this default behavior will + * terminate the application Cantera is invoked from (MATLAB, + * Excel, etc.) If this is not desired, then derive a class + * and reimplement this method. + * + * @param msg Error message to be written to cerr. + */ + virtual void error(const std::string& msg) { + std::cerr << msg << std::endl; + std::exit(-1); + } - /// Return an integer specifying the application environment. - virtual int env() { return 0; } + /// Return an integer specifying the application environment. + virtual int env() { return 0; } }; } diff --git a/Cantera/src/thermo/IdealMolalSoln.cpp b/Cantera/src/thermo/IdealMolalSoln.cpp index 59015f68a..5bde94fbd 100644 --- a/Cantera/src/thermo/IdealMolalSoln.cpp +++ b/Cantera/src/thermo/IdealMolalSoln.cpp @@ -98,7 +98,7 @@ namespace Cantera { // // -------- Molar Thermodynamic Properties of the Solution --------------- // - /** + /* * Molar enthalpy of the solution: Units: J/kmol. * * Returns the amount of enthalpy per mole of solution. @@ -120,7 +120,7 @@ namespace Cantera { return val; } - /** + /* * Molar internal energy of the solution: Units: J/kmol. * * Returns the amount of internal energy per mole of solution. @@ -136,7 +136,7 @@ namespace Cantera { return mean_X(DATA_PTR(m_tmpV)); } - /** + /* * Molar entropy of the solution: Units J/kmol/K. * * Returns the amount of entropy per mole of solution. @@ -156,7 +156,7 @@ namespace Cantera { return mean_X(DATA_PTR(m_tmpV)); } - /** + /* * Molar Gibbs function for the solution: Units J/kmol. * * Returns the gibbs free energy of the solution per mole @@ -173,7 +173,7 @@ namespace Cantera { return mean_X(DATA_PTR(m_tmpV)); } - /** + /* * Molar heat capacity at constant pressure: Units: J/kmol/K. * * \f[ * \bar{c}_p(T, P, X_k) = \sum_k X_k \bar{c}_{p,k}(T) @@ -187,7 +187,7 @@ namespace Cantera { return val; } - /** + /* * Molar heat capacity at constant volume: Units: J/kmol/K. * NOT IMPLEMENTED. * Units: J/kmol/K @@ -200,7 +200,7 @@ namespace Cantera { // ------- Mechanical Equation of State Properties ------------------------ // - /** + /* * Pressure. Units: Pa. * For this incompressible system, we return the internally storred * independent value of the pressure. @@ -209,7 +209,7 @@ namespace Cantera { return m_Pcurrent; } - /** + /* * The isothermal compressibility. Units: 1/Pa. * The isothermal compressibility is defined as * \f[ @@ -223,7 +223,7 @@ namespace Cantera { return 0.0; } - /** + /* * The thermal expansion coefficient. Units: 1/K. * The thermal expansion coefficient is defined as * @@ -238,7 +238,7 @@ namespace Cantera { return 0.0; } - /** + /* * Overwritten setDensity() function is necessary because the * density is not an indendent variable. * @@ -262,7 +262,7 @@ namespace Cantera { } } - /** + /* * Overwritten setMolarDensity() function is necessary because the * density is not an indendent variable. * @@ -283,7 +283,7 @@ namespace Cantera { // ------- Activities and Activity Concentrations // - /** + /* * This method returns an array of activity concentrations \f$ C^a_k\f$. * \f$ C^a_k\f$ are defined such that * \f$ a_k = C^a_k / C^s_k, \f$ where \f$ C^s_k \f$ @@ -312,7 +312,7 @@ namespace Cantera { } } - /** + /* * The standard concentration \f$ C^s_k \f$ used to normalize * the activity concentration. In many cases, this quantity * will be the same for all species in a phase - for example, @@ -340,7 +340,7 @@ namespace Cantera { return c0; } - /** + /* * Returns the natural logarithm of the standard * concentration of the kth species */ @@ -349,7 +349,7 @@ namespace Cantera { return log(c0); } - /** + /* * Returns the units of the standard and general concentrations * Note they have the same units, as their divisor is * defined to be equal to the activity of the kth species @@ -389,7 +389,7 @@ namespace Cantera { } } - /** + /* * Get the array of non-dimensional molality-based * activities at the current solution temperature, * pressure, and solution concentration. @@ -412,7 +412,7 @@ namespace Cantera { exp((xmolSolvent - 1.0)/xmolSolvent); } - /** + /* * Get the array of non-dimensional Molality based * activity coefficients at * the current solution temperature, pressure, and @@ -438,7 +438,7 @@ namespace Cantera { // ------ Partial Molar Properties of the Solution ----------------- // - /** + /* * Get the species chemical potentials: Units: J/kmol. * * This function returns a vector of chemical potentials of the @@ -494,18 +494,10 @@ namespace Cantera { (RT * (xmolSolvent - 1.0) / xx); } - /** + /* * Returns an array of partial molar enthalpies for the species * in the mixture: Units (J/kmol). * - * For this phase, the partial molar enthalpies are equal to the - * SS species enthalpies - * \f[ - * \bar{h}_k(T,P) = \hat h^{0}_k(T,P) - * \f] - * - * note hbar = ubar + T d(ubar/dT) - * see note about partial molar entropies. */ void IdealMolalSoln::getPartialMolarEnthalpies(doublereal* hbar) const { getEnthalpy_RT(hbar); @@ -515,7 +507,7 @@ namespace Cantera { } } - /** + /* * Returns an array of partial molar entropies of the species in the * solution: Units: J/kmol. * @@ -558,7 +550,7 @@ namespace Cantera { sbar[m_indexSolvent] -= (R * (xmolSolvent - 1.0) / xmolSolvent); } - /** + /* * Returns an array of partial molar volumes of the species * in the solution: Units: m^3 kmol-1. * @@ -571,7 +563,7 @@ namespace Cantera { getStandardVolumes(vbar); } - /** + /* * Partial molar heat capacity of the solution: Units: J/kmol/K. * * The kth partial molar heat capacity is equal to @@ -604,7 +596,7 @@ namespace Cantera { * in the Solution ------------------ */ - /** + /* * Get the standard state chemical potentials of the species. * This is the array of chemical potentials at unit activity * (Mole fraction scale) @@ -628,7 +620,7 @@ namespace Cantera { } } - /** + /* * Get the nondimensional gibbs function for the species * standard states at the current T and P of the solution. * @@ -651,7 +643,7 @@ namespace Cantera { } } - /** + /* * Get the Gibbs functions for the pure species * at the current T and P of the solution. * We assume an incompressible constant partial molar @@ -676,7 +668,7 @@ namespace Cantera { } } - /** + /* * Get the array of nondimensional Enthalpy functions for the ss * species at the current T and P of the solution. * We assume an incompressible constant partial molar @@ -703,7 +695,7 @@ namespace Cantera { } } - /** + /* * Get the nondimensional Entropies for the species * standard states: Units: J/kmol/K * @@ -726,7 +718,7 @@ namespace Cantera { getEntropy_R_ref(sr); } - /** + /* * Get the nondimensional heat capacity at constant pressure * function for the species * standard states: Units J/kmol/K @@ -745,7 +737,7 @@ namespace Cantera { getCp_R_ref(cpr); } - /** + /* * Get the molar volumes of each species in their standard * states at the current * T and P of the solution. @@ -772,7 +764,7 @@ namespace Cantera { * -------------- Utilities ------------------------------- */ - /** + /* * Initialization routine for an IdealMolalSoln phase. * * This is a virtual routine. This routine will call initThermo() @@ -829,7 +821,7 @@ namespace Cantera { delete fxml; } - /** + /* * Import and initialize an IdealMolalSoln phase * specification in an XML tree into the current object. * Here we read an XML description of the phase. @@ -882,7 +874,7 @@ namespace Cantera { } } - /** + /* * Import and initialize an IdealMolalSoln phase * specification in an XML tree into the current object. * @@ -1011,7 +1003,7 @@ namespace Cantera { } - /** + /* * @internal * Set equation of state parameters. The number and meaning of * these depends on the subclass. @@ -1023,7 +1015,8 @@ namespace Cantera { } void IdealMolalSoln::getParameters(int &n, doublereal * const c) { } - /** + + /* * Set equation of state parameter values from XML * entries. This method is called by function importPhase in * file importCTML.cpp when processing a phase definition in @@ -1048,7 +1041,7 @@ namespace Cantera { * ------------ Private and Restricted Functions ------------------ */ - /** + /* * Bail out of functions with an error exit if they are not * implemented. */ @@ -1058,7 +1051,7 @@ namespace Cantera { return 0.0; } - /** + /* * This internal function adjusts the lengths of arrays. * * This function is not virtual nor is it inherited diff --git a/Cantera/src/thermo/IdealMolalSoln.h b/Cantera/src/thermo/IdealMolalSoln.h index 6ae3060b3..911a2b33f 100644 --- a/Cantera/src/thermo/IdealMolalSoln.h +++ b/Cantera/src/thermo/IdealMolalSoln.h @@ -146,22 +146,82 @@ namespace Cantera { * @{ */ - //Molar enthalpy. Units: J/kmol. + //! Molar enthalpy of the solution. Units: J/kmol. + /*! + * + * Returns the amount of enthalpy per mole of solution. + * For an ideal molal solution, + * \f[ + * \bar{h}(T, P, X_k) = \sum_k X_k \bar{h}_k(T) + * \f] + * The formula is written in terms of the partial molar enthalpies. + * \f$ \bar{h}_k(T, p, m_k) \f$. + * See the partial molar enthalpy function, getPartialMolarEnthalpies(), + * for details. + * + * Units: J/kmol + */ virtual doublereal enthalpy_mole() const; - // Molar internal energy. Units: J/kmol. + //! Molar internal energy of the solution: Units: J/kmol. + /*! + * + * Returns the amount of internal energy per mole of solution. + * For an ideal molal solution, + * \f[ + * \bar{u}(T, P, X_k) = \sum_k X_k \bar{u}_k(T) + * \f] + * The formula is written in terms of the partial molar internal energy. + * \f$ \bar{u}_k(T, p, m_k) \f$. + */ virtual doublereal intEnergy_mole() const; - // Molar entropy. Units: J/kmol/K. + //! Molar entropy of the solution. Units: J/kmol/K. + /*! + * Returns the amount of entropy per mole of solution. + * For an ideal molal solution, + * \f[ + * \bar{s}(T, P, X_k) = \sum_k X_k \bar{s}_k(T) + * \f] + * The formula is written in terms of the partial molar entropies. + * \f$ \bar{s}_k(T, p, m_k) \f$. + * See the partial molar entropies function, getPartialMolarEntropies(), + * for details. + * + * Units: J/kmol/K. + */ virtual doublereal entropy_mole() const; - // Molar Gibbs function. Units: J/kmol. + //! Molar Gibbs function for the solution: Units J/kmol. + /*! + * + * Returns the gibbs free energy of the solution per mole + * of the solution. + * + * \f[ + * \bar{g}(T, P, X_k) = \sum_k X_k \mu_k(T) + * \f] + * + * Units: J/kmol + */ virtual doublereal gibbs_mole() const; - // Molar heat capacity at constant pressure. Units: J/kmol/K. + //! Molar heat capacity of the solution at constant pressure. Units: J/kmol/K. + /*! + * \f[ + * \bar{c}_p(T, P, X_k) = \sum_k X_k \bar{c}_{p,k}(T) + * \f] + * + * Units: J/kmol/K + */ virtual doublereal cp_mole() const; - // Molar heat capacity at constant volume. Units: J/kmol/K. + //! Molar heat capacity of the solution at constant volume. Units: J/kmol/K. + /*! + * Molar heat capacity at constant volume: Units: J/kmol/K. + * NOT IMPLEMENTED. + * Units: J/kmol/K + */ virtual doublereal cv_mole() const; //@} @@ -177,7 +237,7 @@ namespace Cantera { */ - /* + /*! * Pressure. Units: Pa. * For this incompressible system, we return the internally storred * independent value of the pressure. @@ -188,12 +248,14 @@ namespace Cantera { * Set the pressure at constant temperature. Units: Pa. * This method sets a constant within the object. * The mass density is not a function of pressure. + * + * @param p Input Pressure */ virtual void setPressure(doublereal p) { m_Pcurrent = p; } - /* + /** * Calculate the density of the mixture using the partial * molar volumes and mole fractions as input * @@ -218,7 +280,7 @@ namespace Cantera { */ void calcDensity(); - /* + /** * Overwritten setDensity() function is necessary because the * density is not an indendent variable. * @@ -233,10 +295,12 @@ namespace Cantera { * * NOTE: This is an overwritten function from the State.h * class + * + * @param rho Input Density */ void setDensity(doublereal rho); - /* + /** * Overwritten setMolarDensity() function is necessary because the * density is not an indendent variable. * @@ -244,25 +308,33 @@ namespace Cantera { * * NOTE: This is an overwritten function from the State.h * class + * + * @param rho Input Density */ void setMolarDensity(doublereal rho); - /* - * The isothermal compressibility. Units: 1/Pa. + //! The isothermal compressibility. Units: 1/Pa. + /*! * The isothermal compressibility is defined as * \f[ * \kappa_T = -\frac{1}{v}\left(\frac{\partial v}{\partial P}\right)_T * \f] + * + * It's equal to zero for this model, since the molar volume + * doesn't change with pressure or temperature. */ virtual doublereal isothermalCompressibility() const; - /* - * The thermal expansion coefficient. Units: 1/K. + //! The thermal expansion coefficient. Units: 1/K. + /*! * The thermal expansion coefficient is defined as * * \f[ * \beta = \frac{1}{v}\left(\frac{\partial v}{\partial T}\right)_P * \f] + * + * It's equal to zero for this model, since the molar volume + * doesn't change with pressure or temperature. */ virtual doublereal thermalExpansionCoeff() const; @@ -277,21 +349,27 @@ namespace Cantera { * @{ */ - /* - * Set the potential energy of species k to pe. + + //!Set the potential energy of species k to pe. + /*! * Units: J/kmol. * This function must be reimplemented in inherited classes * of ThermoPhase. + * + * @param k Species index + * @param pe Input potential energy. */ virtual void setPotentialEnergy(int k, doublereal pe) { err("setPotentialEnergy"); } - + /* * Get the potential energy of species k. * Units: J/kmol. * This function must be reimplemented in inherited classes * of ThermoPhase. + * + * @param k Species index */ virtual doublereal potentialEnergy(int k) const { return err("potentialEnergy"); @@ -302,12 +380,14 @@ namespace Cantera { * This is used by classes InterfaceKinetics and EdgeKinetics to * compute the rates of charge-transfer reactions, and in computing * the electrochemical potentials of the species. + * + * @param v input Electric Potential (volts). */ void setElectricPotential(doublereal v) { m_phi = v; } - /// The electric potential of this phase (V). + //! Returns the electric potential of this phase (V). doublereal electricPotential() const { return m_phi; } @@ -323,7 +403,7 @@ namespace Cantera { * @{ */ - /* + /*! * This method returns an array of generalized concentrations * \f$ C_k\f$ that are defined such that * \f$ a_k = C_k / C^0_k, \f$ where \f$ C^0_k \f$ @@ -338,7 +418,7 @@ namespace Cantera { */ virtual void getActivityConcentrations(doublereal* c) const; - /* + /** * The standard concentration \f$ C^0_k \f$ used to normalize * the generalized concentration. In many cases, this quantity * will be the same for all species in a phase - for example, @@ -348,16 +428,20 @@ namespace Cantera { * concentration is species-specific (e.g. surface species of * different sizes), this method may be called with an * optional parameter indicating the species. + * + * @param k Species index */ virtual doublereal standardConcentration(int k=0) const; - /** + /*! * Returns the natural logarithm of the standard * concentration of the kth species + * + * @param k Species index */ virtual doublereal logStandardConc(int k=0) const; - /* + /*! * Returns the units of the standard and generalized * concentrations Note they have the same units, as their * ratio is defined to be equal to the activity of the kth @@ -367,6 +451,7 @@ namespace Cantera { * units are needed. Usually, MKS units are assumed throughout * the program and in the XML input files. * + * @param uA Output vector containing the units * uA[0] = kmol units - default = 1 * uA[1] = m units - default = -nDim(), the number of spatial * dimensions in the Phase class. @@ -374,20 +459,26 @@ namespace Cantera { * uA[3] = Pa(pressure) units - default = 0; * uA[4] = Temperature units - default = 0; * uA[5] = time units - default = 0 + * @param k species index. Defaults to 0. + * @param sizeUA output int containing the size of the vector. + * Currently, this is equal to 6. */ virtual void getUnitsStandardConc(double *uA, int k = 0, int sizeUA = 6); - /* + /*! * Get the array of non-dimensional activities at * the current solution temperature, pressure, and * solution concentration. * * (note solvent is on molar scale) + * + * @param ac Output activity coefficients. + * Length: m_kk. */ virtual void getActivities(doublereal* ac) const; - /* + /*! * Get the array of non-dimensional molality-based * activity coefficients at the current solution temperature, * pressure, and solution concentration. @@ -395,6 +486,9 @@ namespace Cantera { * * (note solvent is on molar scale. The solvent molar * based activity coefficient is returned). + * + * @param acMolality Output Molality-based activity coefficients. + * Length: m_kk. */ virtual void getMolalityActivityCoefficients(doublereal* acMolality) const; @@ -403,8 +497,31 @@ namespace Cantera { /// @name Partial Molar Properties of the Solution ----------------- //@{ - // Get the species chemical potentials: Units: J/kmol. - // This is also the partial molar gibbs free energies. + + //!Get the species chemical potentials: Units: J/kmol. + /*! + * + * This function returns a vector of chemical potentials of the + * species in solution. + * + * \f[ + * \mu_k = \mu^{o}_k(T,P) + R T \ln(\frac{m_k}{m^\Delta}) + * \f] + * \f[ + * \mu_w = \mu^{o}_w(T,P) + + * R T ((X_w - 1.0) / X_w) + * \f] + * + * \f$ w \f$ refers to the solvent species. + * \f$ X_w \f$ is the mole fraction of the solvent. + * \f$ m_k \f$ is the molality of the kth solute. + * \f$ m^\Delta is 1 gmol solute per kg solvent. \f$ + * + * Units: J/kmol. + * + * @param mu Output vector of species chemical potentials. + * Length: m_kk. + */ virtual void getChemPotentials(doublereal* mu) const; /** @@ -415,6 +532,9 @@ namespace Cantera { * to each chemical potential. * * Units: J/kmol + * + * @param mu Output vector of electrochemical potentials. + * Length: m_kk. */ void getElectrochemPotentials(doublereal* mu) const { getChemPotentials(mu); @@ -424,12 +544,11 @@ namespace Cantera { } } - /* - * Returns an array of partial molar enthalpies for the species - * in the mixture. + //! Returns an array of partial molar enthalpies for the species in the mixture. + /*! * Units (J/kmol) * For this phase, the partial molar enthalpies are equal to the - * pure species enthalpies + * species standard state enthalpies. * \f[ * \bar h_k(T,P) = \hat h^{ref}_k(T) + (P - P_{ref}) \hat V^0_k * \f] @@ -438,29 +557,72 @@ namespace Cantera { * are computed by the species thermodynamic * property manager. They are polynomial functions of temperature. * @see SpeciesThermo + * + * @param hbar Output vector of partial molar enthalpies. + * Length: m_kk. */ virtual void getPartialMolarEnthalpies(doublereal* hbar) const; - /* - * getPartialMolarEntropies() (virtual, const) + + //! Returns an array of partial molar entropies of the species in the solution. Units: J/kmol. + /*! * - * Returns an array of partial molar entropies of the species in the - * solution. Units: J/kmol. + * Maxwell's equations provide an insight in how to calculate this + * (p.215 Smith and Van Ness) + * \f[ + * \frac{d(\mu_k)}{dT} = -\bar{s}_i + * \f] + * For this phase, the partial molar entropies are equal to the + * standard state species entropies plus the ideal molal solution contribution. + * + * \f[ + * \bar{s}_k(T,P) = s^0_k(T) - R log( m_k ) + * \f] + * \f[ + * \bar{s}_w(T,P) = s^0_w(T) - R ((X_w - 1.0) / X_w) + * \f] * + * The subscript, w, refers to the solvent species. \f$ X_w \f$ is + * the mole fraction of solvent. + * The reference-state pure-species entropies,\f$ s^0_k(T) \f$, + * at the reference pressure, \f$ P_{ref} \f$, are computed by the + * species thermodynamic + * property manager. They are polynomial functions of temperature. + * @see SpeciesThermo + * + * @param sbar Output vector of partial molar entropies. + * Length: m_kk. */ virtual void getPartialMolarEntropies(doublereal* sbar) const; // partial molar volumes of the species Units: m^3 kmol-1. + /*! + * For this solution, the partial molar volumes are equal to the + * constant species molar volumes. + * + * Units: m^3 kmol-1. + * @param vbar Output vector of partial molar volumes. + */ virtual void getPartialMolarVolumes(doublereal* vbar) const; - /* - * Partial molar heat capacity of the solution: + + //! Partial molar heat capacity of the solution:. UnitsL J/kmol/K + /*! * The kth partial molar heat capacity is equal to * the temperature derivative of the partial molar * enthalpy of the kth species in the solution at constant * P and composition (p. 220 Smith and Van Ness). + * \f[ + * \bar{Cp}_k(T,P) = {Cp}^0_k(T) + * \f] * - * Cp = -T d2(chemPot_i)/dT2 + * For this solution, this is equal to the reference state + * heat capacities. + * + * Units: J/kmol/K + * + * @param cpbar Output vector of partial molar heat capacities. + * Length: m_kk. */ virtual void getPartialMolarCp(doublereal* cpbar) const; @@ -469,7 +631,7 @@ namespace Cantera { // in the Solution -- //@{ - /* + /*! * Get the standard state chemical potentials of the species. * This is the array of chemical potentials at unit activity * \f$ \mu^0_k(T,P) \f$. @@ -480,10 +642,13 @@ namespace Cantera { * on T and P. This is the norm for liquid and solid systems. * * units = J / kmol + * + * @param mu Output vector of standard state chemical potentials. + * Length: m_kk. */ virtual void getStandardChemPotentials(doublereal* mu) const; - /* + /*! * Get the nondimensional gibbs function for the species * standard states at the current T and P of the solution. * @@ -500,47 +665,68 @@ namespace Cantera { */ virtual void getGibbs_RT(doublereal* grt) const; - /* - * Get the nondimensional Gibbs functions for the standard - * state of the species at the current T and P. - */ - virtual void getPureGibbs(doublereal* gpure) const; - - /* - * - * getEnthalpy_RT() (virtual, const) - * - * Get the array of nondimensional Enthalpy functions for the ss - * species at the current T and P of the solution. + + //! Get the Gibbs functions for the standard state species + //! at the current T and P of the solution. + /*! * We assume an incompressible constant partial molar * volume here: * \f[ + * \mu^0_k(T,p) = \mu^{ref}_k(T) + (P - P_{ref}) * V_k + * \f] + * where \f$V_k\f$ is the molar volume of pure species k. + * \f$ u^{ref}_k(T)\f$ is the chemical potential of pure + * species k at the reference pressure, \f$P_{ref}\f$. + * + * Units: J/kmol + * + * @param gpure Output vector of standard state gibbs free energies. + * Length: m_kk. + */ + virtual void getPureGibbs(doublereal* gpure) const; + + //! Get the array of nondimensional Enthalpy functions for the ss + //! species at the current T and P of the solution. + /*! + * We assume an incompressible constant partial molar volume here: + * + * \f[ * h^0_k(T,P) = h^{ref}_k(T) + (P - P_{ref}) * V_k * \f] + * * where \f$V_k\f$ is the molar volume of SS species k. * \f$ h^{ref}_k(T)\f$ is the enthalpy of the SS * species k at the reference pressure, \f$P_{ref}\f$. + * + * @param hrt Output vector of nondimensional standard state + * enthalpies. Length: m_kk. */ virtual void getEnthalpy_RT(doublereal* hrt) const; - /* - * Get the nondimensional Entropies for the species - * standard states at the current T and P of the solution. + + //! Get the nondimensional Entropies for the species + //! standard states at the current T and P of the solution. + /*! * * Note, this is equal to the reference state entropies * due to the zero volume expansivity: + * * i.e., (dS/dp)_T = (dV/dT)_P = 0.0 * + * \f[ + * S^0_k(T,P) = S^{ref}_k(T) + * \f] + * * @param sr Vector of length m_kk, which on return sr[k] * will contain the nondimensional * standard state entropy of species k. */ virtual void getEntropy_R(doublereal* sr) const; - /* - * Get the nondimensional heat capacity at constant pressure - * function for the species - * standard states at the current T and P of the solution. + + //! Get the nondimensional heat capacity at constant pressure + //! function for the species standard states at the current T and P of the solution. + /*! * \f[ * Cp^0_k(T,P) = Cp^{ref}_k(T) * \f] @@ -554,11 +740,17 @@ namespace Cantera { */ virtual void getCp_R(doublereal* cpr) const; - /* - * Get the molar volumes of each species in their standard - * states at the current - * T and P of the solution. + //! Get the molar volumes of each species in their standard + //! states at the current T and P of the solution. + /*! + * + * \f[ + * V^0_k(T,P) = V^{ref}_k() + * \f] * units = m^3 / kmol + * + * @param vol Output vector of standard state volumes. + * Length: m_kk. */ virtual void getStandardVolumes(doublereal *vol) const; @@ -606,6 +798,8 @@ namespace Cantera { * implements this method can be equilibrated by ChemEquil. * * Not implemented. + * + * @param lambda_RT vector of Nondimensional element potentials. */ virtual void setToEquilState(const doublereal* lambda_RT) { err("setToEquilState"); @@ -613,7 +807,6 @@ namespace Cantera { //@} - /** * @internal * Set equation of state parameters. The number and meaning of @@ -633,7 +826,7 @@ namespace Cantera { */ virtual void getParameters(int &n, doublereal * const c); - /* + /*! * Set equation of state parameter values from XML * entries. This method is called by function importPhase in * file importCTML.cpp when processing a phase definition in @@ -683,6 +876,7 @@ namespace Cantera { /// These methods are only implemented by subclasses that /// implement full liquid-vapor equations of state. /// + /* virtual doublereal satTemperature(doublereal p) const { err("satTemperature"); return -1.0; } @@ -702,7 +896,7 @@ namespace Cantera { virtual void setState_Psat(doublereal p, doublereal x) { err("setState_sat"); } - + */ //@} @@ -710,40 +904,39 @@ namespace Cantera { * -------------- Utilities ------------------------------- */ - /** - * @internal Install a species thermodynamic property - * manager. The species thermodynamic property manager - * computes properties of the pure species for use in - * constructing solution properties. It is meant for internal - * use, and some classes derived from ThermoPhase may not use - * any species thermodynamic property manager. - */ - void setSpeciesThermo(SpeciesThermo* spthermo) - { m_spthermo = spthermo; } - - /** + /*! * Return a reference to the species thermodynamic property * manager. @todo This method will fail if no species thermo * manager has been installed. */ SpeciesThermo& speciesThermo() { return *m_spthermo; } - /* - * initThermo() (virtual from ThermoPhase) - * + + //! Initialization routine for an IdealMolalSoln phase. + /*! * This internal routine is responsible for setting up - * the internal storage. + * the internal storage. This is reimplemented from the ThermoPhase + * class. */ virtual void initThermo(); - /* - * constructPhaseFile (virtual from here) + //! Import and initialize an IdealMolalSoln phase + //! specification in an XML tree into the current object. + /*! + * Here we read an XML description of the phase. + * We import descriptions of the elements that make up the + * species in a phase. + * We import information about the species, including their + * reference state thermodynamic polynomials. We then freeze + * the state of the species. * - * Initialization of an IdealSolidSolnPhase phase using an - * xml file identified by its path + * Then, we read the species molar volumes from the xml + * tree to finish the initialization. * - * This routine is a precursor to constructPhaseXML(XML_Node*) - * routine, which does most of the work. + * This routine is a precursor to constructPhaseXML(XML_Node*) + * routine, which does most of the work. + * + * This is a virtual routine, first used here. * * @param infile XML file containing the description of the * phase @@ -754,13 +947,25 @@ namespace Cantera { */ virtual void constructPhaseFile(std::string infile, std::string id=""); - /* - * constructPhaseXML (virtual from here) - * + //! Import and initialize an IdealMolalSoln phase + //! specification in an XML tree into the current object. + /*! * This is the main routine for constructing the phase. * It processes the XML file, and then it calls importPhase(). * Then, initThermoXML() is called after importPhase(). * + * Here we read an XML description of the phase. + * We import descriptions of the elements that make up the + * species in a phase. + * We import information about the species, including their + * reference state thermodynamic polynomials. We then freeze + * the state of the species. + * + * Then, we read the species molar volumes from the xml + * tree to finish the initialization. + * + * This is a virtual routine, first used in this class. + * * @param phaseNode This object must be the phase node of a * complete XML tree * description of the phase, including all of the @@ -774,10 +979,9 @@ namespace Cantera { */ virtual void constructPhaseXML(XML_Node& phaseNode, std::string id); - /* - * initThermoXML (virtual from ThermoPhase) - * - * + //! Import and initialize an IdealMolalSoln phase + //! specification in an XML tree into the current object. + /*! * This routine is called from importPhase() to finish * up the initialization of the thermo object. It reads in the * species molar volumes. @@ -795,16 +999,20 @@ namespace Cantera { */ virtual void initThermoXML(XML_Node& phaseNode, std::string id=""); + //! Report the molar volume of species k /*! - * Report the molar volume of species k * * units - \f$ m^3 kmol^-1 \f$ + * + * @param k Species index. */ double speciesMolarVolume(int k) const; /*! * Fill in a return vector containing the species molar volumes * units - \f$ m^3 kmol^-1 \f$ + * + * @param smv Output vector of species molar volumes. */ void getSpeciesMolarVolumes(double *smv) const; //@} @@ -815,7 +1023,7 @@ namespace Cantera { */ array_fp m_speciesMolarVolume; - /** + /*! * Current pressure in Pascal. * * This is an independent variable in the problem. diff --git a/Cantera/src/thermo/IdealSolidSolnPhase.h b/Cantera/src/thermo/IdealSolidSolnPhase.h index f4a3b25b7..3f5eeff19 100644 --- a/Cantera/src/thermo/IdealSolidSolnPhase.h +++ b/Cantera/src/thermo/IdealSolidSolnPhase.h @@ -288,6 +288,8 @@ namespace Cantera { * Set the pressure at constant temperature. Units: Pa. * This method sets a constant within the object. * The mass density is not a function of pressure. + * + * @param p Input Pressure (Pa) */ virtual void setPressure(doublereal p); @@ -331,6 +333,8 @@ namespace Cantera { * * NOTE: This is a virtual function that overwrites the State.h * class + * + * @param rho Input density */ virtual void setDensity(doublereal rho); @@ -342,17 +346,47 @@ namespace Cantera { * * NOTE: This is virtual function that overwrites the State.h * class + * + * @param rho Input Density */ virtual void setMolarDensity(doublereal rho); + //! Set the mole fractions + /*! + * @param x Input vector of mole fractions. + * Length: m_kk. + */ virtual void setMoleFractions(doublereal *x); + + //! Set the mole fractions, but don't normalize them to one. + /*! + * @param x Input vector of mole fractions. + * Length: m_kk. + */ virtual void setMoleFractions_NoNorm(doublereal *x); + + //! Set the mass fractions, and normalize them to one. + /*! + * @param y Input vector of mass fractions. + * Length: m_kk. + */ virtual void setMassFractions(doublereal *y); + + //! Set the mass fractions, but don't normalize them to one + /*! + * @param y Input vector of mass fractions. + * Length: m_kk. + */ virtual void setMassFractions_NoNorm(doublereal *y); + + //! Set the concentration, + /*! + * @param c Input vector of concentrations. + * Length: m_kk. + */ virtual void setConcentrations(doublereal *c); - //@} /** @@ -431,7 +465,7 @@ namespace Cantera { * on both temperature and pressure. If we hadn't, it would have * appeared in this function in a very awkwards exp[] format. * - * @param c[] Pointer to array of doubles of length m_kk, which on exit + * @param c Pointer to array of doubles of length m_kk, which on exit * will contain the generalized concentrations. */ virtual void getActivityConcentrations(doublereal* c) const; @@ -460,6 +494,8 @@ namespace Cantera { * for each species. (clone of the standard concentration -> * suggest changing the name). This is the inverse of the species molar * volume. + * + * @param k Species index. */ virtual doublereal referenceConcentration(int k) const; @@ -467,8 +503,8 @@ namespace Cantera { * Returns the log of the standard concentration of the kth species * * @param k Species number: this is a require parameter, - * a change from the ThermoPhase base class, where it was - * an optional parameter. + * a change from the ThermoPhase base class, where it was + * an optional parameter. */ virtual doublereal logStandardConc(int k) const; @@ -482,6 +518,7 @@ namespace Cantera { * units are needed. Usually, MKS units are assumed throughout * the program and in the XML input files. * + * @param uA Output vector containing the units * uA[0] = kmol units - default = 1 * uA[1] = m units - default = -nDim(), the number of spatial * dimensions in the Phase class. @@ -489,6 +526,9 @@ namespace Cantera { * uA[3] = Pa(pressure) units - default = 0; * uA[4] = Temperature units - default = 0; * uA[5] = time units - default = 0 + * @param k species index. Defaults to 0. + * @param sizeUA output int containing the size of the vector. + * Currently, this is equal to 6. * * For EOS types other than cIdealSolidSolnPhase0, the default * kmol/m3 holds for standard concentration units. For @@ -498,8 +538,10 @@ namespace Cantera { virtual void getUnitsStandardConc(double *uA, int k = 0, int sizeUA = 6); - /** - * Get the array of species activity coefficients + + //! Get the array of species activity coefficients + /*! + * @param ac output vector of activity coefficients. Length: m_kk */ virtual void getActivityCoefficients(doublereal * ac) const; @@ -516,6 +558,8 @@ namespace Cantera { * \mu_k = \mu^o_k(T,p) + R T ln(X_k) * \f] * where \f$ \mu^o_k(T,p) = \mu^{ref}_k(T) + V_k * (p - p_o)\f$ + * + * @param mu Output vector of chemical potentials. */ virtual void getChemPotentials(doublereal* mu) const; @@ -529,6 +573,8 @@ namespace Cantera { * where \f$V_k\f$ is the molar volume of pure species k. * \f$ \mu^{ref}_k(T)\f$ is the chemical potential of pure * species k at the reference pressure, \f$P_{ref}\f$. + * + * @param mu Output vector of dimensionless chemical potentials. Length = m_kk. */ virtual void getChemPotentials_RT(doublereal* mu) const; @@ -550,6 +596,9 @@ namespace Cantera { * are computed by the species thermodynamic * property manager. They are polynomial functions of temperature. * @see SpeciesThermo + * + * @param hbar Output vector containing partial molar enthalpies. + * Length: m_kk. */ virtual void getPartialMolarEnthalpies(doublereal* hbar) const; @@ -566,6 +615,9 @@ namespace Cantera { * species thermodynamic * property manager. They are polynomial functions of temperature. * @see SpeciesThermo + * + * @param sbar Output vector containing partial molar entropies. + * Length: m_kk. */ virtual void getPartialMolarEntropies(doublereal* sbar) const; @@ -575,6 +627,8 @@ namespace Cantera { * solution. Units: J/kmol/K. * For this phase, the partial molar heat capacities are equal * to the standard state heat capacities. + * + * @param cpbar Output vector of partial heat capacities. Length: m_kk. */ virtual void getPartialMolarCp(doublereal* cpbar) const; @@ -584,6 +638,8 @@ namespace Cantera { * * For this solution, thepartial molar volumes are equal to the * constant species molar volumes. + * + * @param vbar Output vector of partial molar volumes. Length: m_kk. */ virtual void getPartialMolarVolumes(doublereal* vbar) const; @@ -603,6 +659,9 @@ namespace Cantera { * on T and P. This is the norm for liquid and solid systems. * * units = J / kmol + * + * @param mu0 Output vector of standard state chemical potentials. + * Length: m_kk. */ virtual void getStandardChemPotentials(doublereal* mu0) const { getPureGibbs(mu0); @@ -668,6 +727,9 @@ namespace Cantera { * where \f$V_k\f$ is the molar volume of pure species k. * \f$ \mu^{ref}_k(T)\f$ is the chemical potential of pure * species k at the reference pressure, \f$P_{ref}\f$. + * + * @param gpure Output vector of Gibbs functions for species + * Length: m_kk. */ virtual void getPureGibbs(doublereal* gpure) const; @@ -675,6 +737,9 @@ namespace Cantera { * Returns the vector of nondimensional * internal Energies of the standard state at the current * temperature and pressure of the solution for each species. + * + * @param urt Output vector of standard state nondimensional internal energies. + * Length: m_kk. */ virtual void getIntEnergy_RT(doublereal *urt) const; @@ -700,6 +765,9 @@ namespace Cantera { * states at the current * T and P of the solution. * units = m^3 / kmol + * + * @param vol Output vector of standard state volumes. + * Length: m_kk. */ virtual void getStandardVolumes(doublereal *vol) const; @@ -713,6 +781,9 @@ namespace Cantera { * Returns the vector of nondimensional * enthalpies of the reference state at the current temperature * of the solution and the reference pressure for the species. + * + * @param hrt Output vector containing reference nondimensional enthalpies. + * Length: m_kk. */ virtual void getEnthalpy_RT_ref(doublereal *hrt) const; @@ -720,6 +791,9 @@ namespace Cantera { * Returns the vector of nondimensional * enthalpies of the reference state at the current temperature * of the solution and the reference pressure for the species. + * + * @param grt Output vector containing reference nondimensional Gibbs free energies. + * Length: m_kk. */ virtual void getGibbs_RT_ref(doublereal *grt) const; @@ -728,6 +802,9 @@ namespace Cantera { * gibbs function of the reference state at the current temperature * of the solution and the reference pressure for the species. * units = J/kmol + * + * @param g Output vector containing reference Gibbs free energies. + * Length: m_kk. */ virtual void getGibbs_ref(doublereal *g) const; @@ -735,6 +812,9 @@ namespace Cantera { * Returns the vector of nondimensional * entropies of the reference state at the current temperature * of the solution and the reference pressure for the species. + * + * @param er Output vector containing reference nondimensional entropies. + * Length: m_kk. */ virtual void getEntropy_R_ref(doublereal *er) const; @@ -742,6 +822,9 @@ namespace Cantera { * Returns the vector of nondimensional * internal Energies of the reference state at the current temperature * of the solution and the reference pressure for each species. + * + * @param urt Output vector containing reference nondimensional internal energies. + * Length: m_kk. */ virtual void getIntEnergy_RT_ref(doublereal *urt) const; @@ -750,6 +833,9 @@ namespace Cantera { * constant pressure heat capacities of the reference state * at the current temperature of the solution * and reference pressure for the species. + * + * @param cprt Output vector containing reference nondimensional heat capacities. + * Length: m_kk. */ virtual void getCp_R_ref(doublereal *cprt) const; @@ -912,6 +998,8 @@ namespace Cantera { * Report the molar volume of species k * * units - \f$ m^3 kmol^-1 \f$ + * + * @param k species index */ double speciesMolarVolume(int k) const; @@ -919,6 +1007,9 @@ namespace Cantera { * Fill in a return vector containing the species molar volumes. * * units - \f$ m^3 kmol^-1 \f$ + * + * @param smv output vector containing species molar volumes. + * Length: m_kk. */ void getSpeciesMolarVolumes(doublereal *smv) const; diff --git a/Cantera/src/thermo/MolalityVPSSTP.cpp b/Cantera/src/thermo/MolalityVPSSTP.cpp index fb37c54c8..79bf5ac42 100644 --- a/Cantera/src/thermo/MolalityVPSSTP.cpp +++ b/Cantera/src/thermo/MolalityVPSSTP.cpp @@ -38,7 +38,7 @@ namespace Cantera { { } - /** + /* * Copy Constructor: * * Note this stuff will not work until the underlying phase @@ -87,7 +87,7 @@ namespace Cantera { MolalityVPSSTP::~MolalityVPSSTP() { } - /** + /* * This routine duplicates the current object and returns * a pointer to ThermoPhase. */ @@ -125,7 +125,7 @@ namespace Cantera { return m_indexSolvent; } - /** + /* * Sets the minimum mole fraction in the molality formulation. The * minimum mole fraction must be in the range 0 to 0.9. */ @@ -146,7 +146,7 @@ namespace Cantera { return m_xmolSolventMIN; } - /** + /* * calcMolalities(): * We calculate the vector of molalities of the species * in the phase and store the result internally: @@ -173,7 +173,7 @@ namespace Cantera { } } - /** + /* * getMolalities(): * We calculate the vector of molalities of the species * in the phase @@ -195,7 +195,7 @@ namespace Cantera { } } - /** + /* * setMolalities(): * We are supplied with the molalities of all of the * solute species. We then calculate the mole fractions of all diff --git a/Cantera/src/thermo/MolalityVPSSTP.h b/Cantera/src/thermo/MolalityVPSSTP.h index 700b89db0..20aa89f06 100644 --- a/Cantera/src/thermo/MolalityVPSSTP.h +++ b/Cantera/src/thermo/MolalityVPSSTP.h @@ -40,24 +40,45 @@ namespace Cantera { public: /// Constructors + /*! + * This doesn't do much more than initialize constants with + * default values for water at 25C. Water molecular weight + * comes from the default elements.xml file. It actually + * differs slightly from the IAPWS95 value of 18.015268. However, + * density conservation and therefore element conservation + * is the more important principle to follow. + */ MolalityVPSSTP(); - MolalityVPSSTP(const MolalityVPSSTP &); + + //! Copy constructor + /*! + * Note this stuff will not work until the underlying phase + * has a working copy constructor + * + * @param b class to be copied + */ + MolalityVPSSTP(const MolalityVPSSTP &b); + /// Assignment operator - MolalityVPSSTP& operator=(const MolalityVPSSTP&); + /*! + * Note this stuff will not work until the underlying phase + * has a working assignment operator + * + * @param b class to be copied. + */ + MolalityVPSSTP& operator=(const MolalityVPSSTP&b); /// Destructor. virtual ~MolalityVPSSTP(); - /** - * Duplication routine for objects which inherit from - * ThermoPhase. - * + //! Duplication routine for objects which inherit from ThermoPhase. + /*! * This virtual routine can be used to duplicate thermophase objects * inherited from ThermoPhase even if the application only has * a pointer to ThermoPhase to work with. */ virtual ThermoPhase *duplMyselfAsThermoPhase(); - + /** * * @name Utilities @@ -104,6 +125,8 @@ namespace Cantera { * the solvent mole fraction goes to zero. Numerically, how * this limit is treated and resolved is an ongoing issue within * Cantera. + * + * @param xmolSolventMIN Input double containing the minimum mole fraction */ void setMoleFSolventMin(doublereal xmolSolventMIN); @@ -118,24 +141,82 @@ namespace Cantera { */ doublereal moleFSolventMin() const; - /** - * Calculates the molality of all species and - * stores the result internally. + + //! Calculates the molality of all species andstores the result internally. + /*! + * We calculate the vector of molalities of the species + * in the phase and store the result internally: + * \f[ + * m_i = (n_i) / (1000 * M_o * n_{o,p}) + * \f] + * where + * - \f$ M_o \f$ is the molecular weight of the solvent + * - \f$ n_o \f$ is the mole fraction of the solvent + * - \f$ n_i \f$ is the mole fraction of the solute. + * - \f$ n_{o,p} = max (n_{o, min}, n_o) \f$ + * - \f$ n_{o,min} \f$ = minimum mole fraction of solvent allowed + * in the denominator. */ void calcMolalities() const; - /** - * getMolalities() - * This function will return the molalities of the - * species. + + //! This function will return the molalities of the species. + /*! + * We calculate the vector of molalities of the species + * in the phase + * \f[ + * m_i = (n_i) / (1000 * M_o * n_{o,p}) + * \f] + * where + * - \f$ M_o \f$ is the molecular weight of the solvent + * - \f$ n_o \f$ is the mole fraction of the solvent + * - \f$ n_i \f$ is the mole fraction of the solute. + * - \f$ n_{o,p} = max (n_{o, min}, n_o) \f$ + * - \f$ n_{o,min} \f$ = minimum mole fraction of solvent allowed + * in the denominator. * + * @param molal Output vector of molalities. Length: m_kk. */ void getMolalities(doublereal * const molal) const; - + //! Set the molalities of a phase + /*! + * Set the molalities of the solutes in a phase. Note, the entry for the + * solvent is not used. + * We are supplied with the molalities of all of the + * solute species. We then calculate the mole fractions of all + * species and update the ThermoPhase object. + * + * m_i = (n_i) / (W_o/1000 * n_o_p) + * + * where M_o is the molecular weight of the solvent + * n_o is the mole fraction of the solvent + * n_i is the mole fraction of the solute. + * n_o_p = max (n_o_min, n_o) + * n_o_min = minimum mole fraction of solvent allowed + * in the denominator. + * + * @param molal Input vector of molalities. Length: m_kk. + */ void setMolalities(const doublereal * const molal); + + //! Set the molalities of a phase + /*! + * Set the molalities of the solutes in a phase. Note, the entry for the + * solvent is not used. + * + * @param xMap Composition Map containing the molalities. + */ void setMolalitiesByName(compositionMap& xMap); - void setMolalitiesByName(const std::string &); + + //! Set the molalities of a phase + /*! + * Set the molalities of the solutes in a phase. Note, the entry for the + * solvent is not used. + * + * @param name String containing the information for a composition map. + */ + void setMolalitiesByName(const std::string& name); /** * @} @@ -213,6 +294,8 @@ namespace Cantera { * concentration is species-specific (e.g. surface species of * different sizes), this method may be called with an * optional parameter indicating the species. + * + * @param k species index. Defaults to zero. */ virtual doublereal standardConcentration(int k=0) const { err("standardConcentration"); @@ -222,6 +305,8 @@ namespace Cantera { /** * Returns the natural logarithm of the standard * concentration of the kth species + * + * @param k species index */ virtual doublereal logStandardConc(int k=0) const { err("logStandardConc"); @@ -238,6 +323,7 @@ namespace Cantera { * units are needed. Usually, MKS units are assumed throughout * the program and in the XML input files. * + * @param uA Output vector containing the units * uA[0] = kmol units - default = 1 * uA[1] = m units - default = -nDim(), the number of spatial * dimensions in the Phase class. @@ -245,6 +331,9 @@ namespace Cantera { * uA[3] = Pa(pressure) units - default = 0; * uA[4] = Temperature units - default = 0; * uA[5] = time units - default = 0 + * @param k species index. Defaults to 0. + * @param sizeUA output int containing the size of the vector. + * Currently, this is equal to 6. */ virtual void getUnitsStandardConc(double *uA, int k = 0, int sizeUA = 6); @@ -254,6 +343,8 @@ namespace Cantera { * based for this class and classes that derive from it) at * the current solution temperature, pressure, and * solution concentration. + * + * @param ac Output vector of activities. Length: m_kk. */ virtual void getActivities(doublereal* ac) const { err("getActivities"); @@ -263,10 +354,13 @@ namespace Cantera { * Get the array of non-dimensional activity coefficients at * the current solution temperature, pressure, and * solution concentration. - * These are mole fraction based activity coefficients. In this + * These are mole-fraction based activity coefficients. In this * object, their calculation is based on translating the values - * of Molality based activity coefficients. + * of the molality based activity coefficients. * See Denbigh p. 278 for a thorough discussion + * + * @param ac Output vector containing the mole-fraction based activity coefficients. + * length: m_kk. */ void getActivityCoefficients(doublereal* ac) const; @@ -275,6 +369,9 @@ namespace Cantera { * activity coefficients at the current solution temperature, * pressure, and solution concentration. * See Denbigh p. 278 for a thorough discussion + * + * @param acMolality Output vector containing the molality based activity coefficients. + * length: m_kk. */ virtual void getMolalityActivityCoefficients(doublereal *acMolality) const { @@ -299,6 +396,9 @@ namespace Cantera { * to each chemical potential. * * Units: J/kmol + * + * @param mu output vector containing the species electrochemical potentials. + * Length: m_kk. */ void getElectrochemPotentials(doublereal* mu) const { getChemPotentials(mu); @@ -360,6 +460,9 @@ namespace Cantera { * \f$ \lambda_m \f$ is the element potential of element m. The * temperature is unchanged. Any phase (ideal or not) that * implements this method can be equilibrated by ChemEquil. + * + * @param lambda_RT Input vector containing the dimensionless + * element potentials. */ virtual void setToEquilState(const doublereal* lambda_RT) { err("setToEquilState"); @@ -387,7 +490,7 @@ namespace Cantera { * to everything else. * * @param state An XML_Node object corresponding to - * the "state" entry for this phase in the input file. + * the "state" entry for this phase in the input file. * */ virtual void setStateFromXML(const XML_Node& state); @@ -430,17 +533,33 @@ namespace Cantera { */ void initThermoXML(XML_Node& phaseNode, std::string id); - /** - * Set the temperature (K), pressure (Pa), and molalities - * (gmol kg-1) of the solutes + + //! Set the temperature (K), pressure (Pa), and molalities + //!(gmol kg-1) of the solutes + /*! + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param molalities Input vector of molalities of the solutes. + * Length: m_kk. */ void setState_TPM(doublereal t, doublereal p, const doublereal * const molalities); - /** Set the temperature (K), pressure (Pa), and molalities. */ + //! Set the temperature (K), pressure (Pa), and molalities. + /*! + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param m compositionMap containing the molalities + */ void setState_TPM(doublereal t, doublereal p, compositionMap& m); - /** Set the temperature (K), pressure (Pa), and molalities. */ + //! Set the temperature (K), pressure (Pa), and molalities. + /*! + * @param t Temperature (K) + * @param p Pressure (Pa) + * @param m String which gets translated into a composition + * map for the molalities of the solutes. + */ void setState_TPM(doublereal t, doublereal p, const std::string& m); private: diff --git a/Cantera/src/thermo/VPStandardStateTP.h b/Cantera/src/thermo/VPStandardStateTP.h index 41ba1b957..586a21233 100644 --- a/Cantera/src/thermo/VPStandardStateTP.h +++ b/Cantera/src/thermo/VPStandardStateTP.h @@ -143,6 +143,7 @@ namespace Cantera { * units are needed. Usually, MKS units are assumed throughout * the program and in the XML input files. * + * @param uA Output vector containing the units * uA[0] = kmol units - default = 1 * uA[1] = m units - default = -nDim(), the number of spatial * dimensions in the Phase class. @@ -150,6 +151,9 @@ namespace Cantera { * uA[3] = Pa(pressure) units - default = 0; * uA[4] = Temperature units - default = 0; * uA[5] = time units - default = 0 + * @param k species index. Defaults to 0. + * @param sizeUA output int containing the size of the vector. + * Currently, this is equal to 6. */ virtual void getUnitsStandardConc(double *uA, int k = 0, int sizeUA = 6); @@ -166,6 +170,9 @@ namespace Cantera { * * We close the loop on this function, here, calling * getChemPotentials() and then dividing by RT. + * + * @param mu Output vector of non-dimensional species chemical potentials + * Length: m_kk. */ virtual void getChemPotentials_RT(doublereal* mu) const; @@ -183,12 +190,14 @@ namespace Cantera { * Therefore, we will bring the error routines up to this object */ - /** - * Get the array of chemical potentials at unit activity. - * These - * are the standard state chemical potentials \f$ \mu^0_k(T,P) - * \f$.. The values are evaluated at the current - * temperature and pressure. + + //!Get the array of chemical potentials at unit activity. + /*! + * These are the standard state chemical potentials \f$ \mu^0_k(T,P) + * \f$. The values are evaluated at the current temperature and pressure. + * + * @param mu Output vector of standard state chemical potentials. + * length = m_kk. units are J / kmol. */ virtual void getStandardChemPotentials(doublereal* mu) const { err("getStandardChemPotentials"); @@ -198,6 +207,9 @@ namespace Cantera { * Get the nondimensional Enthalpy functions for the species * at their standard states at the current * T and P of the solution. + * + * @param hrt Output vector of standard state enthalpies. + * length = m_kk. units are unitless. */ virtual void getEnthalpy_RT(doublereal* hrt) const { err("getEnthalpy_RT"); @@ -207,6 +219,9 @@ namespace Cantera { * Get the array of nondimensional Enthalpy functions for the * standard state species * at the current T and P of the solution. + * + * @param sr Output vector of nondimensional standard state + * entropies. length = m_kk. */ virtual void getEntropy_R(doublereal* sr) const { err("getEntropy_R"); @@ -216,6 +231,9 @@ namespace Cantera { * Get the nondimensional Gibbs functions for the species * at their standard states of solution at the current T and P * of the solution. + * + * @param grt Output vector of nondimensional standard state + * Gibbs free energies. length = m_kk. */ virtual void getGibbs_RT(doublereal* grt) const { err("getGibbs_RT"); @@ -224,6 +242,10 @@ namespace Cantera { /** * Get the nondimensional Gibbs functions for the standard * state of the species at the current T and P. + * + * @param gpure Output vector of standard state + * Gibbs free energies. length = m_kk. + * units are J/kmol. */ virtual void getPureGibbs(doublereal* gpure) const { err("getPureGibbs"); @@ -233,6 +255,9 @@ namespace Cantera { * Returns the vector of nondimensional * internal Energies of the standard state at the current temperature * and pressure of the solution for each species. + * + * @param urt Output vector of nondimensional standard state + * internal energies. length = m_kk. */ virtual void getIntEnergy_RT(doublereal *urt) const { err("getIntEnergy_RT"); @@ -242,6 +267,11 @@ namespace Cantera { * Get the nondimensional Heat Capacities at constant * pressure for the standard state of the species * at the current T and P. + * + * @param cpr Output vector containing the + * the nondimensional Heat Capacities at constant + * pressure for the standard state of the species. + * Length: m_kk. */ virtual void getCp_R(doublereal* cpr) const { err("getCp_R"); @@ -252,6 +282,9 @@ namespace Cantera { * states at the current * T and P of the solution. * units = m^3 / kmol + * + * @param vol Output vector of species volumes. length = m_kk. + * units = m^3 / kmol */ virtual void getStandardVolumes(doublereal *vol) const { err("getStandardVolumes"); @@ -261,32 +294,48 @@ namespace Cantera { /// @name Thermodynamic Values for the Species Reference States -------------------- //@{ - /** + /*! * Returns the vector of nondimensional * enthalpies of the reference state at the current temperature * of the solution and the reference pressure for the species. + * + * @param hrt Output vector contains the nondimensional enthalpies + * of the reference state of the species + * length = m_kk, units = dimensionless. */ virtual void getEnthalpy_RT_ref(doublereal *hrt) const; - /** + /*! * Returns the vector of nondimensional - * enthalpies of the reference state at the current temperature + * Gibbs free energies of the reference state at the current temperature * of the solution and the reference pressure for the species. + * + * @param grt Output vector contains the nondimensional Gibbs free energies + * of the reference state of the species + * length = m_kk, units = dimensionless. */ virtual void getGibbs_RT_ref(doublereal *grt) const; - /** + /*! * Returns the vector of the * gibbs function of the reference state at the current temperature * of the solution and the reference pressure for the species. * units = J/kmol + * + * @param g Output vector contain the Gibbs free energies + * of the reference state of the species + * length = m_kk, units = J/kmol. */ virtual void getGibbs_ref(doublereal *g) const; - /** + /*! * Returns the vector of nondimensional * entropies of the reference state at the current temperature * of the solution and the reference pressure for the species. + * + * @param er Output vector contain the nondimensional entropies + * of the species in their reference states + * length: m_kk, units: dimensionless. */ virtual void getEntropy_R_ref(doublereal *er) const; @@ -295,6 +344,10 @@ namespace Cantera { * constant pressure heat capacities of the reference state * at the current temperature of the solution * and reference pressure for the species. + * + * @param cprt Output vector contains the nondimensional heat capacities + * of the species in their reference states + * length: m_kk, units: dimensionless. */ virtual void getCp_R_ref(doublereal *cprt) const; @@ -339,7 +392,7 @@ namespace Cantera { * model. * * @param eosdata An XML_Node object corresponding to - * the "thermo" entry for this phase in the input file. + * the "thermo" entry for this phase in the input file. */ virtual void setParametersFromXML(const XML_Node& eosdata) {} diff --git a/Cantera/src/units.h b/Cantera/src/units.h index 91b525615..a418c30e0 100644 --- a/Cantera/src/units.h +++ b/Cantera/src/units.h @@ -55,6 +55,8 @@ namespace Cantera { * The list of recognized units is storred as a stl map * called m_u[] and m_act_u for activity * coefficients. These maps are initialized with likely values. + * + * @param units String containing the units description */ doublereal toSI(std::string units) { diff --git a/Cantera/src/utilities.h b/Cantera/src/utilities.h index bca8cbbf1..b58b91df4 100755 --- a/Cantera/src/utilities.h +++ b/Cantera/src/utilities.h @@ -23,263 +23,524 @@ namespace Cantera { */ //@{ - /** - * Maximum of i and j. If \a i and \a j have different types, \a j - * is converted to the type of \a i before the comparison. - */ - template - inline T max(T i, S j) { - return (i > T(j) ? i : T(j)); - } - - /** - * Minimum of i and j. If \a i and \a j have different types, \a j - * is converted to the type of \a i before the comparison. - */ - template - inline T min(T i, S j) { - return (i < T(j) ? i : T(j)); - } - - /** - * Inner product of two vectors of length 4. - * If either \a x - * or \a y has length greater than 4, only the first 4 elements - * will be used. - */ - template - inline doublereal dot4(const V& x, const V& y) { - return x[0]*y[0] + x[1]*y[1] + x[2]*y[2] + x[3]*y[3]; - } - - /** - * Inner product of two vectors of length 5. - * If either \a x - * or \a y has length greater than 5, only the first 5 elements - * will be used. - */ - template - inline doublereal dot5(const V& x, const V& y) { - return x[0]*y[0] + x[1]*y[1] + x[2]*y[2] + x[3]*y[3] + - x[4]*y[4]; - } - - /** - * Inner product of two vectors of length 6. - * If either \a x - * or \a y has length greater than 6, only the first 6 elements - * will be used. - */ - template - inline doublereal dot6(const V& x, const V& y) { - return x[0]*y[0] + x[1]*y[1] + x[2]*y[2] + x[3]*y[3] + - x[4]*y[4] + x[5]*y[5]; - } - - /** - * Inner product. - */ - template - inline doublereal dot(InputIter x_begin, InputIter x_end, - InputIter2 y_begin) { - doublereal sum = 0.0; - for(; x_begin != x_end; ++x_begin, ++y_begin) - sum += *x_begin * *y_begin; - return sum; - } - - /** - * Multiply elements of an array by a scale factor. - * \code - * vector_fp in(8, 1.0), out(8); - * scale(in.begin(), in.end(), out.begin(), factor); - * \endcode - */ - template - inline void scale(InputIter begin, InputIter end, - OutputIter out, S scale_factor) { - for (; begin != end; ++begin, ++out) - *out = scale_factor * *begin; - } - - /*! - * Multiply elements of an array, y, by a scale factor, f and add the - * result to an existing array, x. This is essentially a templated daxpy_ - * operation. - * @code - * for (i = 0; i < n; i++) { - * x[i] += f * [i] - * } - * @endcode - * - * It is templated with three parameters. The first template - * is the iterator, InputIter, which controls access to y[]. - * The second template is the iterator OutputIter, which controls - * access to y[]. The third iterator is S, which is f. - * - * @param begin InputIter Iterator for beginning of y[] - * @param end inputIter Iterator for end of y[] - * @param out OutputIter Iterator for beginning of x[] - * @param scale_factor Scale Factor to multiply y[i] by - */ - template - inline void increment_scale(InputIter begin, InputIter end, - OutputIter out, S scale_factor) { - for (; begin != end; ++begin, ++out) - *out += scale_factor * *begin; - } - - /** - * Multiply each entry in x by the corresponding entry in y. - */ - template - inline void multiply_each(OutputIter x_begin, OutputIter x_end, - InputIter y_begin) { - for(; x_begin != x_end; ++x_begin, ++y_begin) *x_begin *= *y_begin; - } - - - /** - * Invoke method 'resize' with argument \a m for a sequence of objects. - */ - template - inline void resize_each(int m, InputIter begin, InputIter end) { - for(; begin != end; ++begin) begin->resize(m); - } - - /** - * The maximum absolute value. - */ - template - inline doublereal absmax(InputIter begin, InputIter end) { - doublereal amax = 0.0; - for(; begin != end; ++begin) - if (fabs(*begin) > amax) amax = fabs(*begin); - return amax; - } - - /** - * Normalize the values in a sequence, such that they sum to 1.0. - */ - template - inline void normalize(InputIter begin, InputIter end, - OutputIter out) { - doublereal sum = accumulate(begin, end, 0.0); - for (; begin != end; ++begin, ++out) *out = *begin/sum; - } - - /** - * Divide each element of \a x by the corresponding element of \a y. - */ - template - inline void divide_each(OutputIter x_begin, OutputIter x_end, - InputIter y_begin) { - for(; x_begin != x_end; ++x_begin, ++y_begin) *x_begin /= *y_begin; - } - - /** - * Increment each entry in \a x by the corresponding entry in \a y. - */ - template - inline void sum_each(OutputIter x_begin, OutputIter x_end, - InputIter y_begin) { - for(; x_begin != x_end; ++x_begin, ++y_begin) *x_begin += *y_begin; - } - - /** Copies a contiguous range in a sequence to indexed - * positions in another sequence. Example: - * - * \code - * vector x(3), y(20), ; - * vector index(3); - * index[0] = 9; - * index[1] = 2; - * index[3] = 16; - * scatter_copy(x.begin(), x.end(), y.begin(), index.begin()); - * \endcode - */ - template - inline void scatter_copy(InputIter begin, InputIter end, - OutputIter result, IndexIter index) { - for (; begin != end; ++begin, ++index) { - *(result + *index) = *begin; - } - } - - /** - * Multiply selected elements in an array by a contiguous - * sequence of multipliers. - * Example: - * \code - * double multipliers[] = {8.9, -2.0, 5.6}; - * int index[] = {7, 4, 13}; - * vector_fp data(20); - * ... - * // multiply elements 7, 4, and 13 in data by multipliers - * scatter_mult(multipliers, multipliers + 3, data.begin(), - * index); - * \endcode - */ - template - inline void scatter_mult(InputIter mult_begin, InputIter mult_end, - RandAccessIter data, IndexIter index) { - for (; mult_begin != mult_end; ++mult_begin, ++index) { - *(data + *index) *= *mult_begin; - } - } + //! Maximum of two templated quantities, i and j. + /*! + * If \a i and \a j have different types, \a j + * is converted to the type of \a i before the comparison. + * + * @param i first argument, instance of templated class T + * @param j Second argument, instance of templated class S + * @return + * This function returns the maximum of the two values + * as an instance of templated type T. + */ + template + inline T max(T i, S j) { + return (i > T(j) ? i : T(j)); + } - /** - * Divide selected elements in an array by a contiguous - * sequence of divisors. - * Example: - * \code - * double divisors[] = {8.9, -2.0, 5.6}; - * int index[] = {7, 4, 13}; - * vector_fp data(20); - * ... - * // divide elements 7, 4, and 13 in data by divisors - * scatter_divide(divisors, divisors + 3, data.begin(), - * index); - * \endcode - */ - template - inline void scatter_divide(InputIter begin, InputIter end, - OutputIter result, IndexIter index) { - for (; begin != end; ++begin, ++index) { - *(result + *index) /= *begin; - } - } + //! Minimum of two templated quantities, i and j. + /*! + * If \a i and \a j have different types, \a j + * is converted to the type of \a i before the comparison. + * + * @param i first argument, instance of templated class T + * @param j Second argument, instance of templated class S + * @return + * This function returns the minimum of the two values + * as an instance of templated type T. + */ + template + inline T min(T i, S j) { + return (i < T(j) ? i : T(j)); + } - /** - * Compute \f[ \sum_k x_k \log x_k. \f]. A small number (1.0E-20) - * is added before taking the log. - */ - template - inline doublereal sum_xlogx(InputIter begin, InputIter end) { - doublereal sum = 0.0; - for (; begin != end; ++begin) { - sum += (*begin) * std::log(*begin + Tiny); - } - return sum; - } + + //! Tempalted Inner product of two vectors of length 4. + /*! + * If either \a x + * or \a y has length greater than 4, only the first 4 elements + * will be used. + * + * @param x first reference to the templated class V + * @param y second reference to the templated class V + * @return + * This class returns a hard-coded type, doublereal. + */ + template + inline doublereal dot4(const V& x, const V& y) { + return x[0]*y[0] + x[1]*y[1] + x[2]*y[2] + x[3]*y[3]; + } + + + //! Tempalted Inner product of two vectors of length 5 + /*! + * If either \a x + * or \a y has length greater than 4, only the first 4 elements + * will be used. + * + * @param x first reference to the templated class V + * @param y second reference to the templated class V + * @return + * This class returns a hard-coded type, doublereal. + */ + template + inline doublereal dot5(const V& x, const V& y) { + return x[0]*y[0] + x[1]*y[1] + x[2]*y[2] + x[3]*y[3] + + x[4]*y[4]; + } + + //! Tempalted Inner product of two vectors of length 6 + /*! + * If either \a x + * or \a y has length greater than 4, only the first 4 elements + * will be used. + * + * @param x first reference to the templated class V + * @param y second reference to the templated class V + * @return + * This class returns a hard-coded type, doublereal. + */ + template + inline doublereal dot6(const V& x, const V& y) { + return x[0]*y[0] + x[1]*y[1] + x[2]*y[2] + x[3]*y[3] + + x[4]*y[4] + x[5]*y[5]; + } + + //! Function that calculates a templated inner product. + /*! + * This inner product is templated twice. The output variable is hard coded + * to return a doublereal. + * + * template + * + * @code + * double x[8], y[8]; + * doublereal dsum = dot(x, &x+7, y); + * @endcode + * + * @param x_begin Iterator pointing to the beginning, belonging to the + * iterator class InputIter. + * @param x_end Iterator pointing to the end, belonging to the + * iterator class InputIter. + * @param y_begin Iterator pointing to the beginning of y, belonging to the + * iterator class InputIter2. + * @return + * The return is hard-coded to return a double. + */ + template + inline doublereal dot(InputIter x_begin, InputIter x_end, + InputIter2 y_begin) { + doublereal sum = 0.0; + for(; x_begin != x_end; ++x_begin, ++y_begin) + sum += *x_begin * *y_begin; + return sum; + } + + //! Multiply elements of an array by a scale factor. + /*! + * \code + * vector_fp in(8, 1.0), out(8); + * scale(in.begin(), in.end(), out.begin(), factor); + * \endcode + * + * @param begin Iterator pointing to the beginning, belonging to the + * iterator class InputIter. + * @param end Iterator pointing to the end, belonging to the + * iterator class InputIter. + * @param out Iterator pointing to the beginning of out, belonging to the + * iterator class OutputIter. This is the output variable + * for this routine. + * @param scale_factor input scale factor belonging to the class S. + */ + template + inline void scale(InputIter begin, InputIter end, + OutputIter out, S scale_factor) { + for (; begin != end; ++begin, ++out) + *out = scale_factor * *begin; + } + + /*! + * Multiply elements of an array, y, by a scale factor, f and add the + * result to an existing array, x. This is essentially a templated daxpy_ + * operation. + * + * The template arguments are: template + * + * Simple Code Example of the functionality; + * @code + * double x[10], y[10], f; + * for (i = 0; i < n; i++) { + * y[i] += f * x[i] + * } + * @endcode + * Example of the function call to implement the simple code example + * @code + * double x[10], y[10], f; + * increment_scale(x, x+10, y, f); + * @endcode + * + * It is templated with three parameters. The first template + * is the iterator, InputIter, which controls access to y[]. + * The second template is the iterator OutputIter, which controls + * access to y[]. The third iterator is S, which is f. + * + * @param begin InputIter Iterator for beginning of y[] + * @param end inputIter Iterator for end of y[] + * @param out OutputIter Iterator for beginning of x[] + * @param scale_factor Scale Factor to multiply y[i] by + */ + template + inline void increment_scale(InputIter begin, InputIter end, + OutputIter out, S scale_factor) { + for (; begin != end; ++begin, ++out) + *out += scale_factor * *begin; + } + + + //! Multiply each entry in x by the corresponding entry in y. + /*! + * The template arguments are: template + * + * Simple code Equivalent: + * \code + * double x[10], y[10] + * for (n = 0; n < 10; n++) { + * x[n] *= y[n]; + * } + * \endcode + * Example of function call usage to implement the simple code example: + * \code + * double x[10], y[10] + * multiply_each(x, x+10, y); + * \endcode + * + * @param x_begin Iterator pointing to the beginning of the vector x, belonging to the + * iterator class InputIter. + * @param x_end Iterator pointing to the end of the vector x, belonging to the + * iterator class InputIter. The difference between end and begin + * determines the loop length + * @param y_begin Iterator pointing to the beginning of the vector y, belonging to the + * iterator class outputIter. + */ + template + inline void multiply_each(OutputIter x_begin, OutputIter x_end, + InputIter y_begin) { + for(; x_begin != x_end; ++x_begin, ++y_begin) *x_begin *= *y_begin; + } - /** - * Compute \f[ \sum_k x_k \log Q_k. \f]. A small number (1.0E-20) - * is added before taking the log. - */ - template - inline doublereal sum_xlogQ(InputIter1 begin, InputIter1 end, - InputIter2 Q_begin) { - doublereal sum = 0.0; - for (; begin != end; ++begin, ++Q_begin) { - sum += (*begin) * std::log(*Q_begin + Tiny); - } - return sum; + //! Invoke method 'resize' with argument \a m for a sequence of objects (templated version) + /*! + * The template arguments are: template + * + * Simple code Equivalent: + * \code + * vector *> VV; + * for (n = 0; n < 20; n++) { + * vector *vp = VV[n]; + * vp->resize(m); + * } + * \endcode + * Example of function call usage to implement the simple code example: + * \code + * vector *> VV; + * resize_each(m, &VV[0], &VV[20]); + * \endcode + * + * @param m Integer specifying the size that each object should be resized to. + * @param begin Iterator pointing to the beginning of the sequence of object, belonging to the + * iterator class InputIter. + * @param end Iterator pointing to the end of the sequence of objects, belonging to the + * iterator class InputIter. The difference between end and begin + * determines the loop length + * + * @note This is currently unused. + */ + template + inline void resize_each(int m, InputIter begin, InputIter end) { + for(; begin != end; ++begin) begin->resize(m); + } + + //! The maximum absolute value (templated version) + /*! + * The template arguments are: template + * + * Simple code Equivalent: + * \code + * double x[10] amax = 0.0; + * for (int n = 0; n < 10; n++) { + * if (fabs(x[n]) > amax) amax = fabs(x[10]); + * } + * return amax; + * \endcode + * Example of function call usage to implement the simple code example: + * \code + * double x[10] + * double amax = absmax(x, x+10); + * \endcode + * + * @param begin Iterator pointing to the beginning of the x vector, belonging to the + * iterator class InputIter. + * @param end Iterator pointing to the end of the x vector, belonging to the + * iterator class InputIter. The difference between end and begin + * determines the loop length + */ + template + inline doublereal absmax(InputIter begin, InputIter end) { + doublereal amax = 0.0; + for(; begin != end; ++begin) + if (fabs(*begin) > amax) amax = fabs(*begin); + return amax; + } + + //! Normalize the values in a sequence, such that they sum to 1.0 (templated version) + /*! + * The template arguments are: template + * + * Simple Equivalent: + * \code + * double x[10], y[10], sum = 0.0; + * for (int n = 0; n < 10; n++) { + * sum += x[10]; + * } + * for (int n = 0; n < 10; n++) { + * y[n] = x[n]/sum; + * } + * \endcode + * Example of function call usage: + * \code + * double x[10], y[10]; + * normalize(x, x+10, y); + * \endcode + * + * @param begin Iterator pointing to the beginning of the x vector, belonging to the + * iterator class InputIter. + * @param end Iterator pointing to the end of the x vector, belonging to the + * iterator class InputIter. The difference between end and begin + * determines the loop length + * @param out Iterator pointing to the beginning of the output vector, belonging to the + * iterator class OutputIter. + */ + template + inline void normalize(InputIter begin, InputIter end, + OutputIter out) { + doublereal sum = accumulate(begin, end, 0.0); + for (; begin != end; ++begin, ++out) *out = *begin/sum; + } + + //! Templated divide of each element of \a x by the corresponding element of \a y. + /*! + * The template arguments are: template + * + * Simple Equivalent: + * \code + * double x[10], y[10]; + * for (n = 0; n < 10; n++) { + * x[n] /= y[n]; + * } + * \endcode + * Example of code usage: + * \code + * double x[10], y[10]; + * divide_each(x, x+10, y); + * \endcode + * + * @param x_begin Iterator pointing to the beginning of the x vector, belonging to the + * iterator class OutputIter. + * @param x_end Iterator pointing to the end of the x vector, belonging to the + * iterator class OutputIter. The difference between end and begin + * determines the number of inner iterations. + * @param y_begin Iterator pointing to the beginning of the yvector, belonging to the + * iterator class InputIter. + */ + template + inline void divide_each(OutputIter x_begin, OutputIter x_end, + InputIter y_begin) { + for(; x_begin != x_end; ++x_begin, ++y_begin) *x_begin /= *y_begin; + } + + //! Increment each entry in \a x by the corresponding entry in \a y. + /*! + * The template arguments are: template + * + * @param x_begin Iterator pointing to the beginning of the x vector, belonging to the + * iterator class OutputIter. + * @param x_end Iterator pointing to the end of the x vector, belonging to the + * iterator class OutputIter. The difference between end and begin + * determines the number of inner iterations. + * @param y_begin Iterator pointing to the beginning of the yvector, belonging to the + * iterator class InputIter. + */ + template + inline void sum_each(OutputIter x_begin, OutputIter x_end, + InputIter y_begin) { + for(; x_begin != x_end; ++x_begin, ++y_begin) *x_begin += *y_begin; + } + + //! Copies a contiguous range in a sequence to indexed + //! positions in another sequence. + /*! + * The template arguments are: template + * + * Example: + * + * \code + * vector x(3), y(20), ; + * vector index(3); + * index[0] = 9; + * index[1] = 2; + * index[3] = 16; + * scatter_copy(x.begin(), x.end(), y.begin(), index.begin()); + * \endcode + * + * This routine is templated 3 times. + * InputIter is an iterator for the source vector + * OutputIter is an iterator for the destination vector + * IndexIter is an iterator for the index into the destination vector. + * + * @param begin Iterator pointing to the beginning of the source vector, belonging to the + * iterator class InputIter. + * @param end Iterator pointing to the end of the source vector, belonging to the + * iterator class InputIter. The difference between end and begin + * determines the number of inner iterations. + * @param result Iterator pointing to the beginning of the output vector, belonging to the + * iterator class outputIter. + * @param index Iterator pointing to the beginning of the index vector, belonging to the + * iterator class IndexIter. + */ + template + inline void scatter_copy(InputIter begin, InputIter end, + OutputIter result, IndexIter index) { + for (; begin != end; ++begin, ++index) { + *(result + *index) = *begin; } + } + + + //! Multiply selected elements in an array by a contiguous + //! sequence of multipliers. + /*! + * The template arguments are: template + * + * Example: + * \code + * double multipliers[] = {8.9, -2.0, 5.6}; + * int index[] = {7, 4, 13}; + * vector_fp data(20); + * ... + * // Multiply elements 7, 4, and 13 in data by multipliers[0], multipliers[1],and multipliers[2], + * // respectively + * scatter_mult(multipliers, multipliers + 3, data.begin(), index); + * \endcode + * + * @param mult_begin Iterator pointing to the beginning of the multiplier vector, belonging to the + * iterator class InputIter. + * @param mult_end Iterator pointing to the end of the multiplier vector, belonging to the + * iterator class InputIter. The difference between end and begin + * determines the number of inner iterations. + * @param data Iterator pointing to the beginning of the output vector, belonging to the + * iterator class RandAccessIter, that will be selectively multipied. + * @param index Iterator pointing to the beginning of the index vector, belonging to the + * iterator class IndexIter. + */ + template + inline void scatter_mult(InputIter mult_begin, InputIter mult_end, + RandAccessIter data, IndexIter index) { + for (; mult_begin != mult_end; ++mult_begin, ++index) { + *(data + *index) *= *mult_begin; + } + } + + + //! Divide selected elements in an array by a contiguous sequence of divisors. + /*! + * The template arguments are: template + * + * Example: + * \code + * double divisors[] = {8.9, -2.0, 5.6}; + * int index[] = {7, 4, 13}; + * vector_fp data(20); + * ... + * // divide elements 7, 4, and 13 in data by divisors[7] divisors[4], and divisors[13] + * // respectively + * scatter_divide(divisors, divisors + 3, data.begin(), index); + * \endcode + * + * @param begin Iterator pointing to the beginning of the source vector, belonging to the + * iterator class InputIter. + * @param end Iterator pointing to the end of the source vector, belonging to the + * iterator class InputIter. The difference between end and begin + * determines the number of inner iterations. + * @param result Iterator pointing to the beginning of the output vector, belonging to the + * iterator class outputIter. + * @param index Iterator pointing to the beginning of the index vector, belonging to the + * iterator class IndexIter. + */ + template + inline void scatter_divide(InputIter begin, InputIter end, + OutputIter result, IndexIter index) { + for (; begin != end; ++begin, ++index) { + *(result + *index) /= *begin; + } + } + + //! Compute \f[ \sum_k x_k \log x_k. \f]. + /*! + * The template arguments are: template + * + * A small number (1.0E-20) is added before taking the log. This templated + * class does the indicated sun. The template must be an iterator. + * + * @param begin Iterator pointing to the beginning, belonging to the + * iterator class InputIter. + * @param end Iterator pointing to the end, belonging to the + * iterator class InputIter. + * @return + * The return from this class is a double. + */ + template + inline doublereal sum_xlogx(InputIter begin, InputIter end) { + doublereal sum = 0.0; + for (; begin != end; ++begin) { + sum += (*begin) * std::log(*begin + Tiny); + } + return sum; + } + + //! Compute \f[ \sum_k x_k \log Q_k. \f]. + /*! + * The template arguments are: template + * + * This class is templated twice. The first template, InputIter1 + * is the iterator that points to $x_k$. The second iterator + * InputIter2, point to $Q_k$. + * A small number (1.0E-20) is added before taking the log. + * + * @param begin Iterator pointing to the beginning, belonging to the + * iterator class InputIter1. + * @param end Iterator pointing to the end, belonging to the + * iterator class InputIter1. + * @param Q_begin Iterator pointing to the beginning of Q_k, belonging to the + * iterator class InputIter2. + * @return + * The return from this class is hard coded to a doublereal. + */ + template + inline doublereal sum_xlogQ(InputIter1 begin, InputIter1 end, + InputIter2 Q_begin) { + doublereal sum = 0.0; + for (; begin != end; ++begin, ++Q_begin) { + sum += (*begin) * std::log(*Q_begin + Tiny); + } + return sum; + } //! scale a templated vector by a constant factor. /*! + * The template arguments are: template + * * This function is essentially a wrapper around the stl * function %scale(). The function is has one template * parameter, OutputIter. OutputIter is a templated iterator @@ -290,15 +551,15 @@ namespace Cantera { * @param x Templated Iterator to the start of the vector * to be scaled. */ - template - inline void scale(int N, double alpha, OutputIter x) { - //#ifdef DARWINNNN - //cblas_dscal(N, alpha, x, 1); - //#else - scale(x, x+N, x, alpha); - //#endif - } - + template + inline void scale(int N, double alpha, OutputIter x) { + //#ifdef DARWINNNN + //cblas_dscal(N, alpha, x, 1); + //#else + scale(x, x+N, x, alpha); + //#endif + } + //@} } diff --git a/tools/doc/Cantera.cfg.in b/tools/doc/Cantera.cfg.in index 5f2ec1392..e4d723f93 100755 --- a/tools/doc/Cantera.cfg.in +++ b/tools/doc/Cantera.cfg.in @@ -75,7 +75,7 @@ QUIET = NO WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO +WARN_NO_PARAMDOC = YES WARN_FORMAT = "$file:$line: $text" WARN_LOGFILE = #--------------------------------------------------------------------------- @@ -85,8 +85,7 @@ INPUT = ../../Cantera/src \ ../../Cantera/src/thermo \ ../../Cantera/cxx/include \ doxyinput -FILE_PATTERNS = Kinetics.h \ - Kinetics.cpp \ +FILE_PATTERNS = Kinetics.h Kinetics.cpp \ misc.cpp \ ct_defs.h \ logger.h \ @@ -95,11 +94,11 @@ FILE_PATTERNS = Kinetics.h \ ctexceptions.h \ *.txt \ equilibrium.h \ - ThermoPhase.h \ - ThermoPhase.cpp \ - State.h \ - Constituents.h \ - Phase.h \ + ThermoPhase.h ThermoPhase.cpp \ + Phase.h Phase.cpp \ + State.h State.cpp \ + Constituents.h Constituents.cpp \ + Elements.h Elements.cpp \ utilities.h \ VPStandardStateTP.h VPStandardStateTP.cpp \ MolalityVPSSTP.h MolalityVPSSTP.cpp \