Cantera  3.1.0a1
Loading...
Searching...
No Matches
LatticeSolidPhase.h
Go to the documentation of this file.
1/**
2 * @file LatticeSolidPhase.h Header for a simple thermodynamics model of a bulk
3 * solid phase derived from ThermoPhase, assuming an ideal solution model
4 * based on a lattice of solid atoms (see @ref thermoprops and class @link
5 * Cantera::LatticeSolidPhase LatticeSolidPhase@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_LATTICESOLID_H
12#define CT_LATTICESOLID_H
13
14#include "ThermoPhase.h"
15
16namespace Cantera
17{
18
19//! A phase that is comprised of a fixed additive combination of other lattice
20//! phases
21/*!
22 * This is the main way %Cantera describes semiconductors and other solid
23 * phases. This ThermoPhase object calculates its properties as a sum over other
24 * LatticePhase objects. Each of the LatticePhase objects is a ThermoPhase
25 * object by itself.
26 *
27 * The results from this LatticeSolidPhase model reduces to the LatticePhase
28 * model when there is one lattice phase and the molar densities of the
29 * sublattice and the molar density within the LatticeSolidPhase have the same
30 * values.
31 *
32 * The mole fraction vector is redefined within the LatticeSolidPhase object.
33 * Each of the mole fractions sum to one on each of the sublattices. The
34 * routine getMoleFraction() and setMoleFraction() have been redefined to use
35 * this convention.
36 *
37 * ## Specification of Species Standard State Properties
38 *
39 * The standard state properties are calculated in the normal way for each of
40 * the sublattices. The normal way here means that a thermodynamic polynomial in
41 * temperature is developed. Also, a constant volume approximation for the
42 * pressure dependence is assumed. All of these properties are on a Joules per
43 * kmol of sublattice constituent basis.
44 *
45 * ## Specification of Solution Thermodynamic Properties
46 *
47 * The sum over the LatticePhase objects is carried out by weighting each
48 * LatticePhase object value with the molar density (kmol m-3) of its
49 * LatticePhase. Then the resulting quantity is divided by the molar density of
50 * the total compound. The LatticeSolidPhase object therefore only contains a
51 * listing of the number of LatticePhase object that comprises the solid, and it
52 * contains a value for the molar density of the entire mixture. This is the
53 * same thing as saying that
54 *
55 * @f[
56 * L_i = L^{solid} \theta_i
57 * @f]
58 *
59 * @f$ L_i @f$ is the molar volume of the ith lattice. @f$ L^{solid} @f$ is the
60 * molar volume of the entire solid. @f$ \theta_i @f$ is a fixed weighting
61 * factor for the ith lattice representing the lattice stoichiometric
62 * coefficient. For this object the @f$ \theta_i @f$ values are fixed.
63 *
64 * Let's take FeS2 as an example, which may be thought of as a combination of
65 * two lattices: Fe and S lattice. The Fe sublattice has a molar density of 1
66 * gmol cm-3. The S sublattice has a molar density of 2 gmol cm-3. We then
67 * define the LatticeSolidPhase object as having a nominal composition of FeS2,
68 * and having a molar density of 1 gmol cm-3. All quantities pertaining to the
69 * FeS2 compound will be have weights associated with the sublattices. The Fe
70 * sublattice will have a weight of 1.0 associated with it. The S sublattice
71 * will have a weight of 2.0 associated with it.
72 *
73 * ### Specification of Solution Density Properties
74 *
75 * Currently, molar density is not a constant within the object, even though the
76 * species molar volumes are a constant. The basic idea is that a swelling of
77 * one of the sublattices will result in a swelling of of all of the lattices.
78 * Therefore, the molar volumes of the individual lattices are not independent
79 * of one another.
80 *
81 * The molar volume of the Lattice solid is calculated from the following
82 * formula
83 *
84 * @f[
85 * V = \sum_i{ \theta_i V_i^{lattice}}
86 * @f]
87 *
88 * where @f$ V_i^{lattice} @f$ is the molar volume of the ith sublattice. This
89 * is calculated from the following standard formula.
90 *
91 * @f[
92 * V_i = \sum_k{ X_k V_k}
93 * @f]
94 *
95 * where k is a species in the ith sublattice.
96 *
97 * The mole fraction vector is redefined within the the LatticeSolidPhase object.
98 * Each of the mole fractions sum to one on each of the sublattices. The
99 * routine getMoleFraction() and setMoleFraction() have been redefined to use
100 * this convention.
101 *
102 * (This object is still under construction)
103 */
105{
106public:
107 //! Base empty constructor
108 LatticeSolidPhase() = default;
109
110 string type() const override {
111 return "compound-lattice";
112 }
113
114 //! String indicating the mechanical phase of the matter in this Phase.
115 /*!
116 * `LatticeSolid` phases only represent solids.
117 */
118 string phaseOfMatter() const override {
119 return "solid";
120 }
121
122 bool isCompressible() const override {
123 return false;
124 }
125
126 map<string, size_t> nativeState() const override {
127 return { {"T", 0}, {"P", 1}, {"X", 2} };
128 }
129
130 double minTemp(size_t k=npos) const override;
131 double maxTemp(size_t k=npos) const override;
132 double refPressure() const override;
133
134 //! This method returns the convention used in specification of the standard
135 //! state, of which there are currently two, temperature based, and variable
136 //! pressure based.
137 /*!
138 * All of the thermo is determined by slave ThermoPhase routines.
139 */
140 int standardStateConvention() const override {
142 }
143
144 //! Return the Molar Enthalpy. Units: J/kmol.
145 /*!
146 * The molar enthalpy is determined by the following formula, where @f$
147 * \theta_n @f$ is the lattice stoichiometric coefficient of the nth lattice
148 *
149 * @f[
150 * \tilde h(T,P) = {\sum_n \theta_n \tilde h_n(T,P) }
151 * @f]
152 *
153 * @f$ \tilde h_n(T,P) @f$ is the enthalpy of the nth lattice.
154 *
155 * units J/kmol
156 */
157 double enthalpy_mole() const override;
158
159 //! Return the Molar Internal Energy. Units: J/kmol.
160 /*!
161 * The molar enthalpy is determined by the following formula, where @f$
162 * \theta_n @f$ is the lattice stoichiometric coefficient of the nth lattice
163 *
164 * @f[
165 * \tilde u(T,P) = {\sum_n \theta_n \tilde u_n(T,P) }
166 * @f]
167 *
168 * @f$ \tilde u_n(T,P) @f$ is the internal energy of the nth lattice.
169 *
170 * units J/kmol
171 */
172 double intEnergy_mole() const override;
173
174 //! Return the Molar Entropy. Units: J/kmol/K.
175 /*!
176 * The molar enthalpy is determined by the following formula, where @f$
177 * \theta_n @f$ is the lattice stoichiometric coefficient of the nth lattice
178 *
179 * @f[
180 * \tilde s(T,P) = \sum_n \theta_n \tilde s_n(T,P)
181 * @f]
182 *
183 * @f$ \tilde s_n(T,P) @f$ is the molar entropy of the nth lattice.
184 *
185 * units J/kmol/K
186 */
187 double entropy_mole() const override;
188
189 //! Return the Molar Gibbs energy. Units: J/kmol.
190 /*!
191 * The molar Gibbs free energy is determined by the following formula, where
192 * @f$ \theta_n @f$ is the lattice stoichiometric coefficient of the nth
193 * lattice
194 *
195 * @f[
196 * \tilde h(T,P) = {\sum_n \theta_n \tilde h_n(T,P) }
197 * @f]
198 *
199 * @f$ \tilde h_n(T,P) @f$ is the enthalpy of the nth lattice.
200 *
201 * units J/kmol
202 */
203 double gibbs_mole() const override;
204
205 //! Return the constant pressure heat capacity. Units: J/kmol/K
206 /*!
207 * The molar constant pressure heat capacity is determined by the following
208 * formula, where @f$ C_n @f$ is the lattice molar density of the nth
209 * lattice, and @f$ C_T @f$ is the molar density of the solid compound.
210 *
211 * @f[
212 * \tilde c_{p,n}(T,P) = \frac{\sum_n C_n \tilde c_{p,n}(T,P) }{C_T},
213 * @f]
214 *
215 * @f$ \tilde c_{p,n}(T,P) @f$ is the heat capacity of the nth lattice.
216 *
217 * units J/kmol/K
218 */
219 double cp_mole() const override;
220
221 //! Return the constant volume heat capacity. Units: J/kmol/K
222 /*!
223 * The molar constant volume heat capacity is determined by the following
224 * formula, where @f$ C_n @f$ is the lattice molar density of the nth
225 * lattice, and @f$ C_T @f$ is the molar density of the solid compound.
226 *
227 * @f[
228 * \tilde c_{v,n}(T,P) = \frac{\sum_n C_n \tilde c_{v,n}(T,P) }{C_T},
229 * @f]
230 *
231 * @f$ \tilde c_{v,n}(T,P) @f$ is the heat capacity of the nth lattice.
232 *
233 * units J/kmol/K
234 */
235 double cv_mole() const override {
236 return cp_mole();
237 }
238
239 //! Report the Pressure. Units: Pa.
240 /*!
241 * This method simply returns the stored pressure value.
242 */
243 double pressure() const override {
244 return m_press;
245 }
246
247 //! Set the pressure at constant temperature. Units: Pa.
248 /*!
249 * @param p Pressure (units - Pa)
250 */
251 void setPressure(double p) override;
252
253 //! Calculate the density of the solid mixture
254 /*!
255 * The formula for this is
256 *
257 * @f[
258 * \rho = \sum_n{ \rho_n \theta_n }
259 * @f]
260 *
261 * where @f$ \rho_n @f$ is the density of the nth sublattice
262 */
263 double calcDensity();
264
265 //! Set the mole fractions to the specified values, and then normalize them
266 //! so that they sum to 1.0 for each of the subphases
267 /*!
268 * On input, the mole fraction vector is assumed to sum to one for each of
269 * the sublattices. The sublattices are updated with this mole fraction
270 * vector. The mole fractions are also stored within this object, after they
271 * are normalized to one by dividing by the number of sublattices.
272 *
273 * @param x Input vector of mole fractions. There is no restriction on the
274 * sum of the mole fraction vector. Internally, this object will
275 * pass portions of this vector to the sublattices which assume
276 * that the portions individually sum to one. Length is m_kk.
277 */
278 void setMoleFractions(const double* const x) override;
279
280 //! Get the species mole fraction vector.
281 /*!
282 * On output the mole fraction vector will sum to one for each of the
283 * subphases which make up this phase.
284 *
285 * @param x On return, x contains the mole fractions. Must have a length
286 * greater than or equal to the number of species.
287 *
288 * @todo This method shadows but does not override Phase::getMoleFractions(). The
289 * LatticeSolidPhase class should be revised to avoid needing to override the
290 * methods for getting composition. See
291 * https://github.com/Cantera/cantera/issues/1310 for additional information.
292 */
293 void getMoleFractions(double* const x) const;
294
295 void setMassFractions(const double* const y) override {
296 throw NotImplementedError("LatticeSolidPhase::setMassFractions");
297 }
298
299 void setMassFractions_NoNorm(const double* const y) override {
300 throw NotImplementedError("LatticeSolidPhase::setMassFractions_NoNorm");
301 }
302
303 void getConcentrations(double* const c) const override {
304 throw NotImplementedError("LatticeSolidPhase::getConcentrations");
305 }
306
307 double concentration(size_t k) const override {
308 throw NotImplementedError("LatticeSolidPhase::concentration");
309 }
310
311 void setConcentrations(const double* const conc) override {
312 throw NotImplementedError("LatticeSolidPhase::setConcentrations");
313 }
314
315 Units standardConcentrationUnits() const override;
316
317 void getActivityConcentrations(double* c) const override;
318
319 void getActivityCoefficients(double* ac) const override;
320
321 //! Get the species chemical potentials. Units: J/kmol.
322 /*!
323 * This function returns a vector of chemical potentials of the species in
324 * solution at the current temperature, pressure and mole fraction of the
325 * solution.
326 *
327 * This returns the underlying lattice chemical potentials, as the units are
328 * kmol-1 of the sublattice species.
329 *
330 * @param mu Output vector of species chemical potentials. Length: m_kk.
331 * Units: J/kmol
332 */
333 void getChemPotentials(double* mu) const override;
334
335 //! Returns an array of partial molar enthalpies for the species in the
336 //! mixture.
337 /*!
338 * Units (J/kmol). For this phase, the partial molar enthalpies are equal to
339 * the pure species enthalpies
340 * @f[
341 * \bar h_k(T,P) = \hat h^{ref}_k(T) + (P - P_{ref}) \hat V^0_k
342 * @f]
343 * The reference-state pure-species enthalpies, @f$ \hat h^{ref}_k(T) @f$,
344 * at the reference pressure,@f$ P_{ref} @f$, are computed by the species
345 * thermodynamic property manager. They are polynomial functions of
346 * temperature.
347 * @see MultiSpeciesThermo
348 *
349 * @param hbar Output vector containing partial molar enthalpies.
350 * Length: m_kk.
351 */
352 void getPartialMolarEnthalpies(double* hbar) const override;
353
354 /**
355 * Returns an array of partial molar entropies of the species in the
356 * solution. Units: J/kmol/K. For this phase, the partial molar entropies
357 * are equal to the pure species entropies plus the ideal solution
358 * contribution.
359 * @f[
360 * \bar s_k(T,P) = \hat s^0_k(T) - R \ln(X_k)
361 * @f]
362 * The reference-state pure-species entropies,@f$ \hat s^{ref}_k(T) @f$, at
363 * the reference pressure, @f$ P_{ref} @f$, are computed by the species
364 * thermodynamic property manager. They are polynomial functions of
365 * temperature.
366 * @see MultiSpeciesThermo
367 *
368 * @param sbar Output vector containing partial molar entropies.
369 * Length: m_kk.
370 */
371 void getPartialMolarEntropies(double* sbar) const override;
372
373 /**
374 * Returns an array of partial molar Heat Capacities at constant pressure of
375 * the species in the solution. Units: J/kmol/K. For this phase, the partial
376 * molar heat capacities are equal to the standard state heat capacities.
377 *
378 * @param cpbar Output vector of partial heat capacities. Length: m_kk.
379 */
380 void getPartialMolarCp(double* cpbar) const override;
381
382 /**
383 * returns an array of partial molar volumes of the species in the solution.
384 * Units: m^3 kmol-1.
385 *
386 * For this solution, the partial molar volumes are equal to the constant
387 * species molar volumes.
388 *
389 * @param vbar Output vector of partial molar volumes. Length: m_kk.
390 */
391 void getPartialMolarVolumes(double* vbar) const override;
392
393 //! Get the array of standard state chemical potentials at unit activity for
394 //! the species at their standard states at the current *T* and *P* of the
395 //! solution.
396 /*!
397 * These are the standard state chemical potentials @f$ \mu^0_k(T,P) @f$.
398 * The values are evaluated at the current temperature and pressure of the
399 * solution.
400 *
401 * This returns the underlying lattice standard chemical potentials, as the
402 * units are kmol-1 of the sublattice species.
403 *
404 * @param mu0 Output vector of chemical potentials.
405 * Length: m_kk. Units: J/kmol
406 */
407 void getStandardChemPotentials(double* mu0) const override;
408
409 double standardConcentration(size_t k=0) const override;
410 double logStandardConc(size_t k=0) const override;
411
412 //! @name Thermodynamic Values for the Species Reference States
413 //! @{
414
415 void getGibbs_RT_ref(double* grt) const override;
416 void getGibbs_ref(double* g) const override;
417 //! @}
418
419 bool addSpecies(shared_ptr<Species> spec) override;
420
421 //! Add a lattice to this phase
422 void addLattice(shared_ptr<ThermoPhase> lattice);
423
424 //! Set the lattice stoichiometric coefficients, @f$ \theta_i @f$
425 void setLatticeStoichiometry(const Composition& comp);
426
427 void setParameters(const AnyMap& phaseNode,
428 const AnyMap& rootNode=AnyMap()) override;
429 void initThermo() override;
430 void getParameters(AnyMap& phaseNode) const override;
431 void getSpeciesParameters(const string& name, AnyMap& speciesNode) const override;
432
433 //! Set the Lattice mole fractions using a string
434 /*!
435 * @param n Integer value of the lattice whose mole fractions are being set
436 * @param x string containing Name:value pairs that will specify the mole
437 * fractions of species on a particular lattice
438 */
439 void setLatticeMoleFractionsByName(int n, const string& x);
440
441 void modifyOneHf298SS(const size_t k, const double Hf298New) override;
442 void resetHf298(const size_t k=npos) override;
443
444protected:
445 //! Current value of the pressure
446 double m_press = -1.0;
447
448 //! Current value of the molar density
449 double m_molar_density = 0.0;
450
451 //! Vector of sublattice ThermoPhase objects
452 vector<shared_ptr<ThermoPhase>> m_lattice;
453
454 //! Vector of mole fractions
455 /*!
456 * Note these mole fractions sum to one when summed over all phases.
457 * However, this is not what's passed down to the lower m_lattice objects.
458 */
459 mutable vector<double> m_x;
460
461 //! Lattice stoichiometric coefficients
462 vector<double> theta_;
463
464 //! Temporary vector
465 mutable vector<double> tmpV_;
466
467 vector<size_t> lkstart_;
468
469 //! Root node of the AnyMap which contains this phase definition.
470 //! Used to look up the phase definitions for the constituent phases.
472
473private:
474 //! Update the reference thermodynamic functions
475 void _updateThermo() const;
476};
477}
478
479#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 phase that is comprised of a fixed additive combination of other lattice phases.
vector< shared_ptr< ThermoPhase > > m_lattice
Vector of sublattice ThermoPhase objects.
void setLatticeStoichiometry(const Composition &comp)
Set the lattice stoichiometric coefficients, .
void getStandardChemPotentials(double *mu0) const override
Get the array of standard state chemical potentials at unit activity for the species at their standar...
double enthalpy_mole() const override
Return the Molar Enthalpy. Units: J/kmol.
double logStandardConc(size_t k=0) const override
Natural logarithm of the standard concentration of the kth species.
AnyMap m_rootNode
Root node of the AnyMap which contains this phase definition.
int standardStateConvention() const override
This method returns the convention used in specification of the standard state, of which there are cu...
void getPartialMolarEnthalpies(double *hbar) const override
Returns an array of partial molar enthalpies for the species in the mixture.
void getChemPotentials(double *mu) const override
Get the species chemical potentials. Units: J/kmol.
vector< double > tmpV_
Temporary vector.
double pressure() const override
Report the Pressure. Units: Pa.
bool isCompressible() const override
Return whether phase represents a compressible substance.
vector< double > m_x
Vector of mole fractions.
void getSpeciesParameters(const string &name, AnyMap &speciesNode) const override
Get phase-specific parameters of a Species object such that an identical one could be reconstructed a...
map< string, size_t > nativeState() const override
Return a map of properties defining the native state of a substance.
void setConcentrations(const double *const conc) override
Set the concentrations to the specified values within the phase.
void getGibbs_ref(double *g) const override
Returns the vector of the Gibbs function of the reference state at the current temperature of the sol...
void setMassFractions(const double *const y) override
Set the mass fractions to the specified values and normalize them.
void modifyOneHf298SS(const size_t k, const double Hf298New) override
Modify the value of the 298 K Heat of Formation of one species in the phase (J kmol-1)
vector< double > theta_
Lattice stoichiometric coefficients.
void getParameters(AnyMap &phaseNode) const override
Store the parameters of a ThermoPhase object such that an identical one could be reconstructed using ...
string type() const override
String indicating the thermodynamic model implemented.
void initThermo() override
Initialize the ThermoPhase object after all species have been set up.
void setMoleFractions(const double *const x) override
Set the mole fractions to the specified values, and then normalize them so that they sum to 1....
void getActivityConcentrations(double *c) const override
This method returns an array of generalized concentrations.
void setPressure(double p) override
Set the pressure at constant temperature. Units: Pa.
void getPartialMolarVolumes(double *vbar) const override
returns an array of partial molar volumes of the species in the solution.
double concentration(size_t k) const override
Concentration of species k.
double cv_mole() const override
Return the constant volume heat capacity. Units: J/kmol/K.
void getConcentrations(double *const c) const override
Get the species concentrations (kmol/m^3).
void setLatticeMoleFractionsByName(int n, const string &x)
Set the Lattice mole fractions using a string.
double m_press
Current value of the pressure.
double refPressure() const override
Returns the reference pressure in Pa.
double minTemp(size_t k=npos) const override
Minimum temperature for which the thermodynamic data for the species or phase are valid.
double intEnergy_mole() const override
Return the Molar Internal Energy. Units: J/kmol.
double entropy_mole() const override
Return the Molar Entropy. Units: J/kmol/K.
void getMoleFractions(double *const x) const
Get the species mole fraction vector.
double cp_mole() const override
Return the constant pressure heat capacity. Units: J/kmol/K.
Units standardConcentrationUnits() const override
Returns the units of the "standard concentration" for this phase.
void getPartialMolarCp(double *cpbar) const override
Returns an array of partial molar Heat Capacities at constant pressure of the species in the solution...
double gibbs_mole() const override
Return the Molar Gibbs energy. Units: J/kmol.
double standardConcentration(size_t k=0) const override
Return the standard concentration for the kth species.
void setMassFractions_NoNorm(const double *const y) override
Set the mass fractions to the specified values without normalizing.
void addLattice(shared_ptr< ThermoPhase > lattice)
Add a lattice to this phase.
double calcDensity()
Calculate the density of the solid mixture.
bool addSpecies(shared_ptr< Species > spec) override
Add a Species to this Phase.
void _updateThermo() const
Update the reference thermodynamic functions.
void getGibbs_RT_ref(double *grt) const override
Returns the vector of nondimensional Gibbs Free Energies of the reference state at the current temper...
void getActivityCoefficients(double *ac) const override
Get the array of non-dimensional molar-based activity coefficients at the current solution temperatur...
LatticeSolidPhase()=default
Base empty constructor.
void setParameters(const AnyMap &phaseNode, const AnyMap &rootNode=AnyMap()) override
Set equation of state parameters from an AnyMap phase description.
double m_molar_density
Current value of the molar density.
void resetHf298(const size_t k=npos) override
Restore the original heat of formation of one or more species.
void getPartialMolarEntropies(double *sbar) const override
Returns an array of partial molar entropies of the species in the solution.
double maxTemp(size_t k=npos) const override
Maximum temperature for which the thermodynamic data for the species are valid.
string phaseOfMatter() const override
String indicating the mechanical phase of the matter in this Phase.
An error indicating that an unimplemented function has been called.
string name() const
Return the name of the phase.
Definition Phase.cpp:20
Base class for a phase with thermodynamic properties.
A representation of the units associated with a dimensional quantity.
Definition Units.h:35
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
const size_t npos
index returned by functions to indicate "no position"
Definition ct_defs.h:180
const int cSS_CONVENTION_SLAVE
Standard state thermodynamics is obtained from slave ThermoPhase objects.
map< string, double > Composition
Map from string names to doubles.
Definition ct_defs.h:177