State Class Reference
[Models of Phases of Matter]

Manages the independent variables of temperature, mass density, and species mass/mole fraction that define the thermodynamic state. More...

#include <State.h>

Inheritance diagram for State:

[legend]

List of all members.

Public Member Functions
	State ()
	Constructor.
virtual	~State ()
	Destructor.
	State (const State &right)
	Copy Constructor for the State Class.
State &	operator= (const State &right)
	Assignment operator for the state class.
bool	ready () const
	True if the number species has been set.
void	stateMFChangeCalc (bool forceChange=false)
	Every time the mole fractions have changed, this routine will increment the stateMFNumber.
int	stateMFNumber () const
	Return the state number.
Species Information
The only thing class State knows about the species is their molecular weights.
const array_fp &	molecularWeights () const
	Return a read-only reference to the array of molecular weights.
Composition

void	getMoleFractions (doublereal *const x) const
	Get the species mole fraction vector.
doublereal	moleFraction (const int k) const
	The mole fraction of species k.
virtual void	setMoleFractions (const doublereal *const x)
	Set the mole fractions to the specified values, and then normalize them so that they sum to 1.0.
virtual void	setMoleFractions_NoNorm (const doublereal *const x)
	Set the mole fractions to the specified values without normalizing.
void	getMassFractions (doublereal *const y) const
	Get the species mass fractions.
doublereal	massFraction (const int k) const
	Mass fraction of species k.
virtual void	setMassFractions (const doublereal *const y)
	Set the mass fractions to the specified values, and then normalize them so that they sum to 1.0.
virtual void	setMassFractions_NoNorm (const doublereal *const y)
	Set the mass fractions to the specified values without normalizing.
void	getConcentrations (doublereal *const c) const
	Get the species concentrations (kmol/m^3).
doublereal	concentration (const int k) const
	Concentration of species k.
virtual void	setConcentrations (const doublereal *const conc)
	Set the concentrations to the specified values within the phase.
const doublereal *	massFractions () const
	Returns a read-only pointer to the start of the massFraction array.
const doublereal *	moleFractdivMMW () const
	Returns a read-only pointer to the start of the moleFraction/MW array.
Mean Properties

doublereal	mean_X (const doublereal *const Q) const
	Evaluate the mole-fraction-weighted mean of Q: $\sum_k X_k Q_k.$ Array Q should contain pure-species molar property values.
doublereal	mean_Y (const doublereal *const Q) const
	Evaluate the mass-fraction-weighted mean of Q: $\sum_k Y_k Q_k$ .
doublereal	meanMolecularWeight () const
	The mean molecular weight.
doublereal	sum_xlogx () const
	Evaluate $\sum_k X_k \log X_k$ .
doublereal	sum_xlogQ (doublereal *const Q) const
	Evaluate $\sum_k X_k \log Q_k$ .
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.
doublereal	temperature () const
	Temperature (K).
virtual doublereal	density () const
	Density (kg/m^3).
doublereal	molarDensity () const
	Molar density (kmol/m^3).
virtual void	setDensity (const doublereal density)
	Set the internally storred density (kg/m^3) of the phase.
virtual void	setMolarDensity (const doublereal molarDensity)
	Set the internally storred molar density (kmol/m^3) of the phase.
virtual void	setTemperature (const doublereal temp)
	Set the temperature (K).
Protected Member Functions
void	init (const array_fp &mw)
void	setMolecularWeight (const int k, const double mw)
	Set the molecular weight of a single species to a given value.
Protected Attributes
int	m_kk
	m_kk is the number of species in the phase
Private Attributes
doublereal	m_temp
	Temperature.
doublereal	m_dens
	Density.
doublereal	m_mmw
	m_mmw is the mean molecular weight of the mixture (kg kmol-1)
array_fp	m_ym
	m_ym[k] = mole fraction of species k divided by the mean molecular weight of mixture.
array_fp	m_y
	m_y[k] = mass fraction of species k
array_fp	m_molwts
	m_molwts[k] = molecular weight of species k (kg kmol-1)
array_fp	m_rmolwts
	m_rmolwts[k] = inverse of the molecular weight of species k units = kmol kg-1.
int	m_stateNum
	State Change variable.

Detailed Description

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 only properties of the species that class State knows about. For efficiency in mass/mole conversion, the vector of mass fractions divided by molecular weight $ Y_k/M_k $ is also stored.

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 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.

Definition at line 62 of file State.h.

Constructor & Destructor Documentation

State ( )

Constructor.

Definition at line 38 of file State.cpp.

~State ( ) [virtual]

Destructor.

Since no memory is allocated by methods of this class, the destructor does nothing.

