Cantera  2.1.2
GibbsExcessVPSSTP.h
Go to the documentation of this file.
1 /**
2  * @file GibbsExcessVPSSTP.h
3  * Header for intermediate ThermoPhase object for phases which
4  * employ gibbs excess free energy based formulations
5  * (see \ref thermoprops
6  * and class \link Cantera::GibbsExcessVPSSTP GibbsExcessVPSSTP\endlink).
7  *
8  * Header file for a derived class of ThermoPhase that handles
9  * variable pressure standard state methods for calculating
10  * thermodynamic properties that are further based upon activities
11  * based on the molality scale. These include most of the methods for
12  * calculating liquid electrolyte thermodynamics.
13  */
14 /*
15  * Copyright (2006) Sandia Corporation. Under the terms of
16  * Contract DE-AC04-94AL85000 with Sandia Corporation, the
17  * U.S. Government retains certain rights in this software.
18  */
19 #ifndef CT_GIBBSEXCESSVPSSTP_H
20 #define CT_GIBBSEXCESSVPSSTP_H
21 
22 #include "VPStandardStateTP.h"
23 
24 namespace Cantera
25 {
26 
27 /**
28  * @ingroup thermoprops
29  */
30 
31 /*!
32  * GibbsExcessVPSSTP is a derived class of ThermoPhase that handles
33  * variable pressure standard state methods for calculating
34  * thermodynamic properties that are further based on
35  * expressing the Excess Gibbs free energy as a function of
36  * the mole fractions (or pseudo mole fractions) of constituents.
37  * This category is the workhorse for describing molten salts,
38  * solid-phase mixtures of semiconductors, and mixtures of miscible
39  * and semi-miscible compounds.
40  *
41  * It includes
42  * - regular solutions
43  * - Margules expansions
44  * - NTRL equation
45  * - Wilson's equation
46  * - UNIQUAC equation of state.
47  *
48  * This class adds additional functions onto the ThermoPhase interface
49  * that handles the calculation of the excess Gibbs free energy. The ThermoPhase
50  * class includes a member function, ThermoPhase::activityConvention()
51  * that indicates which convention the activities are based on. The
52  * default is to assume activities are based on the molar convention.
53  * That default is used here.
54  *
55  * All of the Excess Gibbs free energy formulations in this area employ
56  * symmetrical formulations.
57  *
58  * Chemical potentials
59  * of species k, \f$ \mu_o \f$, has the following general format:
60  *
61  * \f[
62  * \mu_k = \mu^o_k(T,P) + R T ln( \gamma_k X_k )
63  * \f]
64  *
65  * where \f$ \gamma_k^{\triangle} \f$ is a molar based activity coefficient for species
66  * \f$k\f$.
67  *
68  * GibbsExcessVPSSTP contains an internal vector with the current mole
69  * fraction vector. That's one of its primary usages. In order to keep the mole fraction
70  * vector constant, all of the setState functions are redesigned at this layer.
71  *
72  * <H3>
73  * Activity Concentrations: Relationship of %ThermoPhase to %Kinetics Expressions
74  * </H3>
75  *
76  * As explained in a similar discussion in the ThermoPhase class, the actual units used
77  * in kinetics expressions must be specified in the ThermoPhase class for the corresponding
78  * species. These units vary with the field of study. %Cantera uses the concept of
79  * activity concentrations to represent this. Activity concentrations are used directly
80  * in the expressions for kinetics. Standard concentrations are used as the multiplicative
81  * constant that takes the activity of a species and turns it into an activity concentration.
82  * Standard concentrations must not depend on the concentration of the species in the phase.
83  *
84  * Here we set a standard for the specification of the standard concentrations for this class
85  * and all child classes underneath it. We specify here that the standard concentration is
86  * equal to 1 for all species. Therefore, the activities appear directly in kinetics expressions
87  * involving species in underlying %GibbsExcessVPSSTP phases.
88  *
89  * <H3>
90  * SetState Strategy
91  * </H3>
92  *
93  * All setState functions that set the internal state of the ThermoPhase object are
94  * overloaded at this level, so that a current mole fraction vector is maintained within
95  * the object.
96  */
98 {
99 public:
100  //! @name Constructors
101  //! @{
102  /*!
103  * This doesn't do much more than initialize constants with
104  * default values for water at 25C. Water molecular weight
105  * comes from the default elements.xml file. It actually
106  * differs slightly from the IAPWS95 value of 18.015268. However,
107  * density conservation and therefore element conservation
108  * is the more important principle to follow.
109  */
111 
112  //! Copy constructor
113  /*!
114  * @param b class to be copied
115  */
117 
118  /// Assignment operator
119  /*!
120  * @param b class to be copied.
121  */
123 
124  //! Duplication routine for objects which inherit from ThermoPhase.
125  /*!
126  * This virtual routine can be used to duplicate thermophase objects
127  * inherited from ThermoPhase even if the application only has
128  * a pointer to ThermoPhase to work with.
129  */
130  virtual ThermoPhase* duplMyselfAsThermoPhase() const;
131  //! @}
132 
133  //! Equation of state type flag.
134  /*!
135  * The ThermoPhase base class returns
136  * zero. Subclasses should define this to return a unique
137  * non-zero value. Known constants defined for this purpose are
138  * listed in mix_defs.h. The MolalityVPSSTP class also returns
139  * zero, as it is a non-complete class.
140  */
141  virtual int eosType() const;
142 
143  //! @}
144  //! @name Mechanical Properties
145  //! @{
146 
147  //! Set the internally stored pressure (Pa) at constant
148  //! temperature and composition
149  /*!
150  * This method sets the pressure within the object.
151  * The water model is a completely compressible model.
152  * Also, the dielectric constant is pressure dependent.
153  *
154  * @param p input Pressure (Pa)
155  *
156  * @todo Implement a variable pressure capability
157  */
158  virtual void setPressure(doublereal p);
159 
160 protected:
161  /**
162  * Calculate the density of the mixture using the partial
163  * molar volumes and mole fractions as input
164  *
165  * The formula for this is
166  *
167  * \f[
168  * \rho = \frac{\sum_k{X_k W_k}}{\sum_k{X_k V_k}}
169  * \f]
170  *
171  * where \f$X_k\f$ are the mole fractions, \f$W_k\f$ are
172  * the molecular weights, and \f$V_k\f$ are the pure species
173  * molar volumes.
174  *
175  * Note, the basis behind this formula is that in an ideal
176  * solution the partial molar volumes are equal to the pure
177  * species molar volumes. We have additionally specified
178  * in this class that the pure species molar volumes are
179  * independent of temperature and pressure.
180  *
181  * NOTE: This is a non-virtual function, which is not a
182  * member of the ThermoPhase base class.
183  */
184  void calcDensity();
185 
186 public:
187  /**
188  * @}
189  * @name Activities, Standard States, and Activity Concentrations
190  *
191  * The activity \f$a_k\f$ of a species in solution is
192  * related to the chemical potential by \f[ \mu_k = \mu_k^0(T)
193  * + \hat R T \log a_k. \f] The quantity \f$\mu_k^0(T,P)\f$ is
194  * the chemical potential at unit activity, which depends only
195  * on temperature and pressure.
196  * @{
197  */
198 
199  //! This method returns an array of generalized concentrations
200  /*!
201  * \f$ C^a_k\f$ are defined such that \f$ a_k = C^a_k /
202  * C^0_k, \f$ where \f$ C^0_k \f$ is a standard concentration
203  * defined below and \f$ a_k \f$ are activities used in the
204  * thermodynamic functions. These activity (or generalized)
205  * concentrations are used by kinetics manager classes to compute the forward and
206  * reverse rates of elementary reactions. Note that they may
207  * or may not have units of concentration --- they might be
208  * partial pressures, mole fractions, or surface coverages,
209  * for example.
210  *
211  * @param c Output array of generalized concentrations. The
212  * units depend upon the implementation of the
213  * reaction rate expressions within the phase.
214  */
215  virtual void getActivityConcentrations(doublereal* c) const;
216 
217  /**
218  * The standard concentration \f$ C^0_k \f$ used to normalize
219  * the generalized concentration. In many cases, this quantity
220  * will be the same for all species in a phase - for example,
221  * for an ideal gas \f$ C^0_k = P/\hat R T \f$. For this
222  * reason, this method returns a single value, instead of an
223  * array. However, for phases in which the standard
224  * concentration is species-specific (e.g. surface species of
225  * different sizes), this method may be called with an
226  * optional parameter indicating the species.
227  *
228  * The standard concentration for defaulted to 1. In other words
229  * the activity concentration is assumed to be 1.
230  *
231  * @param k species index. Defaults to zero.
232  */
233  virtual doublereal standardConcentration(size_t k=0) const;
234 
235  /**
236  * Returns the natural logarithm of the standard
237  * concentration of the kth species
238  *
239  * @param k species index
240  */
241  virtual doublereal logStandardConc(size_t k=0) const;
242 
243  /**
244  * Returns the units of the standard and generalized
245  * concentrations Note they have the same units, as their
246  * ratio is defined to be equal to the activity of the kth
247  * species in the solution, which is unitless.
248  *
249  * This routine is used in print out applications where the
250  * units are needed. Usually, MKS units are assumed throughout
251  * the program and in the XML input files.
252  *
253  * @param uA Output vector containing the units
254  * uA[0] = kmol units - default = 1
255  * uA[1] = m units - default = -nDim(), the number of spatial
256  * dimensions in the Phase class.
257  * uA[2] = kg units - default = 0;
258  * uA[3] = Pa(pressure) units - default = 0;
259  * uA[4] = Temperature units - default = 0;
260  * uA[5] = time units - default = 0
261  * @param k species index. Defaults to 0.
262  * @param sizeUA output int containing the size of the vector.
263  * Currently, this is equal to 6.
264  * @deprecated
265  */
266  virtual void getUnitsStandardConc(double* uA, int k = 0,
267  int sizeUA = 6) const;
268 
269 
270  //! Get the array of non-dimensional activities (molality
271  //! based for this class and classes that derive from it) at
272  //! the current solution temperature, pressure, and solution concentration.
273  /*!
274  * \f[
275  * a_i^\triangle = \gamma_k^{\triangle} \frac{m_k}{m^\triangle}
276  * \f]
277  *
278  * This function must be implemented in derived classes.
279  *
280  * @param ac Output vector of molality-based activities. Length: m_kk.
281  */
282  virtual void getActivities(doublereal* ac) const;
283 
284  //! Get the array of non-dimensional molar-based activity coefficients at
285  //! the current solution temperature, pressure, and solution concentration.
286  /*!
287  * @param ac Output vector of activity coefficients. Length: m_kk.
288  */
289  virtual void getActivityCoefficients(doublereal* ac) const;
290 
291  //! Get the array of temperature derivatives of the log activity coefficients
292  /*!
293  * This function is a virtual class, but it first appears in GibbsExcessVPSSTP
294  * class and derived classes from GibbsExcessVPSSTP.
295  *
296  * units = 1/Kelvin
297  *
298  * @param dlnActCoeffdT Output vector of temperature derivatives of the
299  * log Activity Coefficients. length = m_kk
300  */
301  virtual void getdlnActCoeffdT(doublereal* dlnActCoeffdT) const {
302  err("getdlnActCoeffdT");
303  }
304 
305  //! Get the array of derivatives of the log activity coefficients with respect to the log of the species mole numbers
306  /*!
307  * Implementations should take the derivative of the logarithm of the activity coefficient with respect to a
308  * species log mole number (with all other species mole numbers held constant). The default treatment in the
309  * %ThermoPhase object is to set this vector to zero.
310  *
311  * units = 1 / kmol
312  *
313  * dlnActCoeffdlnN[ ld * k + m] will contain the derivative of log act_coeff for the <I>m</I><SUP>th</SUP>
314  * species with respect to the number of moles of the <I>k</I><SUP>th</SUP> species.
315  *
316  * \f[
317  * \frac{d \ln(\gamma_m) }{d \ln( n_k ) }\Bigg|_{n_i}
318  * \f]
319  *
320  * @param ld Number of rows in the matrix
321  * @param dlnActCoeffdlnN Output vector of derivatives of the
322  * log Activity Coefficients. length = m_kk * m_kk
323  */
324  virtual void getdlnActCoeffdlnN(const size_t ld, doublereal* const dlnActCoeffdlnN) {
325  err(" getdlnActCoeffdlnN: nonzero and nonimplemented");
326  }
327 
328  //! Get the array of log concentration-like derivatives of the
329  //! log activity coefficients
330  /*!
331  * This function is a virtual method. For ideal mixtures
332  * (unity activity coefficients), this can return zero.
333  * Implementations should take the derivative of the
334  * logarithm of the activity coefficient with respect to the
335  * logarithm of the concentration-like variable (i.e. number of moles in
336  * in a unit volume. ) that represents the standard state.
337  * This quantity is to be used in conjunction with derivatives of
338  * that concentration-like variable when the derivative of the chemical
339  * potential is taken.
340  *
341  * units = dimensionless
342  *
343  * @param dlnActCoeffdlnX Output vector of derivatives of the
344  * log Activity Coefficients. length = m_kk
345  */
346  virtual void getdlnActCoeffdlnX(doublereal* dlnActCoeffdlnX) const {
347  err("getdlnActCoeffdlnX");
348  }
349 
350  //@}
351  /// @name Partial Molar Properties of the Solution
352  //@{
353 
354  /**
355  * Get the species electrochemical potentials.
356  * These are partial molar quantities.
357  * This method adds a term \f$ Fz_k \phi_k \f$ to the
358  * to each chemical potential.
359  *
360  * Units: J/kmol
361  *
362  * @param mu output vector containing the species electrochemical potentials.
363  * Length: m_kk.
364  */
365  void getElectrochemPotentials(doublereal* mu) const;
366 
367  //! Return an array of partial molar volumes for the
368  //! species in the mixture. Units: m^3/kmol.
369  /*!
370  * Frequently, for this class of thermodynamics representations,
371  * the excess Volume due to mixing is zero. Here, we set it as
372  * a default. It may be overridden in derived classes.
373  *
374  * @param vbar Output vector of species partial molar volumes.
375  * Length = m_kk. units are m^3/kmol.
376  */
377  virtual void getPartialMolarVolumes(doublereal* vbar) const;
378  virtual const vector_fp& getPartialMolarVolumes() const;
379 
380  /**
381  * @}
382  * @name Setting the State
383  * These methods set all or part of the thermodynamic state.
384  * @{
385  */
386 
387  //! Set the temperature (K) and pressure (Pa)
388  /*!
389  * Set the temperature and pressure.
390  *
391  * @param t Temperature (K)
392  * @param p Pressure (Pa)
393  */
394  virtual void setState_TP(doublereal t, doublereal p);
395 
396  /**
397  * Set the mass fractions to the specified values, and then
398  * normalize them so that they sum to 1.0.
399  * @param y Array of unnormalized mass fraction values (input).
400  * Must have a length greater than or equal to the number of
401  * species.
402  *
403  * @param y Input vector of mass fractions.
404  * Length is m_kk.
405  */
406  virtual void setMassFractions(const doublereal* const y);
407 
408  /**
409  * Set the mass fractions to the specified values without
410  * normalizing. This is useful when the normalization
411  * condition is being handled by some other means, for example
412  * by a constraint equation as part of a larger set of
413  * equations.
414  *
415  * @param y Input vector of mass fractions.
416  * Length is m_kk.
417  */
418  virtual void setMassFractions_NoNorm(const doublereal* const y);
419 
420  /**
421  * Set the mole fractions to the specified values, and then
422  * normalize them so that they sum to 1.0.
423  * @param x Array of unnormalized mole fraction values (input).
424  * Must have a length greater than or equal to the number of
425  * species.
426  *
427  * @param x Input vector of mole fractions.
428  * Length is m_kk.
429  */
430  virtual void setMoleFractions(const doublereal* const x);
431 
432  /**
433  * Set the mole fractions to the specified values without
434  * normalizing. This is useful when the normalization
435  * condition is being handled by some other means, for example
436  * by a constraint equation as part of a larger set of
437  * equations.
438  *
439  * @param x Input vector of mole fractions.
440  * Length is m_kk.
441  */
442  virtual void setMoleFractions_NoNorm(const doublereal* const x);
443 
444  /**
445  * Set the concentrations to the specified values within the
446  * phase.
447  *
448  * @param c The input vector to this routine is in dimensional
449  * units. For volumetric phases c[k] is the
450  * concentration of the kth species in kmol/m3.
451  * For surface phases, c[k] is the concentration
452  * in kmol/m2. The length of the vector is the number
453  * of species in the phase.
454  */
455  virtual void setConcentrations(const doublereal* const c);
456  //@}
457 
458  /*!
459  * @internal Initialize. This method is provided to allow
460  * subclasses to perform any initialization required after all
461  * species have been added. For example, it might be used to
462  * resize internal work arrays that must have an entry for
463  * each species. The base class implementation does nothing,
464  * and subclasses that do not require initialization do not
465  * need to overload this method. When importing a CTML phase
466  * description, this method is called just prior to returning
467  * from function importPhase.
468  *
469  * @see importCTML.cpp
470  */
471  virtual void initThermo();
472 
473 private:
474  //! Initialize lengths of local variables after all species have
475  //! been identified.
476  void initLengths();
477 
478  //! Error function
479  /*!
480  * Print an error string and exit
481  *
482  * @param msg Message to be printed
483  */
484  doublereal err(const std::string& msg) const;
485 
486 protected:
487  //! utility routine to check mole fraction sum
488  /*!
489  * @param x vector of mole fractions.
490  * @deprecated
491  */
492  double checkMFSum(const doublereal* const x) const;
493 
494 protected:
495  //! Storage for the current values of the mole fractions of the species
496  /*!
497  * This vector is kept up-to-date when the setState functions are called.
498  * Therefore, it may be considered to be an independent variable.
499  *
500  * Note in order to do this, the setState functions are redefined to always
501  * keep this vector current.
502  */
503  mutable std::vector<doublereal> moleFractions_;
504 
505  //! Storage for the current values of the activity coefficients of the
506  //! species
507  mutable std::vector<doublereal> lnActCoeff_Scaled_;
508 
509  //! Storage for the current derivative values of the
510  //! gradients with respect to temperature of the
511  //! log of the activity coefficients of the species
512  mutable std::vector<doublereal> dlnActCoeffdT_Scaled_;
513 
514  //! Storage for the current derivative values of the
515  //! gradients with respect to temperature of the
516  //! log of the activity coefficients of the species
517  mutable std::vector<doublereal> d2lnActCoeffdT2_Scaled_;
518 
519  //! Storage for the current derivative values of the
520  //! gradients with respect to logarithm of the mole fraction of the
521  //! log of the activity coefficients of the species @deprecated
522  mutable std::vector<doublereal> dlnActCoeffdlnN_diag_;
523 
524  //! Storage for the current derivative values of the
525  //! gradients with respect to logarithm of the mole fraction of the
526  //! log of the activity coefficients of the species @deprecated
527  mutable std::vector<doublereal> dlnActCoeffdlnX_diag_;
528 
529  //! Storage for the current derivative values of the gradients with respect to logarithm of the species mole number of the
530  //! log of the activity coefficients of the species
531  /*!
532  * dlnActCoeffdlnN_(k, m) is the derivative of ln(gamma_k) wrt ln mole number of species m
533  */
535 
536  //! Temporary storage space that is fair game
537  mutable std::vector<doublereal> m_pp;
538 };
539 
540 }
541 
542 #endif
virtual void getdlnActCoeffdlnN(const size_t ld, doublereal *const dlnActCoeffdlnN)
Get the array of derivatives of the log activity coefficients with respect to the log of the species ...
std::vector< doublereal > m_pp
Temporary storage space that is fair game.
void initLengths()
Initialize lengths of local variables after all species have been identified.
GibbsExcessVPSSTP & operator=(const GibbsExcessVPSSTP &b)
Assignment operator.
virtual void getActivities(doublereal *ac) const
Get the array of non-dimensional activities (molality based for this class and classes that derive fr...
virtual doublereal logStandardConc(size_t k=0) const
Returns the natural logarithm of the standard concentration of the kth species.
virtual ThermoPhase * duplMyselfAsThermoPhase() const
Duplication routine for objects which inherit from ThermoPhase.
virtual void getUnitsStandardConc(double *uA, int k=0, int sizeUA=6) const
Returns the units of the standard and generalized concentrations Note they have the same units...
std::vector< doublereal > d2lnActCoeffdT2_Scaled_
Storage for the current derivative values of the gradients with respect to temperature of the log of ...
virtual void setState_TP(doublereal t, doublereal p)
Set the temperature (K) and pressure (Pa)
virtual doublereal standardConcentration(size_t k=0) const
The standard concentration used to normalize the generalized concentration.
std::vector< doublereal > dlnActCoeffdlnN_diag_
Storage for the current derivative values of the gradients with respect to logarithm of the mole frac...
A class for 2D arrays stored in column-major (Fortran-compatible) form.
Definition: Array.h:33
virtual void getActivityCoefficients(doublereal *ac) const
Get the array of non-dimensional molar-based activity coefficients at the current solution temperatur...
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:101
virtual int eosType() const
Equation of state type flag.
virtual void setConcentrations(const doublereal *const c)
Set the concentrations to the specified values within the phase.
virtual void getdlnActCoeffdT(doublereal *dlnActCoeffdT) const
Get the array of temperature derivatives of the log activity coefficients.
void calcDensity()
Calculate the density of the mixture using the partial molar volumes and mole fractions as input...
double checkMFSum(const doublereal *const x) const
utility routine to check mole fraction sum
This is a filter class for ThermoPhase that implements some prepatory steps for efficiently handling ...
void getElectrochemPotentials(doublereal *mu) const
Get the species electrochemical potentials.
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...
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...
virtual void setMassFractions_NoNorm(const doublereal *const y)
Set the mass fractions to the specified values without normalizing.
std::vector< doublereal > dlnActCoeffdlnX_diag_
Storage for the current derivative values of the gradients with respect to logarithm of the mole frac...
virtual void getActivityConcentrations(doublereal *c) const
This method returns an array of generalized concentrations.
Header file for a derived class of ThermoPhase that handles variable pressure standard state methods ...
std::vector< doublereal > lnActCoeff_Scaled_
Storage for the current values of the activity coefficients of the species.
std::vector< double > vector_fp
Turn on the use of stl vectors for the basic array type within cantera Vector of doubles.
Definition: ct_defs.h:165
virtual void setPressure(doublereal p)
Set the internally stored pressure (Pa) at constant temperature and composition.
std::vector< doublereal > moleFractions_
Storage for the current values of the mole fractions of the species.
Array2D dlnActCoeffdlnN_
Storage for the current derivative values of the gradients with respect to logarithm of the species m...
virtual void setMoleFractions_NoNorm(const doublereal *const x)
Set the mole fractions to the specified values without normalizing.
std::vector< doublereal > dlnActCoeffdT_Scaled_
Storage for the current derivative values of the gradients with respect to temperature of the log of ...
doublereal err(const std::string &msg) const
Error function.
virtual void getdlnActCoeffdlnX(doublereal *dlnActCoeffdlnX) const
Get the array of log concentration-like derivatives of the log activity coefficients.