From 8f2ed853ce5210a04b9f8a31da9746005b018124 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Thu, 5 Dec 2019 20:48:02 -0600 Subject: [PATCH] [Thermo] update documentation for state definitions --- include/cantera/thermo/Phase.h | 68 +++++++++++++++++----------- include/cantera/thermo/ThermoPhase.h | 10 ++-- 2 files changed, 46 insertions(+), 32 deletions(-) diff --git a/include/cantera/thermo/Phase.h b/include/cantera/thermo/Phase.h index aed2e8e9e..6ddda467c 100644 --- a/include/cantera/thermo/Phase.h +++ b/include/cantera/thermo/Phase.h @@ -32,7 +32,8 @@ namespace Cantera //! Class Phase is the base class for phases of matter, managing the species and //! elements in a phase, as well as the independent variables of temperature, -//! mass density, species mass/mole fraction, and other generalized forces and +//! mass density (compressible substances) or pressure (incompressible +//! substances), species mass/mole fraction, and other generalized forces and //! intrinsic properties (such as electric potential) that define the //! thermodynamic state. /*! @@ -49,23 +50,32 @@ namespace Cantera * * Class Phase is not usually used directly. Its primary use is as a base class * for class ThermoPhase. It is not generally necessary to overloaded any of - * class Phase's methods, with the exception of incompressible phases. In that - * case, the density must be replaced by the pressure as the independent - * variable and functions such as setMassFraction within class Phase must - * actually now calculate the density (at constant T and P) instead of leaving - * it alone as befits an independent variable. This also applies for nearly- - * incompressible phases or phases which utilize standard states based on a - * T and P, in which case they need to overload these functions too. + * class Phase's methods, which handles both compressible and incompressible + * phases. For incompressible phases, the density is replaced by the pressure + * as the independent variable, and can no longer be set directly. In this case, + * the density needs to be calculated from a suitable equation of state, and + * assigned to the object using the assignDensity() method. This also applies + * for nearly-incompressible phases or phases which utilize standard states + * based on a T and P, in which case they need to overload these functions too. * * Class Phase contains a number 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 + * temperature and then density (or pressure for incompressible substances) + * An example of this is the function * Phase::setState_TRY(double t, double dens, const double* y). * - * Class Phase contains method for saving and restoring the full internal states - * of each phase. These are saveState() and restoreState(). These functions - * operate on a state vector, which is in general of length (2 + nSpecies()). - * The first two entries of the state vector are temperature and density. + * Class Phase contains methods for saving and restoring the full internal state + * of a given phase. These are saveState() and restoreState(). These functions + * operate on a state vector, which by default uses the first two entries for + * temperature and density (compressible substances) or temperature and + * pressure (incompressible substances). If the substance is not pure in a + * thermodyanmic sense (i.e. it may contain multiple species), the state also + * contains nSpecies() entries that specify the composition by corresponding + * mass fractions. Default definitions can be overloaded by derived classes. + * For any phase, the native definition of its thermodynamic state is defined + * the method nativeState(), with the length of the state vector returned by + * by stateSize(). In addition, methods isPure() and isCompressible() provide + * information on on the implementation of a Phase object. * * A species name is referred to via speciesName(), which is unique within a * given phase. Note that within multiphase mixtures (MultiPhase()), both a @@ -281,8 +291,7 @@ public: //!@} end group Element and Species Information - //! Return whether phase represents a stoichiometric (fixed composition) - //! substance + //! Return whether phase represents a pure (single species) substance virtual bool isPure() const { return false; } @@ -296,6 +305,8 @@ public: //! By default, entries include "T", "D", "Y" for a compressible substance //! and "T", "P", "Y" for an incompressible substance, with offsets 0, 1 and //! 2, respectively. Mass fractions "Y" are omitted for pure species. + //! In all cases, offsets into the state vector are used by saveState() + //! and restoreState(). virtual std::map nativeState() const; //! Return a vector containing full states defining a phase. @@ -323,17 +334,17 @@ public: virtual std::vector partialStates() const; //! Return size of vector defining internal state of the phase. - //! Used by saveState and restoreState. + //! Used by saveState() and restoreState(). virtual size_t stateSize() const; //! 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. + //! @param state output vector. Will be resized to stateSize(). 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 + //! @param lenstate length of the state array. Must be >= stateSize() + //! @param state output vector. Must be of length stateSizes() or //! greater. virtual void saveState(size_t lenstate, doublereal* state) const; @@ -643,10 +654,11 @@ public: //! Return the thermodynamic pressure (Pa). /*! - * This method must be overloaded in derived classes. Since the mass - * density, temperature, and mass fractions are stored, this method should + * This method must be overloaded in derived classes. Within %Cantera, the + * independent variable is either density or pressure. If the state is + * defined by temperature, density, and mass fractions, this method should * use these values to implement the mechanical equation of state \f$ P(T, - * \rho, Y_1, \dots, Y_K) \f$. + * \rho, Y_1, \dots, Y_K) \f$. Alternatively, it returns a stored value. */ virtual double pressure() const { throw NotImplementedError("Phase::pressure"); @@ -680,8 +692,9 @@ public: /*! * 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 + * independent variable is either density or pressure. Therefore, this + * function may either solve for the density that will yield the desired + * input pressure or set an independent variable. The temperature * and composition are held constant during this process. * * @param p input Pressure (Pa) @@ -932,9 +945,10 @@ private: doublereal m_temp; //!< Temperature (K). This is an independent variable - //! Density (kg m-3). This is an independent variable except in the - //! incompressible degenerate case. Thus, the pressure is determined from - //! this variable rather than other way round. + //! Density (kg m-3). This is an independent variable except in the case + //! of incompressible phases, where it has to be changed using the + //! assignDensity() method. For compressible substances, the pressure is + //! determined from this variable rather than other way round. doublereal m_dens; doublereal m_mmw; //!< mean molecular weight of the mixture (kg kmol-1) diff --git a/include/cantera/thermo/ThermoPhase.h b/include/cantera/thermo/ThermoPhase.h index ca7291437..61f285ea0 100644 --- a/include/cantera/thermo/ThermoPhase.h +++ b/include/cantera/thermo/ThermoPhase.h @@ -51,11 +51,11 @@ const int cSS_CONVENTION_SLAVE = 2; * ThermoPhase. * * Class ThermoPhase extends class Phase by adding methods to compute - * thermodynamic properties in addition to the ones (temperature, density, - * composition) that class Phase provides. The distinction is that the methods - * declared in ThermoPhase require knowing the particular equation of state of - * the phase of interest, while those of class Phase do not, since they only - * involve data values stored within the object. + * thermodynamic properties in addition to the ones that are used to define the + * state of a substance (temperature, density/pressure and composition). The + * distinction is that the methods declared in ThermoPhase require knowing the + * particular equation of state of the phase of interest, while those of class + * Phase do not, since they only involve data values stored within the object. * * Instances of subclasses of ThermoPhase should be created using the factory * class ThermoFactory, not by calling the constructor directly. This allows new