| Cantera 3.0.0

Loading...
Searching...
No Matches
ThermoPhase.h
Go to the documentation of this file.
1/**
2 * @file ThermoPhase.h
3 * Header file for class ThermoPhase, the base class for phases with
4 * thermodynamic properties, and the text for the Module thermoprops
5 * (see @ref thermoprops and class @link Cantera::ThermoPhase ThermoPhase@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_THERMOPHASE_H
12#define CT_THERMOPHASE_H
13
14#include "Phase.h"
15#include "MultiSpeciesThermo.h"
16#include "cantera/base/Units.h"
17#include "cantera/base/AnyMap.h"
18
19 namespace Cantera
20{
21
22/**
23 * @defgroup thermoprops Thermodynamic Properties
24 *
25 * These classes are used to compute the thermodynamic properties of phases of matter.
26 * The main base class for describing thermodynamic properties of phases within %Cantera
27 * is called ThermoPhase. %ThermoPhase is a large class that describes the interface
28 * within %Cantera to thermodynamic functions for a phase.
29 *
30 * ## Categorizing the Different ThermoPhase Objects
31 *
32 * ThermoPhase objects may be cataloged into four general bins.
33 *
34 * The first type are those whose underlying species have a reference state associated
35 * with them. The reference state describes the thermodynamic functions for a species at
36 * a single reference pressure, @f$ p_0 @f$. The thermodynamic functions are specified
37 * via derived objects of the SpeciesThermoInterpType object class, and usually consist
38 * of polynomials in temperature such as the NASA polynomial or the Shomate polynomial.
39 * Calculators for these reference states, which manage the calculation for all of the
40 * species in a phase, are all derived from the virtual base class
41 * SpeciesThermoInterpType. Calculators are needed because the actual calculation of the
42 * reference state thermodynamics has been shown to be relatively expensive. A great
43 * deal of work has gone into devising efficient schemes for calculating the
44 * thermodynamic polynomials of a set of species in a phase, in particular gas species
45 * in ideal gas phases whose reference state thermodynamics is specified by NASA
46 * polynomials.
47 *
48 * The reference state thermodynamics combined with the mixing rules and an assumption
49 * about the pressure dependence yields the thermodynamic functions for the phase.
50 * Expressions involving the specification of the fugacities of species would fall into
51 * this category of %ThermoPhase objects. Note, however, that at this time, we do not
52 * have any nontrivial examples of these types of phases. In general, the independent
53 * variables that completely describe the state of the system for this class are
54 * temperature, the phase density, and @f$ N - 1 @f$ species mole or mass fractions.
55 * Additionally, if the phase involves charged species, the phase electric potential is
56 * an added independent variable. Examples of this first class of %ThermoPhase models,
57 * which includes the IdealGasPhase object, the most commonly used object with %Cantera,
58 * include:
59 *
60 * - IdealGasPhase
61 * - StoichSubstance
62 * - SurfPhase
63 * - EdgePhase
64 * - LatticePhase
65 * - LatticeSolidPhase
66 * - PureFluidPhase
67 * - IdealSolidSolnPhase
68 * - VPStandardStateTP
69 *
70 * The second class of objects are all derivatives of the VPStandardStateTP class listed
71 * above. These classes assume that there exists a standard state for each species in
72 * the phase, where the thermodynamic functions are specified as a function of
73 * temperature and pressure. Standard state objects for each species are all derived
74 * from the PDSS virtual base class. In turn, these standard states may employ reference
75 * state calculation to aid in their calculations. However, there are some PDSS objects
76 * which do not employ reference state calculations. An example of this is real equation
77 * of state for liquid water used within the calculation of brine thermodynamics. In
78 * general, the independent variables that completely describe the state of the system
79 * for this class are temperature, the phase pressure, and @f$ N - 1 @f$ species mole or
80 * mass fractions or molalities. The standard state thermodynamics combined with the
81 * mixing rules yields the thermodynamic functions for the phase. Mixing rules are given
82 * in terms of specifying the molar-base activity coefficients or activities. Lists of
83 * phases which belong to this group are given below
84 *
85 * - IdealSolnGasVPSS
86 * - MolalityVPSSTP
87 *
88 * Note, the ideal gas and ideal solution approximations are lumped together in the
89 * class IdealSolnGasVPSS, because at this level they look alike having the same mixing
90 * rules with respect to the specification of the excess thermodynamic properties.
91 *
92 * The third class of objects are all derivatives of the MolalityVPSSTP object. They
93 * assume that the standard states are temperature and pressure dependent but they also
94 * assume that the standard states are molality-based. In other words, they assume that
95 * the standard state of the solute species are in a pseudo state of 1 molality but at
96 * infinite dilution. A solvent must be specified in these calculations, defined as the
97 * first species in the phase, and its standard state is the pure solvent state. Phases
98 * which belong to this group include:
99 *
100 * - DebyeHuckel
101 * - IdealMolalSoln
102 * - HMWSoln
103 *
104 * The fourth class of %ThermoPhase objects are stoichiometric phases. Stoichiometric
105 * phases are phases which consist of one and only one species. The class
106 * SingleSpeciesTP is the base class for these substances. Within the class, the general
107 * %ThermoPhase interface is dumbed down so that phases consisting of one species may be
108 * succinctly described. These phases may have PDSS classes or SpeciesThermoInterpType
109 * calculators associated with them. In general, the independent variables that
110 * completely describe the state of the system for this class are temperature and either
111 * the phase density or the phase pressure. Classes in this group include:
112 *
113 * - StoichSubstance
114 * - WaterSSTP
115 *
116 * ## Creating ThermoPhase objects
117 *
118 * Instances of subclasses of ThermoPhase should be created using the factory methods
119 * newThermo(const string&, const string&), newThermo(const AnyMap&, const AnyMap&), or
120 * newThermoPhase(). This allows new classes to be used with the various %Cantera
121 * language interfaces.
122 *
123 * ## Defining new thermodynamic models
124 *
125 * To implement a new equation of state, derive a class from ThermoPhase or a relevant
126 * existing derived class and overload the virtual methods in ThermoPhase. Methods that
127 * are not needed can be left unimplemented, which will cause an exception to be thrown
128 * if they are called.
129 */
130
131//! @name CONSTANTS - Specification of the Molality convention
132//! @{
133
134//! Standard state uses the molar convention
135 const int cAC_CONVENTION_MOLAR = 0;
136//! Standard state uses the molality convention
137 const int cAC_CONVENTION_MOLALITY = 1;
138
139//! @}
140//! @name CONSTANTS - Specification of the SS convention
141//! @{
142
143//! Standard state uses the molar convention
144 const int cSS_CONVENTION_TEMPERATURE = 0;
145//! Standard state uses the molality convention
146 const int cSS_CONVENTION_VPSS = 1;
147//! Standard state thermodynamics is obtained from slave ThermoPhase objects
148 const int cSS_CONVENTION_SLAVE = 2;
149//! @}
150
151//! Differentiate between mole fractions and mass fractions for input mixture
152//! composition
153 enum class ThermoBasis
154{
155 mass,
156 molar
157};
158
159//! Base class for a phase with thermodynamic properties.
160/*!
161 * Class ThermoPhase is the base class for the family of classes that represent
162 * phases of matter of any type. It defines a common public interface, and
163 * implements a few methods. Most of the methods, however, are declared virtual
164 * and are meant to be overloaded in derived classes. The standard way used
165 * throughout %Cantera to compute properties of phases of matter is through
166 * pointers of type `ThermoPhase*` that point to objects of subclasses of
167 * ThermoPhase.
168 *
169 * Class ThermoPhase extends class Phase by adding methods to compute
170 * thermodynamic properties in addition to the ones that are used to define the
171 * state of a substance (temperature, density/pressure and composition). The
172 * distinction is that the methods declared in ThermoPhase require knowing the
173 * particular equation of state of the phase of interest, while those of class
174 * Phase do not, since they only involve data values stored within the object.
175 *
176 * ## Calculating and accessing thermodynamic properties
177 *
178 * The calculation of thermodynamic functions within %ThermoPhase is broken down roughly
179 * into two or more steps. First, the standard state properties of all of the species
180 * are calculated at the current temperature and at either the current pressure or at a
181 * reference pressure. If the calculation is carried out at a reference pressure instead
182 * of at the current pressure the calculation is called a "reference state properties"
183 * calculation, just to make the distinction (even though it may be considered to be a
184 * fixed-pressure standard-state calculation). The next step is to adjust the reference
185 * state calculation to the current pressure. The thermodynamic functions then are
186 * considered to be at the standard state of each species. Lastly the mixing
187 * contributions are added to arrive at the thermodynamic functions for the solution.
188 *
189 * The %ThermoPhase class provides interfaces to thermodynamic properties calculated for
190 * the reference state of each species, the standard state values for each species, the
191 * thermodynamic functions for solution values, both on a per mole of solution basis
192 * (such as ThermoPhase::enthalpy_mole()), on a per kg of solution basis, and on a
193 * partial molar basis for each species (such as
194 * ThermoPhase::getPartialMolarEnthalpies). At each level, functions for the enthalpy,
195 * entropy, Gibbs free energy, internal energy, and volume are provided. So, 5 levels
196 * (reference state, standard state, partial molar, per mole of solution, and per mass
197 * of solution) and 5 functions multiplied together makes 25 possible functions. That's
198 * why %ThermoPhase is such a large class.
199 *
200 * ## Setting the State of the phase
201 *
202 * Typically, the way the ThermoPhase object works is that there are a set of functions
203 * that set the state of the phase via setting the internal independent variables. Then,
204 * there are another set of functions that query the thermodynamic functions evaluated
205 * at the current %State of the phase. Internally, most of the intermediate work
206 * generally occurs at the point where the internal state of the system is set and not
207 * at the time when individual thermodynamic functions are queried (though the actual
208 * breakdown in work is dependent on the individual derived ThermoPhase object).
209 * Therefore, for efficiency, the user should lump together queries of thermodynamic
210 * functions after setting the state. Moreover, in setting the state, if the density is
211 * the independent variable, the following order should be used:
212 *
213 * - Set the temperature
214 * - Set the mole or mass fractions or set the molalities
215 * - set the pressure.
216 *
217 * For classes which inherit from VPStandardStateTP, the above order may be used, or the
218 * following order may be used. It's not important.
219 *
220 * - Set the temperature
221 * - Set the pressure
222 * - Set the mole or mass fractions or set the molalities
223 *
224 * See the @ref sec-thermophase-set-state "list of methods" that can be used to set
225 * the complete state of ThermoPhase objects.
226 *
227 * ## Treatment of the phase potential and the electrochemical potential of a species
228 *
229 * The electrochemical potential of species k in a phase p, @f$ \zeta_k @f$, is related
230 * to the chemical potential as:
231 *
232 * @f[
233 * \zeta_{k}(T,P) = \mu_{k}(T,P) + z_k \phi_p
234 * @f]
235 *
236 * where @f$ \nu_k @f$ is the charge of species k, and @f$ \phi_p @f$ is the electric
237 * potential of phase p.
238 *
239 * The potential @f$ \phi_p @f$ is tracked and internally stored within the base
240 * ThermoPhase object. It constitutes a specification of the internal state of the
241 * phase; it's the third state variable, the first two being temperature and density
242 * (or, pressure, for incompressible equations of state). It may be set with the
243 * function, setElectricPotential(), and may be queried with the function
244 * electricPotential().
245 *
246 * Note, the overall electrochemical potential of a phase may not be changed by the
247 * potential because many phases enforce charge neutrality:
248 *
249 * @f[
250 * 0 = \sum_k z_k X_k
251 * @f]
252 *
253 * Whether charge neutrality is necessary for a phase is also specified within the
254 * ThermoPhase object, by the function call chargeNeutralityNecessary(). Note, that it
255 * is not necessary for the ideal gas phase, currently. However, it is necessary for
256 * liquid phases such as DebyeHuckel and HMWSoln for the proper specification of the
257 * chemical potentials.
258 *
259 * This equation, when applied to the @f$ \zeta_k @f$ equation described above, results
260 * in a zero net change in the effective Gibbs free energy of the phase. However,
261 * specific charged species in the phase may increase or decrease their electrochemical
262 * potentials, which will have an effect on interfacial reactions involving charged
263 * species, when there is a potential drop between phases. This effect is used within
264 * the InterfaceKinetics and EdgeKinetics classes.
265 *
266 * ## Specification of Activities and Activity Conventions
267 *
268 * The activity @f$ a_k @f$ and activity coefficient @f$ \gamma_k @f$ of a species in
269 * solution is related to the chemical potential by
270 *
271 * @f[
272 * \mu_k = \mu_k^0(T,P) + \hat R T \ln a_k = \mu_k^0(T,P) + \hat R T \ln x_k \gamma_k
273 * @f]
274 *
275 * The quantity @f$ \mu_k^0(T,P) @f$ is the standard chemical potential at unit
276 * activity, which depends on the temperature and pressure, but not on the composition.
277 * The activity is dimensionless. Within liquid electrolytes it's common to use a
278 * molality convention, where solute species employ the molality-based activity
279 * coefficients:
280 *
281 * @f[
282 * \mu_k = \mu_k^\triangle(T,P) + R T \ln a_k^{\triangle} =
283 * \mu_k^\triangle(T,P) + R T \ln \frac{\gamma_k^{\triangle} m_k}{m^\triangle}
284 * @f]
285 *
286 * And the solvent employs the convention
287 * @f[
288 * \mu_o = \mu^o_o(T,P) + RT \ln a_o
289 * @f]
290 *
291 * where @f$ a_o @f$ is often redefined in terms of the osmotic coefficient @f$ \phi
292 * @f$:
293 *
294 * @f[
295 * \phi = \frac{- \ln a_o}{\tilde{M}_o \sum_{i \ne o} m_i}
296 * @f]
297 *
298 * ThermoPhase classes which employ the molality based convention are all derived from
299 * the MolalityVPSSTP class. See the class description for further information on its
300 * capabilities.
301 *
302 * The activity convention used by a ThermoPhase object may be queried via the
303 * activityConvention() function. A zero means molar based, while a one
304 * means molality based.
305 *
306 * The function getActivities() returns a vector of activities. Whether these are
307 * molar-based or molality-based depends on the value of activityConvention().
308 *
309 * The function getActivityCoefficients() always returns molar-based activity
310 * coefficients regardless of the activity convention used. The function
311 * MolalityVPSSTP::getMolalityActivityCoefficients() returns molality
312 * based activity coefficients for those ThermoPhase objects derived
313 * from the MolalityVPSSTP class. The function MolalityVPSSTP::osmoticCoefficient()
314 * returns the osmotic coefficient.
315
316 * ## Activity Concentrations: Relationship of ThermoPhase to Kinetics Expressions
317 *
318 * %Cantera can handle both thermodynamics and kinetics mechanisms. Reversible kinetics
319 * mechanisms within %Cantera must be compatible with thermodynamics in the sense that
320 * at equilibrium, or at infinite times, the concentrations of species must conform to
321 * thermodynamics. This means that for every valid reversible kinetics reaction in a
322 * mechanism, it must be reducible to an expression involving the ratio of the product
323 * activity to the reactant activities being equal to the exponential of the
324 * dimensionless standard state gibbs free energies of reaction. Irreversible kinetics
325 * reactions do not have this requirement; however, their usage can yield unexpected and
326 * inconsistent results in many situations.
327 *
328 * The actual units used in a kinetics expression depend on the context or the relative
329 * field of study. For example, in gas phase kinetics, species in kinetics expressions
330 * are expressed in terms of concentrations, for example, gmol cm-3. In solid phase
331 * studies, however, kinetics is usually expressed in terms of unitless activities,
332 * which most often equate to solid phase mole fractions. In order to accommodate
333 * variability here, %Cantera has come up with the idea of activity concentrations,
334 * @f$ C^a_k @f$. Activity concentrations are the expressions used directly in kinetics
335 * expressions. These activity (or generalized) concentrations are used by kinetics
336 * manager classes to compute the forward and reverse rates of elementary reactions.
337 * Note that they may or may not have units of concentration --- they might be partial
338 * pressures, mole fractions, or surface coverages, The activity concentrations for
339 * species *k*, @f$ C^a_k @f$, are related to the activity for species *k*, @f$ a_k @f$,
340 * via the expression:
341 *
342 * @f[
343 * a_k = C^a_k / C^0_k
344 * @f]
345 *
346 * @f$ C^0_k @f$ are called standard concentrations. They serve as multiplicative
347 * factors between the activities and the generalized concentrations. Standard
348 * concentrations may be different for each species. They may depend on both the
349 * temperature and the pressure. However, they may not depend on the composition of the
350 * phase. For example, for the IdealGasPhase object the standard concentration is
351 * defined as
352 *
353 * @f[
354 * C^0_k = \frac{P}{RT}
355 * @f]
356 *
357 * while in many solid phase kinetics problems,
358 *
359 * @f[
360 * C^0_k = 1.0
361 * @f]
362 *
363 * is employed making the units for activity concentrations in solids unitless.
364 *
365 * ThermoPhase member functions dealing with this concept include
366 * getActivityConcentrations(), which provides a vector of the current activity
367 * concentrations. The function standardConcentration() returns the standard
368 * concentration of the kth species. The function logStandardConc(), returns the natural
369 * log of the kth standard concentration. The function standardConcentrationUnits()
370 * returns the units of the standard concentration.
371 *
372 * ### Equilibrium constants
373 *
374 * - @f$ K_a @f$ is the equilibrium constant defined in terms of the standard state
375 * Gibbs free energy values. It is by definition dimensionless.
376 *
377 * - @f$ K_p @f$ is the equilibrium constant defined in terms of the reference state
378 * Gibbs free energy values. It is by definition dimensionless. The pressure
379 * dependence is handled entirely on the RHS of the equilibrium expression.
380 *
381 * - @f$ K_c @f$ is the equilibrium constant defined in terms of the activity
382 * concentrations. The dimensions depend on the number of products and reactants.
383 *
384 * The kinetics manager requires the calculation of @f$ K_c @f$ for the calculation of
385 * the reverse rate constant.
386 *
387 * @ingroup thermoprops
388 */
389 class ThermoPhase : public Phase
390{
391 public:
392 //! Constructor. Note that ThermoPhase is meant to be used as a base class,
393 //! so this constructor should not be called explicitly.
394 ThermoPhase() = default;
395
396 //! @name Information Methods
397 //! @{
398
399 string type() const override {
400 return "none";
401 }
402
403 //! Boolean indicating whether phase is ideal
404 virtual bool isIdeal() const {
405 return false;
406 }
407
408 //! String indicating the mechanical phase of the matter in this Phase.
409 /*!
410 * Options for the string are:
411 * * `unspecified`
412 * * `supercritical`
413 * * `gas`
414 * * `liquid`
415 * * `solid`
416 * * `solid-liquid-mix`
417 * * `solid-gas-mix`
418 * * `liquid-gas-mix`
419 * * `solid-liquid-gas-mix`
420 *
421 * `unspecified` is the default and should be used when the Phase does not
422 * distinguish between mechanical phases or does not have enough information to
423 * determine which mechanical phase(s) are present.
424 *
425 * @todo Needs to be implemented for all phase types. Currently only implemented for
426 * PureFluidPhase.
427 */
428 virtual string phaseOfMatter() const {
429 return "unspecified";
430 }
431
432 /**
433 * Returns the reference pressure in Pa. This function is a wrapper
434 * that calls the species thermo refPressure function.
435 */
436 virtual double refPressure() const {
437 return m_spthermo.refPressure();
438 }
439
440 //! Minimum temperature for which the thermodynamic data for the species
441 //! or phase are valid.
442 /*!
443 * If no argument is supplied, the value returned will be the lowest
444 * temperature at which the data for @e all species are valid. Otherwise,
445 * the value will be only for species @e k. This function is a wrapper that
446 * calls the species thermo minTemp function.
447 *
448 * @param k index of the species. Default is -1, which will return the max
449 * of the min value over all species.
450 */
451 virtual double minTemp(size_t k = npos) const {
452 return m_spthermo.minTemp(k);
453 }
454
455 //! Report the 298 K Heat of Formation of the standard state of one species
456 //! (J kmol-1)
457 /*!
458 * The 298K Heat of Formation is defined as the enthalpy change to create
459 * the standard state of the species from its constituent elements in their
460 * standard states at 298 K and 1 bar.
461 *
462 * @param k species index
463 * @returns the current value of the Heat of Formation at 298K
464 * and 1 bar
465 */
466 double Hf298SS(const size_t k) const {
467 return m_spthermo.reportOneHf298(k);
468 }
469
470 //! Modify the value of the 298 K Heat of Formation of one species in the
471 //! phase (J kmol-1)
472 /*!
473 * The 298K heat of formation is defined as the enthalpy change to create
474 * the standard state of the species from its constituent elements in their
475 * standard states at 298 K and 1 bar.
476 *
477 * @param k Species k
478 * @param Hf298New Specify the new value of the Heat of Formation at
479 * 298K and 1 bar
480 */
481 virtual void modifyOneHf298SS(const size_t k, const double Hf298New) {
482 m_spthermo.modifyOneHf298(k, Hf298New);
483 invalidateCache();
484 }
485
486 //! Restore the original heat of formation of one or more species
487 /*!
488 * Resets changes made by modifyOneHf298SS(). If the species index is not
489 * specified, the heats of formation for all species are restored.
490 */
491 virtual void resetHf298(const size_t k=npos);
492
493 //! Maximum temperature for which the thermodynamic data for the species
494 //! are valid.
495 /*!
496 * If no argument is supplied, the value returned will be the highest
497 * temperature at which the data for @e all species are valid. Otherwise,
498 * the value will be only for species @e k. This function is a wrapper that
499 * calls the species thermo maxTemp function.
500 *
501 * @param k index of the species. Default is -1, which will return the min
502 * of the max value over all species.
503 */
504 virtual double maxTemp(size_t k = npos) const {
505 return m_spthermo.maxTemp(k);
506 }
507
508 //! Returns the chargeNeutralityNecessity boolean
509 /*!
510 * Some phases must have zero net charge in order for their thermodynamics
511 * functions to be valid. If this is so, then the value returned from this
512 * function is true. If this is not the case, then this is false. Now, ideal
513 * gases have this parameter set to false, while solution with molality-
514 * based activity coefficients have this parameter set to true.
515 */
516 bool chargeNeutralityNecessary() const {
517 return m_chargeNeutralityNecessary;
518 }
519
520 //! @}
521 //! @name Molar Thermodynamic Properties of the Solution
522 //! @{
523
524 //! Molar enthalpy. Units: J/kmol.
525 virtual double enthalpy_mole() const {
526 throw NotImplementedError("ThermoPhase::enthalpy_mole");
527 }
528
529 //! Molar internal energy. Units: J/kmol.
530 virtual double intEnergy_mole() const {
531 return enthalpy_mole() - pressure()* molarVolume();
532 }
533
534 //! Molar entropy. Units: J/kmol/K.
535 virtual double entropy_mole() const {
536 throw NotImplementedError("ThermoPhase::entropy_mole");
537 }
538
539 //! Molar Gibbs function. Units: J/kmol.
540 virtual double gibbs_mole() const {
541 return enthalpy_mole() - temperature()*entropy_mole();
542 }
543
544 //! Molar heat capacity at constant pressure. Units: J/kmol/K.
545 virtual double cp_mole() const {
546 throw NotImplementedError("ThermoPhase::cp_mole");
547 }
548
549 //! Molar heat capacity at constant volume. Units: J/kmol/K.
550 virtual double cv_mole() const {
551 throw NotImplementedError("ThermoPhase::cv_mole");
552 }
553
554 //! @}
555 //! @name Mechanical Properties
556 //! @{
557
558 //! Returns the isothermal compressibility. Units: 1/Pa.
559 /*!
560 * The isothermal compressibility is defined as
561 * @f[
562 * \kappa_T = -\frac{1}{v}\left(\frac{\partial v}{\partial P}\right)_T
563 * @f]
564 * or
565 * @f[
566 * \kappa_T = \frac{1}{\rho}\left(\frac{\partial \rho}{\partial P}\right)_T
567 * @f]
568 */
569 virtual double isothermalCompressibility() const {
570 throw NotImplementedError("ThermoPhase::isothermalCompressibility");
571 }
572
573 //! Return the volumetric thermal expansion coefficient. Units: 1/K.
574 /*!
575 * The thermal expansion coefficient is defined as
576 * @f[
577 * \beta = \frac{1}{v}\left(\frac{\partial v}{\partial T}\right)_P
578 * @f]
579 */
580 virtual double thermalExpansionCoeff() const {
581 throw NotImplementedError("ThermoPhase::thermalExpansionCoeff");
582 }
583
584 //! Return the speed of sound. Units: m/s.
585 /*!
586 * The speed of sound is defined as
587 * @f[
588 * c = \sqrt{\left(\frac{\partial P}{\partial\rho}\right)_s}
589 * @f]
590 */
591 virtual double soundSpeed() const {
592 throw NotImplementedError("ThermoPhase::soundSpeed");
593 }
594
595 //! @}
596 //! @name Electric Potential
597 //!
598 //! The phase may be at some non-zero electrical potential. These methods
599 //! set or get the value of the electric potential.
600 //! @{
601
602 //! Set the electric potential of this phase (V).
603 /*!
604 * This is used by classes InterfaceKinetics and EdgeKinetics to
605 * compute the rates of charge-transfer reactions, and in computing
606 * the electrochemical potentials of the species.
607 *
608 * Each phase may have its own electric potential.
609 *
610 * @param v Input value of the electric potential in Volts
611 */
612 void setElectricPotential(double v) {
613 m_phi = v;
614 invalidateCache();
615 }
616
617 //! Returns the electric potential of this phase (V).
618 /*!
619 * Units are Volts (which are Joules/coulomb)
620 */
621 double electricPotential() const {
622 return m_phi;
623 }
624
625 //! @}
626 //! @name Activities, Standard States, and Activity Concentrations
627 //!
628 //! The activity @f$ a_k @f$ of a species in solution is related to the
629 //! chemical potential by @f[ \mu_k = \mu_k^0(T,P) + \hat R T \ln a_k. @f]
630 //! The quantity @f$ \mu_k^0(T,P) @f$ is the standard chemical potential at
631 //! unit activity, which depends on temperature and pressure, but not on
632 //! composition. The activity is dimensionless.
633 //! @{
634
635 //! This method returns the convention used in specification of the
636 //! activities, of which there are currently two, molar- and molality-based
637 //! conventions.
638 /*!
639 * Currently, there are two activity conventions:
640 * - Molar-based activities
641 * %Unit activity of species at either a hypothetical pure
642 * solution of the species or at a hypothetical
643 * pure ideal solution at infinite dilution
644 * cAC_CONVENTION_MOLAR 0
645 * - default
646 *
647 * - Molality-based activities
648 * (unit activity of solutes at a hypothetical 1 molal
649 * solution referenced to infinite dilution at all
650 * pressures and temperatures).
651 * cAC_CONVENTION_MOLALITY 1
652 */
653 virtual int activityConvention() const;
654
655 //! This method returns the convention used in specification of the standard
656 //! state, of which there are currently two, temperature based, and variable
657 //! pressure based.
658 /*!
659 * Currently, there are two standard state conventions:
660 * - Temperature-based activities
661 * cSS_CONVENTION_TEMPERATURE 0
662 * - default
663 *
664 * - Variable Pressure and Temperature -based activities
665 * cSS_CONVENTION_VPSS 1
666 *
667 * - Thermodynamics is set via slave ThermoPhase objects with
668 * nothing being carried out at this ThermoPhase object level
669 * cSS_CONVENTION_SLAVE 2
670 */
671 virtual int standardStateConvention() const;
672
673 //! Returns the units of the "standard concentration" for this phase
674 /*!
675 * These are the units of the values returned by the functions
676 * getActivityConcentrations() and standardConcentration(), which can
677 * vary between different ThermoPhase-derived classes, or change within
678 * a single class depending on input options. See the documentation for
679 * standardConcentration() for the derived class for specific details.
680 */
681 virtual Units standardConcentrationUnits() const;
682
683 //! This method returns an array of generalized concentrations
684 /*!
685 * @f$ C^a_k @f$ are defined such that @f$ a_k = C^a_k / C^0_k, @f$ where
686 * @f$ C^0_k @f$ is a standard concentration defined below and @f$ a_k @f$
687 * are activities used in the thermodynamic functions. These activity (or
688 * generalized) concentrations are used by kinetics manager classes to
689 * compute the forward and reverse rates of elementary reactions. Note that
690 * they may or may not have units of concentration --- they might be partial
691 * pressures, mole fractions, or surface coverages, for example.
692 *
693 * @param c Output array of generalized concentrations. The units depend
694 * upon the implementation of the reaction rate expressions within
695 * the phase.
696 */
697 virtual void getActivityConcentrations(double* c) const {
698 throw NotImplementedError("ThermoPhase::getActivityConcentrations");
699 }
700
701 //! Return the standard concentration for the kth species
702 /*!
703 * The standard concentration @f$ C^0_k @f$ used to normalize the activity
704 * (that is, generalized) concentration. In many cases, this quantity will be
705 * the same for all species in a phase - for example, for an ideal gas @f$
706 * C^0_k = P/\hat R T @f$. For this reason, this method returns a single
707 * value, instead of an array. However, for phases in which the standard
708 * concentration is species-specific (such as surface species of different
709 * sizes), this method may be called with an optional parameter indicating
710 * the species.
711 *
712 * @param k Optional parameter indicating the species. The default
713 * is to assume this refers to species 0.
714 * @return
715 * Returns the standard concentration. The units are by definition
716 * dependent on the ThermoPhase and kinetics manager representation.
717 */
718 virtual double standardConcentration(size_t k=0) const {
719 throw NotImplementedError("ThermoPhase::standardConcentration");
720 }
721
722 //! Natural logarithm of the standard concentration of the kth species.
723 /*!
724 * @param k index of the species (defaults to zero)
725 */
726 virtual double logStandardConc(size_t k=0) const;
727
728 //! Get the array of non-dimensional activities at the current solution
729 //! temperature, pressure, and solution concentration.
730 /*!
731 * Note, for molality based formulations, this returns the molality based
732 * activities.
733 *
734 * We resolve this function at this level by calling on the
735 * activityConcentration function. However, derived classes may want to
736 * override this default implementation.
737 *
738 * @param a Output vector of activities. Length: m_kk.
739 */
740 virtual void getActivities(double* a) const;
741
742 //! Get the array of non-dimensional molar-based activity coefficients at
743 //! the current solution temperature, pressure, and solution concentration.
744 /*!
745 * @param ac Output vector of activity coefficients. Length: m_kk.
746 */
747 virtual void getActivityCoefficients(double* ac) const {
748 if (m_kk == 1) {
749 ac[0] = 1.0;
750 } else {
751 throw NotImplementedError("ThermoPhase::getActivityCoefficients");
752 }
753 }
754
755 //! Get the array of non-dimensional molar-based ln activity coefficients at
756 //! the current solution temperature, pressure, and solution concentration.
757 /*!
758 * @param lnac Output vector of ln activity coefficients. Length: m_kk.
759 */
760 virtual void getLnActivityCoefficients(double* lnac) const;
761
762 //! @}
763 //! @name Partial Molar Properties of the Solution
764 //! @{
765
766 /**
767 * Get the array of non-dimensional species chemical potentials
768 * These are partial molar Gibbs free energies.
769 * @f$ \mu_k / \hat R T @f$.
770 * Units: unitless
771 *
772 * @param mu Output vector of dimensionless chemical potentials.
773 * Length: m_kk.
774 *
775 * @deprecated To be removed after %Cantera 3.0. Use getChemPotentials() instead.
776 */
777 virtual void getChemPotentials_RT(double* mu) const {
778 throw NotImplementedError("ThermoPhase::getChemPotentials_RT");
779 }
780
781 //! Get the species chemical potentials. Units: J/kmol.
782 /*!
783 * This function returns a vector of chemical potentials of the species in
784 * solution at the current temperature, pressure and mole fraction of the
785 * solution.
786 *
787 * @param mu Output vector of species chemical
788 * potentials. Length: m_kk. Units: J/kmol
789 */
790 virtual void getChemPotentials(double* mu) const {
791 throw NotImplementedError("ThermoPhase::getChemPotentials");
792 }
793
794 //! Get the species electrochemical potentials.
795 /*!
796 * These are partial molar quantities. This method adds a term @f$ F z_k
797 * \phi_p @f$ to each chemical potential. The electrochemical potential of
798 * species k in a phase p, @f$ \zeta_k @f$, is related to the chemical
799 * potential via the following equation,
800 *
801 * @f[
802 * \zeta_{k}(T,P) = \mu_{k}(T,P) + F z_k \phi_p
803 * @f]
804 *
805 * @param mu Output vector of species electrochemical
806 * potentials. Length: m_kk. Units: J/kmol
807 */
808 void getElectrochemPotentials(double* mu) const;
809
810 //! Returns an array of partial molar enthalpies for the species
811 //! in the mixture. Units (J/kmol)
812 /*!
813 * @param hbar Output vector of species partial molar enthalpies.
814 * Length: m_kk. units are J/kmol.
815 */
816 virtual void getPartialMolarEnthalpies(double* hbar) const {
817 throw NotImplementedError("ThermoPhase::getPartialMolarEnthalpies");
818 }
819
820 //! Returns an array of partial molar entropies of the species in the
821 //! solution. Units: J/kmol/K.
822 /*!
823 * @param sbar Output vector of species partial molar entropies.
824 * Length = m_kk. units are J/kmol/K.
825 */
826 virtual void getPartialMolarEntropies(double* sbar) const {
827 throw NotImplementedError("ThermoPhase::getPartialMolarEntropies");
828 }
829
830 //! Return an array of partial molar internal energies for the
831 //! species in the mixture. Units: J/kmol.
832 /*!
833 * @param ubar Output vector of species partial molar internal energies.
834 * Length = m_kk. units are J/kmol.
835 */
836 virtual void getPartialMolarIntEnergies(double* ubar) const {
837 throw NotImplementedError("ThermoPhase::getPartialMolarIntEnergies");
838 }
839
840 //! Return an array of partial molar heat capacities for the
841 //! species in the mixture. Units: J/kmol/K
842 /*!
843 * @param cpbar Output vector of species partial molar heat
844 * capacities at constant pressure.
845 * Length = m_kk. units are J/kmol/K.
846 */
847 virtual void getPartialMolarCp(double* cpbar) const {
848 throw NotImplementedError("ThermoPhase::getPartialMolarCp");
849 }
850
851 //! Return an array of partial molar volumes for the
852 //! species in the mixture. Units: m^3/kmol.
853 /*!
854 * @param vbar Output vector of species partial molar volumes.
855 * Length = m_kk. units are m^3/kmol.
856 */
857 virtual void getPartialMolarVolumes(double* vbar) const {
858 throw NotImplementedError("ThermoPhase::getPartialMolarVolumes");
859 }
860
861 //! @}
862 //! @name Properties of the Standard State of the Species in the Solution
863 //! @{
864
865 //! Get the array of chemical potentials at unit activity for the species at
866 //! their standard states at the current *T* and *P* of the solution.
867 /*!
868 * These are the standard state chemical potentials @f$ \mu^0_k(T,P)
869 * @f$. The values are evaluated at the current temperature and pressure of
870 * the solution
871 *
872 * @param mu Output vector of chemical potentials.
873 * Length: m_kk.
874 */
875 virtual void getStandardChemPotentials(double* mu) const {
876 throw NotImplementedError("ThermoPhase::getStandardChemPotentials");
877 }
878
879 //! Get the nondimensional Enthalpy functions for the species at their
880 //! standard states at the current *T* and *P* of the solution.
881 /*!
882 * @param hrt Output vector of nondimensional standard state enthalpies.
883 * Length: m_kk.
884 */
885 virtual void getEnthalpy_RT(double* hrt) const {
886 throw NotImplementedError("ThermoPhase::getEnthalpy_RT");
887 }
888
889 //! Get the array of nondimensional Entropy functions for the standard state
890 //! species at the current *T* and *P* of the solution.
891 /*!
892 * @param sr Output vector of nondimensional standard state entropies.
893 * Length: m_kk.
894 */
895 virtual void getEntropy_R(double* sr) const {
896 throw NotImplementedError("ThermoPhase::getEntropy_R");
897 }
898
899 //! Get the nondimensional Gibbs functions for the species in their standard
900 //! states at the current *T* and *P* of the solution.
901 /*!
902 * @param grt Output vector of nondimensional standard state Gibbs free
903 * energies. Length: m_kk.
904 */
905 virtual void getGibbs_RT(double* grt) const {
906 throw NotImplementedError("ThermoPhase::getGibbs_RT");
907 }
908
909 //! Get the Gibbs functions for the standard state of the species at the
910 //! current *T* and *P* of the solution
911 /*!
912 * Units are Joules/kmol
913 * @param gpure Output vector of standard state Gibbs free energies.
914 * Length: m_kk.
915 */
916 virtual void getPureGibbs(double* gpure) const {
917 throw NotImplementedError("ThermoPhase::getPureGibbs");
918 }
919
920 //! Returns the vector of nondimensional Internal Energies of the standard
921 //! state species at the current *T* and *P* of the solution
922 /*!
923 * @param urt output vector of nondimensional standard state internal energies
924 * of the species. Length: m_kk.
925 */
926 virtual void getIntEnergy_RT(double* urt) const {
927 throw NotImplementedError("ThermoPhase::getIntEnergy_RT");
928 }
929
930 //! Get the nondimensional Heat Capacities at constant pressure for the
931 //! species standard states at the current *T* and *P* of the
932 //! solution
933 /*!
934 * @param cpr Output vector of nondimensional standard state heat
935 * capacities. Length: m_kk.
936 */
937 virtual void getCp_R(double* cpr) const {
938 throw NotImplementedError("ThermoPhase::getCp_R");
939 }
940
941 //! Get the molar volumes of the species standard states at the current
942 //! *T* and *P* of the solution.
943 /*!
944 * units = m^3 / kmol
945 *
946 * @param vol Output vector containing the standard state volumes.
947 * Length: m_kk.
948 */
949 virtual void getStandardVolumes(double* vol) const {
950 throw NotImplementedError("ThermoPhase::getStandardVolumes");
951 }
952
953 //! @}
954 //! @name Thermodynamic Values for the Species Reference States
955 //! @{
956
957 //! Returns the vector of nondimensional enthalpies of the reference state
958 //! at the current temperature of the solution and the reference pressure
959 //! for the species.
960 /*!
961 * @param hrt Output vector containing the nondimensional reference
962 * state enthalpies. Length: m_kk.
963 */
964 virtual void getEnthalpy_RT_ref(double* hrt) const {
965 throw NotImplementedError("ThermoPhase::getEnthalpy_RT_ref");
966 }
967
968 //! Returns the vector of nondimensional Gibbs Free Energies of the
969 //! reference state at the current temperature of the solution and the
970 //! reference pressure for the species.
971 /*!
972 * @param grt Output vector containing the nondimensional reference state
973 * Gibbs Free energies. Length: m_kk.
974 */
975 virtual void getGibbs_RT_ref(double* grt) const {
976 throw NotImplementedError("ThermoPhase::getGibbs_RT_ref");
977 }
978
979 //! Returns the vector of the Gibbs function of the reference state at the
980 //! current temperature of the solution and the reference pressure for the
981 //! species.
982 /*!
983 * @param g Output vector containing the reference state
984 * Gibbs Free energies. Length: m_kk. Units: J/kmol.
985 */
986 virtual void getGibbs_ref(double* g) const {
987 throw NotImplementedError("ThermoPhase::getGibbs_ref");
988 }
989
990 //! Returns the vector of nondimensional entropies of the reference state at
991 //! the current temperature of the solution and the reference pressure for
992 //! each species.
993 /*!
994 * @param er Output vector containing the nondimensional reference
995 * state entropies. Length: m_kk.
996 */
997 virtual void getEntropy_R_ref(double* er) const {
998 throw NotImplementedError("ThermoPhase::getEntropy_R_ref");
999 }
1000
1001 //! Returns the vector of nondimensional internal Energies of the reference
1002 //! state at the current temperature of the solution and the reference
1003 //! pressure for each species.
1004 /*!
1005 * @param urt Output vector of nondimensional reference state internal
1006 * energies of the species. Length: m_kk
1007 */
1008 virtual void getIntEnergy_RT_ref(double* urt) const {
1009 throw NotImplementedError("ThermoPhase::getIntEnergy_RT_ref");
1010 }
1011
1012 //! Returns the vector of nondimensional constant pressure heat capacities
1013 //! of the reference state at the current temperature of the solution and
1014 //! reference pressure for each species.
1015 /*!
1016 * @param cprt Output vector of nondimensional reference state
1017 * heat capacities at constant pressure for the species.
1018 * Length: m_kk
1019 */
1020 virtual void getCp_R_ref(double* cprt) const {
1021 throw NotImplementedError("ThermoPhase::getCp_R_ref");
1022 }
1023
1024 //! Get the molar volumes of the species reference states at the current
1025 //! *T* and *P_ref* of the solution.
1026 /*!
1027 * units = m^3 / kmol
1028 *
1029 * @param vol Output vector containing the standard state volumes.
1030 * Length: m_kk.
1031 */
1032 virtual void getStandardVolumes_ref(double* vol) const {
1033 throw NotImplementedError("ThermoPhase::getStandardVolumes_ref");
1034 }
1035
1036 // The methods below are not virtual, and should not be overloaded.
1037
1038 //! @}
1039 //! @name Specific Properties
1040 //! @{
1041
1042 //! Specific enthalpy. Units: J/kg.
1043 double enthalpy_mass() const {
1044 return enthalpy_mole()/meanMolecularWeight();
1045 }
1046
1047 //! Specific internal energy. Units: J/kg.
1048 double intEnergy_mass() const {
1049 return intEnergy_mole()/meanMolecularWeight();
1050 }
1051
1052 //! Specific entropy. Units: J/kg/K.
1053 double entropy_mass() const {
1054 return entropy_mole()/meanMolecularWeight();
1055 }
1056
1057 //! Specific Gibbs function. Units: J/kg.
1058 double gibbs_mass() const {
1059 return gibbs_mole()/meanMolecularWeight();
1060 }
1061
1062 //! Specific heat at constant pressure. Units: J/kg/K.
1063 double cp_mass() const {
1064 return cp_mole()/meanMolecularWeight();
1065 }
1066
1067 //! Specific heat at constant volume. Units: J/kg/K.
1068 double cv_mass() const {
1069 return cv_mole()/meanMolecularWeight();
1070 }
1071 //! @}
1072
1073 //! Return the Gas Constant multiplied by the current temperature
1074 /*!
1075 * The units are Joules kmol-1
1076 */
1077 double RT() const {
1078 return temperature() * GasConstant;
1079 }
1080
1081 //! @name Setting the State
1082 //! @anchor sec-thermophase-set-state
1083 //!
1084 //! These methods set all or part of the thermodynamic state.
1085 //! @{
1086
1087 //! Set the temperature (K), pressure (Pa), and mole fractions.
1088 /*!
1089 * Note, the mole fractions are set first before the pressure is set.
1090 * Setting the pressure may involve the solution of a nonlinear equation.
1091 *
1092 * @param t Temperature (K)
1093 * @param p Pressure (Pa)
1094 * @param x Vector of mole fractions.
1095 * Length is equal to m_kk.
1096 */
1097 virtual void setState_TPX(double t, double p, const double* x);
1098
1099 //! Set the temperature (K), pressure (Pa), and mole fractions.
1100 /*!
1101 * Note, the mole fractions are set first before the pressure is set.
1102 * Setting the pressure may involve the solution of a nonlinear equation.
1103 *
1104 * @param t Temperature (K)
1105 * @param p Pressure (Pa)
1106 * @param x Composition map of mole fractions. Species not in
1107 * the composition map are assumed to have zero mole fraction
1108 */
1109 virtual void setState_TPX(double t, double p, const Composition& x);
1110
1111 //! Set the temperature (K), pressure (Pa), and mole fractions.
1112 /*!
1113 * Note, the mole fractions are set first before the pressure is set.
1114 * Setting the pressure may involve the solution of a nonlinear equation.
1115 *
1116 * @param t Temperature (K)
1117 * @param p Pressure (Pa)
1118 * @param x String containing a composition map of the mole fractions.
1119 * Species not in the composition map are assumed to have zero
1120 * mole fraction
1121 */
1122 virtual void setState_TPX(double t, double p, const string& x);
1123
1124 //! Set the internally stored temperature (K), pressure (Pa), and mass
1125 //! fractions of the phase.
1126 /*!
1127 * Note, the mass fractions are set first before the pressure is set.
1128 * Setting the pressure may involve the solution of a nonlinear equation.
1129 *
1130 * @param t Temperature (K)
1131 * @param p Pressure (Pa)
1132 * @param y Vector of mass fractions.
1133 * Length is equal to m_kk.
1134 */
1135 virtual void setState_TPY(double t, double p, const double* y);
1136
1137 //! Set the internally stored temperature (K), pressure (Pa), and mass
1138 //! fractions of the phase
1139 /*!
1140 * Note, the mass fractions are set first before the pressure is set.
1141 * Setting the pressure may involve the solution of a nonlinear equation.
1142 *
1143 * @param t Temperature (K)
1144 * @param p Pressure (Pa)
1145 * @param y Composition map of mass fractions. Species not in
1146 * the composition map are assumed to have zero mass fraction
1147 */
1148 virtual void setState_TPY(double t, double p, const Composition& y);
1149
1150 //! Set the internally stored temperature (K), pressure (Pa), and mass
1151 //! fractions of the phase
1152 /*!
1153 * Note, the mass fractions are set first before the pressure is set.
1154 * Setting the pressure may involve the solution of a nonlinear equation.
1155 *
1156 * @param t Temperature (K)
1157 * @param p Pressure (Pa)
1158 * @param y String containing a composition map of the mass fractions.
1159 * Species not in the composition map are assumed to have zero
1160 * mass fraction
1161 */
1162 virtual void setState_TPY(double t, double p, const string& y);
1163
1164 //! Set the temperature (K) and pressure (Pa)
1165 /*!
1166 * Setting the pressure may involve the solution of a nonlinear equation.
1167 *
1168 * @param t Temperature (K)
1169 * @param p Pressure (Pa)
1170 */
1171 virtual void setState_TP(double t, double p);
1172
1173 //! Set the pressure (Pa) and mole fractions.
1174 /*!
1175 * Note, the mole fractions are set first before the pressure is set.
1176 * Setting the pressure may involve the solution of a nonlinear equation.
1177 *
1178 * @param p Pressure (Pa)
1179 * @param x Vector of mole fractions.
1180 * Length is equal to m_kk.
1181 * @deprecated To be removed after %Cantera 3.0.
1182 */
1183 virtual void setState_PX(double p, double* x);
1184
1185 //! Set the internally stored pressure (Pa) and mass fractions.
1186 /*!
1187 * Note, the temperature is held constant during this operation. Note, the
1188 * mass fractions are set first before the pressure is set. Setting the
1189 * pressure may involve the solution of a nonlinear equation.
1190 *
1191 * @param p Pressure (Pa)
1192 * @param y Vector of mass fractions.
1193 * Length is equal to m_kk.
1194 * @deprecated To be removed after %Cantera 3.0.
1195 */
1196 virtual void setState_PY(double p, double* y);
1197
1198 //! Set the internally stored specific enthalpy (J/kg) and pressure (Pa) of
1199 //! the phase.
1200 /*!
1201 * @param h Specific enthalpy (J/kg)
1202 * @param p Pressure (Pa)
1203 * @param tol Optional parameter setting the tolerance of the calculation.
1204 * Important for some applications where numerical Jacobians
1205 * are being calculated.
1206 */
1207 virtual void setState_HP(double h, double p, double tol=1e-9);
1208
1209 //! Set the specific internal energy (J/kg) and specific volume (m^3/kg).
1210 /*!
1211 * This function fixes the internal state of the phase so that the specific
1212 * internal energy and specific volume have the value of the input
1213 * parameters.
1214 *
1215 * @param u specific internal energy (J/kg)
1216 * @param v specific volume (m^3/kg).
1217 * @param tol Optional parameter setting the tolerance of the calculation.
1218 * Important for some applications where numerical Jacobians
1219 * are being calculated.
1220 */
1221 virtual void setState_UV(double u, double v, double tol=1e-9);
1222
1223 //! Set the specific entropy (J/kg/K) and pressure (Pa).
1224 /*!
1225 * This function fixes the internal state of the phase so that the specific
1226 * entropy and the pressure have the value of the input parameters.
1227 *
1228 * @param s specific entropy (J/kg/K)
1229 * @param p specific pressure (Pa).
1230 * @param tol Optional parameter setting the tolerance of the calculation.
1231 * Important for some applications where numerical Jacobians
1232 * are being calculated.
1233 */
1234 virtual void setState_SP(double s, double p, double tol=1e-9);
1235
1236 //! Set the specific entropy (J/kg/K) and specific volume (m^3/kg).
1237 /*!
1238 * This function fixes the internal state of the phase so that the specific
1239 * entropy and specific volume have the value of the input parameters.
1240 *
1241 * @param s specific entropy (J/kg/K)
1242 * @param v specific volume (m^3/kg).
1243 * @param tol Optional parameter setting the tolerance of the calculation.
1244 * Important for some applications where numerical Jacobians
1245 * are being calculated.
1246 */
1247 virtual void setState_SV(double s, double v, double tol=1e-9);
1248
1249 //! Set the specific entropy (J/kg/K) and temperature (K).
1250 /*!
1251 * This function fixes the internal state of the phase so that the specific
1252 * entropy and temperature have the value of the input parameters.
1253 * This base class function will throw an exception if not overridden.
1254 *
1255 * @param s specific entropy (J/kg/K)
1256 * @param t temperature (K)
1257 * @param tol Optional parameter setting the tolerance of the calculation.
1258 * Important for some applications where numerical Jacobians
1259 * are being calculated.
1260 */
1261 virtual void setState_ST(double s, double t, double tol=1e-9) {
1262 throw NotImplementedError("ThermoPhase::setState_ST");
1263 }
1264
1265 //! Set the temperature (K) and specific volume (m^3/kg).
1266 /*!
1267 * This function fixes the internal state of the phase so that the
1268 * temperature and specific volume have the value of the input parameters.
1269 * This base class function will throw an exception if not overridden.
1270 *
1271 * @param t temperature (K)
1272 * @param v specific volume (m^3/kg)
1273 * @param tol Optional parameter setting the tolerance of the calculation.
1274 * Important for some applications where numerical Jacobians
1275 * are being calculated.
1276 */
1277 virtual void setState_TV(double t, double v, double tol=1e-9) {
1278 throw NotImplementedError("ThermoPhase::setState_TV");
1279 }
1280
1281 //! Set the pressure (Pa) and specific volume (m^3/kg).
1282 /*!
1283 * This function fixes the internal state of the phase so that the
1284 * pressure and specific volume have the value of the input parameters.
1285 * This base class function will throw an exception if not overridden.
1286 *
1287 * @param p pressure (Pa)
1288 * @param v specific volume (m^3/kg)
1289 * @param tol Optional parameter setting the tolerance of the calculation.
1290 * Important for some applications where numerical Jacobians
1291 * are being calculated.
1292 */
1293 virtual void setState_PV(double p, double v, double tol=1e-9) {
1294 throw NotImplementedError("ThermoPhase::setState_PV");
1295 }
1296
1297 //! Set the specific internal energy (J/kg) and pressure (Pa).
1298 /*!
1299 * This function fixes the internal state of the phase so that the specific
1300 * internal energy and pressure have the value of the input parameters.
1301 * This base class function will throw an exception if not overridden.
1302 *
1303 * @param u specific internal energy (J/kg)
1304 * @param p pressure (Pa)
1305 * @param tol Optional parameter setting the tolerance of the calculation.
1306 * Important for some applications where numerical Jacobians
1307 * are being calculated.
1308 */
1309 virtual void setState_UP(double u, double p, double tol=1e-9) {
1310 throw NotImplementedError("ThermoPhase::setState_UP");
1311 }
1312
1313 //! Set the specific volume (m^3/kg) and the specific enthalpy (J/kg)
1314 /*!
1315 * This function fixes the internal state of the phase so that the specific
1316 * volume and the specific enthalpy have the value of the input parameters.
1317 * This base class function will throw an exception if not overridden.
1318 *
1319 * @param v specific volume (m^3/kg)
1320 * @param h specific enthalpy (J/kg)
1321 * @param tol Optional parameter setting the tolerance of the calculation.
1322 * Important for some applications where numerical Jacobians
1323 * are being calculated.
1324 */
1325 virtual void setState_VH(double v, double h, double tol=1e-9) {
1326 throw NotImplementedError("ThermoPhase::setState_VH");
1327 }
1328
1329 //! Set the temperature (K) and the specific enthalpy (J/kg)
1330 /*!
1331 * This function fixes the internal state of the phase so that the
1332 * temperature and specific enthalpy have the value of the input parameters.
1333 * This base class function will throw an exception if not overridden.
1334 *
1335 * @param t temperature (K)
1336 * @param h specific enthalpy (J/kg)
1337 * @param tol Optional parameter setting the tolerance of the calculation.
1338 * Important for some applications where numerical Jacobians
1339 * are being calculated.
1340 */
1341 virtual void setState_TH(double t, double h, double tol=1e-9) {
1342 throw NotImplementedError("ThermoPhase::setState_TH");
1343 }
1344
1345 //! Set the specific entropy (J/kg/K) and the specific enthalpy (J/kg)
1346 /*!
1347 * This function fixes the internal state of the phase so that the
1348 * temperature and pressure have the value of the input parameters.
1349 * This base class function will throw an exception if not overridden.
1350 *
1351 * @param s specific entropy (J/kg/K)
1352 * @param h specific enthalpy (J/kg)
1353 * @param tol Optional parameter setting the tolerance of the calculation.
1354 * Important for some applications where numerical Jacobians
1355 * are being calculated.
1356 */
1357 virtual void setState_SH(double s, double h, double tol=1e-9) {
1358 throw NotImplementedError("ThermoPhase::setState_SH");
1359 }
1360
1361 //! Set the density (kg/m**3) and pressure (Pa) at constant composition
1362 /*!
1363 * This method must be reimplemented in derived classes, where it may
1364 * involve the solution of a nonlinear equation. Within %Cantera, the
1365 * independent variable is the density. Therefore, this function solves for
1366 * the temperature that will yield the desired input pressure and density.
1367 * The composition is held constant during this process.
1368 *
1369 * This base class function will print an error, if not overridden.
1370 *
1371 * @param rho Density (kg/m^3)
1372 * @param p Pressure (Pa)
1373 * @deprecated To be removed after %Cantera 3.0; renamed to setState_DP()
1374 */
1375 void setState_RP(double rho, double p);
1376
1377 //! Set the density (kg/m**3) and pressure (Pa) at constant composition
1378 /*!
1379 * This method must be reimplemented in derived classes, where it may
1380 * involve the solution of a nonlinear equation. Within %Cantera, the
1381 * independent variable is the density. Therefore, this function solves for
1382 * the temperature that will yield the desired input pressure and density.
1383 * The composition is held constant during this process.
1384 *
1385 * This base class function will print an error, if not overridden.
1386 *
1387 * @param rho Density (kg/m^3)
1388 * @param p Pressure (Pa)
1389 * @since New in %Cantera 3.0.
1390 */
1391 virtual void setState_DP(double rho, double p) {
1392 throw NotImplementedError("ThermoPhase::setState_DP");
1393 }
1394
1395 //! Set the density (kg/m**3), pressure (Pa) and mole fractions
1396 /*!
1397 * Note, the mole fractions are set first before the density and pressure
1398 * are set. Setting the pressure may involve the solution of a nonlinear
1399 * equation.
1400 *
1401 * @param rho Density (kg/m^3)
1402 * @param p Pressure (Pa)
1403 * @param x Vector of mole fractions.
1404 * Length is equal to m_kk.
1405 * @deprecated To be removed after %Cantera 3.0; replaceable by calls to
1406 * setMoleFractions() and setState_DP().
1407 */
1408 virtual void setState_RPX(double rho, double p, const double* x);
1409
1410 //! Set the density (kg/m**3), pressure (Pa) and mole fractions
1411 /*!
1412 * Note, the mole fractions are set first before the density and pressure
1413 * are set. Setting the pressure may involve the solution of a nonlinear
1414 * equation.
1415 *
1416 * @param rho Density (kg/m^3)
1417 * @param p Pressure (Pa)
1418 * @param x Composition map of mole fractions. Species not in
1419 * the composition map are assumed to have zero mole fraction
1420 * @deprecated To be removed after %Cantera 3.0; replaceable by calls to
1421 * setMoleFractionsByName() and setState_DP().
1422 */
1423 virtual void setState_RPX(double rho, double p, const Composition& x);
1424
1425 //! Set the density (kg/m**3), pressure (Pa) and mole fractions
1426 /*!
1427 * Note, the mole fractions are set first before the density and pressure
1428 * are set. Setting the pressure may involve the solution of a nonlinear
1429 * equation.
1430 *
1431 * @param rho Density (kg/m^3)
1432 * @param p Pressure (Pa)
1433 * @param x String containing a composition map of the mole fractions.
1434 * Species not in the composition map are assumed to have zero
1435 * mole fraction
1436 * @deprecated To be removed after %Cantera 3.0; replaceable by calls to
1437 * setMoleFractionsByName() and setState_DP().
1438 */
1439 virtual void setState_RPX(double rho, double p, const string& x);
1440
1441 //! Set the density (kg/m**3), pressure (Pa) and mass fractions
1442 /*!
1443 * Note, the mass fractions are set first before the density and pressure
1444 * are set. Setting the pressure may involve the solution of a nonlinear
1445 * equation.
1446 *
1447 * @param rho Density (kg/m^3)
1448 * @param p Pressure (Pa)
1449 * @param y Vector of mole fractions.
1450 * Length is equal to m_kk.
1451 * @deprecated To be removed after %Cantera 3.0; replaceable by calls to
1452 * setMassFractions() and setState_DP().
1453 */
1454 virtual void setState_RPY(double rho, double p, const double* y);
1455
1456 //! Set the density (kg/m**3), pressure (Pa) and mass fractions
1457 /*!
1458 * Note, the mass fractions are set first before the density and pressure
1459 * are set. Setting the pressure may involve the solution of a nonlinear
1460 * equation.
1461 *
1462 * @param rho Density (kg/m^3)
1463 * @param p Pressure (Pa)
1464 * @param y Composition map of mole fractions. Species not in
1465 * the composition map are assumed to have zero mole fraction
1466 * @deprecated To be removed after %Cantera 3.0; replaceable by calls to
1467 * setMassFractionsByName() and setState_DP().
1468 */
1469 virtual void setState_RPY(double rho, double p, const Composition& y);
1470
1471 //! Set the density (kg/m**3), pressure (Pa) and mass fractions
1472 /*!
1473 * Note, the mass fractions are set first before the density and pressure
1474 * are set. Setting the pressure may involve the solution of a nonlinear
1475 * equation.
1476 *
1477 * @param rho Density (kg/m^3)
1478 * @param p Pressure (Pa)
1479 * @param y String containing a composition map of the mole fractions.
1480 * Species not in the composition map are assumed to have zero
1481 * mole fraction
1482 * @deprecated To be removed after %Cantera 3.0; replaceable by calls to
1483 * setMassFractionsByName() and setState_DP().
1484 */
1485 virtual void setState_RPY(double rho, double p, const string& y);
1486
1487 //! Set the state using an AnyMap containing any combination of properties
1488 //! supported by the thermodynamic model
1489 /*!
1490 * Accepted keys are:
1491 * * `X` (mole fractions)
1492 * * `Y` (mass fractions)
1493 * * `T` or `temperature`
1494 * * `P` or `pressure` [Pa]
1495 * * `H` or `enthalpy` [J/kg]
1496 * * `U` or `internal-energy` [J/kg]
1497 * * `S` or `entropy` [J/kg/K]
1498 * * `V` or `specific-volume` [m^3/kg]
1499 * * `D` or `density` [kg/m^3]
1500 *
1501 * Composition can be specified as either an AnyMap of species names to
1502 * values or as a composition string. All other values can be given as
1503 * floating point values in Cantera's default units, or as strings with the
1504 * units specified, which will be converted using the Units class.
1505 *
1506 * If no thermodynamic property pair is given, or only one of temperature or
1507 * pressure is given, then 298.15 K and 101325 Pa will be used as necessary
1508 * to fully set the state.
1509 */
1510 virtual void setState(const AnyMap& state);
1511
1512 //! @}
1513 //! @name Set Mixture Composition by Mixture Fraction
1514 //! @{
1515
1516 //! Set the mixture composition according to the
1517 //! mixture fraction = kg fuel / (kg oxidizer + kg fuel)
1518 /*!
1519 * Fuel and oxidizer compositions are given either as
1520 * mole fractions or mass fractions (specified by `basis`)
1521 * and do not need to be normalized. Pressure and temperature are
1522 * kept constant. Elements C, S, H and O are considered for the oxidation.
1523 *
1524 * @param mixFrac mixture fraction (between 0 and 1)
1525 * @param fuelComp composition of the fuel
1526 * @param oxComp composition of the oxidizer
1527 * @param basis either ThermoPhase::molar or ThermoPhase::mass.
1528 * Fuel and oxidizer composition are interpreted
1529 * as mole or mass fractions (default: molar)
1530 */
1531 void setMixtureFraction(double mixFrac, const double* fuelComp,
1532 const double* oxComp, ThermoBasis basis=ThermoBasis::molar);
1533 //! @copydoc ThermoPhase::setMixtureFraction
1534 void setMixtureFraction(double mixFrac, const string& fuelComp,
1535 const string& oxComp, ThermoBasis basis=ThermoBasis::molar);
1536 //! @copydoc ThermoPhase::setMixtureFraction
1537 void setMixtureFraction(double mixFrac, const Composition& fuelComp,
1538 const Composition& oxComp, ThermoBasis basis=ThermoBasis::molar);
1539 //! @}
1540 //! @name Compute Mixture Fraction
1541 //! @{
1542
1543 //! Compute the mixture fraction = kg fuel / (kg oxidizer + kg fuel) for
1544 //! the current mixture given fuel and oxidizer compositions.
1545 /*!
1546 * Fuel and oxidizer compositions are given either as
1547 * mole fractions or mass fractions (specified by `basis`)
1548 * and do not need to be normalized.
1549 * The mixture fraction @f$ Z @f$ can be computed from a single element
1550 * @f[ Z_m = \frac{Z_{\mathrm{mass},m}-Z_{\mathrm{mass},m,\mathrm{ox}}}
1551 * {Z_{\mathrm{mass},\mathrm{fuel}}-Z_{\mathrm{mass},m,\mathrm{ox}}} @f] where
1552 * @f$ Z_{\mathrm{mass},m} @f$ is the elemental mass fraction of element m
1553 * in the mixture, and @f$ Z_{\mathrm{mass},m,\mathrm{ox}} @f$ and
1554 * @f$ Z_{\mathrm{mass},m,\mathrm{fuel}} @f$ are the elemental mass fractions
1555 * of the oxidizer and fuel, or from the Bilger mixture fraction,
1556 * which considers the elements C, S, H and O @cite bilger1979
1557 * @f[ Z_{\mathrm{Bilger}} = \frac{\beta-\beta_{\mathrm{ox}}}
1558 * {\beta_{\mathrm{fuel}}-\beta_{\mathrm{ox}}} @f]
1559 * with @f$ \beta = 2\frac{Z_C}{M_C}+2\frac{Z_S}{M_S}+\frac{1}{2}\frac{Z_H}{M_H}
1560 * -\frac{Z_O}{M_O} @f$
1561 * and @f$ M_m @f$ the atomic weight of element @f$ m @f$.
1562 *
1563 * @param fuelComp composition of the fuel
1564 * @param oxComp composition of the oxidizer
1565 * @param basis either ThermoBasis::molar or ThermoBasis::mass.
1566 * Fuel and oxidizer composition are interpreted
1567 * as mole or mass fractions (default: molar)
1568 * @param element either "Bilger" to compute the mixture fraction
1569 * in terms of the Bilger mixture fraction, or
1570 * an element name, to compute the mixture fraction
1571 * based on a single element (default: "Bilger")
1572 * @returns mixture fraction (kg fuel / kg mixture)
1573 */
1574 double mixtureFraction(const double* fuelComp, const double* oxComp,
1575 ThermoBasis basis=ThermoBasis::molar,
1576 const string& element="Bilger") const;
1577 //! @copydoc ThermoPhase::mixtureFraction
1578 double mixtureFraction(const string& fuelComp, const string& oxComp,
1579 ThermoBasis basis=ThermoBasis::molar,
1580 const string& element="Bilger") const;
1581 //! @copydoc ThermoPhase::mixtureFraction
1582 double mixtureFraction(const Composition& fuelComp, const Composition& oxComp,
1583 ThermoBasis basis=ThermoBasis::molar,
1584 const string& element="Bilger") const;
1585 //! @}
1586 //! @name Set Mixture Composition by Equivalence Ratio
1587 //! @{
1588
1589 //! Set the mixture composition according to the equivalence ratio.
1590 /*!
1591 * Fuel and oxidizer compositions are given either as
1592 * mole fractions or mass fractions (specified by `basis`)
1593 * and do not need to be normalized. Pressure and temperature are
1594 * kept constant. Elements C, S, H and O are considered for the oxidation.
1595 *
1596 * @param phi equivalence ratio
1597 * @param fuelComp composition of the fuel
1598 * @param oxComp composition of the oxidizer
1599 * @param basis either ThermoBasis::mole or ThermoBasis::mass.
1600 * Fuel and oxidizer composition are interpreted
1601 * as mole or mass fractions (default: molar)
1602 */
1603 void setEquivalenceRatio(double phi, const double* fuelComp, const double* oxComp,
1604 ThermoBasis basis=ThermoBasis::molar);
1605 //! @copydoc ThermoPhase::setEquivalenceRatio
1606 void setEquivalenceRatio(double phi, const string& fuelComp,
1607 const string& oxComp, ThermoBasis basis=ThermoBasis::molar);
1608 //! @copydoc ThermoPhase::setEquivalenceRatio
1609 void setEquivalenceRatio(double phi, const Composition& fuelComp,
1610 const Composition& oxComp, ThermoBasis basis=ThermoBasis::molar);
1611 //! @}
1612
1613 //! @name Compute Equivalence Ratio
1614 //! @{
1615
1616 //! Compute the equivalence ratio for the current mixture
1617 //! given the compositions of fuel and oxidizer
1618 /*!
1619 * The equivalence ratio @f$ \phi @f$ is computed from
1620 * @f[ \phi = \frac{Z}{1-Z}\frac{1-Z_{\mathrm{st}}}{Z_{\mathrm{st}}} @f]
1621 * where @f$ Z @f$ is the Bilger mixture fraction @cite bilger1979 of the mixture
1622 * given the specified fuel and oxidizer compositions
1623 * @f$ Z_{\mathrm{st}} @f$ is the mixture fraction at stoichiometric
1624 * conditions. Fuel and oxidizer compositions are given either as
1625 * mole fractions or mass fractions (specified by `basis`)
1626 * and do not need to be normalized.
1627 * Elements C, S, H and O are considered for the oxidation.
1628 * If fuel and oxidizer composition are unknown or not specified,
1629 * use the version that takes no arguments.
1630 *
1631 * @param fuelComp composition of the fuel
1632 * @param oxComp composition of the oxidizer
1633 * @param basis either ThermoPhase::mole or ThermoPhase::mass.
1634 * Fuel and oxidizer composition are interpreted
1635 * as mole or mass fractions (default: molar)
1636 * @returns equivalence ratio
1637 * @see mixtureFraction for the definition of the Bilger mixture fraction
1638 * @see equivalenceRatio() for the computation of @f$ \phi @f$ without arguments
1639 */
1640 double equivalenceRatio(const double* fuelComp, const double* oxComp,
1641 ThermoBasis basis=ThermoBasis::molar) const;
1642 //! @copydoc ThermoPhase::equivalenceRatio
1643 double equivalenceRatio(const string& fuelComp, const string& oxComp,
1644 ThermoBasis basis=ThermoBasis::molar) const;
1645 //! @copydoc ThermoPhase::equivalenceRatio
1646 double equivalenceRatio(const Composition& fuelComp,
1647 const Composition& oxComp, ThermoBasis basis=ThermoBasis::molar) const;
1648 //! @}
1649
1650 //! Compute the equivalence ratio for the current mixture
1651 //! from available oxygen and required oxygen
1652 /*!
1653 * Computes the equivalence ratio @f$ \phi @f$ from
1654 * @f[ \phi =
1655 * \frac{Z_{\mathrm{mole},C} + Z_{\mathrm{mole},S} + \frac{1}{4}Z_{\mathrm{mole},H}}
1656 * {\frac{1}{2}Z_{\mathrm{mole},O}} @f]
1657 * where @f$ Z_{\mathrm{mole},m} @f$ is the elemental mole fraction
1658 * of element @f$ m @f$. In this special case, the equivalence ratio
1659 * is independent of a fuel or oxidizer composition because it only
1660 * considers the locally available oxygen compared to the required oxygen
1661 * for complete oxidation. It is the same as assuming that the oxidizer
1662 * only contains O (and inert elements) and the fuel contains only
1663 * H, C and S (and inert elements). If either of these conditions is
1664 * not met, use the version of this functions which takes the fuel and
1665 * oxidizer compositions as input
1666 *
1667 * @returns equivalence ratio
1668 * @see equivalenceRatio compute the equivalence ratio from specific
1669 * fuel and oxidizer compositions
1670 */
1671 double equivalenceRatio() const;
1672
1673 //! @name Compute Stoichiometric Air to Fuel Ratio
1674 //! @{
1675
1676 //! Compute the stoichiometric air to fuel ratio (kg oxidizer / kg fuel)
1677 //! given fuel and oxidizer compositions.
1678 /*!
1679 * Fuel and oxidizer compositions are given either as
1680 * mole fractions or mass fractions (specified by `basis`)
1681 * and do not need to be normalized.
1682 * Elements C, S, H and O are considered for the oxidation.
1683 * Note that the stoichiometric air to fuel ratio @f$ \mathit{AFR}_{\mathrm{st}} @f$
1684 * does not depend on the current mixture composition. The current air to fuel ratio
1685 * can be computed from @f$ \mathit{AFR} = \mathit{AFR}_{\mathrm{st}}/\phi @f$
1686 * where @f$ \phi @f$ is the equivalence ratio of the current mixture
1687 *
1688 * @param fuelComp composition of the fuel
1689 * @param oxComp composition of the oxidizer
1690 * @param basis either ThermoPhase::mole or ThermoPhase::mass.
1691 * Fuel and oxidizer composition are interpreted
1692 * as mole or mass fractions (default: molar)
1693 * @returns Stoichiometric Air to Fuel Ratio (kg oxidizer / kg fuel)
1694 */
1695 double stoichAirFuelRatio(const double* fuelComp, const double* oxComp,
1696 ThermoBasis basis=ThermoBasis::molar) const;
1697 //! @copydoc ThermoPhase::stoichAirFuelRatio
1698 double stoichAirFuelRatio(const string& fuelComp, const string& oxComp,
1699 ThermoBasis basis=ThermoBasis::molar) const;
1700 //! @copydoc ThermoPhase::stoichAirFuelRatio
1701 double stoichAirFuelRatio(const Composition& fuelComp,
1702 const Composition& oxComp, ThermoBasis basis=ThermoBasis::molar) const;
1703 //! @}
1704
1705 private:
1706
1707 //! Carry out work in HP and UV calculations.
1708 /*!
1709 * @param h Specific enthalpy or internal energy (J/kg)
1710 * @param p Pressure (Pa) or specific volume (m^3/kg)
1711 * @param tol Optional parameter setting the tolerance of the calculation.
1712 * Important for some applications where numerical Jacobians
1713 * are being calculated.
1714 * @param doUV True if solving for UV, false for HP.
1715 */
1716 void setState_HPorUV(double h, double p, double tol=1e-9, bool doUV = false);
1717
1718 //! Carry out work in SP and SV calculations.
1719 /*!
1720 * @param s Specific entropy (J/kg)
1721 * @param p Pressure (Pa) or specific volume (m^3/kg)
1722 * @param tol Optional parameter setting the tolerance of the calculation.
1723 * Important for some applications where numerical Jacobians
1724 * are being calculated.
1725 * @param doSV True if solving for SV, false for SP.
1726 */
1727 void setState_SPorSV(double s, double p, double tol=1e-9, bool doSV = false);
1728
1729 //! Helper function used by setState_HPorUV and setState_SPorSV.
1730 //! Sets the temperature and (if set_p is true) the pressure.
1731 void setState_conditional_TP(double t, double p, bool set_p);
1732
1733 //! Helper function for computing the amount of oxygen required for complete
1734 //! oxidation.
1735 /*!
1736 * @param y array of (possibly non-normalized) mass fractions (length m_kk)
1737 * @returns amount of required oxygen in kmol O / kg mixture
1738 */
1739 double o2Required(const double* y) const;
1740
1741 //! Helper function for computing the amount of oxygen
1742 //! available in the current mixture.
1743 /*!
1744 * @param y array of (possibly non-normalized) mass fractions (length m_kk)
1745 * @returns amount of O in kmol O / kg mixture
1746 */
1747 double o2Present(const double* y) const;
1748
1749 public:
1750 //! @name Chemical Equilibrium
1751 //!
1752 //! Chemical equilibrium.
1753 //! @{
1754
1755 //! Equilibrate a ThermoPhase object
1756 /*!
1757 * Set this phase to chemical equilibrium by calling one of several
1758 * equilibrium solvers. The XY parameter indicates what two thermodynamic
1759 * quantities are to be held constant during the equilibration process.
1760 *
1761 * @param XY String representation of what two properties are being
1762 * held constant
1763 * @param solver Name of the solver to be used to equilibrate the phase.
1764 * If solver = 'element_potential', the ChemEquil element potential
1765 * solver will be used. If solver = 'vcs', the VCS solver will be used.
1766 * If solver = 'gibbs', the MultiPhaseEquil solver will be used. If
1767 * solver = 'auto', the solvers will be tried in order if the initial
1768 * solver(s) fail.
1769 * @param rtol Relative tolerance
1770 * @param max_steps Maximum number of steps to take to find the solution
1771 * @param max_iter For the 'gibbs' and 'vcs' solvers, this is the maximum
1772 * number of outer temperature or pressure iterations to take when T
1773 * and/or P is not held fixed.
1774 * @param estimate_equil For MultiPhaseEquil solver, an integer indicating
1775 * whether the solver should estimate its own initial condition. If 0,
1776 * the initial mole fraction vector in the ThermoPhase object is used
1777 * as the initial condition. If 1, the initial mole fraction vector is
1778 * used if the element abundances are satisfied. If -1, the initial
1779 * mole fraction vector is thrown out, and an estimate is formulated.
1780 * @param log_level loglevel Controls amount of diagnostic output.
1781 * log_level=0 suppresses diagnostics, and increasingly-verbose
1782 * messages are written as loglevel increases.
1783 *
1784 * @ingroup equilGroup
1785 */
1786 void equilibrate(const string& XY, const string& solver="auto",
1787 double rtol=1e-9, int max_steps=50000, int max_iter=100,
1788 int estimate_equil=0, int log_level=0);
1789
1790 //!This method is used by the ChemEquil equilibrium solver.
1791 /*!
1792 * It sets the state such that the chemical potentials satisfy
1793 * @f[ \frac{\mu_k}{\hat R T} = \sum_m A_{k,m}
1794 * \left(\frac{\lambda_m} {\hat R T}\right) @f] where
1795 * @f$ \lambda_m @f$ is the element potential of element m. The
1796 * temperature is unchanged. Any phase (ideal or not) that
1797 * implements this method can be equilibrated by ChemEquil.
1798 *
1799 * @param mu_RT Input vector of dimensionless chemical potentials
1800 * The length is equal to nSpecies().
1801 */
1802 virtual void setToEquilState(const double* mu_RT) {
1803 throw NotImplementedError("ThermoPhase::setToEquilState");
1804 }
1805
1806 //! Indicates whether this phase type can be used with class MultiPhase for
1807 //! equilibrium calculations. Returns `false` for special phase types which
1808 //! already represent multi-phase mixtures, namely PureFluidPhase.
1809 virtual bool compatibleWithMultiPhase() const {
1810 return true;
1811 }
1812
1813 //! @}
1814 //! @name Critical State Properties
1815 //!
1816 //! These methods are only implemented by subclasses that implement
1817 //! liquid-vapor equations of state.
1818 //! @{
1819
1820 //! Critical temperature (K).
1821 virtual double critTemperature() const {
1822 throw NotImplementedError("ThermoPhase::critTemperature");
1823 }
1824
1825 //! Critical pressure (Pa).
1826 virtual double critPressure() const {
1827 throw NotImplementedError("ThermoPhase::critPressure");
1828 }
1829
1830 //! Critical volume (m3/kmol).
1831 virtual double critVolume() const {
1832 throw NotImplementedError("ThermoPhase::critVolume");
1833 }
1834
1835 //! Critical compressibility (unitless).
1836 virtual double critCompressibility() const {
1837 throw NotImplementedError("ThermoPhase::critCompressibility");
1838 }
1839
1840 //! Critical density (kg/m3).
1841 virtual double critDensity() const {
1842 throw NotImplementedError("ThermoPhase::critDensity");
1843 }
1844
1845 //! @}
1846 //! @name Saturation Properties
1847 //!
1848 //! These methods are only implemented by subclasses that implement full
1849 //! liquid-vapor equations of state.
1850 //! @{
1851
1852 //! Return the saturation temperature given the pressure
1853 /*!
1854 * @param p Pressure (Pa)
1855 */
1856 virtual double satTemperature(double p) const {
1857 throw NotImplementedError("ThermoPhase::satTemperature");
1858 }
1859
1860 //! Return the saturation pressure given the temperature
1861 /*!
1862 * @param t Temperature (Kelvin)
1863 */
1864 virtual double satPressure(double t) {
1865 throw NotImplementedError("ThermoPhase::satPressure");
1866 }
1867
1868 //! Return the fraction of vapor at the current conditions
1869 virtual double vaporFraction() const {
1870 throw NotImplementedError("ThermoPhase::vaporFraction");
1871 }
1872
1873 //! Set the state to a saturated system at a particular temperature
1874 /*!
1875 * @param t Temperature (kelvin)
1876 * @param x Fraction of vapor
1877 */
1878 virtual void setState_Tsat(double t, double x) {
1879 throw NotImplementedError("ThermoPhase::setState_Tsat");
1880 }
1881
1882 //! Set the state to a saturated system at a particular pressure
1883 /*!
1884 * @param p Pressure (Pa)
1885 * @param x Fraction of vapor
1886 */
1887 virtual void setState_Psat(double p, double x) {
1888 throw NotImplementedError("ThermoPhase::setState_Psat");
1889 }
1890
1891 //! Set the temperature, pressure, and vapor fraction (quality).
1892 /*!
1893 * An exception is thrown if the thermodynamic state is not consistent.
1894 *
1895 * For temperatures below the critical temperature, if the vapor fraction is
1896 * not 0 or 1, the pressure and temperature must fall on the saturation
1897 * line.
1898 *
1899 * Above the critical temperature, the vapor fraction must be 1 if the
1900 * pressure is less than the critical pressure. Above the critical pressure,
1901 * the vapor fraction is not defined, and its value is ignored.
1902 *
1903 * @param T Temperature (K)
1904 * @param P Pressure (Pa)
1905 * @param Q vapor fraction
1906 */
1907 void setState_TPQ(double T, double P, double Q);
1908
1909 //! @}
1910 //! @name Initialization Methods - For Internal Use (ThermoPhase)
1911 //!
1912 //! The following methods are used in the process of constructing
1913 //! the phase and setting its parameters from a specification in an
1914 //! input file. They are not normally used in application programs.
1915 //! To see how they are used, see importPhase().
1916 //! @{
1917
1918 bool addSpecies(shared_ptr<Species> spec) override;
1919
1920 void modifySpecies(size_t k, shared_ptr<Species> spec) override;
1921
1922 //! Return a changeable reference to the calculation manager for species
1923 //! reference-state thermodynamic properties
1924 /*!
1925 * @param k Species id. The default is -1, meaning return the default
1926 */
1927 virtual MultiSpeciesThermo& speciesThermo(int k = -1);
1928
1929 virtual const MultiSpeciesThermo& speciesThermo(int k = -1) const;
1930
1931 /**
1932 * Initialize a ThermoPhase object using an input file.
1933 *
1934 * Used to implement constructors for derived classes which take a
1935 * file name and phase name as arguments.
1936 *
1937 * @param inputFile Input file containing the description of the phase. If blank,
1938 * no setup will be performed.
1939 * @param id Optional parameter identifying the name of the phase. If
1940 * blank, the first phase definition encountered will be used.
1941 */
1942 void initThermoFile(const string& inputFile, const string& id);
1943
1944 //! Initialize the ThermoPhase object after all species have been set up
1945 /*!
1946 * This method is provided to allow subclasses to perform any initialization
1947 * required after all species have been added. For example, it might be used
1948 * to resize internal work arrays that must have an entry for each species.
1949 * The base class implementation does nothing, and subclasses that do not
1950 * require initialization do not need to overload this method. Derived
1951 * classes which do override this function should call their parent class's
1952 * implementation of this function as their last action.
1953 *
1954 * When importing from an AnyMap phase description (or from a YAML file),
1955 * setupPhase() adds all the species, stores the input data in #m_input, and then
1956 * calls this method to set model parameters from the data stored in #m_input.
1957 */
1958 virtual void initThermo();
1959
1960 //! Set equation of state parameters from an AnyMap phase description.
1961 //! Phases that need additional parameters from the root node should
1962 //! override this method.
1963 virtual void setParameters(const AnyMap& phaseNode,
1964 const AnyMap& rootNode=AnyMap());
1965
1966 //! Returns the parameters of a ThermoPhase object such that an identical
1967 //! one could be reconstructed using the newThermo(AnyMap&) function.
1968 //! @param withInput If true, include additional input data fields associated
1969 //! with the phase description, such as user-defined fields from a YAML input
1970 //! file, as returned by the input() method.
1971 AnyMap parameters(bool withInput=true) const;
1972
1973 //! Get phase-specific parameters of a Species object such that an
1974 //! identical one could be reconstructed and added to this phase.
1975 /*!
1976 * @param name Name of the species
1977 * @param speciesNode Mapping to be populated with parameters
1978 */
1979 virtual void getSpeciesParameters(const string& name, AnyMap& speciesNode) const {}
1980
1981 //! Access input data associated with the phase description
1982 const AnyMap& input() const;
1983 AnyMap& input();
1984
1985 void invalidateCache() override;
1986
1987 //! @}
1988 //! @name Derivatives of Thermodynamic Variables needed for Applications
1989 //!
1990 //! Derivatives of the activity coefficients are needed to evaluate terms arising
1991 //! in multicomponent transport models for non-ideal systems. While %Cantera does
1992 //! not currently implement such models, these derivatives are provided by a few
1993 //! phase models.
1994 //! @{
1995
1996 //! Get the change in activity coefficients wrt changes in state (temp, mole
1997 //! fraction, etc) along a line in parameter space or along a line in
1998 //! physical space
1999 /*!
2000 * @param dTds Input of temperature change along the path
2001 * @param dXds Input vector of changes in mole fraction along the
2002 * path. length = m_kk Along the path length it must
2003 * be the case that the mole fractions sum to one.
2004 * @param dlnActCoeffds Output vector of the directional derivatives of the
2005 * log Activity Coefficients along the path. length =
2006 * m_kk units are 1/units(s). if s is a physical
2007 * coordinate then the units are 1/m.
2008 */
2009 virtual void getdlnActCoeffds(const double dTds, const double* const dXds,
2010 double* dlnActCoeffds) const {
2011 throw NotImplementedError("ThermoPhase::getdlnActCoeffds");
2012 }
2013
2014 //! Get the array of ln mole fraction derivatives of the log activity
2015 //! coefficients - diagonal component only
2016 /*!
2017 * For ideal mixtures (unity activity coefficients), this can return zero.
2018 * Implementations should take the derivative of the logarithm of the
2019 * activity coefficient with respect to the logarithm of the mole fraction
2020 * variable that represents the standard state. This quantity is to be used
2021 * in conjunction with derivatives of that mole fraction variable when the
2022 * derivative of the chemical potential is taken.
2023 *
2024 * units = dimensionless
2025 *
2026 * @param dlnActCoeffdlnX_diag Output vector of derivatives of the log
2027 * Activity Coefficients wrt the mole fractions. length = m_kk
2028 */
2029 virtual void getdlnActCoeffdlnX_diag(double* dlnActCoeffdlnX_diag) const {
2030 throw NotImplementedError("ThermoPhase::getdlnActCoeffdlnX_diag");
2031 }
2032
2033 //! Get the array of log species mole number derivatives of the log activity
2034 //! coefficients
2035 /*!
2036 * For ideal mixtures (unity activity coefficients), this can return zero.
2037 * Implementations should take the derivative of the logarithm of the
2038 * activity coefficient with respect to the logarithm of the concentration-
2039 * like variable (for example, moles) that represents the standard state. This
2040 * quantity is to be used in conjunction with derivatives of that species
2041 * mole number variable when the derivative of the chemical potential is
2042 * taken.
2043 *
2044 * units = dimensionless
2045 *
2046 * @param dlnActCoeffdlnN_diag Output vector of derivatives of the
2047 * log Activity Coefficients. length = m_kk
2048 */
2049 virtual void getdlnActCoeffdlnN_diag(double* dlnActCoeffdlnN_diag) const {
2050 throw NotImplementedError("ThermoPhase::getdlnActCoeffdlnN_diag");
2051 }
2052
2053 //! Get the array of derivatives of the log activity coefficients with
2054 //! respect to the log of the species mole numbers
2055 /*!
2056 * Implementations should take the derivative of the logarithm of the
2057 * activity coefficient with respect to a species log mole number (with all
2058 * other species mole numbers held constant). The default treatment in the
2059 * ThermoPhase object is to set this vector to zero.
2060 *
2061 * units = 1 / kmol
2062 *
2063 * dlnActCoeffdlnN[ ld * k + m] will contain the derivative of log
2064 * act_coeff for the *m*-th species with respect to the number of moles of
2065 * the *k*-th species.
2066 *
2067 * @f[
2068 * \frac{d \ln(\gamma_m) }{d \ln( n_k ) }\Bigg|_{n_i}
2069 * @f]
2070 *
2071 * When implemented, this method is used within the VCS equilibrium solver to
2072 * calculate the Jacobian elements, which accelerates convergence of the algorithm.
2073 *
2074 * @param ld Number of rows in the matrix
2075 * @param dlnActCoeffdlnN Output vector of derivatives of the
2076 * log Activity Coefficients. length = m_kk * m_kk
2077 */
2078 virtual void getdlnActCoeffdlnN(const size_t ld, double* const dlnActCoeffdlnN);
2079
2080 virtual void getdlnActCoeffdlnN_numderiv(const size_t ld,
2081 double* const dlnActCoeffdlnN);
2082
2083 //! @}
2084 //! @name Printing
2085 //! @{
2086
2087 //! returns a summary of the state of the phase as a string
2088 /*!
2089 * @param show_thermo If true, extra information is printed out
2090 * about the thermodynamic state of the system.
2091 * @param threshold Show information about species with mole fractions
2092 * greater than *threshold*.
2093 */
2094 virtual string report(bool show_thermo=true, double threshold=-1e-14) const;
2095
2096 //! returns a summary of the state of the phase to a comma separated file.
2097 /*!
2098 * To customize the data included in the report, derived classes should
2099 * override the getCsvReportData method.
2100 *
2101 * @param csvFile ofstream file to print comma separated data for the phase
2102 * @deprecated To be removed after %Cantera 3.0.
2103 */
2104 virtual void reportCSV(std::ofstream& csvFile) const;
2105
2106 //! @}
2107
2108 protected:
2109 //! Store the parameters of a ThermoPhase object such that an identical
2110 //! one could be reconstructed using the newThermo(AnyMap&) function. This
2111 //! does not include user-defined fields available in input().
2112 virtual void getParameters(AnyMap& phaseNode) const;
2113
2114 //! Fills `names` and `data` with the column names and species thermo
2115 //! properties to be included in the output of the reportCSV method.
2116 //! @deprecated To be removed after %Cantera 3.0.
2117 virtual void getCsvReportData(vector<string>& names,
2118 vector<vector<double>>& data) const;
2119
2120 //! Pointer to the calculation manager for species reference-state
2121 //! thermodynamic properties
2122 /*!
2123 * This class is called when the reference-state thermodynamic properties
2124 * of all the species in the phase needs to be evaluated.
2125 */
2126 MultiSpeciesThermo m_spthermo;
2127
2128 //! Data supplied via setParameters. When first set, this may include
2129 //! parameters used by different phase models when initThermo() is called.
2130 AnyMap m_input;
2131
2132 //! Stored value of the electric potential for this phase. Units are Volts.
2133 double m_phi = 0.0;
2134
2135 //! Boolean indicating whether a charge neutrality condition is a necessity
2136 /*!
2137 * Note, the charge neutrality condition is not a necessity for ideal gas
2138 * phases. There may be a net charge in those phases, because the NASA
2139 * polynomials for ionized species in Ideal gases take this condition into
2140 * account. However, liquid phases usually require charge neutrality in
2141 * order for their derived thermodynamics to be valid.
2142 */
2143 bool m_chargeNeutralityNecessary = false;
2144
2145 //! Contains the standard state convention
2146 int m_ssConvention = cSS_CONVENTION_TEMPERATURE;
2147
2148 //! last value of the temperature processed by reference state
2149 mutable double m_tlast = 0.0;
2150};
2151
2152}
2153
2154#endif
AnyMap.h
MultiSpeciesThermo.h
Header for a general species thermodynamic property manager for a phase (see MultiSpeciesThermo).
Phase.h
Header file for class Phase.
Units.h
Header for unit conversion utilities, which are used to translate user input from input files (See In...
Cantera::AnyMap
A map of string keys to values whose type can vary at runtime.
Definition AnyMap.h:427
Cantera::MultiSpeciesThermo
A species thermodynamic property manager for a phase.
Definition MultiSpeciesThermo.h:47
Cantera::MultiSpeciesThermo::refPressure
virtual double refPressure(size_t k=npos) const
The reference-state pressure for species k.
Definition MultiSpeciesThermo.cpp:152
Cantera::MultiSpeciesThermo::minTemp
virtual double minTemp(size_t k=npos) const
Minimum temperature.
Definition MultiSpeciesThermo.cpp:130
Cantera::MultiSpeciesThermo::maxTemp
virtual double maxTemp(size_t k=npos) const
Maximum temperature.
Definition MultiSpeciesThermo.cpp:141
Cantera::MultiSpeciesThermo::modifyOneHf298
virtual void modifyOneHf298(const size_t k, const double Hf298New)
Modify the value of the 298 K Heat of Formation of the standard state of one species in the phase (J ...
Definition MultiSpeciesThermo.cpp:196
Cantera::MultiSpeciesThermo::reportOneHf298
virtual double reportOneHf298(const size_t k) const
Report the 298 K Heat of Formation of the standard state of one species (J kmol-1)
Definition MultiSpeciesThermo.cpp:186
Cantera::NotImplementedError
An error indicating that an unimplemented function has been called.
Definition ctexceptions.h:195
Cantera::Phase
Class Phase is the base class for phases of matter, managing the species and elements in a phase,...
Definition Phase.h:95
Cantera::Phase::m_kk
size_t m_kk
Number of species in the phase.
Definition Phase.h:947
Cantera::Phase::temperature
double temperature() const
Temperature (K).
Definition Phase.h:662
Cantera::Phase::meanMolecularWeight
double meanMolecularWeight() const
The mean molecular weight. Units: (kg/kmol)
Definition Phase.h:760
Cantera::Phase::molarVolume
virtual double molarVolume() const
Molar volume (m^3/kmol).
Definition Phase.cpp:702
Cantera::Phase::pressure
virtual double pressure() const
Return the thermodynamic pressure (Pa).
Definition Phase.h:680
Cantera::Phase::name
string name() const
Return the name of the phase.
Definition Phase.cpp:20
Cantera::ThermoPhase
Base class for a phase with thermodynamic properties.
Definition ThermoPhase.h:390
Cantera::ThermoPhase::m_ssConvention
int m_ssConvention
Contains the standard state convention.
Definition ThermoPhase.h:2146
Cantera::ThermoPhase::getPartialMolarEnthalpies
virtual void getPartialMolarEnthalpies(double *hbar) const
Returns an array of partial molar enthalpies for the species in the mixture.
Definition ThermoPhase.h:816
Cantera::ThermoPhase::critTemperature
virtual double critTemperature() const
Critical temperature (K).
Definition ThermoPhase.h:1821
Cantera::ThermoPhase::setState_HP
virtual void setState_HP(double h, double p, double tol=1e-9)
Set the internally stored specific enthalpy (J/kg) and pressure (Pa) of the phase.
Definition ThermoPhase.cpp:211
Cantera::ThermoPhase::setState_PX
virtual void setState_PX(double p, double *x)
Set the pressure (Pa) and mole fractions.
Definition ThermoPhase.cpp:195
Cantera::ThermoPhase::electricPotential
double electricPotential() const
Returns the electric potential of this phase (V).
Definition ThermoPhase.h:621
Cantera::ThermoPhase::getEntropy_R
virtual void getEntropy_R(double *sr) const
Get the array of nondimensional Entropy functions for the standard state species at the current T and...
Definition ThermoPhase.h:895
Cantera::ThermoPhase::setState_UV
virtual void setState_UV(double u, double v, double tol=1e-9)
Set the specific internal energy (J/kg) and specific volume (m^3/kg).
Definition ThermoPhase.cpp:216
Cantera::ThermoPhase::chargeNeutralityNecessary
bool chargeNeutralityNecessary() const
Returns the chargeNeutralityNecessity boolean.
Definition ThermoPhase.h:516
Cantera::ThermoPhase::cp_mole
virtual double cp_mole() const
Molar heat capacity at constant pressure. Units: J/kmol/K.
Definition ThermoPhase.h:545
Cantera::ThermoPhase::equivalenceRatio
double equivalenceRatio() const
Compute the equivalence ratio for the current mixture from available oxygen and required oxygen.
Definition ThermoPhase.cpp:859
Cantera::ThermoPhase::setParameters
virtual void setParameters(const AnyMap &phaseNode, const AnyMap &rootNode=AnyMap())
Set equation of state parameters from an AnyMap phase description.
Definition ThermoPhase.cpp:1161
Cantera::ThermoPhase::thermalExpansionCoeff
virtual double thermalExpansionCoeff() const
Return the volumetric thermal expansion coefficient. Units: 1/K.
Definition ThermoPhase.h:580
Cantera::ThermoPhase::getEnthalpy_RT_ref
virtual void getEnthalpy_RT_ref(double *hrt) const
Returns the vector of nondimensional enthalpies of the reference state at the current temperature of ...
Definition ThermoPhase.h:964
Cantera::ThermoPhase::getParameters
virtual void getParameters(AnyMap &phaseNode) const
Store the parameters of a ThermoPhase object such that an identical one could be reconstructed using ...
Definition ThermoPhase.cpp:1176
Cantera::ThermoPhase::enthalpy_mole
virtual double enthalpy_mole() const
Molar enthalpy. Units: J/kmol.
Definition ThermoPhase.h:525
Cantera::ThermoPhase::getChemPotentials_RT
virtual void getChemPotentials_RT(double *mu) const
Get the array of non-dimensional species chemical potentials These are partial molar Gibbs free energ...
Definition ThermoPhase.h:777
Cantera::ThermoPhase::setState_TP
virtual void setState_TP(double t, double p)
Set the temperature (K) and pressure (Pa)
Definition ThermoPhase.cpp:121
Cantera::ThermoPhase::standardConcentration
virtual double standardConcentration(size_t k=0) const
Return the standard concentration for the kth species.
Definition ThermoPhase.h:718
Cantera::ThermoPhase::getCp_R_ref
virtual void getCp_R_ref(double *cprt) const
Returns the vector of nondimensional constant pressure heat capacities of the reference state at the ...
Definition ThermoPhase.h:1020
Cantera::ThermoPhase::setState_TV
virtual void setState_TV(double t, double v, double tol=1e-9)
Set the temperature (K) and specific volume (m^3/kg).
Definition ThermoPhase.h:1277
Cantera::ThermoPhase::logStandardConc
virtual double logStandardConc(size_t k=0) const
Natural logarithm of the standard concentration of the kth species.
Definition ThermoPhase.cpp:55
Cantera::ThermoPhase::o2Present
double o2Present(const double *y) const
Helper function for computing the amount of oxygen available in the current mixture.
Definition ThermoPhase.cpp:743
Cantera::ThermoPhase::setState_PV
virtual void setState_PV(double p, double v, double tol=1e-9)
Set the pressure (Pa) and specific volume (m^3/kg).
Definition ThermoPhase.h:1293
Cantera::ThermoPhase::setState
virtual void setState(const AnyMap &state)
Set the state using an AnyMap containing any combination of properties supported by the thermodynamic...
Definition ThermoPhase.cpp:222
Cantera::ThermoPhase::minTemp
virtual double minTemp(size_t k=npos) const
Minimum temperature for which the thermodynamic data for the species or phase are valid.
Definition ThermoPhase.h:451
Cantera::ThermoPhase::setState_RPY
virtual void setState_RPY(double rho, double p, const double *y)
Set the density (kg/m**3), pressure (Pa) and mass fractions.
Definition ThermoPhase.cpp:161
Cantera::ThermoPhase::getdlnActCoeffdlnN_diag
virtual void getdlnActCoeffdlnN_diag(double *dlnActCoeffdlnN_diag) const
Get the array of log species mole number derivatives of the log activity coefficients.
Definition ThermoPhase.h:2049
Cantera::ThermoPhase::setState_TPX
virtual void setState_TPX(double t, double p, const double *x)
Set the temperature (K), pressure (Pa), and mole fractions.
Definition ThermoPhase.cpp:85
Cantera::ThermoPhase::getCsvReportData
virtual void getCsvReportData(vector< string > &names, vector< vector< double > > &data) const
Fills names and data with the column names and species thermo properties to be included in the output...
Definition ThermoPhase.cpp:1520
Cantera::ThermoPhase::setState_SPorSV
void setState_SPorSV(double s, double p, double tol=1e-9, bool doSV=false)
Carry out work in SP and SV calculations.
Definition ThermoPhase.cpp:541
Cantera::ThermoPhase::RT
double RT() const
Return the Gas Constant multiplied by the current temperature.
Definition ThermoPhase.h:1077
Cantera::ThermoPhase::setState_RPX
virtual void setState_RPX(double rho, double p, const double *x)
Set the density (kg/m**3), pressure (Pa) and mole fractions.
Definition ThermoPhase.cpp:134
Cantera::ThermoPhase::getPartialMolarCp
virtual void getPartialMolarCp(double *cpbar) const
Return an array of partial molar heat capacities for the species in the mixture.
Definition ThermoPhase.h:847
Cantera::ThermoPhase::critPressure
virtual double critPressure() const
Critical pressure (Pa).
Definition ThermoPhase.h:1826
Cantera::ThermoPhase::getGibbs_RT_ref
virtual void getGibbs_RT_ref(double *grt) const
Returns the vector of nondimensional Gibbs Free Energies of the reference state at the current temper...
Definition ThermoPhase.h:975
Cantera::ThermoPhase::soundSpeed
virtual double soundSpeed() const
Return the speed of sound. Units: m/s.
Definition ThermoPhase.h:591
Cantera::ThermoPhase::setState_TPY
virtual void setState_TPY(double t, double p, const double *y)
Set the internally stored temperature (K), pressure (Pa), and mass fractions of the phase.
Definition ThermoPhase.cpp:103
Cantera::ThermoPhase::m_tlast
double m_tlast
last value of the temperature processed by reference state
Definition ThermoPhase.h:2149
Cantera::ThermoPhase::setState_ST
virtual void setState_ST(double s, double t, double tol=1e-9)
Set the specific entropy (J/kg/K) and temperature (K).
Definition ThermoPhase.h:1261
Cantera::ThermoPhase::setState_HPorUV
void setState_HPorUV(double h, double p, double tol=1e-9, bool doUV=false)
Carry out work in HP and UV calculations.
Definition ThermoPhase.cpp:339
Cantera::ThermoPhase::gibbs_mass
double gibbs_mass() const
Specific Gibbs function. Units: J/kg.
Definition ThermoPhase.h:1058
Cantera::ThermoPhase::getActivityConcentrations
virtual void getActivityConcentrations(double *c) const
This method returns an array of generalized concentrations.
Definition ThermoPhase.h:697
Cantera::ThermoPhase::stoichAirFuelRatio
double stoichAirFuelRatio(const double *fuelComp, const double *oxComp, ThermoBasis basis=ThermoBasis::molar) const
Compute the stoichiometric air to fuel ratio (kg oxidizer / kg fuel) given fuel and oxidizer composit...
Definition ThermoPhase.cpp:777
Cantera::ThermoPhase::type
string type() const override
String indicating the thermodynamic model implemented.
Definition ThermoPhase.h:399
Cantera::ThermoPhase::parameters
AnyMap parameters(bool withInput=true) const
Returns the parameters of a ThermoPhase object such that an identical one could be reconstructed usin...
Definition ThermoPhase.cpp:1166
Cantera::ThermoPhase::m_chargeNeutralityNecessary
bool m_chargeNeutralityNecessary
Boolean indicating whether a charge neutrality condition is a necessity.
Definition ThermoPhase.h:2143
Cantera::ThermoPhase::getPureGibbs
virtual void getPureGibbs(double *gpure) const
Get the Gibbs functions for the standard state of the species at the current T and P of the solution.
Definition ThermoPhase.h:916
Cantera::ThermoPhase::report
virtual string report(bool show_thermo=true, double threshold=-1e-14) const
returns a summary of the state of the phase as a string
Definition ThermoPhase.cpp:1354
Cantera::ThermoPhase::getPartialMolarIntEnergies
virtual void getPartialMolarIntEnergies(double *ubar) const
Return an array of partial molar internal energies for the species in the mixture.
Definition ThermoPhase.h:836
Cantera::ThermoPhase::getIntEnergy_RT
virtual void getIntEnergy_RT(double *urt) const
Returns the vector of nondimensional Internal Energies of the standard state species at the current T...
Definition ThermoPhase.h:926
Cantera::ThermoPhase::getCp_R
virtual void getCp_R(double *cpr) const
Get the nondimensional Heat Capacities at constant pressure for the species standard states at the cu...
Definition ThermoPhase.h:937
Cantera::ThermoPhase::maxTemp
virtual double maxTemp(size_t k=npos) const
Maximum temperature for which the thermodynamic data for the species are valid.
Definition ThermoPhase.h:504
Cantera::ThermoPhase::m_phi
double m_phi
Stored value of the electric potential for this phase. Units are Volts.
Definition ThermoPhase.h:2133
Cantera::ThermoPhase::isothermalCompressibility
virtual double isothermalCompressibility() const
Returns the isothermal compressibility. Units: 1/Pa.
Definition ThermoPhase.h:569
Cantera::ThermoPhase::mixtureFraction
double mixtureFraction(const double *fuelComp, const double *oxComp, ThermoBasis basis=ThermoBasis::molar, const string &element="Bilger") const
Compute the mixture fraction = kg fuel / (kg oxidizer + kg fuel) for the current mixture given fuel a...
Definition ThermoPhase.cpp:992
Cantera::ThermoPhase::o2Required
double o2Required(const double *y) const
Helper function for computing the amount of oxygen required for complete oxidation.
Definition ThermoPhase.cpp:714
Cantera::ThermoPhase::satTemperature
virtual double satTemperature(double p) const
Return the saturation temperature given the pressure.
Definition ThermoPhase.h:1856
Cantera::ThermoPhase::getdlnActCoeffds
virtual void getdlnActCoeffds(const double dTds, const double *const dXds, double *dlnActCoeffds) const
Get the change in activity coefficients wrt changes in state (temp, mole fraction,...
Definition ThermoPhase.h:2009
Cantera::ThermoPhase::getElectrochemPotentials
void getElectrochemPotentials(double *mu) const
Get the species electrochemical potentials.
Definition ThermoPhase.cpp:76
Cantera::ThermoPhase::getdlnActCoeffdlnN
virtual void getdlnActCoeffdlnN(const size_t ld, double *const dlnActCoeffdlnN)
Get the array of derivatives of the log activity coefficients with respect to the log of the species ...
Definition ThermoPhase.cpp:1289
Cantera::ThermoPhase::setState_RP
void setState_RP(double rho, double p)
Set the density (kg/m**3) and pressure (Pa) at constant composition.
Definition ThermoPhase.cpp:188
Cantera::ThermoPhase::getGibbs_RT
virtual void getGibbs_RT(double *grt) const
Get the nondimensional Gibbs functions for the species in their standard states at the current T and ...
Definition ThermoPhase.h:905
Cantera::ThermoPhase::critVolume
virtual double critVolume() const
Critical volume (m3/kmol).
Definition ThermoPhase.h:1831
Cantera::ThermoPhase::getActivityCoefficients
virtual void getActivityCoefficients(double *ac) const
Get the array of non-dimensional molar-based activity coefficients at the current solution temperatur...
Definition ThermoPhase.h:747
Cantera::ThermoPhase::phaseOfMatter
virtual string phaseOfMatter() const
String indicating the mechanical phase of the matter in this Phase.
Definition ThermoPhase.h:428
Cantera::ThermoPhase::getStandardVolumes
virtual void getStandardVolumes(double *vol) const
Get the molar volumes of the species standard states at the current T and P of the solution.
Definition ThermoPhase.h:949
Cantera::ThermoPhase::setState_Tsat
virtual void setState_Tsat(double t, double x)
Set the state to a saturated system at a particular temperature.
Definition ThermoPhase.h:1878
Cantera::ThermoPhase::entropy_mole
virtual double entropy_mole() const
Molar entropy. Units: J/kmol/K.
Definition ThermoPhase.h:535
Cantera::ThermoPhase::setElectricPotential
void setElectricPotential(double v)
Set the electric potential of this phase (V).
Definition ThermoPhase.h:612
Cantera::ThermoPhase::cv_mass
double cv_mass() const
Specific heat at constant volume. Units: J/kg/K.
Definition ThermoPhase.h:1068
Cantera::ThermoPhase::activityConvention
virtual int activityConvention() const
This method returns the convention used in specification of the activities, of which there are curren...
Definition ThermoPhase.cpp:39
Cantera::ThermoPhase::initThermo
virtual void initThermo()
Initialize the ThermoPhase object after all species have been set up.
Definition ThermoPhase.cpp:1093
Cantera::ThermoPhase::setState_PY
virtual void setState_PY(double p, double *y)
Set the internally stored pressure (Pa) and mass fractions.
Definition ThermoPhase.cpp:203
Cantera::ThermoPhase::entropy_mass
double entropy_mass() const
Specific entropy. Units: J/kg/K.
Definition ThermoPhase.h:1053
Cantera::ThermoPhase::critDensity
virtual double critDensity() const
Critical density (kg/m3).
Definition ThermoPhase.h:1841
Cantera::ThermoPhase::getGibbs_ref
virtual void getGibbs_ref(double *g) const
Returns the vector of the Gibbs function of the reference state at the current temperature of the sol...
Definition ThermoPhase.h:986
Cantera::ThermoPhase::speciesThermo
virtual MultiSpeciesThermo & speciesThermo(int k=-1)
Return a changeable reference to the calculation manager for species reference-state thermodynamic pr...
Definition ThermoPhase.cpp:1061
Cantera::ThermoPhase::setState_UP
virtual void setState_UP(double u, double p, double tol=1e-9)
Set the specific internal energy (J/kg) and pressure (Pa).
Definition ThermoPhase.h:1309
Cantera::ThermoPhase::initThermoFile
void initThermoFile(const string &inputFile, const string &id)
Initialize a ThermoPhase object using an input file.
Definition ThermoPhase.cpp:1072
Cantera::ThermoPhase::setState_SP
virtual void setState_SP(double s, double p, double tol=1e-9)
Set the specific entropy (J/kg/K) and pressure (Pa).
Definition ThermoPhase.cpp:530
Cantera::ThermoPhase::modifyOneHf298SS
virtual void modifyOneHf298SS(const size_t k, const double Hf298New)
Modify the value of the 298 K Heat of Formation of one species in the phase (J kmol-1)
Definition ThermoPhase.h:481
Cantera::ThermoPhase::standardStateConvention
virtual int standardStateConvention() const
This method returns the convention used in specification of the standard state, of which there are cu...
Definition ThermoPhase.cpp:44
Cantera::ThermoPhase::modifySpecies
void modifySpecies(size_t k, shared_ptr< Species > spec) override
Modify the thermodynamic data associated with a species.
Definition ThermoPhase.cpp:1145
Cantera::ThermoPhase::setState_SH
virtual void setState_SH(double s, double h, double tol=1e-9)
Set the specific entropy (J/kg/K) and the specific enthalpy (J/kg)
Definition ThermoPhase.h:1357
Cantera::ThermoPhase::getdlnActCoeffdlnX_diag
virtual void getdlnActCoeffdlnX_diag(double *dlnActCoeffdlnX_diag) const
Get the array of ln mole fraction derivatives of the log activity coefficients - diagonal component o...
Definition ThermoPhase.h:2029
Cantera::ThermoPhase::invalidateCache
void invalidateCache() override
Invalidate any cached values which are normally updated only when a change in state is detected.
Definition ThermoPhase.cpp:1239
Cantera::ThermoPhase::getActivities
virtual void getActivities(double *a) const
Get the array of non-dimensional activities at the current solution temperature, pressure,...
Definition ThermoPhase.cpp:60
Cantera::ThermoPhase::setMixtureFraction
void setMixtureFraction(double mixFrac, const double *fuelComp, const double *oxComp, ThermoBasis basis=ThermoBasis::molar)
Set the mixture composition according to the mixture fraction = kg fuel / (kg oxidizer + kg fuel)
Definition ThermoPhase.cpp:935
Cantera::ThermoPhase::getStandardVolumes_ref
virtual void getStandardVolumes_ref(double *vol) const
Get the molar volumes of the species reference states at the current T and P_ref of the solution.
Definition ThermoPhase.h:1032
Cantera::ThermoPhase::vaporFraction
virtual double vaporFraction() const
Return the fraction of vapor at the current conditions.
Definition ThermoPhase.h:1869
Cantera::ThermoPhase::resetHf298
virtual void resetHf298(const size_t k=npos)
Restore the original heat of formation of one or more species.
Definition ThermoPhase.cpp:28
Cantera::ThermoPhase::getStandardChemPotentials
virtual void getStandardChemPotentials(double *mu) const
Get the array of chemical potentials at unit activity for the species at their standard states at the...
Definition ThermoPhase.h:875
Cantera::ThermoPhase::getEnthalpy_RT
virtual void getEnthalpy_RT(double *hrt) const
Get the nondimensional Enthalpy functions for the species at their standard states at the current T a...
Definition ThermoPhase.h:885
Cantera::ThermoPhase::getEntropy_R_ref
virtual void getEntropy_R_ref(double *er) const
Returns the vector of nondimensional entropies of the reference state at the current temperature of t...
Definition ThermoPhase.h:997
Cantera::ThermoPhase::getChemPotentials
virtual void getChemPotentials(double *mu) const
Get the species chemical potentials. Units: J/kmol.
Definition ThermoPhase.h:790
Cantera::ThermoPhase::cp_mass
double cp_mass() const
Specific heat at constant pressure. Units: J/kg/K.
Definition ThermoPhase.h:1063
Cantera::ThermoPhase::setState_TH
virtual void setState_TH(double t, double h, double tol=1e-9)
Set the temperature (K) and the specific enthalpy (J/kg)
Definition ThermoPhase.h:1341
Cantera::ThermoPhase::getLnActivityCoefficients
virtual void getLnActivityCoefficients(double *lnac) const
Get the array of non-dimensional molar-based ln activity coefficients at the current solution tempera...
Definition ThermoPhase.cpp:68
Cantera::ThermoPhase::intEnergy_mass
double intEnergy_mass() const
Specific internal energy. Units: J/kg.
Definition ThermoPhase.h:1048
Cantera::ThermoPhase::getSpeciesParameters
virtual void getSpeciesParameters(const string &name, AnyMap &speciesNode) const
Get phase-specific parameters of a Species object such that an identical one could be reconstructed a...
Definition ThermoPhase.h:1979
Cantera::ThermoPhase::standardConcentrationUnits
virtual Units standardConcentrationUnits() const
Returns the units of the "standard concentration" for this phase.
Definition ThermoPhase.cpp:49
Cantera::ThermoPhase::getIntEnergy_RT_ref
virtual void getIntEnergy_RT_ref(double *urt) const
Returns the vector of nondimensional internal Energies of the reference state at the current temperat...
Definition ThermoPhase.h:1008
Cantera::ThermoPhase::Hf298SS
double Hf298SS(const size_t k) const
Report the 298 K Heat of Formation of the standard state of one species (J kmol-1)
Definition ThermoPhase.h:466
Cantera::ThermoPhase::ThermoPhase
ThermoPhase()=default
Constructor.
Cantera::ThermoPhase::isIdeal
virtual bool isIdeal() const
Boolean indicating whether phase is ideal.
Definition ThermoPhase.h:404
Cantera::ThermoPhase::cv_mole
virtual double cv_mole() const
Molar heat capacity at constant volume. Units: J/kmol/K.
Definition ThermoPhase.h:550
Cantera::ThermoPhase::m_spthermo
MultiSpeciesThermo m_spthermo
Pointer to the calculation manager for species reference-state thermodynamic properties.
Definition ThermoPhase.h:2126
Cantera::ThermoPhase::satPressure
virtual double satPressure(double t)
Return the saturation pressure given the temperature.
Definition ThermoPhase.h:1864
Cantera::ThermoPhase::refPressure
virtual double refPressure() const
Returns the reference pressure in Pa.
Definition ThermoPhase.h:436
Cantera::ThermoPhase::critCompressibility
virtual double critCompressibility() const
Critical compressibility (unitless).
Definition ThermoPhase.h:1836
Cantera::ThermoPhase::addSpecies
bool addSpecies(shared_ptr< Species > spec) override
Add a Species to this Phase.
Definition ThermoPhase.cpp:1131
Cantera::ThermoPhase::m_input
AnyMap m_input
Data supplied via setParameters.
Definition ThermoPhase.h:2130
Cantera::ThermoPhase::intEnergy_mole
virtual double intEnergy_mole() const
Molar internal energy. Units: J/kmol.
Definition ThermoPhase.h:530
Cantera::ThermoPhase::reportCSV
virtual void reportCSV(std::ofstream &csvFile) const
returns a summary of the state of the phase to a comma separated file.
Definition ThermoPhase.cpp:1487
Cantera::ThermoPhase::setState_DP
virtual void setState_DP(double rho, double p)
Set the density (kg/m**3) and pressure (Pa) at constant composition.
Definition ThermoPhase.h:1391
Cantera::ThermoPhase::setEquivalenceRatio
void setEquivalenceRatio(double phi, const double *fuelComp, const double *oxComp, ThermoBasis basis=ThermoBasis::molar)
Set the mixture composition according to the equivalence ratio.
Definition ThermoPhase.cpp:808
Cantera::ThermoPhase::setState_TPQ
void setState_TPQ(double T, double P, double Q)
Set the temperature, pressure, and vapor fraction (quality).
Definition ThermoPhase.cpp:1102
Cantera::ThermoPhase::setState_VH
virtual void setState_VH(double v, double h, double tol=1e-9)
Set the specific volume (m^3/kg) and the specific enthalpy (J/kg)
Definition ThermoPhase.h:1325
Cantera::ThermoPhase::getPartialMolarEntropies
virtual void getPartialMolarEntropies(double *sbar) const
Returns an array of partial molar entropies of the species in the solution.
Definition ThermoPhase.h:826
Cantera::ThermoPhase::gibbs_mole
virtual double gibbs_mole() const
Molar Gibbs function. Units: J/kmol.
Definition ThermoPhase.h:540
Cantera::ThermoPhase::setState_SV
virtual void setState_SV(double s, double v, double tol=1e-9)
Set the specific entropy (J/kg/K) and specific volume (m^3/kg).
Definition ThermoPhase.cpp:535
Cantera::ThermoPhase::input
const AnyMap & input() const
Access input data associated with the phase description.
Definition ThermoPhase.cpp:1229
Cantera::ThermoPhase::setState_Psat
virtual void setState_Psat(double p, double x)
Set the state to a saturated system at a particular pressure.
Definition ThermoPhase.h:1887
Cantera::ThermoPhase::setState_conditional_TP
void setState_conditional_TP(double t, double p, bool set_p)
Helper function used by setState_HPorUV and setState_SPorSV.
Definition ThermoPhase.cpp:331
Cantera::ThermoPhase::getPartialMolarVolumes
virtual void getPartialMolarVolumes(double *vbar) const
Return an array of partial molar volumes for the species in the mixture.
Definition ThermoPhase.h:857
Cantera::ThermoPhase::enthalpy_mass
double enthalpy_mass() const
Specific enthalpy. Units: J/kg.
Definition ThermoPhase.h:1043
Cantera::Units
A representation of the units associated with a dimensional quantity.
Definition Units.h:35
Cantera::ThermoPhase::equilibrate
void equilibrate(const string &XY, const string &solver="auto", double rtol=1e-9, int max_steps=50000, int max_iter=100, int estimate_equil=0, int log_level=0)
Equilibrate a ThermoPhase object.
Definition ThermoPhase.cpp:1244
Cantera::ThermoPhase::compatibleWithMultiPhase
virtual bool compatibleWithMultiPhase() const
Indicates whether this phase type can be used with class MultiPhase for equilibrium calculations.
Definition ThermoPhase.h:1809
Cantera::ThermoPhase::setToEquilState
virtual void setToEquilState(const double *mu_RT)
This method is used by the ChemEquil equilibrium solver.
Definition ThermoPhase.h:1802
Cantera::GasConstant
const double GasConstant
Universal Gas Constant [J/kmol/K].
Definition ct_defs.h:120
Cantera
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
Cantera::npos
const size_t npos
index returned by functions to indicate "no position"
Definition ct_defs.h:195
Cantera::cSS_CONVENTION_VPSS
const int cSS_CONVENTION_VPSS
Standard state uses the molality convention.
Definition ThermoPhase.h:146
Cantera::cAC_CONVENTION_MOLAR
const int cAC_CONVENTION_MOLAR
Standard state uses the molar convention.
Definition ThermoPhase.h:135
Cantera::cSS_CONVENTION_TEMPERATURE
const int cSS_CONVENTION_TEMPERATURE
Standard state uses the molar convention.
Definition ThermoPhase.h:144
Cantera::ThermoBasis
ThermoBasis
Differentiate between mole fractions and mass fractions for input mixture composition.
Definition ThermoPhase.h:154
Cantera::cSS_CONVENTION_SLAVE
const int cSS_CONVENTION_SLAVE
Standard state thermodynamics is obtained from slave ThermoPhase objects.
Definition ThermoPhase.h:148
Cantera::Composition
map< string, double > Composition
Map from string names to doubles.
Definition ct_defs.h:184
Cantera::cAC_CONVENTION_MOLALITY
const int cAC_CONVENTION_MOLALITY
Standard state uses the molality convention.
Definition ThermoPhase.h:137