Definition at line 47 of file State.cpp.

State ( const State & right )

Copy Constructor for the State Class.

Parameters:

right

Reference to the class to be copied.

Definition at line 51 of file State.cpp.

References State::operator=().

Member Function Documentation

doublereal concentration ( const int k ) const

Concentration of species k.

If k is outside the valid range, an exception will be thrown.

Parameters:

k

Index of species

Definition at line 134 of file State.cpp.

References State::m_dens, State::m_kk, State::m_rmolwts, and State::m_y.

virtual doublereal density ( ) const [inline, virtual]

Density (kg/m^3).

Reimplemented in HMWSoln.

Definition at line 314 of file State.h.

References State::m_dens.

Referenced by SingleSpeciesTP::cv_mole(), WaterSSTP::dthermalExpansionCoeffdT(), WaterSSTP::getCp_R_ref(), WaterSSTP::getEnthalpy_RT_ref(), WaterSSTP::getEntropy_R_ref(), WaterSSTP::getGibbs_RT_ref(), StoichSubstanceSSTP::getParameters(), MineralEQ3::getParameters(), MetalSHEelectrons::getParameters(), ConstDensityThermo::getParameters(), SingleSpeciesTP::getPartialMolarVolumes(), SingleSpeciesTP::getStandardVolumes(), WaterSSTP::getStandardVolumes_ref(), State::molarDensity(), ThermoPhase::report(), PureFluidPhase::report(), MolalityVPSSTP::report(), WaterSSTP::satPressure(), Phase::saveState(), IdealSolidSolnPhase::setDensity(), IdealMolalSoln::setDensity(), DebyeHuckel::setDensity(), WaterSSTP::setPressure(), WaterSSTP::setTemperature(), and WaterSSTP::vaporFraction().

void getConcentrations ( doublereal *const c ) const

Get the species concentrations (kmol/m^3).

Parameters:

c

On return, c contains the concentrations for all species. Array c must have a length greater than or equal to the number of species.

Definition at line 219 of file State.cpp.

References State::m_dens, State::m_ym, and Cantera::scale().

Referenced by ConstDensityThermo::getActivityCoefficients(), SurfPhase::getActivityConcentrations(), IdealSolnGasVPSS::getActivityConcentrations(), IdealGasPhase::getActivityConcentrations(), and SurfPhase::getCoverages().

void getMassFractions ( doublereal *const y ) const

Get the species mass fractions.

Parameters:

	y	On return, y contains the mass fractions. Array y must have a length greater than or equal to the number of species.
	y	Output vector of mass fractions. Length is m_kk.

Definition at line 235 of file State.cpp.

References State::m_y.

Referenced by ThermoPhase::report(), PureFluidPhase::report(), and Phase::saveState().

void getMoleFractions ( doublereal *const x ) const

Get the species mole fraction vector.

Parameters:

x

On return, x contains the mole fractions. Must have a length greater than or equal to the number of species.

Definition at line 231 of file State.cpp.

References State::m_mmw, State::m_ym, and Cantera::scale().

Referenced by IdealMolalSoln::calcDensity(), DebyeHuckel::calcDensity(), MolalityVPSSTP::calcMolalities(), IdealMolalSoln::enthalpy_mole(), LatticePhase::getActivityCoefficients(), HMWSoln::relative_enthalpy(), ThermoPhase::report(), PureFluidPhase::report(), MolalityVPSSTP::report(), MolalityVPSSTP::setMolalitiesByName(), MultiPhase::setMoles(), ThermoPhase::setReferenceComposition(), and MultiPhase::uploadMoleFractionsFromPhases().

void init ( const array_fp & mw ) [protected]

For internal use only.

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.

Parameters:

mw

Vector of molecular weights of the species.

Definition at line 244 of file State.cpp.

References Cantera::int2str(), State::m_kk, State::m_mmw, State::m_molwts, State::m_rmolwts, State::m_y, State::m_ym, and Cantera::Tiny.

Referenced by Phase::freezeSpecies().

