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