Cantera  2.5.1
FixedChemPotSSTP.h
Go to the documentation of this file.
1 /**
2  * @file FixedChemPotSSTP.h
3  * Header file for the FixedChemPotSSTP class, which represents a fixed-composition
4  * incompressible substance with a constant chemical potential (see \ref thermoprops and
5  * class \link Cantera::FixedChemPotSSTP FixedChemPotSSTP\endlink)
6  */
7 
8 // This file is part of Cantera. See License.txt in the top-level directory or
9 // at https://cantera.org/license.txt for license and copyright information.
10 
11 #ifndef CT_FIXEDCHEMPOTSSTP_H
12 #define CT_FIXEDCHEMPOTSSTP_H
13 
14 #include "SingleSpeciesTP.h"
15 
16 namespace Cantera
17 {
18 
19 //! Class FixedChemPotSSTP represents a stoichiometric (fixed composition)
20 //! incompressible substance.
21 /*!
22  * This class internally changes the independent degree of freedom from density
23  * to pressure. This is necessary because the phase is incompressible. It uses a
24  * zero volume approximation.
25  *
26  * ## Specification of Species Standard State Properties
27  *
28  * This class inherits from SingleSpeciesTP. It uses a single value for the
29  * chemical potential which is assumed to be constant with respect to
30  * temperature and pressure.
31  *
32  * The reference state thermodynamics is inherited from SingleSpeciesTP.
33  * However, it's only used to set the initial chemical potential to the value of
34  * the chemical potential at the starting conditions. Thereafter, it is ignored.
35  *
36  * For a zero volume material, the internal energy and the enthalpy are equal to
37  * the chemical potential. The entropy, the heat capacity, and the molar volume
38  * are equal to zero.
39  *
40  * ## Specification of Solution Thermodynamic Properties
41  *
42  * All solution properties are obtained from the standard state species
43  * functions, since there is only one species in the phase.
44  *
45  * ## Application within Kinetics Managers
46  *
47  * The standard concentration is equal to 1.0. This means that the kinetics
48  * operator works on an (activities basis). Since this is a stoichiometric
49  * substance, this means that the concentration of this phase drops out of
50  * kinetics expressions.
51  *
52  * An example of a reaction using this is a sticking coefficient reaction of a
53  * substance in an ideal gas phase on a surface with a bulk phase species in
54  * this phase. In this case, the rate of progress for this reaction, \f$ R_s
55  * \f$, may be expressed via the following equation:
56  * \f[
57  * R_s = k_s C_{gas}
58  * \f]
59  * where the units for \f$ R_s \f$ are kmol m-2 s-1. \f$ C_{gas} \f$ has units
60  * of kmol m-3. Therefore, the kinetic rate constant, \f$ k_s \f$, has units of
61  * m s-1. Nowhere does the concentration of the bulk phase appear in the rate
62  * constant expression, since it's a stoichiometric phase, and the activity is
63  * always equal to 1.0.
64  *
65  * ## Instantiation of the Class
66  *
67  * This phase may be instantiated by calling the default ThermoFactory routine
68  * for %Cantera. This new FixedChemPotSSTP object must then have a standalone
69  * XML file description an example of which is given below.
70  *
71  * It may also be created by the following code snippets. The code includes the
72  * special member function setChemicalPotential( chempot), which sets the
73  * chemical potential to a specific value in J / kmol.
74  *
75  * @code
76  * XML_Node *xm = get_XML_NameID("phase", iFile + "#Li(Fixed)", 0);
77  * FixedChemPotSSTP *LiFixed = new FixedChemPotSSTP(*xm);
78  * // Set the chemical potential to -2.3E7 J/kmol
79  * LiFixed->setChemicalPotential(-2.3E7.)
80  * @endcode
81  *
82  * or by the following call to importPhase():
83  *
84  * @code
85  * XML_Node *xm = get_XML_NameID("phase", iFile + "#NaCl(S)", 0);
86  * FixedChemPotSSTP solid;
87  * importPhase(*xm, &solid);
88  * @endcode
89  *
90  * The phase may also be created by a special constructor so that element
91  * potentials may be set. The constructor takes the name of the element and
92  * the value of the element chemical potential. An example is given below.
93  *
94  * @code
95  * FixedChemPotSSTP *LiFixed = new FixedChemPotSSTP("Li", -2.3E7);
96  * @endcode
97  *
98  * ## XML Example
99  *
100  * The phase model name for this is called FixedChemPot. It must be supplied
101  * as the model attribute of the thermo XML element entry.
102  *
103  * @code
104  * <?xml version="1.0"?>
105  * <ctml>
106  * <validate reactions="yes" species="yes"/>
107  *
108  * <!-- phase NaCl(S) -->
109  * <phase dim="3" id="LiFixed">
110  * <elementArray datasrc="elements.xml">
111  * Li
112  * </elementArray>
113  * <speciesArray datasrc="#species_Li(Fixed)">
114  * LiFixed
115  * </speciesArray>
116  * <thermo model="FixedChemPot">
117  * <chemicalPotential units="J/kmol"> -2.3E7 </chemicalPotential>
118  * </thermo>
119  * <transport model="None"/>
120  * <kinetics model="none"/>
121  * </phase>
122  *
123  * <!-- species definitions -->
124  * <speciesData id="species_Li(Fixed)">
125  * <species name="LiFixed">
126  * <atomArray> Li:1 </atomArray>
127  * <thermo>
128  * <Shomate Pref="1 bar" Tmax="1075.0" Tmin="250.0">
129  * <floatArray size="7">
130  * 50.72389, 6.672267, -2.517167,
131  * 10.15934, -0.200675, -427.2115,
132  * 130.3973
133  * </floatArray>
134  * </Shomate>
135  * </thermo>
136  * </species>
137  * </speciesData>
138  * </ctml>
139  * @endcode
140  *
141  * The model attribute, "FixedChemPot", on the thermo element
142  * identifies the phase as being a FixedChemPotSSTP object.
143  *
144  * @ingroup thermoprops
145  *
146  * @deprecated To be removed after Cantera 2.5. Use the `fixed-stoichiometry`
147  * thermo model (class StoichSubstance) with a `constant-cp` species thermo
148  * model, `h0` set to the desired chemical potential, and `s0` set to 0.
149  */
151 {
152 public:
153  //! Default constructor for the FixedChemPotSSTP class
155 
156  //! Construct and initialize a FixedChemPotSSTP ThermoPhase object
157  //! directly from an ASCII input file
158  /*!
159  * @param infile name of the input file
160  * @param id name of the phase id in the file.
161  * If this is blank, the first phase in the file is used.
162  */
163  FixedChemPotSSTP(const std::string& infile, const std::string& id = "");
164 
165  //! Construct and initialize a FixedChemPotSSTP ThermoPhase object
166  //! directly from an XML database
167  /*!
168  * @param phaseRef XML node pointing to a FixedChemPotSSTP description
169  * @param id Id of the phase.
170  */
171  FixedChemPotSSTP(XML_Node& phaseRef, const std::string& id = "");
172 
173  //! Special constructor for the FixecChemPotSSTP class setting an element
174  //! chemical potential directly
175  /*!
176  * This will create a FixedChemPotSSTP consisting of a single species with the
177  * stoichiometry of one of the specified atom. It will have a chemical potential
178  * that is given by the second argument.
179  *
180  * @param Ename String name of the element
181  * @param chemPot Value of the chemical potential of that element (J/kmol)
182  */
183  FixedChemPotSSTP(const std::string& Ename, doublereal chemPot);
184 
185  virtual std::string type() const {
186  return "FixedChemPot";
187  }
188 
189  virtual bool isCompressible() const {
190  return false;
191  }
192 
193  //! @}
194  //! @name Mechanical Equation of State
195  //! @{
196 
197  //! Report the Pressure. Units: Pa.
198  /*!
199  * For an incompressible substance, the density is independent of pressure.
200  * This method simply returns the stored pressure value.
201  */
202  virtual doublereal pressure() const;
203 
204  //! Set the pressure at constant temperature. Units: Pa.
205  /*!
206  * For an incompressible substance, the density is independent of pressure.
207  * Therefore, this method only stores the specified pressure value. It does
208  * not modify the density.
209  *
210  * @param p Pressure (units - Pa)
211  */
212  virtual void setPressure(doublereal p);
213 
214  virtual doublereal isothermalCompressibility() const;
215  virtual doublereal thermalExpansionCoeff() const;
216 
217  /**
218  * @}
219  * @name Activities, Standard States, and Activity Concentrations
220  *
221  * This section is largely handled by parent classes, since there
222  * is only one species. Therefore, the activity is equal to one.
223  * @{
224  */
225 
226  virtual Units standardConcentrationUnits() const;
227 
228  //! @copydoc ThermoPhase::getActivityConcentrations
229  /*!
230  * For a stoichiometric substance, there is only one species, and the
231  * generalized concentration is 1.0.
232  */
233  virtual void getActivityConcentrations(doublereal* c) const;
234 
235  //! Return the standard concentration for the kth species
236  /*!
237  * The standard concentration \f$ C^0_k \f$ used to normalize the activity
238  * (i.e., generalized) concentration. This phase assumes that the kinetics
239  * operator works on an dimensionless basis. Thus, the standard
240  * concentration is equal to 1.0.
241  *
242  * @param k Optional parameter indicating the species. The default is to
243  * assume this refers to species 0.
244  * @return
245  * Returns The standard Concentration as 1.0
246  */
247  virtual doublereal standardConcentration(size_t k=0) const;
248  virtual doublereal logStandardConc(size_t k=0) const;
249 
250  //! Get the array of chemical potentials at unit activity for the species at
251  //! their standard states at the current *T* and *P* of the solution.
252  /*!
253  * For a stoichiometric substance, there is no activity term in the chemical
254  * potential expression, and therefore the standard chemical potential and
255  * the chemical potential are both equal to the molar Gibbs function.
256  *
257  * These are the standard state chemical potentials \f$ \mu^0_k(T,P) \f$.
258  * The values are evaluated at the current temperature and pressure of the
259  * solution
260  *
261  * @param mu0 Output vector of chemical potentials. Length: m_kk.
262  */
263  virtual void getStandardChemPotentials(doublereal* mu0) const;
264 
265  //@}
266  /// @name Partial Molar Properties of the Solution
267  /// These properties are handled by the parent class, SingleSpeciesTP
268  //@{
269 
270  //! Get the species partial molar volumes. Units: m^3/kmol.
271  /*!
272  * This is the phase molar volume. \f$ V(T,P) = V_o(T,P) \f$.
273  *
274  * set to zero.
275  *
276  * @param vbar On return, contains the molar volume of the single species
277  * and the phase. Units are m^3 / kmol. Length = 1
278  */
279  virtual void getPartialMolarVolumes(doublereal* vbar) const;
280 
281  //@}
282  /// @name Properties of the Standard State of the Species in the Solution
283  //@{
284 
285  virtual void getEnthalpy_RT(doublereal* hrt) const;
286  virtual void getEntropy_R(doublereal* sr) const;
287  virtual void getGibbs_RT(doublereal* grt) const;
288  virtual void getCp_R(doublereal* cpr) const;
289 
290  //! Returns the vector of nondimensional Internal Energies of the standard
291  //! state species at the current *T* and *P* of the solution
292  /*!
293  * For an incompressible, stoichiometric substance, the molar internal
294  * energy is independent of pressure. Since the thermodynamic properties are
295  * specified by giving the standard-state enthalpy, the term \f$ P_{ref}
296  * \hat v\f$ is subtracted from the specified reference molar enthalpy to
297  * compute the standard state molar internal energy.
298  *
299  * @param urt output vector of nondimensional standard state
300  * internal energies of the species. Length: m_kk.
301  */
302  virtual void getIntEnergy_RT(doublereal* urt) const;
303 
304  //! Get the molar volumes of each species in their standard states at the
305  //! current *T* and *P* of the solution.
306  /*
307  * units = m^3 / kmol
308  *
309  * We set this to zero
310  *
311  * @param vbar On output this contains the standard volume of the species
312  * and phase (m^3/kmol). Vector of length 1
313  */
314  virtual void getStandardVolumes(doublereal* vbar) const;
315 
316  //@}
317  /// @name Thermodynamic Values for the Species Reference States
318  //@{
319 
320  virtual void getIntEnergy_RT_ref(doublereal* urt) const;
321  virtual void getEnthalpy_RT_ref(doublereal* hrt) const;
322  virtual void getGibbs_RT_ref(doublereal* grt) const;
323  virtual void getGibbs_ref(doublereal* g) const;
324  virtual void getEntropy_R_ref(doublereal* er) const;
325  virtual void getCp_R_ref(doublereal* cprt) const;
326 
327  //@}
328 
329  virtual void initThermoXML(XML_Node& phaseNode, const std::string& id);
330 
331  virtual void initThermo();
332 
333  //! Set the equation of state parameters
334  /*!
335  * @internal
336  * @param n number of parameters = 1
337  * @param c array of \a n coefficients
338  * c[0] = density of phase [ kg/m3 ]
339  */
340  virtual void setParameters(int n, doublereal* const c);
341 
342  //! Get the equation of state parameters in a vector
343  /*!
344  * @internal
345  *
346  * @param n number of parameters
347  * @param c array of \a n coefficients
348  *
349  * For this phase:
350  * - n = 1
351  * - c[0] = density of phase [ kg/m3 ]
352  */
353  virtual void getParameters(int& n, doublereal* const c) const;
354 
355  //! Set equation of state parameter values from XML entries.
356  /*!
357  * This method is called by function importPhase() when processing a phase
358  * definition in an input file. It should be overloaded in subclasses to set
359  * any parameters that are specific to that particular phase model. Note,
360  * this method is called before the phase is initialized with elements
361  * and/or species.
362  *
363  * For this phase, the chemical potential is set.
364  *
365  * @param eosdata An XML_Node object corresponding to
366  * the "thermo" entry for this phase in the input file.
367  *
368  * eosdata points to the thermo block, and looks like this:
369  *
370  * @code
371  * <phase id="stoichsolid" >
372  * <thermo model="FixedChemPot">
373  * <chemicalPotential units="J/kmol"> -2.7E7 </chemicalPotential>
374  * </thermo>
375  * </phase>
376  * @endcode
377  */
378  virtual void setParametersFromXML(const XML_Node& eosdata);
379 
380  //! Function to set the chemical potential directly
381  /*!
382  * @param chemPot Value of the chemical potential (units J/kmol)
383  */
384  void setChemicalPotential(doublereal chemPot);
385 
386 protected:
387  //! Value of the chemical potential of the bath species
388  /*!
389  * units are J/kmol
390  */
391  doublereal chemPot_;
392 };
393 
394 }
395 
396 #endif
Cantera::FixedChemPotSSTP::getIntEnergy_RT_ref
virtual void getIntEnergy_RT_ref(doublereal *urt) const
Returns the vector of nondimensional internal Energies of the reference state at the current temperat...
Definition: FixedChemPotSSTP.cpp:176
Cantera::FixedChemPotSSTP::isothermalCompressibility
virtual doublereal isothermalCompressibility() const
Returns the isothermal compressibility. Units: 1/Pa.
Definition: FixedChemPotSSTP.cpp:98
Cantera::FixedChemPotSSTP::setParametersFromXML
virtual void setParametersFromXML(const XML_Node &eosdata)
Set equation of state parameter values from XML entries.
Definition: FixedChemPotSSTP.cpp:250
Cantera::FixedChemPotSSTP::getCp_R
virtual void getCp_R(doublereal *cpr) const
Get the nondimensional Heat Capacities at constant pressure for the species standard states at the cu...
Definition: FixedChemPotSSTP.cpp:159
Cantera::FixedChemPotSSTP::getActivityConcentrations
virtual void getActivityConcentrations(doublereal *c) const
This method returns an array of generalized concentrations.
Definition: FixedChemPotSSTP.cpp:115
Cantera::FixedChemPotSSTP::getIntEnergy_RT
virtual void getIntEnergy_RT(doublereal *urt) const
Returns the vector of nondimensional Internal Energies of the standard state species at the current T...
Definition: FixedChemPotSSTP.cpp:164
Cantera::FixedChemPotSSTP::type
virtual std::string type() const
String indicating the thermodynamic model implemented.
Definition: FixedChemPotSSTP.h:185
Cantera::FixedChemPotSSTP::getGibbs_ref
virtual void getGibbs_ref(doublereal *g) const
Returns the vector of the Gibbs function of the reference state at the current temperature of the sol...
Definition: FixedChemPotSSTP.cpp:196
Cantera::FixedChemPotSSTP::getStandardVolumes
virtual void getStandardVolumes(doublereal *vbar) const
Get the molar volumes of each species in their standard states at the current T and P of the solution...
Definition: FixedChemPotSSTP.cpp:169
Cantera::FixedChemPotSSTP::getEnthalpy_RT
virtual void getEnthalpy_RT(doublereal *hrt) const
Get the nondimensional Enthalpy functions for the species at their standard states at the current T a...
Definition: FixedChemPotSSTP.cpp:144
Cantera::FixedChemPotSSTP::standardConcentrationUnits
virtual Units standardConcentrationUnits() const
Returns the units of the "standard concentration" for this phase.
Definition: FixedChemPotSSTP.cpp:110
Cantera::FixedChemPotSSTP::getStandardChemPotentials
virtual void getStandardChemPotentials(doublereal *mu0) const
Get the array of chemical potentials at unit activity for the species at their standard states at the...
Definition: FixedChemPotSSTP.cpp:139
Cantera::FixedChemPotSSTP
Class FixedChemPotSSTP represents a stoichiometric (fixed composition) incompressible substance.
Definition: FixedChemPotSSTP.h:150
Cantera::FixedChemPotSSTP::getParameters
virtual void getParameters(int &n, doublereal *const c) const
Get the equation of state parameters in a vector.
Definition: FixedChemPotSSTP.cpp:244
Cantera::FixedChemPotSSTP::getEnthalpy_RT_ref
virtual void getEnthalpy_RT_ref(doublereal *hrt) const
Returns the vector of nondimensional enthalpies of the reference state at the current temperature of ...
Definition: FixedChemPotSSTP.cpp:181
Cantera::FixedChemPotSSTP::thermalExpansionCoeff
virtual doublereal thermalExpansionCoeff() const
Return the volumetric thermal expansion coefficient. Units: 1/K.
Definition: FixedChemPotSSTP.cpp:103
Cantera::FixedChemPotSSTP::getGibbs_RT
virtual void getGibbs_RT(doublereal *grt) const
Get the nondimensional Gibbs functions for the species in their standard states at the current T and ...
Definition: FixedChemPotSSTP.cpp:154
Cantera::FixedChemPotSSTP::setParameters
virtual void setParameters(int n, doublereal *const c)
Set the equation of state parameters.
Definition: FixedChemPotSSTP.cpp:239
Cantera::SingleSpeciesTP
Definition: SingleSpeciesTP.h:56
Cantera::FixedChemPotSSTP::getCp_R_ref
virtual void getCp_R_ref(doublereal *cprt) const
Returns the vector of nondimensional constant pressure heat capacities of the reference state at the ...
Definition: FixedChemPotSSTP.cpp:201
Cantera::FixedChemPotSSTP::chemPot_
doublereal chemPot_
Value of the chemical potential of the bath species.
Definition: FixedChemPotSSTP.h:391
Cantera::FixedChemPotSSTP::getEntropy_R
virtual void getEntropy_R(doublereal *sr) const
Get the array of nondimensional Entropy functions for the standard state species at the current T and...
Definition: FixedChemPotSSTP.cpp:149
Cantera::FixedChemPotSSTP::standardConcentration
virtual doublereal standardConcentration(size_t k=0) const
Return the standard concentration for the kth species.
Definition: FixedChemPotSSTP.cpp:120
Cantera::FixedChemPotSSTP::logStandardConc
virtual doublereal logStandardConc(size_t k=0) const
Natural logarithm of the standard concentration of the kth species.
Definition: FixedChemPotSSTP.cpp:125
Cantera::XML_Node
Class XML_Node is a tree-based representation of the contents of an XML file.
Definition: xml.h:103
Cantera::FixedChemPotSSTP::getPartialMolarVolumes
virtual void getPartialMolarVolumes(doublereal *vbar) const
Get the species partial molar volumes. Units: m^3/kmol.
Definition: FixedChemPotSSTP.cpp:132
Cantera::FixedChemPotSSTP::getEntropy_R_ref
virtual void getEntropy_R_ref(doublereal *er) const
Returns the vector of nondimensional entropies of the reference state at the current temperature of t...
Definition: FixedChemPotSSTP.cpp:186
Cantera::FixedChemPotSSTP::initThermo
virtual void initThermo()
Initialize the ThermoPhase object after all species have been set up.
Definition: FixedChemPotSSTP.cpp:231
Cantera::FixedChemPotSSTP::setChemicalPotential
void setChemicalPotential(doublereal chemPot)
Function to set the chemical potential directly.
Definition: FixedChemPotSSTP.cpp:263
Cantera::Units
A representation of the units associated with a dimensional quantity.
Definition: Units.h:29
Cantera::FixedChemPotSSTP::FixedChemPotSSTP
FixedChemPotSSTP()
Default constructor for the FixedChemPotSSTP class.
Definition: FixedChemPotSSTP.cpp:23
Cantera::FixedChemPotSSTP::getGibbs_RT_ref
virtual void getGibbs_RT_ref(doublereal *grt) const
Returns the vector of nondimensional Gibbs Free Energies of the reference state at the current temper...
Definition: FixedChemPotSSTP.cpp:191
Cantera::FixedChemPotSSTP::isCompressible
virtual bool isCompressible() const
Return whether phase represents a compressible substance.
Definition: FixedChemPotSSTP.h:189
SingleSpeciesTP.h
Cantera::FixedChemPotSSTP::initThermoXML
virtual void initThermoXML(XML_Node &phaseNode, const std::string &id)
Import and initialize a ThermoPhase object using an XML tree.
Definition: FixedChemPotSSTP.cpp:208
Cantera
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:263
Cantera::FixedChemPotSSTP::setPressure
virtual void setPressure(doublereal p)
Set the pressure at constant temperature. Units: Pa.
Definition: FixedChemPotSSTP.cpp:93
Cantera::FixedChemPotSSTP::pressure
virtual doublereal pressure() const
Report the Pressure. Units: Pa.
Definition: FixedChemPotSSTP.cpp:88