Cantera  2.1.2
StoichSubstanceSSTP.h
Go to the documentation of this file.
1 /**
2  * @file StoichSubstanceSSTP.h
3  * Header file for the StoichSubstanceSSTP class, which represents a fixed-composition
4  * incompressible substance (see \ref thermoprops and
5  * class \link Cantera::StoichSubstanceSSTP StoichSubstanceSSTP\endlink)
6  */
7 
8 /*
9  * Copyright (2005) Sandia Corporation. Under the terms of
10  * Contract DE-AC04-94AL85000 with Sandia Corporation, the
11  * U.S. Government retains certain rights in this software.
12  */
13 #ifndef CT_STOICHSUBSTANCESSTP_H
14 #define CT_STOICHSUBSTANCESSTP_H
15 
16 #include "mix_defs.h"
17 #include "SingleSpeciesTP.h"
18 #include "SpeciesThermo.h"
19 
20 namespace Cantera
21 {
22 
23 //! Class %StoichSubstanceSSTP represents a stoichiometric (fixed
24 //! composition) incompressible substance.
25 /*!
26  * This class internally changes the independent degree of freedom from
27  * density to pressure. This is necessary because the phase is
28  * incompressible. It uses a constant volume approximation.
29  *
30  * <b> Specification of Species Standard %State Properties </b>
31  *
32  * This class inherits from SingleSpeciesTP.
33  * It is assumed that the reference state thermodynamics may be
34  * obtained by a pointer to a populated species thermodynamic property
35  * manager class (see ThermoPhase::m_spthermo). How to relate pressure
36  * changes to the reference state thermodynamics is resolved at this level.
37  *
38  * For an incompressible,
39  * stoichiometric substance, the molar internal energy is
40  * independent of pressure. Since the thermodynamic properties
41  * are specified by giving the standard-state enthalpy, the
42  * term \f$ P_0 \hat v\f$ is subtracted from the specified molar
43  * enthalpy to compute the molar internal energy. The entropy is
44  * assumed to be independent of the pressure.
45  *
46  * The enthalpy function is given by the following relation.
47  *
48  * \f[
49  * h^o_k(T,P) =
50  * h^{ref}_k(T) + \tilde v \left( P - P_{ref} \right)
51  * \f]
52  *
53  * For an incompressible,
54  * stoichiometric substance, the molar internal energy is
55  * independent of pressure. Since the thermodynamic properties
56  * are specified by giving the standard-state enthalpy, the
57  * term \f$ P_{ref} \tilde v\f$ is subtracted from the specified reference molar
58  * enthalpy to compute the molar internal energy.
59  *
60  * \f[
61  * u^o_k(T,P) = h^{ref}_k(T) - P_{ref} \tilde v
62  * \f]
63  *
64  * The standard state heat capacity and entropy are independent
65  * of pressure. The standard state gibbs free energy is obtained
66  * from the enthalpy and entropy functions.
67  *
68  * <b> Specification of Solution Thermodynamic Properties </b>
69  *
70  * All solution properties are obtained from the standard state
71  * species functions, since there is only one species in the phase.
72  *
73  * <b> Application within %Kinetics Managers </b>
74  *
75  * The standard concentration is equal to 1.0. This means that the
76  * kinetics operator works on an (activities basis). Since this
77  * is a stoichiometric substance, this means that the concentration
78  * of this phase drops out of kinetics expressions.
79  *
80  * An example of a reaction using this is a sticking coefficient
81  * reaction of a substance in an ideal gas phase on a surface with a bulk phase
82  * species in this phase. In this case, the rate of progress for this
83  * reaction, \f$ R_s \f$, may be expressed via the following equation:
84  * \f[
85  * R_s = k_s C_{gas}
86  * \f]
87  * where the units for \f$ R_s \f$ are kmol m-2 s-1. \f$ C_{gas} \f$ has units
88  * of kmol m-3. Therefore, the kinetic rate constant, \f$ k_s \f$, has
89  * units of m s-1. Nowhere does the concentration of the bulk phase
90  * appear in the rate constant expression, since it's a stoichiometric
91  * phase and the activity is always equal to 1.0.
92  *
93  * <b> Instantiation of the Class </b>
94  *
95  * The constructor for this phase is NOT located in the default ThermoFactory
96  * for %Cantera. However, a new %StoichSubstanceSSTP may be created by
97  * the following code snippets:
98  *
99  * @code
100  * sprintf(file_ID,"%s#NaCl(S)", iFile);
101  * XML_Node *xm = get_XML_NameID("phase", file_ID, 0);
102  * StoichSubstanceSSTP *solid = new StoichSubstanceSSTP(*xm);
103  * @endcode
104  *
105  * or by the following call to importPhase():
106  *
107  * @code
108  * sprintf(file_ID,"%s#NaCl(S)", iFile);
109  * XML_Node *xm = get_XML_NameID("phase", file_ID, 0);
110  * StoichSubstanceSSTP solid;
111  * importPhase(*xm, &solid);
112  * @endcode
113  *
114  * <b> XML Example </b>
115  *
116  * The phase model name for this is called StoichSubstance. It must be supplied
117  * as the model attribute of the thermo XML element entry.
118  * Within the phase XML block,
119  * the density of the phase must be specified. An example of an XML file
120  * this phase is given below.
121  *
122  * @code
123  * <!-- phase NaCl(S) -->
124  * <phase dim="3" id="NaCl(S)">
125  * <elementArray datasrc="elements.xml">
126  * Na Cl
127  * </elementArray>
128  * <speciesArray datasrc="#species_NaCl(S)"> NaCl(S) </speciesArray>
129  * <thermo model="StoichSubstanceSSTP">
130  * <density units="g/cm3">2.165</density>
131  * </thermo>
132  * <transport model="None"/>
133  * <kinetics model="none"/>
134  * </phase>
135  *
136  * <!-- species definitions -->
137  * <speciesData id="species_NaCl(S)">
138  * <!-- species NaCl(S) -->
139  * <species name="NaCl(S)">
140  * <atomArray> Na:1 Cl:1 </atomArray>
141  * <thermo>
142  * <Shomate Pref="1 bar" Tmax="1075.0" Tmin="250.0">
143  * <floatArray size="7">
144  * 50.72389, 6.672267, -2.517167,
145  * 10.15934, -0.200675, -427.2115,
146  * 130.3973
147  * </floatArray>
148  * </Shomate>
149  * </thermo>
150  * <density units="g/cm3">2.165</density>
151  * </species>
152  * </speciesData> @endcode
153  *
154  * The model attribute, "StoichSubstanceSSTP", on the thermo element
155  * identifies the phase as being a StoichSubstanceSSTP object.
156  *
157  * @ingroup thermoprops
158  */
160 {
161 public:
162  //! Default constructor for the StoichSubstanceSSTP class
164 
165  //! Construct and initialize a StoichSubstanceSSTP ThermoPhase object
166  //! directly from an ASCII input file
167  /*!
168  * @param infile name of the input file
169  * @param id name of the phase id in the file.
170  * If this is blank, the first phase in the file is used.
171  */
172  StoichSubstanceSSTP(const std::string& infile, std::string id = "");
173 
174  //! Construct and initialize a StoichSubstanceSSTP ThermoPhase object
175  //! directly from an XML database
176  /*!
177  * @param phaseRef XML node pointing to a StoichSubstanceSSTP description
178  * @param id Id of the phase.
179  */
180  StoichSubstanceSSTP(XML_Node& phaseRef, const std::string& id = "");
181 
182  //! Copy constructor
183  /*!
184  * @param right Object to be copied
185  */
187 
188  //! Assignment operator
189  /*!
190  * @param right Object to be copied
191  */
193 
194  //! Duplication function
195  /*!
196  * This virtual function is used to create a duplicate of the
197  * current phase. It's used to duplicate the phase when given
198  * a ThermoPhase pointer to the phase.
199  *
200  * @return It returns a ThermoPhase pointer.
201  */
203 
204  /**
205  * Equation of state flag.
206  *
207  * Returns the value cStoichSubstance, defined in mix_defs.h.
208  */
209  virtual int eosType() const;
210 
211  //! @name Mechanical Equation of State
212  //! @{
213 
214  //! Report the Pressure. Units: Pa.
215  /*!
216  * For an incompressible substance, the density is independent
217  * of pressure. This method simply returns the stored
218  * pressure value.
219  */
220  virtual doublereal pressure() const;
221 
222  //! Set the pressure at constant temperature. Units: Pa.
223  /*!
224  * For an incompressible substance, the density is
225  * independent of pressure. Therefore, this method only
226  * stores the specified pressure value. It does not
227  * modify the density.
228  *
229  * @param p Pressure (units - Pa)
230  */
231  virtual void setPressure(doublereal p);
232 
233  //! Returns the isothermal compressibility. Units: 1/Pa.
234  /*!
235  * The isothermal compressibility is defined as
236  * \f[
237  * \kappa_T = -\frac{1}{v}\left(\frac{\partial v}{\partial P}\right)_T
238  * \f]
239  */
240  virtual doublereal isothermalCompressibility() const;
241 
242  //! Return the volumetric thermal expansion coefficient. Units: 1/K.
243  /*!
244  * The thermal expansion coefficient is defined as
245  * \f[
246  * \beta = \frac{1}{v}\left(\frac{\partial v}{\partial T}\right)_P
247  * \f]
248  */
249  virtual doublereal thermalExpansionCoeff() const ;
250 
251  /**
252  * @}
253  * @name Activities, Standard States, and Activity Concentrations
254  *
255  * This section is largely handled by parent classes, since there
256  * is only one species. Therefore, the activity is equal to one.
257  * @{
258  */
259 
260  //! This method returns an array of generalized concentrations
261  /*!
262  * \f$ C^a_k\f$ are defined such that \f$ a_k = C^a_k /
263  * C^0_k, \f$ where \f$ C^0_k \f$ is a standard concentration
264  * defined below and \f$ a_k \f$ are activities used in the
265  * thermodynamic functions. These activity (or generalized)
266  * concentrations are used
267  * by kinetics manager classes to compute the forward and
268  * reverse rates of elementary reactions.
269  *
270  * For a stoichiometric substance, there is
271  * only one species, and the generalized concentration is 1.0.
272  *
273  * @param c Output array of generalized concentrations. The
274  * units depend upon the implementation of the
275  * reaction rate expressions within the phase.
276  */
277  virtual void getActivityConcentrations(doublereal* c) const;
278 
279  //! Return the standard concentration for the kth species
280  /*!
281  * The standard concentration \f$ C^0_k \f$ used to normalize
282  * the activity (i.e., generalized) concentration.
283  * This phase assumes that the kinetics operator works on an
284  * dimensionless basis. Thus, the standard concentration is
285  * equal to 1.0.
286  *
287  * @param k Optional parameter indicating the species. The default
288  * is to assume this refers to species 0.
289  * @return
290  * Returns The standard Concentration as 1.0
291  */
292  virtual doublereal standardConcentration(size_t k=0) const;
293 
294  //! Natural logarithm of the standard concentration of the kth species.
295  /*!
296  * @param k index of the species (defaults to zero)
297  */
298  virtual doublereal logStandardConc(size_t k=0) const;
299 
300  //! Get the array of chemical potentials at unit activity for the species
301  //! at their standard states at the current <I>T</I> and <I>P</I> of the solution.
302  /*!
303  * For a stoichiometric substance, there is no activity term in
304  * the chemical potential expression, and therefore the
305  * standard chemical potential and the chemical potential
306  * are both equal to the molar Gibbs function.
307  *
308  * These are the standard state chemical potentials \f$ \mu^0_k(T,P)
309  * \f$. The values are evaluated at the current
310  * temperature and pressure of the solution
311  *
312  * @param mu0 Output vector of chemical potentials.
313  * Length: m_kk.
314  */
315  virtual void getStandardChemPotentials(doublereal* mu0) const;
316 
317  //! Returns the units of the standard and generalized concentrations.
318  /*!
319  * Note they have the same units, as their
320  * ratio is defined to be equal to the activity of the kth
321  * species in the solution, which is unitless.
322  *
323  * This routine is used in print out applications where the
324  * units are needed. Usually, MKS units are assumed throughout
325  * the program and in the XML input files.
326  *
327  * The base %ThermoPhase class assigns the default quantities
328  * of (kmol/m3) for all species.
329  * Inherited classes are responsible for overriding the default
330  * values if necessary.
331  *
332  * @param uA Output vector containing the units
333  *
334  * uA[0] = kmol units - default = 1
335  * uA[1] = m units - default = -nDim(), the number of spatial
336  * dimensions in the Phase class.
337  * uA[2] = kg units - default = 0;
338  * uA[3] = Pa(pressure) units - default = 0;
339  * uA[4] = Temperature units - default = 0;
340  * uA[5] = time units - default = 0
341  *
342  * @param k species index. Defaults to 0.
343  * @param sizeUA output int containing the size of the vector.
344  * Currently, this is equal to 6.
345  * @deprecated
346  */
347  virtual void getUnitsStandardConc(doublereal* uA, int k = 0,
348  int sizeUA = 6) const;
349 
350  //@}
351  /// @name Properties of the Standard State of the Species in the Solution
352  //@{
353 
354  //! Get the nondimensional Enthalpy functions for the species
355  //! at their standard states at the current <I>T</I> and <I>P</I> of the solution.
356  /*!
357  * @param hrt Output vector of nondimensional standard state enthalpies.
358  * Length: m_kk.
359  */
360  virtual void getEnthalpy_RT(doublereal* hrt) const;
361 
362  //! Get the array of nondimensional Entropy functions for the
363  //! standard state species at the current <I>T</I> and <I>P</I> of the solution.
364  /*!
365  * @param sr Output vector of nondimensional standard state entropies.
366  * Length: m_kk.
367  */
368  virtual void getEntropy_R(doublereal* sr) const;
369 
370  //! Get the nondimensional Gibbs functions for the species
371  //! in their standard states at the current <I>T</I> and <I>P</I> of the solution.
372  /*!
373  * @param grt Output vector of nondimensional standard state gibbs free energies
374  * Length: m_kk.
375  */
376  virtual void getGibbs_RT(doublereal* grt) const;
377 
378  //! Get the nondimensional Heat Capacities at constant
379  //! pressure for the species standard states
380  //! at the current <I>T</I> and <I>P</I> of the solution
381  /*!
382  * @param cpr Output vector of nondimensional standard state heat capacities
383  * Length: m_kk.
384  */
385  virtual void getCp_R(doublereal* cpr) const;
386 
387  //! Returns the vector of nondimensional Internal Energies of the standard
388  //! state species at the current <I>T</I> and <I>P</I> of the solution
389  /*!
390  * For an incompressible,
391  * stoichiometric substance, the molar internal energy is
392  * independent of pressure. Since the thermodynamic properties
393  * are specified by giving the standard-state enthalpy, the
394  * term \f$ P_{ref} \hat v\f$ is subtracted from the specified reference molar
395  * enthalpy to compute the standard state molar internal energy.
396  *
397  * @param urt output vector of nondimensional standard state
398  * internal energies of the species. Length: m_kk.
399  */
400  virtual void getIntEnergy_RT(doublereal* urt) const;
401 
402  //@}
403  /// @name Thermodynamic Values for the Species Reference States
404  //@{
405 
406  //! Returns the vector of nondimensional
407  //! internal Energies of the reference state at the current temperature
408  //! of the solution and the reference pressure for each species.
409  /*!
410  * @param urt Output vector of nondimensional reference state
411  * internal energies of the species.
412  * Length: m_kk
413  */
414  virtual void getIntEnergy_RT_ref(doublereal* urt) const;
415  // @}
416 
417  /*
418  * @internal Initialize. This method is provided to allow
419  * subclasses to perform any initialization required after all
420  * species have been added. For example, it might be used to
421  * resize internal work arrays that must have an entry for
422  * each species. The base class implementation does nothing,
423  * and subclasses that do not require initialization do not
424  * need to overload this method. When importing a CTML phase
425  * description, this method is called just prior to returning
426  * from function importPhase.
427  *
428  * @see importCTML.cpp
429  */
430  virtual void initThermo();
431 
432  virtual void initThermoXML(XML_Node& phaseNode, const std::string& id);
433 
434  //! Set the equation of state parameters
435  /*!
436  * @internal
437  * The number and meaning of these depends on the subclass.
438  *
439  * @param n number of parameters
440  * @param c array of \a n coefficients
441  * c[0] = density of phase [ kg/m3 ]
442  * @deprecated Use setDensity()
443  */
444  virtual void setParameters(int n, doublereal* const c);
445 
446  //! Get the equation of state parameters in a vector
447  /*!
448  * @internal
449  *
450  * @param n number of parameters
451  * @param c array of \a n coefficients
452  *
453  * For this phase:
454  * - n = 1
455  * - c[0] = density of phase [ kg/m3 ]
456  * @deprecated Use density()
457  */
458  virtual void getParameters(int& n, doublereal* const c) const;
459 
460  //! Set equation of state parameter values from XML entries.
461  /*!
462  * This method is called by function importPhase() in
463  * file importCTML.cpp when processing a phase definition in
464  * an input file. It should be overloaded in subclasses to set
465  * any parameters that are specific to that particular phase
466  * model. Note, this method is called before the phase is
467  * initialized with elements and/or species.
468  *
469  * For this phase, the density of the phase is specified in this block.
470  *
471  * @param eosdata An XML_Node object corresponding to
472  * the "thermo" entry for this phase in the input file.
473  *
474  * eosdata points to the thermo block, and looks like this:
475  *
476  * @code
477  * <phase id="stoichsolid" >
478  * <thermo model="StoichSubstance">
479  * <density units="g/cm3">3.52</density>
480  * </thermo>
481  * </phase>
482  * @endcode
483  */
484  virtual void setParametersFromXML(const XML_Node& eosdata);
485 };
486 
487 //! Class %electrodeElectron represents an electron in a
488 //! metal using the Standard hydrogen reference electrode
489 /*!
490  * The class is based on the electron have a chemical potential
491  * equal to one-half of the entropy of the H2 gas at 1 bar.
492  */
494 {
495 public:
496  //! Default constructor for the electrodeElectron class
498 
499  //! Construct and initialize a electrodeElectron ThermoPhase object
500  //! directly from an ASCII input file
501  /*!
502  * @param infile name of the input file
503  * @param id name of the phase id in the file.
504  * If this is blank, the first phase in the file is used.
505  */
506  electrodeElectron(const std::string& infile, std::string id = "");
507 
508  //! Construct and initialize a electrodeElectron ThermoPhase object
509  //! directly from an XML database
510  /*!
511  * @param phaseRef XML node pointing to a electrodeElectron description
512  * @param id Id of the phase.
513  */
514  electrodeElectron(XML_Node& phaseRef, const std::string& id = "");
515 
516  //! Copy constructor
517  /*!
518  * @param right Object to be copied
519  */
520  electrodeElectron(const electrodeElectron& right);
521 
522  //! Assignment operator
523  /*!
524  * @param right Object to be copied
525  */
527 
528  //! Destructor
529  virtual ~electrodeElectron();
530 
531  void setParametersFromXML(const XML_Node& eosdata);
532 
533  virtual void initThermoXML(XML_Node& phaseNode, const std::string& id);
534 
535  //! @deprecated Use setDensity()
536  void setParameters(int n, doublereal* const c);
537 };
538 
539 }
540 
541 #endif
Class electrodeElectron represents an electron in a metal using the Standard hydrogen reference elect...
void setParametersFromXML(const XML_Node &eosdata)
Set equation of state parameter values from XML entries.
virtual void getIntEnergy_RT_ref(doublereal *urt) const
Returns the vector of nondimensional internal Energies of the reference state at the current temperat...
virtual void getIntEnergy_RT(doublereal *urt) const
Returns the vector of nondimensional Internal Energies of the standard state species at the current T...
virtual doublereal isothermalCompressibility() const
Returns the isothermal compressibility. Units: 1/Pa.
StoichSubstanceSSTP & operator=(const StoichSubstanceSSTP &right)
Assignment operator.
Class XML_Node is a tree-based representation of the contents of an XML file.
Definition: xml.h:100
Virtual base class for the calculation of multiple-species thermodynamic reference-state property man...
virtual void getUnitsStandardConc(doublereal *uA, int k=0, int sizeUA=6) const
Returns the units of the standard and generalized concentrations.
virtual ~electrodeElectron()
Destructor.
electrodeElectron()
Default constructor for the electrodeElectron class.
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:101
Class StoichSubstanceSSTP represents a stoichiometric (fixed composition) incompressible substance...
virtual doublereal pressure() const
Report the Pressure. Units: Pa.
electrodeElectron & operator=(const electrodeElectron &right)
Assignment operator.
virtual doublereal logStandardConc(size_t k=0) const
Natural logarithm of the standard concentration of the kth species.
virtual void getParameters(int &n, doublereal *const c) const
Get the equation of state parameters in a vector.
virtual int eosType() const
Equation of state flag.
Header for the SingleSpeciesTP class, which is a filter class for ThermoPhase, that eases the constru...
virtual doublereal thermalExpansionCoeff() const
Return the volumetric thermal expansion coefficient. Units: 1/K.
virtual void getEnthalpy_RT(doublereal *hrt) const
Get the nondimensional Enthalpy functions for the species at their standard states at the current T a...
void setParameters(int n, doublereal *const c)
StoichSubstanceSSTP()
Default constructor for the StoichSubstanceSSTP class.
virtual void getCp_R(doublereal *cpr) const
Get the nondimensional Heat Capacities at constant pressure for the species standard states at the cu...
virtual void getGibbs_RT(doublereal *grt) const
Get the nondimensional Gibbs functions for the species in their standard states at the current T and ...
virtual void getEntropy_R(doublereal *sr) const
Get the array of nondimensional Entropy functions for the standard state species at the current T and...
virtual void getStandardChemPotentials(doublereal *mu0) const
Get the array of chemical potentials at unit activity for the species at their standard states at the...
virtual void setPressure(doublereal p)
Set the pressure at constant temperature. Units: Pa.
virtual void setParameters(int n, doublereal *const c)
Set the equation of state parameters.
virtual void getActivityConcentrations(doublereal *c) const
This method returns an array of generalized concentrations.
ThermoPhase * duplMyselfAsThermoPhase() const
Duplication function.
virtual void initThermoXML(XML_Node &phaseNode, const std::string &id)
Import and initialize a ThermoPhase object using an XML tree.
virtual void setParametersFromXML(const XML_Node &eosdata)
Set equation of state parameter values from XML entries.
virtual doublereal standardConcentration(size_t k=0) const
Return the standard concentration for the kth species.
The SingleSpeciesTP class is a filter class for ThermoPhase.
virtual void initThermoXML(XML_Node &phaseNode, const std::string &id)
Import and initialize a ThermoPhase object using an XML tree.