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