Cantera 2.6.0
StoichSubstance.h
Go to the documentation of this file.
1/**
2 * @file StoichSubstance.h
3 * Header file for the StoichSubstance class, which represents a fixed-composition
4 * incompressible substance (see \ref thermoprops and
5 * class \link Cantera::StoichSubstance StoichSubstance\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_STOICHSUBSTANCE_H
12#define CT_STOICHSUBSTANCE_H
13
14#include "SingleSpeciesTP.h"
15
16namespace Cantera
17{
18
19//! Class StoichSubstance 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 * constant volume approximation.
25 *
26 * ## Specification of Species Standard State Properties
27 *
28 * This class inherits from SingleSpeciesTP. It is assumed that the reference
29 * state thermodynamics may be obtained by a pointer to a populated species
30 * thermodynamic property manager class (see ThermoPhase::m_spthermo). How to
31 * relate pressure changes to the reference state thermodynamics is resolved at
32 * this level.
33 *
34 * For an incompressible, stoichiometric substance, the molar internal energy is
35 * independent of pressure. Since the thermodynamic properties are specified by
36 * giving the standard-state enthalpy, the term \f$ P_0 \hat v\f$ is subtracted
37 * from the specified molar enthalpy to compute the molar internal energy. The
38 * entropy is assumed to be independent of the pressure.
39 *
40 * The enthalpy function is given by the following relation.
41 *
42 * \f[
43 * h^o_k(T,P) =
44 * h^{ref}_k(T) + \tilde v \left( P - P_{ref} \right)
45 * \f]
46 *
47 * For an incompressible, stoichiometric substance, the molar internal energy is
48 * independent of pressure. Since the thermodynamic properties are specified by
49 * giving the standard-state enthalpy, the term \f$ P_{ref} \tilde v\f$ is
50 * subtracted from the specified reference molar enthalpy to compute the molar
51 * internal energy.
52 *
53 * \f[
54 * u^o_k(T,P) = h^{ref}_k(T) - P_{ref} \tilde v
55 * \f]
56 *
57 * The standard state heat capacity and entropy are independent of pressure. The
58 * standard state Gibbs free energy is obtained from the enthalpy and entropy
59 * functions.
60 *
61 * ## Specification of Solution Thermodynamic Properties
62 *
63 * All solution properties are obtained from the standard state species
64 * functions, since there is only one species in the phase.
65 *
66 * ## Application within Kinetics Managers
67 *
68 * The standard concentration is equal to 1.0. This means that the kinetics
69 * operator works on an (activities basis). Since this is a stoichiometric
70 * substance, this means that the concentration of this phase drops out of
71 * kinetics expressions.
72 *
73 * An example of a reaction using this is a sticking coefficient reaction of a
74 * substance in an ideal gas phase on a surface with a bulk phase species in
75 * this phase. In this case, the rate of progress for this reaction,
76 * \f$ R_s \f$, may be expressed via the following equation:
77 * \f[
78 * R_s = k_s C_{gas}
79 * \f]
80 * where the units for \f$ R_s \f$ are kmol m-2 s-1. \f$ C_{gas} \f$ has units
81 * of kmol m-3. Therefore, the kinetic rate constant, \f$ k_s \f$, has units of
82 * m s-1. Nowhere does the concentration of the bulk phase appear in the rate
83 * constant expression, since it's a stoichiometric phase and the activity is
84 * always equal to 1.0.
85 *
86 * ## Instantiation of the Class
87 *
88 * The constructor for this phase is NOT located in the default ThermoFactory
89 * for %Cantera. However, a new StoichSubstance may be created by
90 * the following code snippets:
91 *
92 * @code
93 * XML_Node *xm = get_XML_NameID("phase", iFile + "#NaCl(S)", 0);
94 * StoichSubstance *solid = new StoichSubstance(*xm);
95 * @endcode
96 *
97 * or by the following call to importPhase():
98 *
99 * @code
100 * XML_Node *xm = get_XML_NameID("phase", iFile + "#NaCl(S)", 0);
101 * StoichSubstance solid;
102 * importPhase(*xm, &solid);
103 * @endcode
104 *
105 * ## XML Example
106 *
107 * *Note: The XML input format is deprecated and will be removed in %Cantera 3.0*
108 *
109 * The phase model name for this is called StoichSubstance. It must be supplied
110 * as the model attribute of the thermo XML element entry. Within the phase XML
111 * block, the density of the phase must be specified. An example of an XML file
112 * this phase is given below.
113 *
114 * @code
115 * <!-- phase NaCl(S) -->
116 * <phase dim="3" id="NaCl(S)">
117 * <elementArray datasrc="elements.xml">
118 * Na Cl
119 * </elementArray>
120 * <speciesArray datasrc="#species_NaCl(S)"> NaCl(S) </speciesArray>
121 * <thermo model="StoichSubstance">
122 * <density units="g/cm3">2.165</density>
123 * </thermo>
124 * <transport model="None"/>
125 * <kinetics model="none"/>
126 * </phase>
127 *
128 * <!-- species definitions -->
129 * <speciesData id="species_NaCl(S)">
130 * <!-- species NaCl(S) -->
131 * <species name="NaCl(S)">
132 * <atomArray> Na:1 Cl:1 </atomArray>
133 * <thermo>
134 * <Shomate Pref="1 bar" Tmax="1075.0" Tmin="250.0">
135 * <floatArray size="7">
136 * 50.72389, 6.672267, -2.517167,
137 * 10.15934, -0.200675, -427.2115,
138 * 130.3973
139 * </floatArray>
140 * </Shomate>
141 * </thermo>
142 * <density units="g/cm3">2.165</density>
143 * </species>
144 * </speciesData> @endcode
145 *
146 * The model attribute, "StoichSubstance", on the thermo element
147 * identifies the phase as being a StoichSubstance object.
148 *
149 * @ingroup thermoprops
150 */
152{
153public:
154 //! Construct and initialize a StoichSubstance ThermoPhase object directly
155 //! from an ASCII input file
156 /*!
157 * @param infile name of the input file. If blank, an empty phase will be
158 * created.
159 * @param id name of the phase id in the file.
160 * If this is blank, the first phase in the file is used.
161 */
162 explicit StoichSubstance(const std::string& infile="",
163 const std::string& id="");
164
165 //! Construct and initialize a StoichSubstance ThermoPhase object directly
166 //! from an XML database
167 /*!
168 * @param phaseRef XML node pointing to a StoichSubstance description
169 * @param id Id of the phase.
170 *
171 * @deprecated The XML input format is deprecated and will be removed in
172 * Cantera 3.0.
173 */
174 StoichSubstance(XML_Node& phaseRef, const std::string& id = "");
175
176 virtual std::string type() const {
177 return "StoichSubstance";
178 }
179
180 virtual bool isCompressible() const {
181 return false;
182 }
183
184 //! @name Mechanical Equation of State
185 //! @{
186
187 //! Report the Pressure. Units: Pa.
188 /*!
189 * For an incompressible substance, the density is independent of pressure.
190 * This method simply returns the stored pressure value.
191 */
192 virtual doublereal pressure() const;
193
194 //! Set the pressure at constant temperature. Units: Pa.
195 /*!
196 * For an incompressible substance, the density is independent of pressure.
197 * Therefore, this method only stores the specified pressure value. It does
198 * not modify the density.
199 *
200 * @param p Pressure (units - Pa)
201 */
202 virtual void setPressure(doublereal p);
203
204 virtual doublereal isothermalCompressibility() const;
205 virtual doublereal thermalExpansionCoeff() const;
206
207 /**
208 * @}
209 * @name Activities, Standard States, and Activity Concentrations
210 *
211 * This section is largely handled by parent classes, since there
212 * is only one species. Therefore, the activity is equal to one.
213 * @{
214 */
215
216 virtual Units standardConcentrationUnits() const;
217
218 //! This method returns an array of generalized concentrations
219 /*!
220 * \f$ C^a_k\f$ are defined such that \f$ a_k = C^a_k / C^0_k, \f$ where
221 * \f$ C^0_k \f$ is a standard concentration defined below and \f$ a_k \f$
222 * are activities used in the thermodynamic functions. These activity (or
223 * generalized) concentrations are used by kinetics manager classes to
224 * compute the forward and reverse rates of elementary reactions.
225 *
226 * For a stoichiometric substance, there is only one species, and the
227 * generalized concentration is 1.0.
228 *
229 * @param c Output array of generalized concentrations. The
230 * units depend upon the implementation of the
231 * reaction rate expressions within the phase.
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 * (that is, 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
243 * is to 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.
262 * Length: m_kk.
263 */
264 virtual void getStandardChemPotentials(doublereal* mu0) const;
265
266 //! @}
267 //! @name Properties of the Standard State of the Species in the Solution
268 //! @{
269
270 virtual void getEnthalpy_RT(doublereal* hrt) const;
271 virtual void getEntropy_R(doublereal* sr) const;
272 virtual void getGibbs_RT(doublereal* grt) const;
273 virtual void getCp_R(doublereal* cpr) const;
274
275 //! Returns the vector of nondimensional Internal Energies of the standard
276 //! state species at the current *T* and *P* of the solution
277 /*!
278 * For an incompressible, stoichiometric substance, the molar internal
279 * energy is independent of pressure. Since the thermodynamic properties
280 * are specified by giving the standard-state enthalpy, the term
281 * \f$ P_{ref} \hat v\f$ is subtracted from the specified reference molar
282 * enthalpy to compute the standard state molar internal energy.
283 *
284 * @param urt output vector of nondimensional standard state
285 * internal energies of the species. Length: m_kk.
286 */
287 virtual void getIntEnergy_RT(doublereal* urt) const;
288
289 //! @}
290 //! @name Thermodynamic Values for the Species Reference States
291 //! @{
292
293 //! Returns the vector of nondimensional internal Energies of the reference
294 //! state at the current temperature of the solution and the reference
295 //! pressure for each species.
296 /*!
297 * @param urt Output vector of nondimensional reference state internal
298 * energies of the species. Length: m_kk
299 */
300 virtual void getIntEnergy_RT_ref(doublereal* urt) const;
301 //! @}
302
303 virtual void initThermo();
304 virtual void getSpeciesParameters(const std::string& name,
305 AnyMap& speciesNode) const;
306 virtual void initThermoXML(XML_Node& phaseNode, const std::string& id);
307
308 //! Set the equation of state parameters
309 /*!
310 * @internal
311 *
312 * @param n number of parameters
313 * @param c array of \a n coefficients
314 * c[0] = density of phase [ kg/m3 ]
315 */
316 virtual void setParameters(int n, doublereal* const c);
317
318 //! Get the equation of state parameters in a vector
319 /*!
320 * @internal
321 *
322 * @param n number of parameters
323 * @param c array of \a n coefficients
324 *
325 * For this phase:
326 * - n = 1
327 * - c[0] = density of phase [ kg/m3 ]
328 */
329 virtual void getParameters(int& n, doublereal* const c) const;
330
331 //! Set equation of state parameter values from XML entries.
332 /*!
333 * For this phase, the density of the phase is specified in this block.
334 *
335 * @param eosdata An XML_Node object corresponding to
336 * the "thermo" entry for this phase in the input file.
337 *
338 * eosdata points to the thermo block, and looks like this:
339 *
340 * @code
341 * <phase id="stoichsolid" >
342 * <thermo model="StoichSubstance">
343 * <density units="g/cm3">3.52</density>
344 * </thermo>
345 * </phase>
346 * @endcode
347 *
348 * @deprecated The XML input format is deprecated and will be removed in
349 * Cantera 3.0.
350 */
351 virtual void setParametersFromXML(const XML_Node& eosdata);
352};
353
354}
355
356#endif
Header for the SingleSpeciesTP class, which is a filter class for ThermoPhase, that eases the constru...
A map of string keys to values whose type can vary at runtime.
Definition: AnyMap.h:399
std::string name() const
Return the name of the phase.
Definition: Phase.cpp:70
The SingleSpeciesTP class is a filter class for ThermoPhase.
Class StoichSubstance represents a stoichiometric (fixed composition) incompressible substance.
virtual void getGibbs_RT(doublereal *grt) const
Get the nondimensional Gibbs functions for the species in their standard states at the current T and ...
virtual doublereal pressure() const
Report the Pressure. Units: Pa.
StoichSubstance(const std::string &infile="", const std::string &id="")
Construct and initialize a StoichSubstance ThermoPhase object directly from an ASCII input file.
virtual void initThermoXML(XML_Node &phaseNode, const std::string &id)
Import and initialize a ThermoPhase object using an XML tree.
virtual doublereal logStandardConc(size_t k=0) const
Natural logarithm of the standard concentration of the kth species.
virtual void getActivityConcentrations(doublereal *c) const
This method returns an array of generalized concentrations.
virtual doublereal thermalExpansionCoeff() const
Return the volumetric thermal expansion coefficient. Units: 1/K.
virtual void getCp_R(doublereal *cpr) const
Get the nondimensional Heat Capacities at constant pressure for the species standard states at the cu...
virtual void getStandardChemPotentials(doublereal *mu0) const
Get the array of chemical potentials at unit activity for the species at their standard states at the...
virtual bool isCompressible() const
Return whether phase represents a compressible substance.
virtual void getEntropy_R(doublereal *sr) const
Get the array of nondimensional Entropy functions for the standard state species at the current T and...
virtual void setPressure(doublereal p)
Set the pressure at constant temperature. Units: Pa.
virtual void initThermo()
Initialize the ThermoPhase object after all species have been set up.
virtual std::string type() const
String indicating the thermodynamic model implemented.
virtual void getIntEnergy_RT_ref(doublereal *urt) const
Returns the vector of nondimensional internal Energies of the reference state at the current temperat...
virtual void getIntEnergy_RT(doublereal *urt) const
Returns the vector of nondimensional Internal Energies of the standard state species at the current T...
virtual Units standardConcentrationUnits() const
Returns the units of the "standard concentration" for this phase.
virtual void setParametersFromXML(const XML_Node &eosdata)
Set equation of state parameter values from XML entries.
virtual void getSpeciesParameters(const std::string &name, AnyMap &speciesNode) const
Get phase-specific parameters of a Species object such that an identical one could be reconstructed a...
virtual void setParameters(int n, doublereal *const c)
Set the equation of state parameters.
virtual void getEnthalpy_RT(doublereal *hrt) const
Get the nondimensional Enthalpy functions for the species at their standard states at the current T a...
virtual void getParameters(int &n, doublereal *const c) const
Get the equation of state parameters in a vector.
virtual doublereal isothermalCompressibility() const
Returns the isothermal compressibility. Units: 1/Pa.
virtual doublereal standardConcentration(size_t k=0) const
Return the standard concentration for the kth species.
A representation of the units associated with a dimensional quantity.
Definition: Units.h:30
Class XML_Node is a tree-based representation of the contents of an XML file.
Definition: xml.h:103
Namespace for the Cantera kernel.
Definition: AnyMap.h:29