Cantera 2.6.0

BinarySolutionTabulatedThermo.h
Go to the documentation of this file.
1/**
2 * @file BinarySolutionTabulatedThermo.h
3 * Header file for an binary solution model with tabulated standard state
4 * thermodynamic data (see \ref thermoprops and class
5 * \link Cantera::BinarySolutionTabulatedThermo BinarySolutionTabulatedThermo\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_BINARYSOLUTIONTABULATEDTHERMO_H
12#define CT_BINARYSOLUTIONTABULATEDTHERMO_H
13
14#include "IdealSolidSolnPhase.h"
15#include "cantera/base/utilities.h"
16
17 namespace Cantera
18{
19
20//! Overloads the virtual methods of class IdealSolidSolnPhase to implement
21//! tabulated standard state thermodynamics for one species in a binary
22//! solution.
23/**
24 *
25 * BinarySolutionTabulatedThermo is derived from IdealSolidSolnPhase, but
26 * overwrites the standard state thermodynamic data using tabulated data,
27 * as provided by the user in the input file. This ends up being useful for
28 * certain non-ideal / non-dilute species where the interaction potentials, as
29 * a function of composition / solute mole fraction, are not easily represented
30 * by any closed-form equation of state.
31 *
32 * A good example of this type of phase is intercalation-based lithium storage
33 * materials used for lithium-ion battery electrodes. Measuring the open
34 * circuit voltage \f$ E_eq \f$, relative to a reference electrode, as a
35 * function of lithium mole fraction and as a function of temperature, provides
36 * a means to evaluate the gibbs free energy of reaction:
37 *
38 * \f[
39 * \Delta g_{\rm rxn} = -\frac{E_eq}{nF}
40 * \f]
41 *
42 * where \f$ n\f$ is the charge number transferred to the phase, via the
43 * reaction, and \f$ F \f$ is Faraday's constant. The gibbs energy of
44 * reaction, in turn, can be separated into enthalpy and entropy of reaction
45 * components:
46 *
47 * \f[
48 * \Delta g_{\rm rxn} = \Delta h_{\rm rxn} - T\Delta s_{\rm rxn}
49 * \f]
50 * \f[
51 * \frac{d\Delta g_{\rm rxn}}{dT} = - \Delta s_{\rm rxn}
52 * \f]
53 *
54 * For the tabulated binary phase, the user identifies a 'tabulated' species,
55 * while the other is considered the 'reference' species. The standard state
56 * thermo variables for the tabulated species therefore incorporate any and all
57 * excess energy contributions, and are calculated according to the reaction
58 * energy terms:
59 *
60 * \f[
61 * \Delta h_{\rm rxn} = \sum_k \nu_k h^{\rm o}_k
62 * \f]
63 * \f[
64 * \Delta s_{\rm rxn} = \sum_k \nu_k s^{\rm o}_k + RT\ln\left(\prod_k\left(\frac{c_k}{c^{\rm o}_k} \right)^{\nu_k}\right)
65 * \f]
66 *
67 * Where the 'reference' species is automatically assigned standard state
68 * thermo variables \f$ h^{\rm o} = 0\f$ and \f$ s^{\rm o} = 0\f$, and standard
69 * state thermo variables for species in any other phases are calculated
70 * according to the rules specified in that phase definition.
71 *
72 * The present model is intended for modeling non-ideal, tabulated
73 * thermodynamics for binary solutions where the tabulated species is
74 * incorporated via an electrochemical reaction, such that the open circuit
75 * voltage can be measured, relative to a counter electrode species with
76 * standard state thermo properties \f$ h^{\rm o} = 0\f$.
77 * It is possible that this can be generalized such that this assumption about
78 * the counter-electrode is not required. At present, this is left as future
79 * work.
80 *
81 * The user therefore provides a table of three equally-sized vectors of
82 * tabulated data:
83 *
84 * - \f$ x_{\rm tab}\f$ = array of mole fractions for the tabulated species
85 * at which measurements were conducted and thermo
86 * data are provided.
87 * - \f$ h_{\rm tab}\f$ = \f$ F\left(-E_{\rm eq}\left(x,T^{\rm o} \right) + T^{\rm o} \frac{dE_{\rm eq}\left(x,T^{\rm o} \right)}{dT}\right) \f$
88 * - \f$ s_{\rm tab}\f$ = \f$ F \left(\frac{dE_{\rm eq}\left(x,T^{\rm o} \right)}{dT} + s_{\rm counter}^{\rm o} \right) \f$
89 *
90 * where \f$ E_{\rm eq}\left(x,T^{\rm o} \right) \f$ and \f$ \frac{dE_{\rm eq}\left(x,T^{\rm o} \right)}{dT} \f$
91 * are the experimentally-measured open circuit voltage and derivative in
92 * open circuit voltage with respect to temperature, respectively, both
93 * measured as a mole fraction of \f$ x \f$ for the tabulated species and at a
94 * temperature of \f$ T^{\rm o} \f$. The arrays \f$ h_{\rm tab}\f$ and
95 * \f$ s_{\rm tab}\f$ must be the same length as the \f$ x_{\rm tab}\f$ array.
96 *
97 * From these tabulated inputs, the standard state thermodynamic properties
98 * for the tabulated species (subscript \f$ k\f$, tab) are calculated as:
99 *
100 * \f[
101 * h^{\rm o}_{k,\,{\rm tab}} = h_{\rm tab}
102 * \f]
103 * \f[
104 * s^{\rm o}_{k,\,{\rm tab}} = s_{\rm tab} + R\ln\frac{x_{k,\,{\rm tab}}}{1-x_{k,\,{\rm tab}}} + \frac{R}{F} \ln\left(\frac{c^{\rm o}_{k,\,{\rm ref}}}{c^{\rm o}_{k,\,{\rm tab}}}\right)
105 * \f]
106 *
107 * Now, whenever the composition has changed, the lookup/interpolation of the
108 * tabulated thermo data is performed to update the standard state
109 * thermodynamic data for the tabulated species.
110 *
111 * Furthermore, there is an optional feature to include non-ideal effects regarding
112 * partial molar volumes of the species, \f$ \bar V_k\f$. Being derived from
113 * IdealSolidSolnPhase, the default assumption in BinarySolutionTabulatedThermo
114 * is that the species comprising the binary solution have constant partial molar
115 * volumes equal to their pure species molar volumes. However, this assumption only
116 * holds true if there is no or only weak interactions between the two species in the
117 * binary mixture. In non-ideal solid materials, for example intercalation-based
118 * lithium storage materials, the partial molar volumes of the species typically show a
119 * strong non-linear dependency on the composition of the mixture. These dependencies
120 * can most often only be determined experimentally, for example via X-ray diffraction
121 * (XRD) measurements of the unit cell volume. Therefore, the user can provide an optional fourth vector of
122 * tabulated molar volume data with the same size as the other tabulated data:
123 *
124 * - \f$ V_{\mathrm{m,tab}}\f$ = array of the molar volume of the binary solution phase at
125 * the tabulated mole fractions.
126 *
127 * The partial molar volumes \f$ \bar V_1\f$ of the tabulated species and
128 * \f$ \bar V_2\f$ of the 'reference' species, respectively, can then be derived from
129 * the provided molar volume:
130 *
131 * \f[
132 * \bar V_1 = V_{\mathrm{m,tab}} + \left(1-x_{\mathrm {tab}}\right) \cdot
133 * \frac{\mathrm{d}V_{\mathrm{m,tab}}}{\mathrm{d}x_{\mathrm {tab}}} \\
134 * \bar V_2 = V_{\mathrm{m,tab}} - x_{\mathrm {tab}} \cdot
135 * \frac{\mathrm{d}V_{\mathrm{m,tab}}}{\mathrm{d}x_{\mathrm {tab}}}
136 * \f]
137 *
138 * The derivation is implemented using forward differences at the boundaries of the
139 * input vector and a central differencing scheme at interior points. As the
140 * derivative is determined numerically, the input data should be relatively smooth
141 * (recommended is one data point for every mole fraction per cent). The calculated
142 * partial molar volumes are accessible to the user via getPartialMolarVolumes().
143 *
144 * The calculation of the mass density incorporates the non-ideal behavior by using
145 * the provided molar volume in the equation:
146 *
147 * \f[
148 * \rho = \frac{\sum_k{x_k W_k}}{V_\mathrm{m}}
149 * \f]
150 *
151 * where \f$x_k\f$ are the mole fractions, \f$W_k\f$ are the molecular weights, and
152 * \f$V_\mathrm{m}\f$ is the molar volume interpolated from \f$V_{\mathrm{m,tab}}\f$.
153 *
154 * If the optional fourth input vector is not specified, the molar volume is calculated
155 * by using the pure species molar volumes, as in IdealSolidSolnPhase. Regardless if the
156 * molarVolume key is provided or not, the equation-of-state field in the pure species
157 * entries has to be defined.
158 *
159 * @ingroup thermoprops
160 */
161 class BinarySolutionTabulatedThermo : public IdealSolidSolnPhase
162{
163 public:
164 //! Construct and initialize an BinarySolutionTabulatedThermo ThermoPhase object
165 //! directly from an input file
166 /*!
167 * This constructor will also fully initialize the object.
168 *
169 * @param infile File name for the input file containing information
170 * for this phase. If not specified, an empty phase will be created.
171 * @param id The name of this phase. This is used to look up
172 * the phase in the input file.
173 */
174 explicit BinarySolutionTabulatedThermo(const std::string& infile="", const std::string& id="");
175
176 //! Construct and initialize an BinarySolutionTabulatedThermo ThermoPhase object
177 //! directly from an XML database
178 /*!
179 * @param root XML tree containing a description of the phase.
180 * The tree must be positioned at the XML element
181 * named phase with id, "id", on input to this routine.
182 * @param id The name of this phase. This is used to look up
183 * the phase in the XML datafile.
184 *
185 * @deprecated The XML input format is deprecated and will be removed in
186 * Cantera 3.0.
187 */
188 BinarySolutionTabulatedThermo(XML_Node& root, const std::string& id="");
189
190 virtual std::string type() const {
191 return "BinarySolutionTabulatedThermo";
192 }
193
194 virtual bool addSpecies(shared_ptr<Species> spec);
195 virtual void initThermo();
196 virtual bool ready() const;
197 virtual void getParameters(AnyMap& phaseNode) const;
198 virtual void initThermoXML(XML_Node& phaseNode, const std::string& id_);
199
200 /**
201 * returns an array of partial molar volumes of the species
202 * in the solution. Units: m^3 kmol-1.
203 *
204 * The partial molar volumes are derived as shown in the equations in the detailed
205 * description section.
206 *
207 * @param vbar Output vector of partial molar volumes. Length: m_kk.
208 */
209 virtual void getPartialMolarVolumes(double* vbar) const;
210
211 /**
212 * Overloads the calcDensity() method of IdealSolidSoln to also consider non-ideal
213 * behavior.
214 *
215 * The formula for this is
216 *
217 * \f[
218 * \rho = \frac{\sum_k{X_k W_k}}{V_\mathrm{m}}
219 * \f]
220 *
221 * where \f$X_k\f$ are the mole fractions, \f$W_k\f$ are the molecular weights, and
222 * \f$V_\mathrm{m}\f$ is the molar volume interpolated from \f$V_{\mathrm{m,tab}}\f$.
223 */
224 virtual void calcDensity();
225
226 protected:
227 //! If the compositions have changed, update the tabulated thermo lookup
228 virtual void compositionChanged();
229
230 //! Species thermodynamics linear interpolation function
231 /*!
232 * Tabulated values are only interpolated within the limits of the provided mole
233 * fraction. If these limits are exceeded, the values are capped at the lower or
234 * the upper limit.
235 *
236 * @param x Current mole fraction at which to interpolate.
237 * @param inputData Input vector of the data to be interpolated.
238 * @returns Linear interpolation of tabulated data at the current
239 * mole fraction x.
240 */
241 double interpolate(const double x, const vector_fp& inputData) const;
242
243 //! Numerical derivative of the molar volume table
244 /*!
245 * Tabulated values are only interpolated within the limits of the provided mole
246 * fraction. If these limits are exceeded, the values are capped at the lower or
247 * the upper limit.
248 *
249 * @param inputData Input vector of tabulated data to be derived.
250 * @param derivedData Output vector of tabulated data that is numerically
251 * derived with respect to the mole fraction.
252 */
253 void diff(const vector_fp& inputData, vector_fp& derivedData) const;
254
255 //! Current tabulated species index
256 size_t m_kk_tab;
257
258 //! Current tabulated species mole fraction
259 mutable double m_xlast;
260
261 //! Tabulated contribution to h0[m_kk_tab] at the current composition
262 mutable double m_h0_tab;
263
264 //! Tabulated contribution to s0[m_kk_tab] at the current composition
265 mutable double m_s0_tab;
266
267 //! Vector for storing tabulated thermo
268 vector_fp m_molefrac_tab;
269 vector_fp m_enthalpy_tab;
270 vector_fp m_entropy_tab;
271 vector_fp m_molar_volume_tab;
272 vector_fp m_derived_molar_volume_tab;
273 vector_fp m_partial_molar_volume_1_tab;
274 vector_fp m_partial_molar_volume_2_tab;
275
276 private:
277 virtual void _updateThermo() const;
278};
279}
280
281#endif
IdealSolidSolnPhase.h
Header file for an ideal solid solution model with incompressible thermodynamics (see Thermodynamic P...
Cantera::AnyMap
A map of string keys to values whose type can vary at runtime.
Definition: AnyMap.h:399
Cantera::BinarySolutionTabulatedThermo
Overloads the virtual methods of class IdealSolidSolnPhase to implement tabulated standard state ther...
Definition: BinarySolutionTabulatedThermo.h:162
Cantera::BinarySolutionTabulatedThermo::m_xlast
double m_xlast
Current tabulated species mole fraction.
Definition: BinarySolutionTabulatedThermo.h:259
Cantera::BinarySolutionTabulatedThermo::addSpecies
virtual bool addSpecies(shared_ptr< Species > spec)
Definition: BinarySolutionTabulatedThermo.cpp:80
Cantera::BinarySolutionTabulatedThermo::getParameters
virtual void getParameters(AnyMap &phaseNode) const
Store the parameters of a ThermoPhase object such that an identical one could be reconstructed using ...
Definition: BinarySolutionTabulatedThermo.cpp:166
Cantera::BinarySolutionTabulatedThermo::diff
void diff(const vector_fp &inputData, vector_fp &derivedData) const
Numerical derivative of the molar volume table.
Definition: BinarySolutionTabulatedThermo.cpp:306
Cantera::BinarySolutionTabulatedThermo::m_s0_tab
double m_s0_tab
Tabulated contribution to s0[m_kk_tab] at the current composition.
Definition: BinarySolutionTabulatedThermo.h:265
Cantera::BinarySolutionTabulatedThermo::m_molefrac_tab
vector_fp m_molefrac_tab
Vector for storing tabulated thermo.
Definition: BinarySolutionTabulatedThermo.h:268
Cantera::BinarySolutionTabulatedThermo::m_kk_tab
size_t m_kk_tab
Current tabulated species index.
Definition: BinarySolutionTabulatedThermo.h:256
Cantera::BinarySolutionTabulatedThermo::initThermo
virtual void initThermo()
Initialize the ThermoPhase object after all species have been set up.
Definition: BinarySolutionTabulatedThermo.cpp:90
Cantera::BinarySolutionTabulatedThermo::type
virtual std::string type() const
String indicating the thermodynamic model implemented.
Definition: BinarySolutionTabulatedThermo.h:190
Cantera::BinarySolutionTabulatedThermo::getPartialMolarVolumes
virtual void getPartialMolarVolumes(double *vbar) const
returns an array of partial molar volumes of the species in the solution.
Definition: BinarySolutionTabulatedThermo.cpp:326
Cantera::BinarySolutionTabulatedThermo::initThermoXML
virtual void initThermoXML(XML_Node &phaseNode, const std::string &id_)
Import and initialize a ThermoPhase object using an XML tree.
Definition: BinarySolutionTabulatedThermo.cpp:177
Cantera::BinarySolutionTabulatedThermo::m_h0_tab
double m_h0_tab
Tabulated contribution to h0[m_kk_tab] at the current composition.
Definition: BinarySolutionTabulatedThermo.h:262
Cantera::BinarySolutionTabulatedThermo::compositionChanged
virtual void compositionChanged()
If the compositions have changed, update the tabulated thermo lookup.
Definition: BinarySolutionTabulatedThermo.cpp:40
Cantera::BinarySolutionTabulatedThermo::interpolate
double interpolate(const double x, const vector_fp &inputData) const
Species thermodynamics linear interpolation function.
Definition: BinarySolutionTabulatedThermo.cpp:286
Cantera::BinarySolutionTabulatedThermo::_updateThermo
virtual void _updateThermo() const
This function gets called for every call to functions in this class.
Definition: BinarySolutionTabulatedThermo.cpp:46
Cantera::BinarySolutionTabulatedThermo::ready
virtual bool ready() const
Returns a bool indicating whether the object is ready for use.
Definition: BinarySolutionTabulatedThermo.cpp:161
Cantera::BinarySolutionTabulatedThermo::BinarySolutionTabulatedThermo
BinarySolutionTabulatedThermo(const std::string &infile="", const std::string &id="")
Construct and initialize an BinarySolutionTabulatedThermo ThermoPhase object directly from an input f...
Definition: BinarySolutionTabulatedThermo.cpp:23
Cantera::BinarySolutionTabulatedThermo::calcDensity
virtual void calcDensity()
Overloads the calcDensity() method of IdealSolidSoln to also consider non-ideal behavior.
Definition: BinarySolutionTabulatedThermo.cpp:333
Cantera::IdealSolidSolnPhase
Class IdealSolidSolnPhase represents a condensed phase ideal solution compound.
Definition: IdealSolidSolnPhase.h:40
Cantera::XML_Node
Class XML_Node is a tree-based representation of the contents of an XML file.
Definition: xml.h:103
Cantera
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:557
Cantera::vector_fp
std::vector< double > vector_fp
Turn on the use of stl vectors for the basic array type within cantera Vector of doubles.
Definition: ct_defs.h:184
utilities.h
Various templated functions that carry out common vector operations (see Templated Utility Functions)...