diff --git a/Cantera/src/Elements.h b/Cantera/src/Elements.h
index a83fdbfdd..9cf2381c4 100644
--- a/Cantera/src/Elements.h
+++ b/Cantera/src/Elements.h
@@ -1,11 +1,3 @@
-/***********************************************************************
- * $RCSfile$
- * $Author$
- * $Date$
- * $Revision$
- ***********************************************************************/
-// Copyright 2001 California Institute of Technology
-
/**
* @file Elements.h
* Header file for class, Elements, which contains the elements that
@@ -13,6 +5,13 @@
*
* This file contains the declarations for the elements class.
*/
+/***********************************************************************
+ * $RCSfile$
+ * $Author$
+ * $Date$
+ * $Revision$
+ ***********************************************************************/
+// Copyright 2001 California Institute of Technology
#ifndef CT_ELEMENTS_H
#define CT_ELEMENTS_H
@@ -27,21 +26,21 @@ namespace Cantera {
class XML_Node;
class ElementRangeError;
- /*!
- * 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
- * employing Multiple phases. In this case, a single Elements object may
- * be shared by more than one Constituents class. Reactions between
- * the phases may then be described using stoichiometry base on the
- * same Elements class object.
- *
- * The member functions return information about the elements described
- * in a particular instantiation of the class.
- *
- * @ingroup phases
- */
+
+ //! Object containing the elements that make up species in a phase.
+ /*!
+ * Class %Elements manages the elements that are part of a
+ * chemistry specification. This class may support calculations
+ * employing Multiple phases. In this case, a single Elements object may
+ * be shared by more than one Constituents class. Reactions between
+ * the phases may then be described using stoichiometry base on the
+ * same Elements class object.
+ *
+ * The member functions return information about the elements described
+ * in a particular instantiation of the class.
+ *
+ * @ingroup phases
+ */
class Elements {
public:
diff --git a/Cantera/src/Phase.h b/Cantera/src/Phase.h
index c59281c8c..94b30fdb2 100755
--- a/Cantera/src/Phase.h
+++ b/Cantera/src/Phase.h
@@ -24,20 +24,122 @@ using namespace ctml;
namespace Cantera {
- /**
- * @defgroup phases Phases of Matter
- *
- * These classes are used to represent phases of matter.
- */
+ /**
+ * @defgroup phases Phases of Matter
+ *
+ * These classes are used to represent the composition and state of a
+ * single phase of matter.
+ * Together these classes form the basis for describing the species and
+ * element compositions of a phase as well as the stoichiometry
+ * of each species, and for describing the current state of the
+ * phase. They do not in themselves contain Thermodynamic equation of
+ * state information. However, they do comprise all of the necessary
+ * background functionality to support thermodynamic calculations, and the
+ * class ThermoPhase inherits from the class Phase (see \ref thermoprops).
+ *
+ * Class Elements manages the elements that are part of a
+ * chemistry specification for a phase. This class may support calculations
+ * employing Multiple phases. In this case, a single Elements object may
+ * be shared by more than one Constituents class. Reactions between
+ * the phases may then be described using stoichiometry base on the
+ * same Elements class object.
+ *
+ * The member functions of class %Elements return information about the elements described
+ * in a particular instantiation of the class.
+ *
+ * Class %Constituents is designed to provide information
+ * about the elements and species in a phase - names, index
+ * numbers (location in arrays), atomic or molecular weights,
+ * etc. No computations are performed by the methods of this
+ * class. The set of elements must include all those that compose
+ * the species, but may include additional elements.
+ *
+ * %Constituents contains a pointer to the Elements object, and
+ * it contains wrapper functions for all of the functionality
+ * of the %Elements object, i.e., atomic weights, number and identity
+ * of the elements. %Elements may be added to a phase by using
+ * the function Constituents::addUniqueElement(). The %Elements
+ * object may be shared amongst different Phases.
+ *
+ * %Constituents also contains utilities retrieving the index of
+ * a species in the phase given its name, Constituents::speciesIndex().
+ *
+ * Class State manages the independent variables of temperature, mass density,
+ * and species mass/mole fraction that define the thermodynamic
+ * state.
+ *
+ * Class %State stores just enough information about a
+ * multicomponent solution to specify its intensive thermodynamic
+ * state. It stores values for the temperature, mass density, and
+ * an array of species mass fractions. It also stores an array of
+ * species molecular weights, which are used to convert between
+ * mole and mass representations of the composition. These are the
+ * \e only properties of the species that class %State knows about.
+ *
+ * Class %State is not usually used directly in application
+ * programs. Its primary use is as a base class for class
+ * Phase. Class %State has no virtual methods, and none of its
+ * methods are meant to be overloaded. However, this is one exception.
+ * If the phase is incompressible, then the density must be replaced
+ * by the pressure as the independent variable. In this case, functions
+ * such as State::setMassFractions() within the class %State must actually now
+ * calculate the density (at constant T and P) instead of leaving
+ * it alone as befits an independent variable. Therefore, these types
+ * of functions are virtual functions and need to be overloaded
+ * for incompressible phases. Note, for nearly incompressible phases
+ * (or phases which utilize standard states based on a T and P) this
+ * change in independent variables may be advantageous as well,
+ * and these functions in %State need to overload as well so that the
+ * storred density within State doesn't become out of date.
+ *
+ * Class Phase derives from both clases
+ * Constituents and State. In addition to the methods of those two
+ * classes, it implements methods that allow referencing a species
+ * by name. And, it contains a lot of utility functions that will
+ * set the %State of the phase in its entirety, by first setting
+ * the composition, then the temperature and then the density.
+ * An example of this is the function,
+ * Phase::setState_TRY(doublereal t, doublereal dens, const doublereal* y).
+ *
+ * Class Phase contains method for saving and restoring the
+ * full internal states of each phase. These are called Phase::saveState()
+ * and Phase::restoreState(). These functions operate on a state
+ * vector, which is in general of length (2 + nSpecies()). The first
+ * two entries of the state vector is temperature and density.
+ *
+ */
- /**
- * Base class for phases of matter. Class Phase derives from both
- * Constituents and State. In addition to the methods of those two
- * classes, it implements methods that allow referencing a species
- * by name.
- * @ingroup phases
- */
+ //! Base class for phases of mater
+ /*!
+ * Base class for phases of matter. Class Phase derives from both
+ * Constituents and State. In addition to the methods of those two
+ * classes, it implements methods that allow referencing a species
+ * by name.
+ *
+ * Class Phase derives from both clases
+ * Constituents and State. In addition to the methods of those two
+ * classes, it implements methods that allow referencing a species
+ * by name. And, it contains a lot of utility functions that will
+ * set the %State of the phase in its entirety, by first setting
+ * the composition, then the temperature and then the density.
+ * An example of this is the function,
+ * Phase::setState_TRY(doublereal t, doublereal dens, const doublereal* y).
+ *
+ * Class Phase contains method for saving and restoring the
+ * full internal states of each phase. These are called Phase::saveState()
+ * and Phase::restoreState(). These functions operate on a state
+ * vector, which is in general of length (2 + nSpecies()). The first
+ * two entries of the state vector is temperature and density.
+ *
+ *
+ * @todo
+ * Make the concept of saving state vectors more general, so that
+ * it can handle other cases where there are additional internal state
+ * variables, such as the voltage, a potential energy, or a strain field.
+ *
+ * @ingroup phases
+ */
class Phase : public Constituents, public State {
public:
diff --git a/Cantera/src/State.h b/Cantera/src/State.h
index ea8fe6833..fb433f99d 100755
--- a/Cantera/src/State.h
+++ b/Cantera/src/State.h
@@ -41,7 +41,17 @@ namespace Cantera {
* Class State is not usually used directly in application
* programs. Its primary use is as a base class for class
* Phase. Class State has no virtual methods, and none of its
- * methods are meant to be overloaded.
+ * methods are meant to be overloaded. However, this is one exception.
+ * If the phase is incompressible, then the density must be replaced
+ * by the pressure as the independent variable. In this case, functions
+ * such as setMassFraction within the class %State must actually now
+ * calculate the density (at constant T and P) instead of leaving
+ * it alone as befits an independent variable. Threfore, these type
+ * of functions are virtual functions and need to be overloaded
+ * for incompressible phases. Note, for almost incompressible phases
+ * (or phases which utilize standard states based on a T and P) this
+ * may be advantageous as well, and they need to overload these functions
+ * too.
*
* @ingroup phases
*/
@@ -109,40 +119,40 @@ namespace Cantera {
*/
doublereal moleFraction(int k) const;
- /**
- * Set the mole fractions to the specified values, and then
- * normalize them so that they sum to 1.0.
- * @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);
+ /**
+ * Set the mole fractions to the specified values, and then
+ * normalize them so that they sum to 1.0.
+ * @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);
- /**
- * Set the mole fractions to the specified values without
- * 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.
- *
- * @param x Input vector of mole fractions.
- * Length is m_kk.
- */
- virtual void setMoleFractions_NoNorm(const doublereal* x);
+ /**
+ * Set the mole fractions to the specified values without
+ * 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.
+ *
+ * @param x Input vector of mole fractions.
+ * Length is m_kk.
+ */
+ virtual void setMoleFractions_NoNorm(const doublereal* x);
- /**
- * 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.
- *
- * @param y Output vector of mass fractions.
- * Length is m_kk.
- */
- void getMassFractions(doublereal* y) const;
+ /**
+ * 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.
+ *
+ * @param y Output vector of mass fractions.
+ * Length is m_kk.
+ */
+ void getMassFractions(doublereal* y) const;
//! Mass fraction of species k.
/*!
@@ -155,90 +165,90 @@ namespace Cantera {
*/
doublereal massFraction(int k) const;
- /**
- * Set the mass fractions to the specified values, and then
- * normalize them so that they sum to 1.0.
- * @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);
+ /**
+ * Set the mass fractions to the specified values, and then
+ * normalize them so that they sum to 1.0.
+ * @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);
- /**
- * Set the mass fractions to the specified values without
- * 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.
- *
- * @param y Input vector of mass fractions.
- * Length is m_kk.
- */
- virtual void setMassFractions_NoNorm(const doublereal* y);
+ /**
+ * Set the mass fractions to the specified values without
+ * 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.
+ *
+ * @param y Input vector of mass fractions.
+ * Length is m_kk.
+ */
+ virtual void setMassFractions_NoNorm(const doublereal* y);
- /**
- * Get the species concentrations (kmol/m^3). @param c On
- * return, \a c contains the concentrations for all species.
- * Array \a c must have a length greater than or equal to the
- * number of species.
- */
- void getConcentrations(doublereal* c) const;
+ /**
+ * Get the species concentrations (kmol/m^3). @param c On
+ * return, \a c contains the concentrations for all species.
+ * Array \a c must have a length greater than or equal to the
+ * number of species.
+ */
+ void getConcentrations(doublereal* c) const;
- /**
- * 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;
+ /**
+ * 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;
- /**
- * Set the concentrations to the specified values within the
- * phase.
- *
- * @param c The input vector to this routine is in dimensional
- * units. For volumetric phases c[k] is the
- * concentration of the kth species in kmol/m3.
- * For surface phases, c[k] is the concentration
- * in kmol/m2. The length of the vector is the number
- * of species in the phase.
- */
- virtual void setConcentrations(const doublereal* c);
+ /**
+ * Set the concentrations to the specified values within the
+ * phase.
+ *
+ * @param c The input vector to this routine is in dimensional
+ * units. For volumetric phases c[k] is the
+ * concentration of the kth species in kmol/m3.
+ * For surface phases, c[k] is the concentration
+ * in kmol/m2. The length of the vector is the number
+ * of species in the phase.
+ */
+ virtual void setConcentrations(const doublereal* c);
- /**
- * Returns a read-only pointer to the start of the
- * massFraction array
- */
- const doublereal* massFractions() const { return &m_y[0]; }
+ /**
+ * Returns a read-only pointer to the start of the
+ * massFraction array
+ */
+ const doublereal* massFractions() const { return &m_y[0]; }
- /**
- * Returns a read-only pointer to the start of the
- * moleFraction/MW array. This array is the array of mole
- * fractions, each divided by the mean molecular weight.
- */
- const doublereal* moleFractdivMMW() const { return &m_ym[0];}
+ /**
+ * Returns a read-only pointer to the start of the
+ * moleFraction/MW array. This array is the array of mole
+ * fractions, each divided by the mean molecular weight.
+ */
+ const doublereal* moleFractdivMMW() const { return &m_ym[0];}
- //@}
+ //@}
- /// @name Mean Properties
- //@{
- /**
- * Evaluate the mole-fraction-weighted mean of Q:
- * \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);
- }
+ /// @name Mean Properties
+ //@{
+ /**
+ * Evaluate the mole-fraction-weighted mean of Q:
+ * \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:
@@ -250,12 +260,12 @@ namespace Cantera {
*/
doublereal mean_Y(const doublereal* Q) const;
- /**
- * The mean molecular weight. Units: (kg/kmol)
- */
- doublereal meanMolecularWeight() const {
- return m_mmw;
- }
+ /**
+ * The mean molecular weight. Units: (kg/kmol)
+ */
+ doublereal meanMolecularWeight() const {
+ return m_mmw;
+ }
//! Evaluate \f$ \sum_k X_k \log X_k \f$.
/*!
@@ -272,23 +282,23 @@ namespace Cantera {
doublereal sum_xlogQ(doublereal* Q) const;
//@}
- /// @name Thermodynamic Properties
- /// Class State only stores enough thermodynamic data to
- /// specify the state. In addition to composition information,
- /// it stores the temperature and
- /// mass density.
- //@{
+ /// @name Thermodynamic Properties
+ /// Class State only stores enough thermodynamic data to
+ /// specify the state. In addition to composition information,
+ /// it stores the temperature and
+ /// mass density.
+ //@{
- /// Temperature (K).
- doublereal temperature() const { return m_temp; }
+ /// Temperature (K).
+ doublereal temperature() const { return m_temp; }
- /// Density (kg/m^3).
- doublereal density() const { return m_dens; }
+ /// Density (kg/m^3).
+ doublereal density() const { return m_dens; }
- /// Molar density (kmol/m^3).
- doublereal molarDensity() const {
- return m_dens/meanMolecularWeight();
- }
+ /// Molar density (kmol/m^3).
+ doublereal molarDensity() const {
+ return m_dens/meanMolecularWeight();
+ }
//! Set the internally storred density (kg/m^3) of the phase
/*!
@@ -348,71 +358,58 @@ namespace Cantera {
* @param k id of the species
* @param mw Molecular Weight (kg kmol-1)
*/
- void setMolecularWeight(int k, double mw) {
- m_molwts[k] = mw;
- m_rmolwts[k] = 1.0/mw;
- }
+ void setMolecularWeight(int k, double mw) {
+ m_molwts[k] = mw;
+ m_rmolwts[k] = 1.0/mw;
+ }
private:
- /**
- * Temperature. This is an independent variable
- * units = Kelvin
- */
- doublereal m_temp;
+ /**
+ * Temperature. This is an independent variable
+ * units = Kelvin
+ */
+ doublereal m_temp;
- /**
- * Density. This is an independent variable except in
- * the incompressible degenerate case. Thus,
- * the pressure is determined from this variable
- * not the other way round.
- * units = kg m-3
- */
- doublereal m_dens;
+ /**
+ * Density. This is an independent variable except in
+ * the incompressible degenerate case. Thus,
+ * the pressure is determined from this variable
+ * not the other way round.
+ * units = kg m-3
+ */
+ doublereal m_dens;
- /**
- * m_mmw is the mean molecular weight of the mixture
- * (kg kmol-1)
- */
- doublereal m_mmw;
+ /**
+ * m_mmw is the mean molecular weight of the mixture
+ * (kg kmol-1)
+ */
+ doublereal m_mmw;
- /**
- * m_ym[k] = mole fraction of species k divided by the
- * mean molecular weight of mixture.
- */
- mutable array_fp m_ym;
+ /**
+ * m_ym[k] = mole fraction of species k divided by the
+ * mean molecular weight of mixture.
+ */
+ mutable array_fp m_ym;
- /**
- * m_y[k] = mass fraction of species k
- */
- mutable array_fp m_y;
+ /**
+ * m_y[k] = mass fraction of species k
+ */
+ mutable array_fp m_y;
- /**
- * m_molwts[k] = molecular weight of species k (kg kmol-1)
- */
- array_fp m_molwts;
+ /**
+ * m_molwts[k] = molecular weight of species k (kg kmol-1)
+ */
+ array_fp m_molwts;
- /**
- * m_rmolwts[k] = inverse of the molecular weight of species k
- * units = kmol kg-1.
- */
- array_fp m_rmolwts;
+ /**
+ * m_rmolwts[k] = inverse of the molecular weight of species k
+ * units = kmol kg-1.
+ */
+ array_fp m_rmolwts;
};
}
#endif
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/tools/doc/doxyinput/Cantera.txt b/tools/doc/doxyinput/Cantera.txt
index a135e5fec..a92a10151 100644
--- a/tools/doc/doxyinput/Cantera.txt
+++ b/tools/doc/doxyinput/Cantera.txt
@@ -5,6 +5,8 @@
Choose one of the links below for an introduction to %Cantera, or use
the menu at the top to view detailed documentation of the code.
+-
+
- \subpage languages
- Building and Installing %Cantera