doublereal massFraction ( const 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.

Parameters:

k

species index

Reimplemented in Phase.

Definition at line 126 of file State.cpp.

References State::m_kk, and State::m_y.

const doublereal* massFractions ( ) const [inline]

Returns a read-only pointer to the start of the massFraction array.

The pointer returned is readonly

Returns:: returns a pointer to a vector of doubles of length m_kk.

Definition at line 242 of file State.h.

References State::m_y.

Referenced by Phase::massFraction().

doublereal mean_X ( const doublereal *const Q ) const

Evaluate the mole-fraction-weighted mean of Q:

$\sum_k X_k Q_k.$

Array Q should contain pure-species molar property values.

Parameters:

Q

input vector of length m_kk that is to be averaged.

Returns:: mole-freaction-weighted mean of Q

Definition at line 223 of file State.cpp.

References State::m_mmw, and State::m_ym.

Referenced by IdealSolnGasVPSS::cp_mole(), IdealSolidSolnPhase::cp_mole(), IdealMolalSoln::cp_mole(), IdealGasPhase::cp_mole(), DebyeHuckel::cp_mole(), LatticePhase::cv_mole(), HMWSoln::cv_mole(), ConstDensityThermo::cv_mole(), SurfPhase::enthalpy_mole(), IdealSolnGasVPSS::enthalpy_mole(), IdealSolidSolnPhase::enthalpy_mole(), IdealMolalSoln::enthalpy_mole(), IdealGasPhase::enthalpy_mole(), DebyeHuckel::enthalpy_mole(), IdealSolnGasVPSS::entropy_mole(), IdealSolidSolnPhase::entropy_mole(), IdealMolalSoln::entropy_mole(), IdealGasPhase::entropy_mole(), DebyeHuckel::entropy_mole(), IdealSolidSolnPhase::gibbs_mole(), IdealMolalSoln::gibbs_mole(), HMWSoln::gibbs_mole(), DebyeHuckel::gibbs_mole(), IdealSolidSolnPhase::intEnergy_mole(), IdealMolalSoln::intEnergy_mole(), IdealGasPhase::intEnergy_mole(), and HMWSoln::relative_enthalpy().

doublereal mean_Y ( const doublereal *const Q ) const

Evaluate the mass-fraction-weighted mean of Q:

$\sum_k Y_k Q_k$

.

Parameters:

Q

Array Q contains a vector of species property values in mass units.

Returns:: Return value containing the mass-fraction-weighted mean of Q.

Definition at line 227 of file State.cpp.

References Cantera::dot(), and State::m_y.

doublereal meanMolecularWeight ( ) const [inline]

The mean molecular weight.

Units: (kg/kmol)

Definition at line 282 of file State.h.

References State::m_mmw.

Referenced by IdealSolnGasVPSS::calcDensity(), IdealMolalSoln::calcDensity(), DebyeHuckel::calcDensity(), ThermoPhase::cp_mass(), ThermoPhase::cv_mass(), ThermoPhase::enthalpy_mass(), ThermoPhase::entropy_mass(), IdealSolidSolnPhase::getActivityConcentrations(), WaterSSTP::getStandardVolumes_ref(), ThermoPhase::gibbs_mass(), ThermoPhase::intEnergy_mass(), State::molarDensity(), ThermoPhase::report(), PureFluidPhase::report(), MolalityVPSSTP::report(), State::setMolarDensity(), and IdealGasPhase::setPressure().

doublereal molarDensity ( ) const

Molar density (kmol/m^3).

Definition at line 192 of file State.cpp.

References State::density(), and State::meanMolecularWeight().

Referenced by IdealSolidSolnPhase::enthalpy_mole(), ConstDensityThermo::getChemPotentials(), StoichSubstanceSSTP::getEnthalpy_RT(), MineralEQ3::getEnthalpy_RT(), StoichSubstanceSSTP::getIntEnergy_RT(), MineralEQ3::getIntEnergy_RT(), StoichSubstanceSSTP::getIntEnergy_RT_ref(), MineralEQ3::getIntEnergy_RT_ref(), MetalSHEelectrons::getIntEnergy_RT_ref(), IdealGasPhase::getPartialMolarVolumes(), IdealGasPhase::getStandardVolumes(), IdealSolnGasVPSS::intEnergy_mole(), IdealSolidSolnPhase::intEnergy_mole(), HMWSoln::intEnergy_mole(), DebyeHuckel::intEnergy_mole(), ConstDensityThermo::logStandardConc(), IdealGasPhase::pressure(), IdealMolalSoln::setMolarDensity(), and DebyeHuckel::setMolarDensity().

const array_fp& molecularWeights ( ) const [inline]

Return a read-only reference to the array of molecular weights.

Reimplemented in Phase.

Definition at line 100 of file State.h.

References State::m_molwts.

const doublereal * moleFractdivMMW ( ) const

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.

Definition at line 215 of file State.cpp.

References State::m_ym.

Referenced by IdealSolnGasVPSS::calcDensity(), IdealSolidSolnPhase::calcDensity(), and IdealSolidSolnPhase::getActivityConcentrations().

doublereal moleFraction ( const 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.

Parameters:

k

species index

Reimplemented in Phase.

Definition at line 91 of file State.cpp.

References State::m_kk, State::m_mmw, and State::m_ym.

State & operator= ( const State & right )

Assignment operator for the state class.

Parameters:

right

Reference to the class to be copied.

Definition at line 67 of file State.cpp.

References State::m_dens, State::m_kk, State::m_mmw, State::m_molwts, State::m_rmolwts, State::m_stateNum, State::m_temp, State::m_y, and State::m_ym.

Referenced by State::State().

bool ready ( ) const

True if the number species has been set.

Reimplemented in Phase.

Definition at line 279 of file State.cpp.

References State::m_kk.

Referenced by Phase::ready().

void setConcentrations ( const doublereal *const conc ) [virtual]

Set the concentrations to the specified values within the phase.

We set the concentrations here and therefore we set the overall density of the phase. We hold the temperature constant during this operation. Therefore, we have possibly changed the pressure of the phase by calling this routine.

Parameters:

conc

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.

Reimplemented in IdealSolidSolnPhase.

Definition at line 196 of file State.cpp.

References State::m_kk, State::m_mmw, State::m_molwts, State::m_y, State::m_ym, State::setDensity(), and State::stateMFChangeCalc().

Referenced by SurfPhase::setCoverages(), and SurfPhase::setCoveragesNoNorm().

virtual void setDensity ( const doublereal density ) [inline, virtual]

Set the internally storred density (kg/m^3) of the phase.

Note the density of a phase is an indepedent variable.

Parameters:

density

Input density (kg/m^3).

Reimplemented in DebyeHuckel, HMWSoln, IdealMolalSoln, IdealSolidSolnPhase, and WaterSSTP.

Definition at line 327 of file State.h.

References State::m_dens.

Referenced by IdealSolnGasVPSS::calcDensity(), electrodeElectron::initThermoXML(), StoichSubstanceSSTP::initThermoXML(), MineralEQ3::initThermoXML(), MetalSHEelectrons::initThermoXML(), Phase::restoreState(), State::setConcentrations(), electrodeElectron::setParameters(), StoichSubstanceSSTP::setParameters(), MineralEQ3::setParameters(), MetalSHEelectrons::setParameters(), ConstDensityThermo::setParameters(), StoichSubstanceSSTP::setParametersFromXML(), MetalSHEelectrons::setParametersFromXML(), IdealGasPhase::setPressure(), ThermoPhase::setState_HPorUV(), Phase::setState_RX(), Phase::setState_RY(), ThermoPhase::setState_SPorSV(), SingleSpeciesTP::setState_SV(), Phase::setState_TR(), Phase::setState_TRX(), Phase::setState_TRY(), SingleSpeciesTP::setState_UV(), and ThermoPhase::setStateFromXML().

void setMassFractions ( const doublereal *const y ) [virtual]

Set the mass fractions to the specified values, and then normalize them so that they sum to 1.0.

Parameters:

	y	Array of unnormalized mass fraction values (input). Must have a length greater than or equal to the number of species.
	y	Input vector of mass fractions. There is no restriction on the sum of the mass fraction vector. Internally, the State object will normalize this vector before storring its contents. Length is m_kk.

Reimplemented in IdealSolidSolnPhase.

Definition at line 142 of file State.cpp.

References State::m_kk, State::m_mmw, State::m_rmolwts, State::m_y, State::m_ym, Cantera::scale(), and State::stateMFChangeCalc().

Referenced by Phase::setMassFractionsByName(), ThermoPhase::setState_PY(), Phase::setState_RY(), ThermoPhase::setState_TPY(), Phase::setState_TRY(), and Phase::setState_TY().

void setMassFractions_NoNorm ( const doublereal *const y ) [virtual]

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.

Parameters:

y

Input vector of mass fractions. Length is m_kk.

Reimplemented in IdealSolidSolnPhase.

Definition at line 167 of file State.cpp.

References State::m_kk, State::m_mmw, State::m_rmolwts, State::m_y, State::m_ym, and State::stateMFChangeCalc().

Referenced by Phase::restoreState().

void setMolarDensity ( const doublereal molarDensity ) [virtual]

Set the internally storred molar density (kmol/m^3) of the phase.

Parameters:

molarDensity

Input molar density (kmol/m^3).

Reimplemented in DebyeHuckel, HMWSoln, IdealMolalSoln, and IdealSolidSolnPhase.

Definition at line 239 of file State.cpp.

References State::m_dens, and State::meanMolecularWeight().

Referenced by Phase::setState_TNX().

void setMolecularWeight	(	const int	k,
		const double	mw
	)			`[inline, protected]`

Set the molecular weight of a single species to a given value.

Parameters:

	k	id of the species
	mw	Molecular Weight (kg kmol-1)

Definition at line 385 of file State.h.

References State::m_molwts, and State::m_rmolwts.

Referenced by WaterSSTP::initThermoXML().

void setMoleFractions ( const doublereal *const x ) [virtual]

Set the mole fractions to the specified values, and then normalize them so that they sum to 1.0.

Parameters:

	x	Array of unnormalized mole fraction values (input). Must have a length greater than or equal to the number of species.
	x	Input vector of mole fractions. There is no restriction on the sum of the mole fraction vector. Internally, the State object will normalize this vector before storring its contents. Length is m_kk.

Reimplemented in IdealSolidSolnPhase.

Definition at line 102 of file State.cpp.

References Cantera::dot(), State::m_kk, State::m_mmw, State::m_molwts, State::m_y, State::m_ym, and State::stateMFChangeCalc().

Referenced by SingleSpeciesTP::initThermo(), WaterSSTP::initThermoXML(), MolalityVPSSTP::setMolalities(), MolalityVPSSTP::setMolalitiesByName(), Phase::setMoleFractionsByName(), ThermoPhase::setState_PX(), Phase::setState_RX(), Phase::setState_TNX(), ThermoPhase::setState_TPX(), Phase::setState_TRX(), and Phase::setState_TX().

void setMoleFractions_NoNorm ( const doublereal *const x ) [virtual]

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.

Parameters:

x

Input vector of mole fractions. Length is m_kk.

Reimplemented in IdealSolidSolnPhase.

Definition at line 115 of file State.cpp.

References Cantera::dot(), State::m_kk, State::m_mmw, State::m_molwts, State::m_y, State::m_ym, and State::stateMFChangeCalc().

virtual void setTemperature ( const doublereal temp ) [inline, virtual]

Set the temperature (K).

This function sets the internally storred temperature of the phase.

Parameters:

temp

Temperature in kelvin

Reimplemented in DebyeHuckel, HMWSoln, VPStandardStateTP, and WaterSSTP.

Definition at line 343 of file State.h.

References State::m_temp.

Referenced by Phase::restoreState(), ThermoPhase::setState_HPorUV(), ThermoPhase::setState_SPorSV(), SingleSpeciesTP::setState_SV(), Phase::setState_TNX(), ThermoPhase::setState_TP(), ThermoPhase::setState_TPX(), SingleSpeciesTP::setState_TPX(), ThermoPhase::setState_TPY(), SingleSpeciesTP::setState_TPY(), Phase::setState_TR(), Phase::setState_TRX(), Phase::setState_TRY(), Phase::setState_TX(), Phase::setState_TY(), SingleSpeciesTP::setState_UV(), ThermoPhase::setStateFromXML(), and SurfPhase::setStateFromXML().

void stateMFChangeCalc ( bool forceChange = false ) [inline]

Every time the mole fractions have changed, this routine will increment the stateMFNumber.

Parameters:

forceChange

If this is true then the stateMFNumber always changes. This defaults to false.

Definition at line 31 of file State.cpp.

References State::m_stateNum.

Referenced by State::setConcentrations(), State::setMassFractions(), State::setMassFractions_NoNorm(), State::setMoleFractions(), and State::setMoleFractions_NoNorm().

int stateMFNumber ( ) const [inline]

Return the state number.

Return the State Mole Fraction Number.

Definition at line 445 of file State.h.

References State::m_stateNum.

doublereal sum_xlogQ ( doublereal *const Q ) const

Evaluate $\sum_k X_k \log Q_k$ .

Parameters:

Q

Vector of length m_kk to take the log average of

Returns:: Returns the indicated sum.

Definition at line 188 of file State.cpp.

References State::m_mmw, and State::m_ym.

doublereal sum_xlogx ( ) const

Evaluate $\sum_k X_k \log X_k$ .

Returns:: returns the indicated sum. units are dimensionless.

Definition at line 184 of file State.cpp.

References State::m_mmw, and State::m_ym.

Referenced by IdealSolnGasVPSS::entropy_mole(), IdealSolidSolnPhase::entropy_mole(), IdealGasPhase::entropy_mole(), and IdealSolidSolnPhase::gibbs_mole().

doublereal temperature ( ) const [inline]

Temperature (K).

Definition at line 309 of file State.h.

References State::m_temp.

Member Data Documentation

doublereal m_dens [private]

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

Definition at line 405 of file State.h.

Referenced by State::concentration(), State::density(), State::getConcentrations(), State::operator=(), State::setDensity(), and State::setMolarDensity().