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
16 namespace 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 */
151 class StoichSubstance : public SingleSpeciesTP
152{
153 public:
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
SingleSpeciesTP.h
Header for the SingleSpeciesTP class, which is a filter class for ThermoPhase, that eases the constru...
Cantera::AnyMap
A map of string keys to values whose type can vary at runtime.
Definition: AnyMap.h:399
Cantera::Phase::name
std::string name() const
Return the name of the phase.
Definition: Phase.cpp:70
Cantera::SingleSpeciesTP
The SingleSpeciesTP class is a filter class for ThermoPhase.
Definition: SingleSpeciesTP.h:57
Cantera::StoichSubstance
Class StoichSubstance represents a stoichiometric (fixed composition) incompressible substance.
Definition: StoichSubstance.h:152
Cantera::StoichSubstance::getGibbs_RT
virtual void getGibbs_RT(doublereal *grt) const
Get the nondimensional Gibbs functions for the species in their standard states at the current T and ...
Definition: StoichSubstance.cpp:95
Cantera::StoichSubstance::pressure
virtual doublereal pressure() const
Report the Pressure. Units: Pa.
Definition: StoichSubstance.cpp:33
Cantera::StoichSubstance::StoichSubstance
StoichSubstance(const std::string &infile="", const std::string &id="")
Construct and initialize a StoichSubstance ThermoPhase object directly from an ASCII input file.
Definition: StoichSubstance.cpp:21
Cantera::StoichSubstance::initThermoXML
virtual void initThermoXML(XML_Node &phaseNode, const std::string &id)
Import and initialize a ThermoPhase object using an XML tree.
Definition: StoichSubstance.cpp:184
Cantera::StoichSubstance::logStandardConc
virtual doublereal logStandardConc(size_t k=0) const
Natural logarithm of the standard concentration of the kth species.
Definition: StoichSubstance.cpp:70
Cantera::StoichSubstance::getActivityConcentrations
virtual void getActivityConcentrations(doublereal *c) const
This method returns an array of generalized concentrations.
Definition: StoichSubstance.cpp:60
Cantera::StoichSubstance::thermalExpansionCoeff
virtual doublereal thermalExpansionCoeff() const
Return the volumetric thermal expansion coefficient. Units: 1/K.
Definition: StoichSubstance.cpp:48
Cantera::StoichSubstance::getCp_R
virtual void getCp_R(doublereal *cpr) const
Get the nondimensional Heat Capacities at constant pressure for the species standard states at the cu...
Definition: StoichSubstance.cpp:101
Cantera::StoichSubstance::getStandardChemPotentials
virtual void getStandardChemPotentials(doublereal *mu0) const
Get the array of chemical potentials at unit activity for the species at their standard states at the...
Definition: StoichSubstance.cpp:77
Cantera::StoichSubstance::isCompressible
virtual bool isCompressible() const
Return whether phase represents a compressible substance.
Definition: StoichSubstance.h:180
Cantera::StoichSubstance::getEntropy_R
virtual void getEntropy_R(doublereal *sr) const
Get the array of nondimensional Entropy functions for the standard state species at the current T and...
Definition: StoichSubstance.cpp:90
Cantera::StoichSubstance::setPressure
virtual void setPressure(doublereal p)
Set the pressure at constant temperature. Units: Pa.
Definition: StoichSubstance.cpp:38
Cantera::StoichSubstance::initThermo
virtual void initThermo()
Initialize the ThermoPhase object after all species have been set up.
Definition: StoichSubstance.cpp:123
Cantera::StoichSubstance::type
virtual std::string type() const
String indicating the thermodynamic model implemented.
Definition: StoichSubstance.h:176
Cantera::StoichSubstance::getIntEnergy_RT_ref
virtual void getIntEnergy_RT_ref(doublereal *urt) const
Returns the vector of nondimensional internal Energies of the reference state at the current temperat...
Definition: StoichSubstance.cpp:115
Cantera::StoichSubstance::getIntEnergy_RT
virtual void getIntEnergy_RT(doublereal *urt) const
Returns the vector of nondimensional Internal Energies of the standard state species at the current T...
Definition: StoichSubstance.cpp:107
Cantera::StoichSubstance::standardConcentrationUnits
virtual Units standardConcentrationUnits() const
Returns the units of the "standard concentration" for this phase.
Definition: StoichSubstance.cpp:55
Cantera::StoichSubstance::setParametersFromXML
virtual void setParametersFromXML(const XML_Node &eosdata)
Set equation of state parameter values from XML entries.
Definition: StoichSubstance.cpp:213
Cantera::StoichSubstance::getSpeciesParameters
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...
Definition: StoichSubstance.cpp:159
Cantera::StoichSubstance::setParameters
virtual void setParameters(int n, doublereal *const c)
Set the equation of state parameters.
Definition: StoichSubstance.cpp:202
Cantera::StoichSubstance::getEnthalpy_RT
virtual void getEnthalpy_RT(doublereal *hrt) const
Get the nondimensional Enthalpy functions for the species at their standard states at the current T a...
Definition: StoichSubstance.cpp:83
Cantera::StoichSubstance::getParameters
virtual void getParameters(int &n, doublereal *const c) const
Get the equation of state parameters in a vector.
Definition: StoichSubstance.cpp:207
Cantera::StoichSubstance::isothermalCompressibility
virtual doublereal isothermalCompressibility() const
Returns the isothermal compressibility. Units: 1/Pa.
Definition: StoichSubstance.cpp:43
Cantera::StoichSubstance::standardConcentration
virtual doublereal standardConcentration(size_t k=0) const
Return the standard concentration for the kth species.
Definition: StoichSubstance.cpp:65
Cantera::Units
A representation of the units associated with a dimensional quantity.
Definition: Units.h:30
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