Cantera  3.1.0a1
Loading...
Searching...
No Matches
Phase.h
Go to the documentation of this file.
1/**
2 * @file Phase.h
3 * Header file for class Phase.
4 */
5
6// This file is part of Cantera. See License.txt in the top-level directory or
7// at https://cantera.org/license.txt for license and copyright information.
8
9#ifndef CT_PHASE_H
10#define CT_PHASE_H
11
15
16namespace Cantera
17{
18
19class Solution;
20class Species;
21
22//! Class Phase is the base class for phases of matter, managing the species and
23//! elements in a phase, as well as the independent variables of temperature,
24//! mass density (compressible substances) or pressure (incompressible
25//! substances), species mass/mole fraction, and other generalized forces and
26//! intrinsic properties (such as electric potential) that define the
27//! thermodynamic state.
28/*!
29 *
30 * Class Phase provides information about the elements and species in a
31 * phase - names, index numbers (location in arrays), atomic or molecular
32 * weights, etc. The set of elements must include all those that compose the
33 * species, but may include additional elements.
34 *
35 * It also stores an array of species molecular weights, which are used to
36 * convert between mole and mass representations of the composition. For
37 * efficiency in mass/mole conversion, the vector of mass fractions divided
38 * by molecular weight @f$ Y_k/M_k @f$ is also stored.
39 *
40 * Class Phase is not usually used directly. Its primary use is as a base class
41 * for class ThermoPhase. It is not generally necessary to overloaded any of
42 * class Phase's methods, which handles both compressible and incompressible
43 * phases. For incompressible phases, the density is replaced by the pressure
44 * as the independent variable, and can no longer be set directly. In this case,
45 * the density needs to be calculated from a suitable equation of state, and
46 * assigned to the object using the assignDensity() method. This also applies
47 * for nearly-incompressible phases or phases which utilize standard states
48 * based on a T and P, in which case they need to overload these functions too.
49 *
50 * Class Phase contains a number of utility functions that will set the state
51 * of the phase in its entirety, by first setting the composition, and then
52 * temperature and pressure. An example of this is the function
53 * Phase::setState_TPY(double t, double p, const double* y).
54 *
55 * For bulk (3-dimensional) phases, the mass density has units of kg/m^3, and the molar
56 * density and concentrations have units of kmol/m^3, and the units listed in the
57 * methods of the Phase class assume a bulk phase. However, for surface (2-dimensional)
58 * phases have units of kg/m^2 and kmol/m^2, respectively. And for edge (1-dimensional)
59 * phases, these units kg/m and kmol/m.
60 *
61 * Class Phase contains methods for saving and restoring the full internal state
62 * of a given phase. These are saveState() and restoreState(). These functions
63 * operate on a state vector, which by default uses the first two entries for
64 * temperature and density (compressible substances) or temperature and
65 * pressure (incompressible substances). If the substance is not pure in a
66 * thermodynamic sense (that is, it may contain multiple species), the state also
67 * contains nSpecies() entries that specify the composition by corresponding
68 * mass fractions. Default definitions can be overloaded by derived classes.
69 * For any phase, the native definition of its thermodynamic state is defined
70 * the method nativeState(), with the length of the state vector returned by
71 * by stateSize(). In addition, methods isPure() and isCompressible() provide
72 * information on the implementation of a Phase object.
73 *
74 * A species name is referred to via speciesName(), which is unique within a
75 * given phase. Note that within multiphase mixtures (MultiPhase()), both a
76 * phase name/index as well as species name are required to access information
77 * about a species in a particular phase. For surfaces, the species names are
78 * unique among the phases.
79 *
80 * @todo
81 * - Specify that the input mole, mass, and volume fraction vectors must sum
82 * to one on entry to the set state routines. Non-conforming mole/mass
83 * fraction vectors are not thermodynamically consistent. Moreover, unless
84 * we do this, the calculation of Jacobians will be altered whenever the
85 * treatment of non- conforming mole fractions is changed. Add setState
86 * functions corresponding to specifying mole numbers, which is actually
87 * what is being done (well one of the options, there are many) when non-
88 * conforming mole fractions are input. Note, we realize that most numerical
89 * Jacobian and some analytical Jacobians use non-conforming calculations.
90 * These can easily be changed to the set mole number setState functions.
91 *
92 * @ingroup thermoprops
93 */
94class Phase
95{
96public:
97 Phase() = default; //!< Default constructor.
98 virtual ~Phase() = default;
99
100 // Phase objects are not copyable or assignable
101 Phase(const Phase&) = delete;
102 Phase& operator=(const Phase&) = delete;
103
104 /**
105 * @name Name
106 * Class Phase uses the string name to identify a phase. For phases instantiated
107 * from YAML input files, the name is the value of the corresponding key in the
108 * phase map.
109 *
110 * However, the name field may be changed to another value during the
111 * course of a calculation. For example, if duplicates of a phase object
112 * are instantiated and used in multiple places (such as a ReactorNet), they
113 * will have the same constitutive input, that is, the names of the phases will
114 * be the same. Note that this is not a problem for %Cantera internally;
115 * however, a user may want to rename phase objects in order to clarify.
116 */
117 //!@{
118
119 //! Return the name of the phase.
120 /*!
121 * Names are unique within a %Cantera problem.
122 */
123 string name() const;
124
125 //! Sets the string name for the phase.
126 //! @param nm String name of the phase
127 void setName(const string& nm);
128
129 //! String indicating the thermodynamic model implemented. Usually
130 //! corresponds to the name of the derived class, less any suffixes such as
131 //! "Phase", TP", "VPSS", etc.
132 //! @since Starting in %Cantera 3.0, the name returned by this method corresponds
133 //! to the canonical name used in the YAML input format.
134 virtual string type() const {
135 return "Phase";
136 }
137
138 //! @} end group Name
139
140 //! @name Element and Species Information
141 //! @{
142
143 //! Name of the element with index m.
144 //! @param m Element index.
145 string elementName(size_t m) const;
146
147 //! Return the index of element named 'name'. The index is an integer
148 //! assigned to each element in the order it was added. Returns @ref npos
149 //! if the specified element is not found.
150 //! @param name Name of the element
151 size_t elementIndex(const string& name) const;
152
153 //! Return a read-only reference to the vector of element names.
154 const vector<string>& elementNames() const;
155
156 //! Atomic weight of element m.
157 //! @param m Element index
158 double atomicWeight(size_t m) const;
159
160 //! Entropy of the element in its standard state at 298 K and 1 bar.
161 //! If no entropy value was provided when the phase was constructed,
162 //! returns the value `ENTROPY298_UNKNOWN`.
163 //! @param m Element index
164 double entropyElement298(size_t m) const;
165
166 //! Atomic number of element m.
167 //! @param m Element index
168 int atomicNumber(size_t m) const;
169
170 //! Return the element constraint type
171 //! Possible types include:
172 //!
173 //! - `CT_ELEM_TYPE_TURNEDOFF -1`
174 //! - `CT_ELEM_TYPE_ABSPOS 0`
175 //! - `CT_ELEM_TYPE_ELECTRONCHARGE 1`
176 //! - `CT_ELEM_TYPE_CHARGENEUTRALITY 2`
177 //! - `CT_ELEM_TYPE_LATTICERATIO 3`
178 //! - `CT_ELEM_TYPE_KINETICFROZEN 4`
179 //! - `CT_ELEM_TYPE_SURFACECONSTRAINT 5`
180 //! - `CT_ELEM_TYPE_OTHERCONSTRAINT 6`
181 //!
182 //! The default is `CT_ELEM_TYPE_ABSPOS`.
183 //! @param m Element index
184 //! @returns the element type
185 int elementType(size_t m) const;
186
187 //! Change the element type of the mth constraint
188 //! Reassigns an element type.
189 //! @param m Element index
190 //! @param elem_type New elem type to be assigned
191 //! @returns the old element type
192 int changeElementType(int m, int elem_type);
193
194 //! Return a read-only reference to the vector of atomic weights.
195 const vector<double>& atomicWeights() const;
196
197 //! Number of elements.
198 size_t nElements() const;
199
200 //! Check that the specified element index is in range.
201 //! Throws an exception if m is greater than nElements()-1
202 void checkElementIndex(size_t m) const;
203
204 //! Check that an array size is at least nElements().
205 //! Throws an exception if mm is less than nElements(). Used before calls
206 //! which take an array pointer.
207 void checkElementArraySize(size_t mm) const;
208
209 //! Number of atoms of element @c m in species @c k.
210 //! @param k species index
211 //! @param m element index
212 double nAtoms(size_t k, size_t m) const;
213
214 //! Returns the index of a species named 'name' within the Phase object.
215 //! The first species in the phase will have an index 0, and the last one
216 //! will have an index of nSpecies() - 1.
217 //! @param name String name of the species. It may also be in the form
218 //! phaseName:speciesName
219 //! @return The index of the species. If the name is not found,
220 //! the value @ref npos is returned.
221 size_t speciesIndex(const string& name) const;
222
223 //! Name of the species with index k
224 //! @param k index of the species
225 string speciesName(size_t k) const;
226
227 //! Return a const reference to the vector of species names
228 const vector<string>& speciesNames() const;
229
230 //! Returns the number of species in the phase
231 size_t nSpecies() const {
232 return m_kk;
233 }
234
235 //! Check that the specified species index is in range.
236 //! Throws an exception if k is greater than nSpecies()-1
237 void checkSpeciesIndex(size_t k) const;
238
239 //! Check that an array size is at least nSpecies().
240 //! Throws an exception if kk is less than nSpecies(). Used before calls
241 //! which take an array pointer.
242 void checkSpeciesArraySize(size_t kk) const;
243
244 //! @} end group Element and Species Information
245
246 //! Return whether phase represents a pure (single species) substance
247 virtual bool isPure() const {
248 return false;
249 }
250
251 //! Return whether phase represents a substance with phase transitions
252 virtual bool hasPhaseTransition() const {
253 return false;
254 }
255
256 //! Return whether phase represents a compressible substance
257 virtual bool isCompressible() const {
258 return true;
259 }
260
261 //! Return a map of properties defining the native state of a substance.
262 //! By default, entries include "T", "D", "Y" for a compressible substance
263 //! and "T", "P", "Y" for an incompressible substance, with offsets 0, 1 and
264 //! 2, respectively. Mass fractions "Y" are omitted for pure species.
265 //! In all cases, offsets into the state vector are used by saveState()
266 //! and restoreState().
267 virtual map<string, size_t> nativeState() const;
268
269 //! Return string acronym representing the native state of a Phase.
270 //! Examples: "TP", "TDY", "TPY".
271 //! @see nativeState
272 //! @since New in %Cantera 3.0
273 string nativeMode() const;
274
275 //! Return a vector containing full states defining a phase.
276 //! Full states list combinations of properties that allow for the
277 //! specification of a thermodynamic state based on user input.
278 //! Properties and states are represented by single letter acronyms, and
279 //! combinations of letters, respectively (for example, "TDY", "TPX", "SVX").
280 //! Supported property acronyms are:
281 //! "T": temperature
282 //! "P": pressure
283 //! "D": density
284 //! "X": mole fractions
285 //! "Y": mass fractions
286 //! "T": temperature
287 //! "U": specific internal energy
288 //! "V": specific volume
289 //! "H": specific enthalpy
290 //! "S": specific entropy
291 //! "Q": vapor fraction
292 virtual vector<string> fullStates() const;
293
294 //! Return a vector of settable partial property sets within a phase.
295 //! Partial states encompass all valid combinations of properties that allow
296 //! for the specification of a state while ignoring species concentrations
297 //! (such as "TD", "TP", "SV").
298 virtual vector<string> partialStates() const;
299
300 //! Return size of vector defining internal state of the phase.
301 //! Used by saveState() and restoreState().
302 virtual size_t stateSize() const;
303
304 //! Save the current internal state of the phase.
305 //! Write to vector 'state' the current internal state.
306 //! @param state output vector. Will be resized to stateSize().
307 void saveState(vector<double>& state) const;
308
309 //! Write to array 'state' the current internal state.
310 //! @param lenstate length of the state array. Must be >= stateSize()
311 //! @param state output vector. Must be of length stateSizes() or
312 //! greater.
313 virtual void saveState(size_t lenstate, double* state) const;
314
315 //! Restore a state saved on a previous call to saveState.
316 //! @param state State vector containing the previously saved state.
317 void restoreState(const vector<double>& state);
318
319 //! Restore the state of the phase from a previously saved state vector.
320 //! @param lenstate Length of the state vector
321 //! @param state Vector of state conditions.
322 virtual void restoreState(size_t lenstate, const double* state);
323
324 //! @name Set Thermodynamic State
325 //!
326 //! Set the internal thermodynamic state by setting the internally stored
327 //! temperature, density and species composition. Note that the composition
328 //! is always set first.
329 //!
330 //! Temperature and density are held constant if not explicitly set.
331 //! @{
332
333 //! Set the species mole fractions by name.
334 //! Species not listed by name in @c xMap are set to zero.
335 //! @param xMap map from species names to mole fraction values.
336 void setMoleFractionsByName(const Composition& xMap);
337
338 //! Set the mole fractions of a group of species by name. Species which
339 //! are not listed by name in the composition map are set to zero.
340 //! @param x string x in the form of a composition map
341 void setMoleFractionsByName(const string& x);
342
343 //! Set the species mass fractions by name.
344 //! Species not listed by name in @c yMap are set to zero.
345 //! @param yMap map from species names to mass fraction values.
346 void setMassFractionsByName(const Composition& yMap);
347
348 //! Set the species mass fractions by name.
349 //! Species not listed by name in @c x are set to zero.
350 //! @param x String containing a composition map
351 void setMassFractionsByName(const string& x);
352
353 //! Set the internally stored temperature (K) and density (kg/m^3)
354 //! @param t Temperature in kelvin
355 //! @param rho Density (kg/m^3)
356 //! @since New in %Cantera 3.0.
357 void setState_TD(double t, double rho);
358
359 //! @} end group set thermo state
360
361 //! Molecular weight of species @c k.
362 //! @param k index of species @c k
363 //! @returns the molecular weight of species @c k.
364 double molecularWeight(size_t k) const;
365
366 //! Copy the vector of molecular weights into array weights.
367 //! @param weights Output array of molecular weights (kg/kmol)
368 void getMolecularWeights(double* weights) const;
369
370 //! Return a const reference to the internal vector of molecular weights.
371 //! units = kg / kmol
372 const vector<double>& molecularWeights() const;
373
374 //! Return a const reference to the internal vector of molecular weights.
375 //! units = kmol / kg
376 const vector<double>& inverseMolecularWeights() const;
377
378 //! Copy the vector of species charges into array charges.
379 //! @param charges Output array of species charges (elem. charge)
380 void getCharges(double* charges) const;
381
382 //! @name Composition
383 //! @{
384
385 //! Get the mole fractions by name.
386 //! @param threshold Exclude species with mole fractions less than or
387 //! equal to this threshold.
388 //! @return Map of species names to mole fractions
389 Composition getMoleFractionsByName(double threshold=0.0) const;
390
391 //! Return the mole fraction of a single species
392 //! @param k species index
393 //! @return Mole fraction of the species
394 double moleFraction(size_t k) const;
395
396 //! Return the mole fraction of a single species
397 //! @param name String name of the species
398 //! @return Mole fraction of the species
399 double moleFraction(const string& name) const;
400
401 //! Get the mass fractions by name.
402 //! @param threshold Exclude species with mass fractions less than or
403 //! equal to this threshold.
404 //! @return Map of species names to mass fractions
405 Composition getMassFractionsByName(double threshold=0.0) const;
406
407 //! Return the mass fraction of a single species
408 //! @param k species index
409 //! @return Mass fraction of the species
410 double massFraction(size_t k) const;
411
412 //! Return the mass fraction of a single species
413 //! @param name String name of the species
414 //! @return Mass Fraction of the species
415 double massFraction(const string& name) const;
416
417 //! Get the species mole fraction vector.
418 //! @param x On return, x contains the mole fractions. Must have a
419 //! length greater than or equal to the number of species.
420 void getMoleFractions(double* const x) const;
421
422 //! Set the mole fractions to the specified values.
423 //! There is no restriction on the sum of the mole fraction vector.
424 //! Internally, the Phase object will normalize this vector before storing
425 //! its contents.
426 //! @param x Array of unnormalized mole fraction values (input). Must
427 //! have a length greater than or equal to the number of species, m_kk.
428 virtual void setMoleFractions(const double* const x);
429
430 //! Set the mole fractions to the specified values without normalizing.
431 //! This is useful when the normalization condition is being handled by
432 //! some other means, for example by a constraint equation as part of a
433 //! larger set of equations.
434 //! @param x Input vector of mole fractions. Length is m_kk.
435 virtual void setMoleFractions_NoNorm(const double* const x);
436
437 //! Get the species mass fractions.
438 //! @param[out] y Array of mass fractions, length nSpecies()
439 void getMassFractions(double* const y) const;
440
441 //! Return a const pointer to the mass fraction array
442 const double* massFractions() const {
443 return &m_y[0];
444 }
445
446 //! Set the mass fractions to the specified values and normalize them.
447 //! @param[in] y Array of unnormalized mass fraction values. Length
448 //! must be greater than or equal to the number of
449 //! species. The Phase object will normalize this vector
450 //! before storing its contents.
451 virtual void setMassFractions(const double* const y);
452
453 //! Set the mass fractions to the specified values without normalizing.
454 //! This is useful when the normalization condition is being handled by
455 //! some other means, for example by a constraint equation as part of a
456 //! larger set of equations.
457 //! @param y Input vector of mass fractions. Length is m_kk.
458 virtual void setMassFractions_NoNorm(const double* const y);
459
460 //! Get the species concentrations (kmol/m^3).
461 /*!
462 * @param[out] c The vector of species concentrations. Units are
463 * kmol/m^3. The length of the vector must be greater than
464 * or equal to the number of species within the phase.
465 */
466 virtual void getConcentrations(double* const c) const;
467
468 //! Concentration of species k.
469 //! If k is outside the valid range, an exception will be thrown.
470 /*!
471 * @param[in] k Index of the species within the phase.
472 *
473 * @returns the concentration of species k (kmol m-3).
474 */
475 virtual double concentration(const size_t k) const;
476
477 //! Set the concentrations to the specified values within the phase.
478 //! We set the concentrations here and therefore we set the overall density
479 //! of the phase. We hold the temperature constant during this operation.
480 //! Therefore, we have possibly changed the pressure of the phase by
481 //! calling this routine.
482 //! @param[in] conc Array of concentrations in dimensional units. For
483 //! bulk phases c[k] is the concentration of the kth
484 //! species in kmol/m3. For surface phases, c[k] is the
485 //! concentration in kmol/m2. The length of the vector
486 //! is the number of species in the phase.
487 virtual void setConcentrations(const double* const conc);
488
489 //! Set the concentrations without ignoring negative concentrations
490 virtual void setConcentrationsNoNorm(const double* const conc);
491 //! @}
492
493 //! Set the state of the object with moles in [kmol]
494 virtual void setMolesNoTruncate(const double* const N);
495
496 //! Elemental mass fraction of element m
497 /*!
498 * The elemental mass fraction @f$ Z_{\mathrm{mass},m} @f$ of element @f$ m @f$
499 * is defined as
500 * @f[
501 * Z_{\mathrm{mass},m} = \sum_k \frac{a_{m,k} M_m}{M_k} Y_k
502 * @f]
503 * with @f$ a_{m,k} @f$ being the number of atoms of element @f$ m @f$ in
504 * species @f$ k @f$, @f$ M_m @f$ the atomic weight of element @f$ m @f$,
505 * @f$ M_k @f$ the molecular weight of species @f$ k @f$, and @f$ Y_k @f$
506 * the mass fraction of species @f$ k @f$.
507 *
508 * @param[in] m Index of the element within the phase. If m is outside
509 * the valid range, an exception will be thrown.
510 *
511 * @return the elemental mass fraction of element m.
512 */
513 double elementalMassFraction(const size_t m) const;
514
515 //! Elemental mole fraction of element m
516 /*!
517 * The elemental mole fraction @f$ Z_{\mathrm{mole},m} @f$ of element @f$ m @f$
518 * is the number of atoms of element *m* divided by the total number of
519 * atoms. It is defined as:
520 *
521 * @f[
522 * Z_{\mathrm{mole},m} = \frac{\sum_k a_{m,k} X_k}
523 * {\sum_k \sum_j a_{j,k} X_k}
524 * @f]
525 * with @f$ a_{m,k} @f$ being the number of atoms of element @f$ m @f$ in
526 * species @f$ k @f$, @f$ \sum_j @f$ being a sum over all elements, and
527 * @f$ X_k @f$ being the mole fraction of species @f$ k @f$.
528 *
529 * @param[in] m Index of the element within the phase. If m is outside the
530 * valid range, an exception will be thrown.
531 * @return the elemental mole fraction of element m.
532 */
533 double elementalMoleFraction(const size_t m) const;
534
535 //! Dimensionless electrical charge of a single molecule of species k
536 //! The charge is normalized by the the magnitude of the electron charge
537 //! @param k species index
538 double charge(size_t k) const {
539 return m_speciesCharge[k];
540 }
541
542 //! Charge density [C/m^3].
543 double chargeDensity() const;
544
545 //! Returns the number of spatial dimensions (1, 2, or 3)
546 size_t nDim() const {
547 return m_ndim;
548 }
549
550 //! Set the number of spatial dimensions (1, 2, or 3). The number of
551 //! spatial dimensions is used for vector involving directions.
552 //! @param ndim Input number of dimensions.
553 void setNDim(size_t ndim) {
554 m_ndim = ndim;
555 }
556
557 //! @name Thermodynamic Properties
558 //! @{
559
560 //! Temperature (K).
561 //! @return The temperature of the phase
562 double temperature() const {
563 return m_temp;
564 }
565
566 //! Electron Temperature (K)
567 //! @return The electron temperature of the phase
568 virtual double electronTemperature() const {
569 return m_temp;
570 }
571
572 //! Return the thermodynamic pressure (Pa).
573 /*!
574 * This method must be overloaded in derived classes. Within %Cantera, the
575 * independent variable is either density or pressure. If the state is
576 * defined by temperature, density, and mass fractions, this method should
577 * use these values to implement the mechanical equation of state @f$ P(T,
578 * \rho, Y_1, \dots, Y_K) @f$. Alternatively, it returns a stored value.
579 */
580 virtual double pressure() const {
581 throw NotImplementedError("Phase::pressure",
582 "Not implemented for thermo model '{}'", type());
583 }
584
585 //! Density (kg/m^3).
586 //! @return The density of the phase
587 virtual double density() const {
588 return m_dens;
589 }
590
591 //! Molar density (kmol/m^3).
592 //! @return The molar density of the phase
593 virtual double molarDensity() const;
594
595 //! Molar volume (m^3/kmol).
596 //! @return The molar volume of the phase
597 virtual double molarVolume() const;
598
599 //! Set the internally stored density (kg/m^3) of the phase.
600 //! Note the density of a phase is an independent variable.
601 //! @param[in] density_ density (kg/m^3).
602 virtual void setDensity(const double density_);
603
604 //! Set the internally stored pressure (Pa) at constant temperature and
605 //! composition
606 /*!
607 * This method must be reimplemented in derived classes, where it may
608 * involve the solution of a nonlinear equation. Within %Cantera, the
609 * independent variable is either density or pressure. Therefore, this
610 * function may either solve for the density that will yield the desired
611 * input pressure or set an independent variable. The temperature
612 * and composition are held constant during this process.
613 *
614 * @param p input Pressure (Pa)
615 */
616 virtual void setPressure(double p) {
617 throw NotImplementedError("Phase::setPressure",
618 "Not implemented for thermo model '{}'", type());
619 }
620
621 //! Set the internally stored temperature of the phase (K).
622 //! @param temp Temperature in Kelvin
623 virtual void setTemperature(double temp) {
624 if (temp > 0) {
625 m_temp = temp;
626 } else {
627 throw CanteraError("Phase::setTemperature",
628 "temperature must be positive. T = {}", temp);
629 }
630 }
631
632 //! Set the internally stored electron temperature of the phase (K).
633 //! @param etemp Electron temperature in Kelvin
634 virtual void setElectronTemperature(double etemp) {
635 throw NotImplementedError("Phase::setElectronTemperature",
636 "Not implemented for thermo model '{}'", type());
637 }
638
639 //! @}
640
641 //! @name Mean Properties
642 //! @{
643
644 //! Evaluate the mole-fraction-weighted mean of an array Q.
645 //! @f[ \sum_k X_k Q_k. @f]
646 //! Q should contain pure-species molar property values.
647 //! @param[in] Q Array of length m_kk that is to be averaged.
648 //! @return mole-fraction-weighted mean of Q
649 double mean_X(const double* const Q) const;
650
651 //! @copydoc Phase::mean_X(const double* const Q) const
652 double mean_X(const vector<double>& Q) const;
653
654 //! The mean molecular weight. Units: (kg/kmol)
655 double meanMolecularWeight() const {
656 return m_mmw;
657 }
658
659 //! Evaluate @f$ \sum_k X_k \ln X_k @f$.
660 //! @return The indicated sum. Dimensionless.
661 double sum_xlogx() const;
662
663 //! @}
664 //! @name Adding Elements and Species
665 //!
666 //! These methods are used to add new elements or species. These are not
667 //! usually called by user programs.
668 //!
669 //! Since species are checked to insure that they are only composed of
670 //! declared elements, it is necessary to first add all elements before
671 //! adding any species.
672 //! @{
673
674 //! Add an element.
675 //! @param symbol Atomic symbol string.
676 //! @param weight Atomic mass in amu.
677 //! @param atomicNumber Atomic number of the element (unitless)
678 //! @param entropy298 Entropy of the element at 298 K and 1 bar in its
679 //! most stable form. The default is the value ENTROPY298_UNKNOWN,
680 //! which is interpreted as an unknown, and if used will cause
681 //! %Cantera to throw an error.
682 //! @param elem_type Specifies the type of the element constraint
683 //! equation. This defaults to CT_ELEM_TYPE_ABSPOS, that is, an element.
684 //! @return index of the element added
685 size_t addElement(const string& symbol, double weight=-12345.0,
686 int atomicNumber=0, double entropy298=ENTROPY298_UNKNOWN,
687 int elem_type=CT_ELEM_TYPE_ABSPOS);
688
689 //! Add a Species to this Phase. Returns `true` if the species was
690 //! successfully added, or `false` if the species was ignored.
691 //!
692 //! Derived classes which need to size arrays according to the number of
693 //! species should overload this method. The derived class implementation
694 //! should call the base class method, and, if this returns `true`
695 //! (indicating that the species has been added), adjust their array sizes
696 //! accordingly.
697 //!
698 //! @see ignoreUndefinedElements addUndefinedElements throwUndefinedElements
699 virtual bool addSpecies(shared_ptr<Species> spec);
700
701 //! Modify the thermodynamic data associated with a species.
702 /*!
703 * The species name, elemental composition, and type of thermo
704 * parameterization must be unchanged. If there are Kinetics objects that
705 * depend on this phase, Kinetics::invalidateCache() should be called on
706 * those objects after calling this function.
707 */
708 virtual void modifySpecies(size_t k, shared_ptr<Species> spec);
709
710 //! Add a species alias (that is, a user-defined alternative species name).
711 //! Aliases are case-sensitive.
712 //! @param name original species name
713 //! @param alias alternate name
714 void addSpeciesAlias(const string& name, const string& alias);
715
716 //! Return a vector with isomers names matching a given composition map
717 //! @param compMap Composition of the species.
718 //! @return A vector of species names for matching species.
719 virtual vector<string> findIsomers(const Composition& compMap) const;
720
721 //! Return a vector with isomers names matching a given composition string
722 //! @param comp String containing a composition map
723 //! @return A vector of species names for matching species.
724 virtual vector<string> findIsomers(const string& comp) const;
725
726 //! Return the Species object for the named species. Changes to this object
727 //! do not affect the ThermoPhase object until the #modifySpecies function
728 //! is called.
729 shared_ptr<Species> species(const string& name) const;
730
731 //! Return the Species object for species whose index is *k*. Changes to
732 //! this object do not affect the ThermoPhase object until the
733 //! #modifySpecies function is called.
734 shared_ptr<Species> species(size_t k) const;
735
736 //! Set behavior when adding a species containing undefined elements to just
737 //! skip the species.
739
740 //! Set behavior when adding a species containing undefined elements to add
741 //! those elements to the phase. This is the default behavior.
743
744 //! Set the behavior when adding a species containing undefined elements to
745 //! throw an exception.
747
748 struct UndefElement { enum behavior {
749 error, ignore, add
750 }; };
751
752 //! @} end group adding species and elements
753
754 //! Returns a bool indicating whether the object is ready for use
755 /*!
756 * @returns true if the object is ready for calculation, false otherwise.
757 */
758 virtual bool ready() const;
759
760 //! Return the State Mole Fraction Number
761 int stateMFNumber() const {
762 return m_stateNum;
763 }
764
765 //! Invalidate any cached values which are normally updated only when a
766 //! change in state is detected
767 virtual void invalidateCache();
768
769 //! Returns `true` if case sensitive species names are enforced
770 bool caseSensitiveSpecies() const {
772 }
773
774 //! Set flag that determines whether case sensitive species are enforced
775 //! in look-up operations, for example speciesIndex
776 void setCaseSensitiveSpecies(bool cflag = true) {
778 }
779
780 //! Converts a Composition to a vector with entries for each species
781 //! Species that are not specified are set to zero in the vector
782 /*!
783 * @param[in] comp Composition containing the mixture composition
784 * @return vector with length m_kk
785 */
786 vector<double> getCompositionFromMap(const Composition& comp) const;
787
788 //! Converts a mixture composition from mole fractions to mass fractions
789 //! @param[in] Y mixture composition in mass fractions (length m_kk)
790 //! @param[out] X mixture composition in mole fractions (length m_kk)
791 void massFractionsToMoleFractions(const double* Y, double* X) const;
792
793 //! Converts a mixture composition from mass fractions to mole fractions
794 //! @param[in] X mixture composition in mole fractions (length m_kk)
795 //! @param[out] Y mixture composition in mass fractions (length m_kk)
796 void moleFractionsToMassFractions(const double* X, double* Y) const;
797
798protected:
799 //! Ensure that phase is compressible.
800 //! An error is raised if the state is incompressible
801 //! @param setter name of setter (used for exception handling)
802 void assertCompressible(const string& setter) const {
803 if (!isCompressible()) {
804 throw CanteraError("Phase::assertCompressible",
805 "Setter '{}' is not available. Density is not an "
806 "independent \nvariable for "
807 "'{}' ('{}')", setter, name(), type());
808 }
809 }
810
811 //! Set the internally stored constant density (kg/m^3) of the phase.
812 //! Used for incompressible phases where the density is not an independent
813 //! variable, that is, density does not affect pressure in state calculations.
814 //! @param[in] density_ density (kg/m^3).
815 void assignDensity(const double density_);
816
817 //! Cached for saved calculations within each ThermoPhase.
818 /*!
819 * For more information on how to use this, see examples within the source
820 * code and documentation for this within ValueCache class itself.
821 */
823
824 //! Set the molecular weight of a single species to a given value.
825 //!
826 //! Used by phases where the equation of state is defined for a specific
827 //! value of the molecular weight which may not exactly correspond to the
828 //! value computed from the chemical formula.
829 //! @param k id of the species
830 //! @param mw Molecular Weight (kg kmol-1)
831 void setMolecularWeight(const int k, const double mw);
832
833 //! Apply changes to the state which are needed after the composition
834 //! changes. This function is called after any call to setMassFractions(),
835 //! setMoleFractions(), or similar. For phases which need to execute a
836 //! callback after any change to the composition, it should be done by
837 //! overriding this function rather than overriding all of the composition-
838 //! setting functions. Derived class implementations of compositionChanged()
839 //! should call the parent class method as well.
840 virtual void compositionChanged();
841
842 size_t m_kk = 0; //!< Number of species in the phase.
843
844 //! Dimensionality of the phase. Volumetric phases have dimensionality 3
845 //! and surface phases have dimensionality 2.
846 size_t m_ndim = 3;
847
848 //! Atomic composition of the species. The number of atoms of element i
849 //! in species k is equal to m_speciesComp[k * m_mm + i]
850 //! The length of this vector is equal to m_kk * m_mm
851 vector<double> m_speciesComp;
852
853 vector<double> m_speciesCharge; //!< Vector of species charges. length m_kk.
854
855 map<string, shared_ptr<Species>> m_species;
856
857 //! Flag determining behavior when adding species with an undefined element
858 UndefElement::behavior m_undefinedElementBehavior = UndefElement::add;
859
860 //! Flag determining whether case sensitive species names are enforced
862
863private:
864 //! Find lowercase species name in m_speciesIndices when case sensitive
865 //! species names are not enforced and a user specifies a non-canonical
866 //! species name. Raise exception if lowercase name is not unique.
867 size_t findSpeciesLower(const string& nameStr) const;
868
869 //! Name of the phase.
870 //! Initially, this is the name specified in the YAML input file. It may be changed
871 //! to another value during the course of a calculation.
872 string m_name;
873
874 double m_temp = 0.001; //!< Temperature (K). This is an independent variable
875
876 //! Density (kg m-3). This is an independent variable except in the case
877 //! of incompressible phases, where it has to be changed using the
878 //! assignDensity() method. For compressible substances, the pressure is
879 //! determined from this variable rather than other way round.
880 double m_dens = 0.001;
881
882 double m_mmw = 0.0; //!< mean molecular weight of the mixture (kg kmol-1)
883
884 //! m_ym[k] = mole fraction of species k divided by the mean molecular
885 //! weight of mixture.
886 mutable vector<double> m_ym;
887
888 //! Mass fractions of the species
889 /*!
890 * Note, this vector
891 * Length is m_kk
892 */
893 mutable vector<double> m_y;
894
895 vector<double> m_molwts; //!< species molecular weights (kg kmol-1)
896
897 vector<double> m_rmolwts; //!< inverse of species molecular weights (kmol kg-1)
898
899 //! State Change variable. Whenever the mole fraction vector changes,
900 //! this int is incremented.
901 int m_stateNum = -1;
902
903 //! Vector of the species names
904 vector<string> m_speciesNames;
905
906 //! Map of species names to indices
907 map<string, size_t> m_speciesIndices;
908
909 //! Map of lower-case species names to indices
910 map<string, size_t> m_speciesLower;
911
912 size_t m_mm = 0; //!< Number of elements.
913 vector<double> m_atomicWeights; //!< element atomic weights (kg kmol-1)
914 vector<int> m_atomicNumbers; //!< element atomic numbers
915 vector<string> m_elementNames; //!< element names
916 vector<int> m_elem_type; //!< Vector of element types
917
918 //! Entropy at 298.15 K and 1 bar of stable state pure elements (J kmol-1)
919 vector<double> m_entropy298;
920};
921
922}
923
924#endif
Contains the getElementWeight function and the definitions of element constraint types.
#define CT_ELEM_TYPE_ABSPOS
Normal element constraint consisting of positive coefficients for the formula matrix.
Definition Elements.h:35
#define ENTROPY298_UNKNOWN
Number indicating we don't know the entropy of the element in its most stable state at 298....
Definition Elements.h:85
Base class for exceptions thrown by Cantera classes.
An error indicating that an unimplemented function has been called.
Class Phase is the base class for phases of matter, managing the species and elements in a phase,...
Definition Phase.h:95
virtual vector< string > partialStates() const
Return a vector of settable partial property sets within a phase.
Definition Phase.cpp:215
void getCharges(double *charges) const
Copy the vector of species charges into array charges.
Definition Phase.cpp:405
virtual void getConcentrations(double *const c) const
Get the species concentrations (kmol/m^3).
Definition Phase.cpp:482
map< string, size_t > m_speciesLower
Map of lower-case species names to indices.
Definition Phase.h:910
double massFraction(size_t k) const
Return the mass fraction of a single species.
Definition Phase.cpp:455
virtual double molarDensity() const
Molar density (kmol/m^3).
Definition Phase.cpp:576
void assignDensity(const double density_)
Set the internally stored constant density (kg/m^3) of the phase.
Definition Phase.cpp:597
Phase()=default
Default constructor.
virtual bool addSpecies(shared_ptr< Species > spec)
Add a Species to this Phase.
Definition Phase.cpp:701
virtual void setMoleFractions(const double *const x)
Set the mole fractions to the specified values.
Definition Phase.cpp:289
int changeElementType(int m, int elem_type)
Change the element type of the mth constraint Reassigns an element type.
Definition Phase.cpp:96
const vector< double > & atomicWeights() const
Return a read-only reference to the vector of atomic weights.
Definition Phase.cpp:81
virtual vector< string > fullStates() const
Return a vector containing full states defining a phase.
Definition Phase.cpp:197
void assertCompressible(const string &setter) const
Ensure that phase is compressible.
Definition Phase.h:802
void checkSpeciesIndex(size_t k) const
Check that the specified species index is in range.
Definition Phase.cpp:153
void restoreState(const vector< double > &state)
Restore a state saved on a previous call to saveState.
Definition Phase.cpp:260
vector< double > m_speciesComp
Atomic composition of the species.
Definition Phase.h:851
ValueCache m_cache
Cached for saved calculations within each ThermoPhase.
Definition Phase.h:822
double m_temp
Temperature (K). This is an independent variable.
Definition Phase.h:874
vector< string > m_speciesNames
Vector of the species names.
Definition Phase.h:904
size_t nSpecies() const
Returns the number of species in the phase.
Definition Phase.h:231
virtual void setElectronTemperature(double etemp)
Set the internally stored electron temperature of the phase (K).
Definition Phase.h:634
bool m_caseSensitiveSpecies
Flag determining whether case sensitive species names are enforced.
Definition Phase.h:861
vector< string > m_elementNames
element names
Definition Phase.h:915
void ignoreUndefinedElements()
Set behavior when adding a species containing undefined elements to just skip the species.
Definition Phase.cpp:873
UndefElement::behavior m_undefinedElementBehavior
Flag determining behavior when adding species with an undefined element.
Definition Phase.h:858
virtual void setMassFractions_NoNorm(const double *const y)
Set the mass fractions to the specified values without normalizing.
Definition Phase.cpp:355
virtual map< string, size_t > nativeState() const
Return a map of properties defining the native state of a substance.
Definition Phase.cpp:167
double chargeDensity() const
Charge density [C/m^3].
Definition Phase.cpp:607
void addUndefinedElements()
Set behavior when adding a species containing undefined elements to add those elements to the phase.
Definition Phase.cpp:877
virtual void setConcentrationsNoNorm(const double *const conc)
Set the concentrations without ignoring negative concentrations.
Definition Phase.cpp:509
virtual string type() const
String indicating the thermodynamic model implemented.
Definition Phase.h:134
void setNDim(size_t ndim)
Set the number of spatial dimensions (1, 2, or 3).
Definition Phase.h:553
vector< int > m_atomicNumbers
element atomic numbers
Definition Phase.h:914
size_t m_kk
Number of species in the phase.
Definition Phase.h:842
int atomicNumber(size_t m) const
Atomic number of element m.
Definition Phase.cpp:86
virtual void modifySpecies(size_t k, shared_ptr< Species > spec)
Modify the thermodynamic data associated with a species.
Definition Phase.cpp:805
double m_mmw
mean molecular weight of the mixture (kg kmol-1)
Definition Phase.h:882
double elementalMoleFraction(const size_t m) const
Elemental mole fraction of element m.
Definition Phase.cpp:558
size_t m_ndim
Dimensionality of the phase.
Definition Phase.h:846
size_t nDim() const
Returns the number of spatial dimensions (1, 2, or 3)
Definition Phase.h:546
bool caseSensitiveSpecies() const
Returns true if case sensitive species names are enforced.
Definition Phase.h:770
void setCaseSensitiveSpecies(bool cflag=true)
Set flag that determines whether case sensitive species are enforced in look-up operations,...
Definition Phase.h:776
void setState_TD(double t, double rho)
Set the internally stored temperature (K) and density (kg/m^3)
Definition Phase.cpp:377
vector< double > m_rmolwts
inverse of species molecular weights (kmol kg-1)
Definition Phase.h:897
double temperature() const
Temperature (K).
Definition Phase.h:562
virtual void setPressure(double p)
Set the internally stored pressure (Pa) at constant temperature and composition.
Definition Phase.h:616
virtual bool isCompressible() const
Return whether phase represents a compressible substance.
Definition Phase.h:257
double meanMolecularWeight() const
The mean molecular weight. Units: (kg/kmol)
Definition Phase.h:655
virtual double electronTemperature() const
Electron Temperature (K)
Definition Phase.h:568
void moleFractionsToMassFractions(const double *X, double *Y) const
Converts a mixture composition from mass fractions to mole fractions.
Definition Phase.cpp:938
virtual bool hasPhaseTransition() const
Return whether phase represents a substance with phase transitions.
Definition Phase.h:252
virtual void setConcentrations(const double *const conc)
Set the concentrations to the specified values within the phase.
Definition Phase.cpp:487
void saveState(vector< double > &state) const
Save the current internal state of the phase.
Definition Phase.cpp:236
Composition getMoleFractionsByName(double threshold=0.0) const
Get the mole fractions by name.
Definition Phase.cpp:410
size_t elementIndex(const string &name) const
Return the index of element named 'name'.
Definition Phase.cpp:55
virtual double concentration(const size_t k) const
Concentration of species k.
Definition Phase.cpp:476
double atomicWeight(size_t m) const
Atomic weight of element m.
Definition Phase.cpp:70
void checkElementArraySize(size_t mm) const
Check that an array size is at least nElements().
Definition Phase.cpp:42
void setMassFractionsByName(const Composition &yMap)
Set the species mass fractions by name.
Definition Phase.cpp:366
int elementType(size_t m) const
Return the element constraint type Possible types include:
Definition Phase.cpp:91
string speciesName(size_t k) const
Name of the species with index k.
Definition Phase.cpp:142
map< string, size_t > m_speciesIndices
Map of species names to indices.
Definition Phase.h:907
virtual void setDensity(const double density_)
Set the internally stored density (kg/m^3) of the phase.
Definition Phase.cpp:586
Composition getMassFractionsByName(double threshold=0.0) const
Get the mass fractions by name.
Definition Phase.cpp:422
virtual size_t stateSize() const
Return size of vector defining internal state of the phase.
Definition Phase.cpp:228
string nativeMode() const
Return string acronym representing the native state of a Phase.
Definition Phase.cpp:184
vector< double > getCompositionFromMap(const Composition &comp) const
Converts a Composition to a vector with entries for each species Species that are not specified are s...
Definition Phase.cpp:909
size_t findSpeciesLower(const string &nameStr) const
Find lowercase species name in m_speciesIndices when case sensitive species names are not enforced an...
Definition Phase.cpp:110
vector< double > m_molwts
species molecular weights (kg kmol-1)
Definition Phase.h:895
virtual vector< string > findIsomers(const Composition &compMap) const
Return a vector with isomers names matching a given composition map.
Definition Phase.cpp:838
const vector< double > & inverseMolecularWeights() const
Return a const reference to the internal vector of molecular weights.
Definition Phase.cpp:400
virtual bool isPure() const
Return whether phase represents a pure (single species) substance.
Definition Phase.h:247
vector< double > m_y
Mass fractions of the species.
Definition Phase.h:893
void getMoleFractions(double *const x) const
Get the species mole fraction vector.
Definition Phase.cpp:434
void setMoleFractionsByName(const Composition &xMap)
Set the species mole fractions by name.
Definition Phase.cpp:330
const double * massFractions() const
Return a const pointer to the mass fraction array.
Definition Phase.h:442
vector< int > m_elem_type
Vector of element types.
Definition Phase.h:916
double sum_xlogx() const
Evaluate .
Definition Phase.cpp:626
string m_name
Name of the phase.
Definition Phase.h:872
const vector< double > & molecularWeights() const
Return a const reference to the internal vector of molecular weights.
Definition Phase.cpp:395
size_t speciesIndex(const string &name) const
Returns the index of a species named 'name' within the Phase object.
Definition Phase.cpp:129
double moleFraction(size_t k) const
Return the mole fraction of a single species.
Definition Phase.cpp:439
double m_dens
Density (kg m-3).
Definition Phase.h:880
const vector< string > & elementNames() const
Return a read-only reference to the vector of element names.
Definition Phase.cpp:65
virtual double density() const
Density (kg/m^3).
Definition Phase.h:587
virtual void compositionChanged()
Apply changes to the state which are needed after the composition changes.
Definition Phase.cpp:905
vector< double > m_atomicWeights
element atomic weights (kg kmol-1)
Definition Phase.h:913
void checkSpeciesArraySize(size_t kk) const
Check that an array size is at least nSpecies().
Definition Phase.cpp:160
void getMolecularWeights(double *weights) const
Copy the vector of molecular weights into array weights.
Definition Phase.cpp:389
double nAtoms(size_t k, size_t m) const
Number of atoms of element m in species k.
Definition Phase.cpp:103
int stateMFNumber() const
Return the State Mole Fraction Number.
Definition Phase.h:761
void addSpeciesAlias(const string &name, const string &alias)
Add a species alias (that is, a user-defined alternative species name).
Definition Phase.cpp:822
virtual void setMolesNoTruncate(const double *const N)
Set the state of the object with moles in [kmol].
Definition Phase.cpp:528
virtual void setTemperature(double temp)
Set the internally stored temperature of the phase (K).
Definition Phase.h:623
size_t nElements() const
Number of elements.
Definition Phase.cpp:30
void setMolecularWeight(const int k, const double mw)
Set the molecular weight of a single species to a given value.
Definition Phase.cpp:895
double mean_X(const double *const Q) const
Evaluate the mole-fraction-weighted mean of an array Q.
Definition Phase.cpp:616
vector< double > m_entropy298
Entropy at 298.15 K and 1 bar of stable state pure elements (J kmol-1)
Definition Phase.h:919
vector< double > m_ym
m_ym[k] = mole fraction of species k divided by the mean molecular weight of mixture.
Definition Phase.h:886
virtual void setMassFractions(const double *const y)
Set the mass fractions to the specified values and normalize them.
Definition Phase.cpp:341
const vector< string > & speciesNames() const
Return a const reference to the vector of species names.
Definition Phase.cpp:148
virtual bool ready() const
Returns a bool indicating whether the object is ready for use.
Definition Phase.cpp:885
double molecularWeight(size_t k) const
Molecular weight of species k.
Definition Phase.cpp:383
double elementalMassFraction(const size_t m) const
Elemental mass fraction of element m.
Definition Phase.cpp:547
shared_ptr< Species > species(const string &name) const
Return the Species object for the named species.
Definition Phase.cpp:856
virtual double molarVolume() const
Molar volume (m^3/kmol).
Definition Phase.cpp:581
virtual void invalidateCache()
Invalidate any cached values which are normally updated only when a change in state is detected.
Definition Phase.cpp:890
void checkElementIndex(size_t m) const
Check that the specified element index is in range.
Definition Phase.cpp:35
void getMassFractions(double *const y) const
Get the species mass fractions.
Definition Phase.cpp:471
int m_stateNum
State Change variable.
Definition Phase.h:901
void throwUndefinedElements()
Set the behavior when adding a species containing undefined elements to throw an exception.
Definition Phase.cpp:881
void setName(const string &nm)
Sets the string name for the phase.
Definition Phase.cpp:25
size_t m_mm
Number of elements.
Definition Phase.h:912
virtual double pressure() const
Return the thermodynamic pressure (Pa).
Definition Phase.h:580
string elementName(size_t m) const
Name of the element with index m.
Definition Phase.cpp:49
double charge(size_t k) const
Dimensionless electrical charge of a single molecule of species k The charge is normalized by the the...
Definition Phase.h:538
void massFractionsToMoleFractions(const double *Y, double *X) const
Converts a mixture composition from mole fractions to mass fractions.
Definition Phase.cpp:923
double entropyElement298(size_t m) const
Entropy of the element in its standard state at 298 K and 1 bar.
Definition Phase.cpp:75
virtual void setMoleFractions_NoNorm(const double *const x)
Set the mole fractions to the specified values without normalizing.
Definition Phase.cpp:321
vector< double > m_speciesCharge
Vector of species charges. length m_kk.
Definition Phase.h:853
size_t addElement(const string &symbol, double weight=-12345.0, int atomicNumber=0, double entropy298=ENTROPY298_UNKNOWN, int elem_type=CT_ELEM_TYPE_ABSPOS)
Add an element.
Definition Phase.cpp:635
string name() const
Return the name of the phase.
Definition Phase.cpp:20
Storage for cached values.
Definition ValueCache.h:153
Definitions for the classes that are thrown when Cantera experiences an error condition (also contain...
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564
map< string, double > Composition
Map from string names to doubles.
Definition ct_defs.h:177