Cantera  3.1.0a1
SurfPhase.h
Go to the documentation of this file.
1 /**
2  * @file SurfPhase.h
3  * Header for a simple thermodynamics model of a surface phase
4  * derived from ThermoPhase,
5  * assuming an ideal solution model
6  * (see @ref thermoprops and class @link Cantera::SurfPhase SurfPhase@endlink).
7  */
8 
9 // This file is part of Cantera. See License.txt in the top-level directory or
10 // at https://cantera.org/license.txt for license and copyright information.
11 
12 #ifndef CT_SURFPHASE_H
13 #define CT_SURFPHASE_H
14 
15 #include "ThermoPhase.h"
16 
17 namespace Cantera
18 {
19 
20 //! A simple thermodynamic model for a surface phase, assuming an ideal solution
21 //! model.
22 /*!
23  * The surface consists of a grid of equivalent sites. Surface species may be
24  * defined to occupy one or more sites. The surface species are assumed to be
25  * independent, and thus the species form an ideal solution.
26  *
27  * The density of surface sites is given by the variable @f$ n_0 @f$,
28  * which has SI units of kmol m-2.
29  *
30  * ## Specification of Species Standard State Properties
31  *
32  * It is assumed that the reference state thermodynamics may be obtained by a
33  * pointer to a populated species thermodynamic property manager class (see
34  * ThermoPhase::m_spthermo). How to relate pressure changes to the reference
35  * state thermodynamics is resolved at this level.
36  *
37  * Pressure is defined as an independent variable in this phase. However, it has
38  * no effect on any quantities, as the molar concentration is a constant.
39  *
40  * Therefore, The standard state internal energy for species *k* is equal to the
41  * enthalpy for species *k*.
42  *
43  * @f[
44  * u^o_k = h^o_k
45  * @f]
46  *
47  * Also, the standard state chemical potentials, entropy, and heat capacities
48  * are independent of pressure. The standard state Gibbs free energy is obtained
49  * from the enthalpy and entropy functions.
50  *
51  * ## Specification of Solution Thermodynamic Properties
52  *
53  * The activity of species defined in the phase is given by
54  * @f[
55  * a_k = \theta_k
56  * @f]
57  *
58  * The chemical potential for species *k* is equal to
59  * @f[
60  * \mu_k(T,P) = \mu^o_k(T) + R T \ln \theta_k
61  * @f]
62  *
63  * Pressure is defined as an independent variable in this phase. However, it has
64  * no effect on any quantities, as the molar concentration is a constant.
65  *
66  * The internal energy for species k is equal to the enthalpy for species *k*
67  * @f[
68  * u_k = h_k
69  * @f]
70  *
71  * The entropy for the phase is given by the following relation, which is
72  * independent of the pressure:
73  *
74  * @f[
75  * s_k(T,P) = s^o_k(T) - R \ln \theta_k
76  * @f]
77  *
78  * ## Application within Kinetics Managers
79  *
80  * The activity concentration,@f$ C^a_k @f$, used by the kinetics manager, is equal to
81  * the actual concentration, @f$ C^s_k @f$, and is given by the following
82  * expression.
83  * @f[
84  * C^a_k = C^s_k = \frac{\theta_k n_0}{s_k}
85  * @f]
86  *
87  * The standard concentration for species *k* is:
88  * @f[
89  * C^0_k = \frac{n_0}{s_k}
90  * @f]
91  *
92  * An example phase definition is given in the
93  * <a href="../../sphinx/html/yaml/phases.html#ideal-surface"> YAML API Reference</a>.
94  *
95  * @ingroup thermoprops
96  */
97 class SurfPhase : public ThermoPhase
98 {
99 public:
100  //! Construct and initialize a SurfPhase ThermoPhase object directly from an
101  //! input file
102  /*!
103  * @param infile name of the input file. If blank, an empty phase will be created.
104  * @param id name of the phase id in the file.
105  * If this is blank, the first phase in the file is used.
106  */
107  explicit SurfPhase(const string& infile="", const string& id="");
108 
109  string type() const override {
110  return "ideal-surface";
111  }
112 
113  bool isCompressible() const override {
114  return false;
115  }
116 
117  //! Return the Molar Enthalpy. Units: J/kmol.
118  /*!
119  * For an ideal solution,
120  * @f[
121  * \hat h(T,P) = \sum_k X_k \hat h^0_k(T),
122  * @f]
123  * and is a function only of temperature. The standard-state pure-species
124  * Enthalpies @f$ \hat h^0_k(T) @f$ are computed by the species
125  * thermodynamic property manager.
126  *
127  * \see MultiSpeciesThermo
128  */
129  double enthalpy_mole() const override;
130 
131  //! Return the Molar Internal Energy. Units: J/kmol
132  /**
133  * For a surface phase, the pressure is not a relevant thermodynamic
134  * variable, and so the Enthalpy is equal to the Internal Energy.
135  */
136  double intEnergy_mole() const override;
137 
138  //! Return the Molar Entropy. Units: J/kmol-K
139  /**
140  * @f[
141  * \hat s(T,P) = \sum_k X_k (\hat s^0_k(T) - R \ln \theta_k)
142  * @f]
143  */
144  double entropy_mole() const override;
145 
146  double cp_mole() const override;
147  double cv_mole() const override;
148 
149  void getChemPotentials(double* mu) const override;
150  void getPartialMolarEnthalpies(double* hbar) const override;
151  void getPartialMolarEntropies(double* sbar) const override;
152  void getPartialMolarCp(double* cpbar) const override;
153  void getPartialMolarVolumes(double* vbar) const override;
154  void getStandardChemPotentials(double* mu0) const override;
155 
156  //! Return a vector of activity concentrations for each species
157  /*!
158  * For this phase the activity concentrations,@f$ C^a_k @f$, are defined to
159  * be equal to the actual concentrations, @f$ C^s_k @f$. Activity
160  * concentrations are
161  *
162  * @f[
163  * C^a_k = C^s_k = \frac{\theta_k n_0}{s_k}
164  * @f]
165  *
166  * where @f$ \theta_k @f$ is the surface site fraction for species k,
167  * @f$ n_0 @f$ is the surface site density for the phase, and
168  * @f$ s_k @f$ is the surface size of species k.
169  *
170  * @f$ C^a_k @f$ that are defined such that @f$ a_k = C^a_k / C^0_k, @f$
171  * where @f$ C^0_k @f$ is a standard concentration defined below and @f$ a_k
172  * @f$ are activities used in the thermodynamic functions. These activity
173  * concentrations are used by kinetics manager classes to compute the
174  * forward and reverse rates of elementary reactions. Note that they may or
175  * may not have units of concentration --- they might be partial pressures,
176  * mole fractions, or surface coverages,
177  *
178  * @param c vector of activity concentration (kmol m-2).
179  */
180  void getActivityConcentrations(double* c) const override;
181 
182  //! Return the standard concentration for the kth species
183  /*!
184  * The standard concentration @f$ C^0_k @f$ used to normalize the activity
185  * (that is, generalized) concentration. For this phase, the standard
186  * concentration is species- specific
187  *
188  * @f[
189  * C^0_k = \frac{n_0}{s_k}
190  * @f]
191  *
192  * This definition implies that the activity is equal to @f$ \theta_k @f$.
193  *
194  * @param k Optional parameter indicating the species. The default
195  * is to assume this refers to species 0.
196  * @return the standard concentration in units of kmol/m^2 for surface phases or
197  * kmol/m for edge phases.
198  */
199  double standardConcentration(size_t k=0) const override;
200  double logStandardConc(size_t k=0) const override;
201 
202  void initThermo() override;
203  void getParameters(AnyMap& phaseNode) const override;
204 
205  bool addSpecies(shared_ptr<Species> spec) override;
206 
207  //! Since interface phases have no volume, this returns 0.0.
208  double molarVolume() const override {
209  return 0.0;
210  }
211 
212  //! Returns the site density
213  /*!
214  * Site density kmol m-2
215  */
216  double siteDensity() const {
217  return m_n0;
218  }
219 
220  //! Returns the number of sites occupied by one molecule of species *k*.
221  double size(size_t k) const {
222  return m_speciesSize[k];
223  }
224 
225  //! Set the site density of the surface phase (kmol m-2)
226  /*!
227  * @param n0 Site density of the surface phase (kmol m-2)
228  */
229  void setSiteDensity(double n0);
230 
231  void getGibbs_RT(double* grt) const override;
232  void getEnthalpy_RT(double* hrt) const override;
233  void getEntropy_R(double* sr) const override;
234  void getCp_R(double* cpr) const override;
235  void getStandardVolumes(double* vol) const override;
236 
237  //! Return the thermodynamic pressure (Pa).
238  double pressure() const override {
239  return m_press;
240  }
241 
242  //! Set the internally stored pressure (Pa) at constant temperature and
243  //! composition
244  /*!
245  * @param p input Pressure (Pa)
246  */
247  void setPressure(double p) override {
248  m_press = p;
249  }
250 
251  void getPureGibbs(double* g) const override;
252  void getGibbs_RT_ref(double* grt) const override;
253  void getEnthalpy_RT_ref(double* hrt) const override;
254  void getEntropy_R_ref(double* er) const override;
255  void getCp_R_ref(double* cprt) const override;
256 
257  //! Set the surface site fractions to a specified state.
258  /*!
259  * This routine converts to concentrations in kmol/m2, using m_n0, the
260  * surface site density, and size(k), which is defined to be the number of
261  * surface sites occupied by the kth molecule. It then calls
262  * Phase::setConcentrations to set the internal concentration in the object.
263  *
264  * @param theta This is the surface site fraction for the kth species in
265  * the surface phase. This is a dimensionless quantity.
266  *
267  * This routine normalizes the theta's to 1, before application
268  */
269  void setCoverages(const double* theta);
270 
271  //! Set the surface site fractions to a specified state.
272  /*!
273  * This routine converts to concentrations in kmol/m2, using m_n0, the
274  * surface site density, and size(k), which is defined to be the number of
275  * surface sites occupied by the kth molecule. It then calls
276  * Phase::setConcentrations to set the internal concentration in the object.
277  *
278  * @param theta This is the surface site fraction for the kth species in
279  * the surface phase. This is a dimensionless quantity.
280  */
281  void setCoveragesNoNorm(const double* theta);
282 
283  //! Set the coverages from a string of colon-separated name:value pairs.
284  /*!
285  * @param cov String containing colon-separated name:value pairs
286  */
287  void setCoveragesByName(const string& cov);
288 
289  //! Set the coverages from a map of name:value pairs
290  void setCoveragesByName(const Composition& cov);
291 
292  //! Return a vector of surface coverages
293  /*!
294  * Get the coverages.
295  *
296  * @param theta Array theta must be at least as long as the number of
297  * species.
298  */
299  void getCoverages(double* theta) const;
300 
301  //! @copydoc ThermoPhase::setState
302  /*!
303  * Additionally uses the key `coverages` to set the fractional coverages.
304  */
305  void setState(const AnyMap& state) override;
306 
307 protected:
308  void compositionChanged() override;
309 
310  //! Surface site density (kmol m-2)
311  double m_n0 = 1.0;
312 
313  //! Vector of species sizes (number of sites occupied). length m_kk.
314  vector<double> m_speciesSize;
315 
316  //! log of the surface site density
317  double m_logn0;
318 
319  //! Current value of the pressure (Pa)
320  double m_press = OneAtm;
321 
322  //! Temporary storage for the reference state enthalpies
323  mutable vector<double> m_h0;
324 
325  //! Temporary storage for the reference state entropies
326  mutable vector<double> m_s0;
327 
328  //! Temporary storage for the reference state heat capacities
329  mutable vector<double> m_cp0;
330 
331  //! Temporary storage for the reference state Gibbs energies
332  mutable vector<double> m_mu0;
333 
334  //! Temporary work array
335  mutable vector<double> m_work;
336 
337  //! vector storing the log of the size of each species.
338  /*!
339  * The size of each species is defined as the number of surface sites each
340  * species occupies.
341  */
342  mutable vector<double> m_logsize;
343 
344  //! Update the species reference state thermodynamic functions
345  /*!
346  * The polynomials for the standard state functions are only reevaluated if
347  * the temperature has changed.
348  *
349  * @param force Boolean, which if true, forces a reevaluation of the thermo
350  * polynomials. default = false.
351  */
352  void _updateThermo(bool force=false) const;
353 };
354 
355 }
356 
357 #endif
Header file for class ThermoPhase, the base class for phases with thermodynamic properties,...
A map of string keys to values whose type can vary at runtime.
Definition: AnyMap.h:427
A simple thermodynamic model for a surface phase, assuming an ideal solution model.
Definition: SurfPhase.h:98
SurfPhase(const string &infile="", const string &id="")
Construct and initialize a SurfPhase ThermoPhase object directly from an input file.
Definition: SurfPhase.cpp:22
double molarVolume() const override
Since interface phases have no volume, this returns 0.0.
Definition: SurfPhase.h:208
void getStandardChemPotentials(double *mu0) const override
Get the array of chemical potentials at unit activity for the species at their standard states at the...
Definition: SurfPhase.cpp:97
void getPureGibbs(double *g) const override
Get the Gibbs functions for the standard state of the species at the current T and P of the solution.
Definition: SurfPhase.cpp:128
double enthalpy_mole() const override
Return the Molar Enthalpy. Units: J/kmol.
Definition: SurfPhase.cpp:28
void setSiteDensity(double n0)
Set the site density of the surface phase (kmol m-2)
Definition: SurfPhase.cpp:204
double logStandardConc(size_t k=0) const override
Natural logarithm of the standard concentration of the kth species.
Definition: SurfPhase.cpp:123
void setState(const AnyMap &state) override
Set the state using an AnyMap containing any combination of properties supported by the thermodynamic...
Definition: SurfPhase.cpp:286
void getPartialMolarEnthalpies(double *hbar) const override
Returns an array of partial molar enthalpies for the species in the mixture.
Definition: SurfPhase.cpp:64
void getChemPotentials(double *mu) const override
Get the species chemical potentials. Units: J/kmol.
Definition: SurfPhase.cpp:103
double pressure() const override
Return the thermodynamic pressure (Pa).
Definition: SurfPhase.h:238
bool isCompressible() const override
Return whether phase represents a compressible substance.
Definition: SurfPhase.h:113
void getEntropy_R(double *sr) const override
Get the array of nondimensional Entropy functions for the standard state species at the current T and...
Definition: SurfPhase.cpp:146
vector< double > m_logsize
vector storing the log of the size of each species.
Definition: SurfPhase.h:342
vector< double > m_work
Temporary work array.
Definition: SurfPhase.h:335
void getCp_R(double *cpr) const override
Get the nondimensional Heat Capacities at constant pressure for the species standard states at the cu...
Definition: SurfPhase.cpp:152
void getParameters(AnyMap &phaseNode) const override
Store the parameters of a ThermoPhase object such that an identical one could be reconstructed using ...
Definition: SurfPhase.cpp:328
string type() const override
String indicating the thermodynamic model implemented.
Definition: SurfPhase.h:109
void initThermo() override
Initialize the ThermoPhase object after all species have been set up.
Definition: SurfPhase.cpp:319
void getActivityConcentrations(double *c) const override
Return a vector of activity concentrations for each species.
Definition: SurfPhase.cpp:113
double m_n0
Surface site density (kmol m-2)
Definition: SurfPhase.h:311
double size(size_t k) const
Returns the number of sites occupied by one molecule of species k.
Definition: SurfPhase.h:221
void setPressure(double p) override
Set the internally stored pressure (Pa) at constant temperature and composition.
Definition: SurfPhase.h:247
vector< double > m_h0
Temporary storage for the reference state enthalpies.
Definition: SurfPhase.h:323
void getPartialMolarVolumes(double *vbar) const override
Return an array of partial molar volumes for the species in the mixture.
Definition: SurfPhase.cpp:92
double cv_mole() const override
Molar heat capacity at constant volume. Units: J/kmol/K.
Definition: SurfPhase.cpp:59
vector< double > m_s0
Temporary storage for the reference state entropies.
Definition: SurfPhase.h:326
void setCoverages(const double *theta)
Set the surface site fractions to a specified state.
Definition: SurfPhase.cpp:215
vector< double > m_cp0
Temporary storage for the reference state heat capacities.
Definition: SurfPhase.h:329
vector< double > m_speciesSize
Vector of species sizes (number of sites occupied). length m_kk.
Definition: SurfPhase.h:314
double m_press
Current value of the pressure (Pa)
Definition: SurfPhase.h:320
double siteDensity() const
Returns the site density.
Definition: SurfPhase.h:216
void getEnthalpy_RT(double *hrt) const override
Get the nondimensional Enthalpy functions for the species at their standard states at the current T a...
Definition: SurfPhase.cpp:140
void getEntropy_R_ref(double *er) const override
Returns the vector of nondimensional entropies of the reference state at the current temperature of t...
Definition: SurfPhase.cpp:175
void getGibbs_RT(double *grt) const override
Get the nondimensional Gibbs functions for the species in their standard states at the current T and ...
Definition: SurfPhase.cpp:134
double intEnergy_mole() const override
Return the Molar Internal Energy. Units: J/kmol.
Definition: SurfPhase.cpp:37
double entropy_mole() const override
Return the Molar Entropy. Units: J/kmol-K.
Definition: SurfPhase.cpp:42
void _updateThermo(bool force=false) const
Update the species reference state thermodynamic functions.
Definition: SurfPhase.cpp:303
void getCp_R_ref(double *cprt) const override
Returns the vector of nondimensional constant pressure heat capacities of the reference state at the ...
Definition: SurfPhase.cpp:180
void getStandardVolumes(double *vol) const override
Get the molar volumes of the species standard states at the current T and P of the solution.
Definition: SurfPhase.cpp:158
void setCoveragesNoNorm(const double *theta)
Set the surface site fractions to a specified state.
Definition: SurfPhase.cpp:231
void getCoverages(double *theta) const
Return a vector of surface coverages.
Definition: SurfPhase.cpp:249
double cp_mole() const override
Molar heat capacity at constant pressure. Units: J/kmol/K.
Definition: SurfPhase.cpp:53
void getPartialMolarCp(double *cpbar) const override
Return an array of partial molar heat capacities for the species in the mixture.
Definition: SurfPhase.cpp:82
void compositionChanged() override
Apply changes to the state which are needed after the composition changes.
Definition: SurfPhase.cpp:297
double standardConcentration(size_t k=0) const override
Return the standard concentration for the kth species.
Definition: SurfPhase.cpp:118
vector< double > m_mu0
Temporary storage for the reference state Gibbs energies.
Definition: SurfPhase.h:332
bool addSpecies(shared_ptr< Species > spec) override
Add a Species to this Phase.
Definition: SurfPhase.cpp:185
void setCoveragesByName(const string &cov)
Set the coverages from a string of colon-separated name:value pairs.
Definition: SurfPhase.cpp:263
void getGibbs_RT_ref(double *grt) const override
Returns the vector of nondimensional Gibbs Free Energies of the reference state at the current temper...
Definition: SurfPhase.cpp:165
double m_logn0
log of the surface site density
Definition: SurfPhase.h:317
void getPartialMolarEntropies(double *sbar) const override
Returns an array of partial molar entropies of the species in the solution.
Definition: SurfPhase.cpp:72
void getEnthalpy_RT_ref(double *hrt) const override
Returns the vector of nondimensional enthalpies of the reference state at the current temperature of ...
Definition: SurfPhase.cpp:170
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:390
const double OneAtm
One atmosphere [Pa].
Definition: ct_defs.h:96
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:564
map< string, double > Composition
Map from string names to doubles.
Definition: ct_defs.h:177