Cantera 2.6.0

MultiPhase.h
Go to the documentation of this file.
1/**
2 * @file MultiPhase.h
3 * Headers for the \link Cantera::MultiPhase MultiPhase\endlink
4 * object that is used to set up multiphase equilibrium problems (see \ref equilfunctions).
5 */
6
7// This file is part of Cantera. See License.txt in the top-level directory or
8// at https://cantera.org/license.txt for license and copyright information.
9
10#ifndef CT_MULTIPHASE_H
11#define CT_MULTIPHASE_H
12
13#include "cantera/numerics/DenseMatrix.h"
14
15 namespace Cantera
16{
17
18 class ThermoPhase;
19
20//! @defgroup equilfunctions Classes and functions used for calculating
21//! chemical equilibrium.
22
23//! A class for multiphase mixtures. The mixture can contain any
24//! number of phases of any type.
25/*!
26 * This object is the basic tool used by Cantera for use in Multiphase
27 * equilibrium calculations.
28 *
29 * It is a container for a set of phases. Each phase has a given number of
30 * kmoles. Therefore, MultiPhase may be considered an "extrinsic"
31 * thermodynamic object, in contrast to the ThermoPhase object, which is an
32 * "intrinsic" thermodynamic object.
33 *
34 * MultiPhase may be considered to be "upstream" of the ThermoPhase objects in
35 * the sense that setting a property within MultiPhase, such as temperature,
36 * pressure, or species mole number, affects the underlying ThermoPhase
37 * object, but not the other way around.
38 *
39 * All phases have the same temperature and pressure, and a specified number
40 * of moles for each phase. The phases do not need to have the same elements.
41 * For example, a mixture might consist of a gaseous phase with elements (H,
42 * C, O, N), a solid carbon phase containing only element C, etc. A master
43 * element set will be constructed for the mixture that is the intersection of
44 * the elements of each phase.
45 *
46 * Below, reference is made to global species and global elements. These refer
47 * to the collective species and elements encompassing all of the phases
48 * tracked by the object.
49 *
50 * The global element list kept by this object is an intersection of the
51 * element lists of all the phases that comprise the MultiPhase.
52 *
53 * The global species list kept by this object is a concatenated list of all
54 * of the species in all the phases that comprise the MultiPhase. The ordering
55 * of species is contiguous with respect to the phase id.
56 *
57 * @ingroup equilfunctions
58 */
59 class MultiPhase
60{
61 public:
62 //! Constructor.
63 /*!
64 * The constructor takes no arguments, since phases are added using
65 * method addPhase().
66 */
67 MultiPhase();
68
69 //! Destructor. Does nothing. Class MultiPhase does not take "ownership"
70 //! (that is, responsibility for destroying) the phase objects.
71 virtual ~MultiPhase() {}
72
73 //! Add a vector of phases to the mixture
74 /*!
75 * See the single addPhases command. This just does a bunch of phases
76 * at one time
77 * @param phases Vector of pointers to phases
78 * @param phaseMoles Vector of mole numbers in each phase (kmol)
79 */
80 void addPhases(std::vector<ThermoPhase*>& phases, const vector_fp& phaseMoles);
81
82 //! Add all phases present in 'mix' to this mixture.
83 /*!
84 * @param mix Add all of the phases in another MultiPhase
85 * object to the current object.
86 */
87 void addPhases(MultiPhase& mix);
88
89 //! Add a phase to the mixture.
90 /*!
91 * This function must be called before the init() function is called,
92 * which serves to freeze the MultiPhase.
93 *
94 * @param p pointer to the phase object
95 * @param moles total number of moles of all species in this phase
96 */
97 void addPhase(ThermoPhase* p, doublereal moles);
98
99 //! Number of elements.
100 size_t nElements() const {
101 return m_nel;
102 }
103
104 //! Check that the specified element index is in range.
105 //! Throws an exception if m is greater than nElements()-1
106 void checkElementIndex(size_t m) const;
107
108 //! Check that an array size is at least nElements().
109 //! Throws an exception if mm is less than nElements(). Used before calls
110 //! which take an array pointer.
111 void checkElementArraySize(size_t mm) const;
112
113 //! Returns the name of the global element *m*.
114 /*!
115 * @param m index of the global element
116 */
117 std::string elementName(size_t m) const;
118
119 //! Returns the index of the element with name \a name.
120 /*!
121 * @param name String name of the global element
122 */
123 size_t elementIndex(const std::string& name) const;
124
125 //! Number of species, summed over all phases.
126 size_t nSpecies() const {
127 return m_nsp;
128 }
129
130 //! Check that the specified species index is in range.
131 //! Throws an exception if k is greater than nSpecies()-1
132 void checkSpeciesIndex(size_t k) const;
133
134 //! Check that an array size is at least nSpecies().
135 //! Throws an exception if kk is less than nSpecies(). Used before calls
136 //! which take an array pointer.
137 void checkSpeciesArraySize(size_t kk) const;
138
139 //! Name of species with global index \a kGlob
140 /*!
141 * @param kGlob global species index
142 */
143 std::string speciesName(const size_t kGlob) const;
144
145 //! Returns the Number of atoms of global element \a mGlob in
146 //! global species \a kGlob.
147 /*!
148 * @param kGlob global species index
149 * @param mGlob global element index
150 * @returns the number of atoms.
151 */
152 doublereal nAtoms(const size_t kGlob, const size_t mGlob) const;
153
154 /// Returns the global Species mole fractions.
155 /*!
156 * Write the array of species mole
157 * fractions into array \c x. The mole fractions are
158 * normalized to sum to one in each phase.
159 *
160 * @param x vector of mole fractions. Length = number of global species.
161 */
162 void getMoleFractions(doublereal* const x) const;
163
164 //! Process phases and build atomic composition array.
165 /*!
166 * This method must be called after all phases are added, before doing
167 * anything else with the mixture. After init() has been called, no more
168 * phases may be added.
169 */
170 void init();
171
172 //! Returns the name of the n'th phase
173 /*!
174 * @param iph phase Index
175 */
176 std::string phaseName(const size_t iph) const;
177
178 //! Returns the index, given the phase name
179 /*!
180 * @param pName Name of the phase
181 * @returns the index. A value of -1 means the phase isn't in the object.
182 */
183 int phaseIndex(const std::string& pName) const;
184
185 //! Return the number of moles in phase n.
186 /*!
187 * @param n Index of the phase.
188 */
189 doublereal phaseMoles(const size_t n) const;
190
191 //! Set the number of moles of phase with index n.
192 /*!
193 * @param n Index of the phase
194 * @param moles Number of moles in the phase (kmol)
195 */
196 void setPhaseMoles(const size_t n, const doublereal moles);
197
198 /// Return a reference to phase n.
199 /*!
200 * The state of phase n is also updated to match the state stored locally
201 * in the mixture object.
202 *
203 * @param n Phase Index
204 * @return Reference to the ThermoPhase object for the phase
205 */
206 ThermoPhase& phase(size_t n);
207
208 //! Check that the specified phase index is in range
209 //! Throws an exception if m is greater than nPhases()
210 void checkPhaseIndex(size_t m) const;
211
212 //! Check that an array size is at least nPhases()
213 //! Throws an exception if mm is less than nPhases(). Used before calls
214 //! which take an array pointer.
215 void checkPhaseArraySize(size_t mm) const;
216
217 //! Returns the moles of global species \c k. units = kmol
218 /*!
219 * @param kGlob Global species index k
220 */
221 doublereal speciesMoles(size_t kGlob) const;
222
223 //! Return the global index of the species belonging to phase number \c p
224 //! with local index \c k within the phase.
225 /*!
226 * @param k local index of the species within the phase
227 * @param p index of the phase
228 */
229 size_t speciesIndex(size_t k, size_t p) const {
230 return m_spstart[p] + k;
231 }
232
233 //! Return the global index of the species belonging to phase name \c phaseName
234 //! with species name \c speciesName
235 /*!
236 * @param speciesName Species Name
237 * @param phaseName Phase Name
238 *
239 * @returns the global index
240 *
241 * If the species or phase name is not recognized, this routine throws a
242 * CanteraError.
243 */
244 size_t speciesIndex(const std::string& speciesName, const std::string& phaseName);
245
246 /// Minimum temperature for which all solution phases have valid thermo
247 /// data. Stoichiometric phases are not considered, since they may have
248 /// thermo data only valid for conditions for which they are stable.
249 doublereal minTemp() const {
250 return m_Tmin;
251 }
252
253 /// Maximum temperature for which all solution phases have valid thermo
254 /// data. Stoichiometric phases are not considered, since they may have
255 /// thermo data only valid for conditions for which they are stable.
256 doublereal maxTemp() const {
257 return m_Tmax;
258 }
259
260 //! Total charge summed over all phases (Coulombs).
261 doublereal charge() const;
262
263 /// Charge (Coulombs) of phase with index \a p.
264 /*!
265 * The net charge is computed as \f[ Q_p = N_p \sum_k F z_k X_k \f]
266 * where the sum runs only over species in phase \a p.
267 * @param p index of the phase for which the charge is desired.
268 */
269 doublereal phaseCharge(size_t p) const;
270
271 //! Total moles of global element \a m, summed over all phases.
272 /*!
273 * @param m Index of the global element
274 */
275 doublereal elementMoles(size_t m) const;
276
277 //! Returns a vector of Chemical potentials.
278 /*!
279 * Write into array \a mu the chemical potentials of all species
280 * [J/kmol]. The chemical potentials are related to the activities by
281 *
282 * \f$
283 * \mu_k = \mu_k^0(T, P) + RT \ln a_k.
284 * \f$.
285 *
286 * @param mu Chemical potential vector. Length = num global species. Units
287 * = J/kmol.
288 */
289 void getChemPotentials(doublereal* mu) const;
290
291 /// Returns a vector of Valid chemical potentials.
292 /*!
293 * Write into array \a mu the chemical potentials of all species with
294 * thermo data valid for the current temperature [J/kmol]. For other
295 * species, set the chemical potential to the value \a not_mu. If \a
296 * standard is set to true, then the values returned are standard chemical
297 * potentials.
298 *
299 * This method is designed for use in computing chemical equilibrium by
300 * Gibbs minimization. For solution phases (more than one species), this
301 * does the same thing as getChemPotentials. But for stoichiometric
302 * phases, this writes into array \a mu the user-specified value \a not_mu
303 * instead of the chemical potential if the temperature is outside the
304 * range for which the thermo data for the one species in the phase are
305 * valid. The need for this arises since many condensed phases have thermo
306 * data fit only for the temperature range for which they are stable. For
307 * example, in the NASA database, the fits for H2O(s) are only done up to
308 * 0 C, the fits for H2O(L) are only done from 0 C to 100 C, etc. Using
309 * the polynomial fits outside the range for which the fits were done can
310 * result in spurious chemical potentials, and can lead to condensed
311 * phases appearing when in fact they should be absent.
312 *
313 * By setting \a not_mu to a large positive value, it is possible to force
314 * routines which seek to minimize the Gibbs free energy of the mixture to
315 * zero out any phases outside the temperature range for which their
316 * thermo data are valid.
317 *
318 * @param not_mu Value of the chemical potential to set species in phases,
319 * for which the thermo data is not valid
320 * @param mu Vector of chemical potentials. length = Global species,
321 * units = J kmol-1
322 * @param standard If this method is called with \a standard set to true,
323 * then the composition-independent standard chemical
324 * potentials are returned instead of the composition-
325 * dependent chemical potentials.
326 */
327 void getValidChemPotentials(doublereal not_mu, doublereal* mu,
328 bool standard = false) const;
329
330 //! Temperature [K].
331 doublereal temperature() const {
332 return m_temp;
333 }
334
335 //! Equilibrate a MultiPhase object
336 /*!
337 * Set this mixture to chemical equilibrium by calling one of Cantera's
338 * equilibrium solvers. The XY parameter indicates what two thermodynamic
339 * quantities are to be held constant during the equilibration process.
340 *
341 * @param XY String representation of what two properties are being
342 * held constant
343 * @param solver Name of the solver to be used to equilibrate the phase.
344 * If solver = 'vcs', the vcs_MultiPhaseEquil solver will be used. If
345 * solver = 'gibbs', the MultiPhaseEquil solver will be used. If solver
346 * = 'auto', the 'vcs' solver will be tried first, followed by the
347 * 'gibbs' solver if the first one fails.
348 * @param rtol Relative tolerance
349 * @param max_steps Maximum number of steps to take to find the solution
350 * @param max_iter The maximum number of outer temperature or pressure
351 * iterations to take when T and/or P is not held fixed.
352 * @param estimate_equil integer indicating whether the solver should
353 * estimate its own initial condition. If 0, the initial mole fraction
354 * vector in the ThermoPhase object is used as the initial condition.
355 * If 1, the initial mole fraction vector is used if the element
356 * abundances are satisfied. If -1, the initial mole fraction vector is
357 * thrown out, and an estimate is formulated.
358 * @param log_level loglevel Controls amount of diagnostic output.
359 * log_level=0 suppresses diagnostics, and increasingly-verbose
360 * messages are written as loglevel increases.
361 *
362 * @ingroup equilfunctions
363 */
364 void equilibrate(const std::string& XY, const std::string& solver="auto",
365 double rtol=1e-9, int max_steps=50000, int max_iter=100,
366 int estimate_equil=0, int log_level=0);
367
368 /// Set the temperature [K].
369 /*!
370 * @param T value of the temperature (Kelvin)
371 */
372 void setTemperature(const doublereal T);
373
374 //! Set the state of the underlying ThermoPhase objects in one call
375 /*!
376 * @param T Temperature of the system (kelvin)
377 * @param Pres pressure of the system (pascal)
378 */
379 void setState_TP(const doublereal T, const doublereal Pres);
380
381 //! Set the state of the underlying ThermoPhase objects in one call
382 /*!
383 * @param T Temperature of the system (kelvin)
384 * @param Pres pressure of the system (pascal)
385 * @param Moles Vector of mole numbers of all the species in all the phases
386 * (kmol)
387 */
388 void setState_TPMoles(const doublereal T, const doublereal Pres, const doublereal* Moles);
389
390 /// Pressure [Pa].
391 doublereal pressure() const {
392 return m_press;
393 }
394
395 /// The total mixture volume [m^3].
396 /*!
397 * Returns the cumulative sum of the volumes of all the phases in the
398 * mixture.
399 */
400 doublereal volume() const;
401
402 //! Set the pressure [Pa].
403 /*!
404 * @param P Set the pressure in the MultiPhase object (Pa)
405 */
406 void setPressure(doublereal P) {
407 m_press = P;
408 updatePhases();
409 }
410
411 //! The enthalpy of the mixture [J].
412 doublereal enthalpy() const;
413
414 //! The internal energy of the mixture [J].
415 doublereal IntEnergy() const;
416
417 //! The entropy of the mixture [J/K].
418 doublereal entropy() const;
419
420 //! The Gibbs function of the mixture [J].
421 doublereal gibbs() const;
422
423 //! Heat capacity at constant pressure [J/K]. Note that this does not
424 //! account for changes in composition of the mixture with temperature.
425 doublereal cp() const;
426
427 //! Number of phases.
428 size_t nPhases() const {
429 return m_phase.size();
430 }
431
432 //! Return true is species \a kGlob is a species in a multicomponent
433 //! solution phase.
434 /*!
435 * @param kGlob index of the global species
436 */
437 bool solutionSpecies(size_t kGlob) const;
438
439 //! Returns the phase index of the Kth "global" species
440 /*!
441 * @param kGlob Global species index.
442 * @returns the index of the owning phase.
443 */
444 size_t speciesPhaseIndex(const size_t kGlob) const;
445
446 //! Returns the mole fraction of global species k
447 /*!
448 * @param kGlob Index of the global species.
449 */
450 doublereal moleFraction(const size_t kGlob) const;
451
452 //! Set the Mole fractions of the nth phase
453 /*!
454 * This function sets the mole fractions of the nth phase. Note, the mole
455 * number of the phase stays constant
456 *
457 * @param n index of the phase
458 * @param x Vector of input mole fractions.
459 */
460 void setPhaseMoleFractions(const size_t n, const doublereal* const x);
461
462 //! Set the number of moles of species in the mixture
463 /*!
464 * @param xMap CompositionMap of the species with nonzero mole numbers.
465 * Mole numbers that are less than or equal to zero will be
466 * set to zero. units = kmol.
467 */
468 void setMolesByName(const compositionMap& xMap);
469
470 //! Set the moles via a string containing their names.
471 /*!
472 * The string x is in the form of a composition map. Species which are not
473 * listed are set to zero.
474 *
475 * @param x string x in the form of a composition map
476 * where values are the moles of the species.
477 */
478 void setMolesByName(const std::string& x);
479
480 //! Get the mole numbers of all species in the multiphase object
481 /*!
482 * @param[out] molNum Vector of doubles of length nSpecies containing the
483 * global mole numbers (kmol).
484 */
485 void getMoles(doublereal* molNum) const;
486
487 //! Sets all of the global species mole numbers
488 /*!
489 * The state of each phase object is also updated to have the specified
490 * composition and the mixture temperature and pressure.
491 *
492 * @param n Vector of doubles of length nSpecies containing the global
493 * mole numbers (kmol).
494 */
495 void setMoles(const doublereal* n);
496
497 //! Adds moles of a certain species to the mixture
498 /*!
499 * @param indexS Index of the species in the MultiPhase object
500 * @param addedMoles Value of the moles that are added to the species.
501 */
502 void addSpeciesMoles(const int indexS, const doublereal addedMoles);
503
504 //! Retrieves a vector of element abundances
505 /*!
506 * @param elemAbundances Vector of element abundances
507 * Length = number of elements in the MultiPhase object.
508 * Index is the global element index. Units is in kmol.
509 */
510 void getElemAbundances(doublereal* elemAbundances) const;
511
512 //! Return true if the phase \a p has valid thermo data for the current
513 //! temperature.
514 /*!
515 * @param p Index of the phase.
516 */
517 bool tempOK(size_t p) const;
518
519 // These methods are meant for internal use.
520
521 //! Update the locally-stored composition within this object to match the
522 //! current compositions of the phase objects.
523 /*!
524 * Query the underlying ThermoPhase objects for their mole fractions and
525 * fill in the mole fraction vector of this current object. Adjust element
526 * compositions within this object to match.
527 *
528 * This is an upload operation in the sense that we are taking downstream
529 * information (ThermoPhase object info) and applying it to an upstream
530 * object (MultiPhase object).
531 */
532 void uploadMoleFractionsFromPhases();
533
534 //! Set the states of the phase objects to the locally-stored
535 //! state within this MultiPhase object.
536 /*!
537 * This method sets each phase to the mixture temperature and pressure,
538 * and sets the phase mole fractions based on the mixture mole numbers.
539 *
540 * This is an download operation in the sense that we are taking upstream
541 * object information (MultiPhase object) and applying it to downstream
542 * objects (ThermoPhase object information)
543 *
544 * Therefore, the term, "update", is appropriate for a downstream operation.
545 */
546 void updatePhases() const;
547
548 private:
549 //! Calculate the element abundance vector
550 void calcElemAbundances() const;
551
552 //! Set the mixture to a state of chemical equilibrium using the
553 //! MultiPhaseEquil solver.
554 /*!
555 * @param XY Integer flag specifying properties to hold fixed.
556 * @param err Error tolerance for \f$\Delta \mu/RT \f$ for all reactions.
557 * Also used as the relative error tolerance for the outer loop.
558 * @param maxsteps Maximum number of steps to take in solving the fixed TP
559 * problem.
560 * @param maxiter Maximum number of "outer" iterations for problems holding
561 * fixed something other than (T,P).
562 * @param loglevel Level of diagnostic output
563 */
564 double equilibrate_MultiPhaseEquil(int XY, doublereal err, int maxsteps,
565 int maxiter, int loglevel);
566
567 //! Vector of the number of moles in each phase.
568 /*!
569 * Length = m_np, number of phases.
570 */
571 vector_fp m_moles;
572
573 //! Vector of the ThermoPhase pointers.
574 std::vector<ThermoPhase*> m_phase;
575
576 //! Global Stoichiometric Coefficient array
577 /*!
578 * This is a two dimensional array m_atoms(m, k). The first index is the
579 * global element index. The second index, k, is the global species index.
580 * The value is the number of atoms of type m in species k.
581 */
582 DenseMatrix m_atoms;
583
584 //! Locally stored vector of mole fractions of all species comprising the
585 //! MultiPhase object.
586 vector_fp m_moleFractions;
587
588 //! Mapping between the global species number and the phase ID
589 /*!
590 * m_spphase[kGlobal] = iPhase
591 * Length = number of global species
592 */
593 std::vector<size_t> m_spphase;
594
595 //! Vector of ints containing of first species index in the global list of
596 //! species for each phase
597 /*!
598 * kfirst = m_spstart[ip], kfirst is the index of the first species in
599 * the ip'th phase.
600 */
601 std::vector<size_t> m_spstart;
602
603 //! String names of the global elements. This has a length equal to the
604 //! number of global elements.
605 std::vector<std::string> m_enames;
606
607 //! Atomic number of each global element.
608 vector_int m_atomicNumber;
609
610 //! Vector of species names in the problem. Vector is over all species
611 //! defined in the object, the global species index.
612 std::vector<std::string> m_snames;
613
614 //! Returns the global element index, given the element string name
615 /*!
616 * -> used in the construction. However, wonder if it needs to be global.
617 */
618 std::map<std::string, size_t> m_enamemap;
619
620 //! Current value of the temperature (kelvin)
621 doublereal m_temp;
622
623 //! Current value of the pressure (Pa)
624 doublereal m_press;
625
626 //! Number of distinct elements in all of the phases
627 size_t m_nel;
628
629 //! Number of distinct species in all of the phases
630 size_t m_nsp;
631
632 //! True if the init() routine has been called, and the MultiPhase frozen
633 bool m_init;
634
635 //! Global ID of the element corresponding to the electronic charge. If
636 //! there is none, then this is equal to -1
637 size_t m_eloc;
638
639 //! Vector of bools indicating whether temperatures are ok for phases.
640 /*!
641 * If the current temperature is outside the range of valid temperatures
642 * for the phase thermodynamics, the phase flag is set to false.
643 */
644 mutable std::vector<bool> m_temp_OK;
645
646 //! Minimum temperature for which thermo parameterizations are valid.
647 //! Stoichiometric phases are ignored in this determination. units Kelvin
648 doublereal m_Tmin;
649
650 //! Minimum temperature for which thermo parameterizations are valid.
651 //! Stoichiometric phases are ignored in this determination. units Kelvin
652 doublereal m_Tmax;
653
654 //! Vector of element abundances
655 /*!
656 * m_elemAbundances[mGlobal] = kmol of element mGlobal summed over all
657 * species in all phases.
658 */
659 mutable vector_fp m_elemAbundances;
660};
661
662//! Function to output a MultiPhase description to a stream
663/*!
664 * Writes out a description of the contents of each phase of the
665 * MultiPhase using the report function.
666 *
667 * @param s ostream
668 * @param x Reference to a MultiPhase
669 * @returns a reference to the ostream
670 */
671std::ostream& operator<<(std::ostream& s, MultiPhase& x);
672
673//! Choose the optimum basis of species for the equilibrium calculations.
674/*!
675 * This is done by choosing the species with the largest mole fraction not
676 * currently a linear combination of the previous components. Then, calculate
677 * the stoichiometric coefficient matrix for that basis.
678 *
679 * Calculates the identity of the component species in the mechanism. Rearranges
680 * the solution data to put the component data at the front of the species list.
681 *
682 * Then, calculates SC(J,I) the formation reactions for all noncomponent
683 * species in the mechanism.
684 *
685 * @param[in] mphase Pointer to the multiphase object. Contains the species
686 * mole fractions, which are used to pick the current optimal species
687 * component basis.
688 * @param[in] orderVectorElements Order vector for the elements. The element
689 * rows in the formula matrix are rearranged according to this vector.
690 * @param[in] orderVectorSpecies Order vector for the species. The species are
691 * rearranged according to this formula. The first nComponents of this
692 * vector contain the calculated species components on exit.
693 * @param[in] doFormRxn If true, the routine calculates the formation
694 * reaction matrix based on the calculated component species. If
695 * false, this step is skipped.
696 * @param[out] usedZeroedSpecies = If true, then a species with a zero
697 * concentration was used as a component. The problem may be converged.
698 * @param[out] formRxnMatrix
699 * @return The number of components.
700 *
701 * @ingroup equilfunctions
702 */
703 size_t BasisOptimize(int* usedZeroedSpecies, bool doFormRxn,
704 MultiPhase* mphase, std::vector<size_t>& orderVectorSpecies,
705 std::vector<size_t>& orderVectorElements,
706 vector_fp& formRxnMatrix);
707
708//! Handles the potential rearrangement of the constraint equations
709//! represented by the Formula Matrix.
710/*!
711 * Rearrangement is only necessary when the number of components is less
712 * than the number of elements. For this case, some constraints can never
713 * be satisfied exactly, because the range space represented by the Formula
714 * Matrix of the components can't span the extra space. These constraints,
715 * which are out of the range space of the component Formula matrix
716 * entries, are migrated to the back of the Formula matrix.
717 *
718 * A prototypical example is an extra element column in FormulaMatrix[], which
719 * is identically zero. For example, let's say that argon is has an element
720 * column in FormulaMatrix[], but no species in the mechanism actually
721 * contains argon. Then, nc < ne. Unless the entry for desired element
722 * abundance vector for Ar is zero, then this element abundance constraint can
723 * never be satisfied. The constraint vector is not in the range space of the
724 * formula matrix.
725 *
726 * Also, without perturbation of FormulaMatrix[], BasisOptimize[] would
727 * produce a zero pivot because the matrix would be singular (unless the argon
728 * element column was already the last column of FormulaMatrix[].
729 *
730 * This routine borrows heavily from BasisOptimize algorithm. It finds nc
731 * constraints which span the range space of the Component Formula matrix, and
732 * assigns them as the first nc components in the formula matrix. This
733 * guarantees that BasisOptimize has a nonsingular matrix to invert.
734 *
735 * @param[in] nComponents Number of components calculated previously.
736 * @param[in] elementAbundances Current value of the element abundances
737 * @param[in] mphase Input pointer to a MultiPhase object
738 * @param[in] orderVectorSpecies input vector containing the ordering of the
739 * global species in mphase. This is used to extract the component
740 * basis of the mphase object.
741 * @param[out] orderVectorElements Output vector containing the order of the
742 * elements that is necessary for calculation of the formula matrix.
743 *
744 * @ingroup equilfunctions
745 */
746 void ElemRearrange(size_t nComponents, const vector_fp& elementAbundances,
747 MultiPhase* mphase,
748 std::vector<size_t>& orderVectorSpecies,
749 std::vector<size_t>& orderVectorElements);
750
751//! External int that is used to turn on debug printing for the
752//! BasisOptimize program.
753/*!
754 * Set this to 1 if you want debug printing from BasisOptimize.
755 */
756 extern int BasisOptimize_print_lvl;
757}
758
759#endif
DenseMatrix.h
Headers for the DenseMatrix object, which deals with dense rectangular matrices and description of th...
Cantera::DenseMatrix
A class for full (non-sparse) matrices with Fortran-compatible data storage, which adds matrix operat...
Definition: DenseMatrix.h:51
Cantera::MultiPhase
A class for multiphase mixtures.
Definition: MultiPhase.h:60
Cantera::MultiPhase::maxTemp
doublereal maxTemp() const
Maximum temperature for which all solution phases have valid thermo data.
Definition: MultiPhase.h:256
Cantera::MultiPhase::init
void init()
Process phases and build atomic composition array.
Definition: MultiPhase.cpp:118
Cantera::MultiPhase::getMoleFractions
void getMoleFractions(doublereal *const x) const
Returns the global Species mole fractions.
Definition: MultiPhase.cpp:771
Cantera::MultiPhase::setState_TPMoles
void setState_TPMoles(const doublereal T, const doublereal Pres, const doublereal *Moles)
Set the state of the underlying ThermoPhase objects in one call.
Definition: MultiPhase.cpp:436
Cantera::MultiPhase::checkPhaseIndex
void checkPhaseIndex(size_t m) const
Check that the specified phase index is in range Throws an exception if m is greater than nPhases()
Definition: MultiPhase.cpp:172
Cantera::MultiPhase::speciesIndex
size_t speciesIndex(size_t k, size_t p) const
Return the global index of the species belonging to phase number p with local index k within the phas...
Definition: MultiPhase.h:229
Cantera::MultiPhase::solutionSpecies
bool solutionSpecies(size_t kGlob) const
Return true is species kGlob is a species in a multicomponent solution phase.
Definition: MultiPhase.cpp:273
Cantera::MultiPhase::m_press
doublereal m_press
Current value of the pressure (Pa)
Definition: MultiPhase.h:624
Cantera::MultiPhase::setMoles
void setMoles(const doublereal *n)
Sets all of the global species mole numbers.
Definition: MultiPhase.cpp:387
Cantera::MultiPhase::m_atoms
DenseMatrix m_atoms
Global Stoichiometric Coefficient array.
Definition: MultiPhase.h:582
Cantera::MultiPhase::getMoles
void getMoles(doublereal *molNum) const
Get the mole numbers of all species in the multiphase object.
Definition: MultiPhase.cpp:372
Cantera::MultiPhase::checkSpeciesIndex
void checkSpeciesIndex(size_t k) const
Check that the specified species index is in range.
Definition: MultiPhase.cpp:747
Cantera::MultiPhase::m_nel
size_t m_nel
Number of distinct elements in all of the phases.
Definition: MultiPhase.h:627
Cantera::MultiPhase::m_moleFractions
vector_fp m_moleFractions
Locally stored vector of mole fractions of all species comprising the MultiPhase object.
Definition: MultiPhase.h:586
Cantera::MultiPhase::minTemp
doublereal minTemp() const
Minimum temperature for which all solution phases have valid thermo data.
Definition: MultiPhase.h:249
Cantera::MultiPhase::equilibrate_MultiPhaseEquil
double equilibrate_MultiPhaseEquil(int XY, doublereal err, int maxsteps, int maxiter, int loglevel)
Set the mixture to a state of chemical equilibrium using the MultiPhaseEquil solver.
Definition: MultiPhase.cpp:484
Cantera::MultiPhase::calcElemAbundances
void calcElemAbundances() const
Calculate the element abundance vector.
Definition: MultiPhase.cpp:452
Cantera::MultiPhase::nSpecies
size_t nSpecies() const
Number of species, summed over all phases.
Definition: MultiPhase.h:126
Cantera::MultiPhase::gibbs
doublereal gibbs() const
The Gibbs function of the mixture [J].
Definition: MultiPhase.cpp:282
Cantera::MultiPhase::cp
doublereal cp() const
Heat capacity at constant pressure [J/K].
Definition: MultiPhase.cpp:330
Cantera::MultiPhase::pressure
doublereal pressure() const
Pressure [Pa].
Definition: MultiPhase.h:391
Cantera::MultiPhase::enthalpy
doublereal enthalpy() const
The enthalpy of the mixture [J].
Definition: MultiPhase.cpp:294
Cantera::MultiPhase::m_enamemap
std::map< std::string, size_t > m_enamemap
Returns the global element index, given the element string name.
Definition: MultiPhase.h:618
Cantera::MultiPhase::speciesMoles
doublereal speciesMoles(size_t kGlob) const
Returns the moles of global species k. units = kmol.
Definition: MultiPhase.cpp:186
Cantera::MultiPhase::addSpeciesMoles
void addSpeciesMoles(const int indexS, const doublereal addedMoles)
Adds moles of a certain species to the mixture.
Definition: MultiPhase.cpp:417
Cantera::MultiPhase::m_temp
doublereal m_temp
Current value of the temperature (kelvin)
Definition: MultiPhase.h:621
Cantera::MultiPhase::IntEnergy
doublereal IntEnergy() const
The internal energy of the mixture [J].
Definition: MultiPhase.cpp:306
Cantera::MultiPhase::checkPhaseArraySize
void checkPhaseArraySize(size_t mm) const
Check that an array size is at least nPhases() Throws an exception if mm is less than nPhases().
Definition: MultiPhase.cpp:179
Cantera::MultiPhase::m_elemAbundances
vector_fp m_elemAbundances
Vector of element abundances.
Definition: MultiPhase.h:659
Cantera::MultiPhase::m_spstart
std::vector< size_t > m_spstart
Vector of ints containing of first species index in the global list of species for each phase.
Definition: MultiPhase.h:601
Cantera::MultiPhase::m_Tmax
doublereal m_Tmax
Minimum temperature for which thermo parameterizations are valid.
Definition: MultiPhase.h:652
Cantera::MultiPhase::m_Tmin
doublereal m_Tmin
Minimum temperature for which thermo parameterizations are valid.
Definition: MultiPhase.h:648
Cantera::MultiPhase::m_moles
vector_fp m_moles
Vector of the number of moles in each phase.
Definition: MultiPhase.h:571
Cantera::MultiPhase::nPhases
size_t nPhases() const
Number of phases.
Definition: MultiPhase.h:428
Cantera::MultiPhase::m_eloc
size_t m_eloc
Global ID of the element corresponding to the electronic charge.
Definition: MultiPhase.h:637
Cantera::MultiPhase::moleFraction
doublereal moleFraction(const size_t kGlob) const
Returns the mole fraction of global species k.
Definition: MultiPhase.cpp:806
Cantera::MultiPhase::phaseMoles
doublereal phaseMoles(const size_t n) const
Return the number of moles in phase n.
Definition: MultiPhase.cpp:791
Cantera::MultiPhase::m_spphase
std::vector< size_t > m_spphase
Mapping between the global species number and the phase ID.
Definition: MultiPhase.h:593
Cantera::MultiPhase::m_snames
std::vector< std::string > m_snames
Vector of species names in the problem.
Definition: MultiPhase.h:612
Cantera::MultiPhase::speciesName
std::string speciesName(const size_t kGlob) const
Name of species with global index kGlob.
Definition: MultiPhase.cpp:761
Cantera::MultiPhase::m_atomicNumber
vector_int m_atomicNumber
Atomic number of each global element.
Definition: MultiPhase.h:608
Cantera::MultiPhase::elementIndex
size_t elementIndex(const std::string &name) const
Returns the index of the element with name name.
Definition: MultiPhase.cpp:737
Cantera::MultiPhase::tempOK
bool tempOK(size_t p) const
Return true if the phase p has valid thermo data for the current temperature.
Definition: MultiPhase.cpp:811
Cantera::MultiPhase::elementName
std::string elementName(size_t m) const
Returns the name of the global element m.
Definition: MultiPhase.cpp:732
Cantera::MultiPhase::nAtoms
doublereal nAtoms(const size_t kGlob, const size_t mGlob) const
Returns the Number of atoms of global element mGlob in global species kGlob.
Definition: MultiPhase.cpp:766
Cantera::MultiPhase::checkElementArraySize
void checkElementArraySize(size_t mm) const
Check that an array size is at least nElements().
Definition: MultiPhase.cpp:725
Cantera::MultiPhase::speciesPhaseIndex
size_t speciesPhaseIndex(const size_t kGlob) const
Returns the phase index of the Kth "global" species.
Definition: MultiPhase.cpp:801
Cantera::MultiPhase::addPhases
void addPhases(std::vector< ThermoPhase * > &phases, const vector_fp &phaseMoles)
Add a vector of phases to the mixture.
Definition: MultiPhase.cpp:42
Cantera::MultiPhase::m_enames
std::vector< std::string > m_enames
String names of the global elements.
Definition: MultiPhase.h:605
Cantera::MultiPhase::setPressure
void setPressure(doublereal P)
Set the pressure [Pa].
Definition: MultiPhase.h:406
Cantera::MultiPhase::elementMoles
doublereal elementMoles(size_t m) const
Total moles of global element m, summed over all phases.
Definition: MultiPhase.cpp:192
Cantera::MultiPhase::setPhaseMoleFractions
void setPhaseMoleFractions(const size_t n, const doublereal *const x)
Set the Mole fractions of the nth phase.
Definition: MultiPhase.cpp:342
Cantera::MultiPhase::charge
doublereal charge() const
Total charge summed over all phases (Coulombs).
Definition: MultiPhase.cpp:207
Cantera::MultiPhase::phaseName
std::string phaseName(const size_t iph) const
Returns the name of the n'th phase.
Definition: MultiPhase.cpp:776
Cantera::MultiPhase::getValidChemPotentials
void getValidChemPotentials(doublereal not_mu, doublereal *mu, bool standard=false) const
Returns a vector of Valid chemical potentials.
Definition: MultiPhase.cpp:253
Cantera::MultiPhase::setState_TP
void setState_TP(const doublereal T, const doublereal Pres)
Set the state of the underlying ThermoPhase objects in one call.
Definition: MultiPhase.cpp:426
Cantera::MultiPhase::entropy
doublereal entropy() const
The entropy of the mixture [J/K].
Definition: MultiPhase.cpp:318
Cantera::MultiPhase::setMolesByName
void setMolesByName(const compositionMap &xMap)
Set the number of moles of species in the mixture.
Definition: MultiPhase.cpp:355
Cantera::MultiPhase::m_nsp
size_t m_nsp
Number of distinct species in all of the phases.
Definition: MultiPhase.h:630
Cantera::MultiPhase::uploadMoleFractionsFromPhases
void uploadMoleFractionsFromPhases()
Update the locally-stored composition within this object to match the current compositions of the pha...
Definition: MultiPhase.cpp:816
Cantera::MultiPhase::m_init
bool m_init
True if the init() routine has been called, and the MultiPhase frozen.
Definition: MultiPhase.h:633
Cantera::MultiPhase::volume
doublereal volume() const
The total mixture volume [m^3].
Definition: MultiPhase.cpp:474
Cantera::MultiPhase::updatePhases
void updatePhases() const
Set the states of the phase objects to the locally-stored state within this MultiPhase object.
Definition: MultiPhase.cpp:827
Cantera::MultiPhase::setPhaseMoles
void setPhaseMoles(const size_t n, const doublereal moles)
Set the number of moles of phase with index n.
Definition: MultiPhase.cpp:796
Cantera::MultiPhase::checkSpeciesArraySize
void checkSpeciesArraySize(size_t kk) const
Check that an array size is at least nSpecies().
Definition: MultiPhase.cpp:754
Cantera::MultiPhase::getElemAbundances
void getElemAbundances(doublereal *elemAbundances) const
Retrieves a vector of element abundances.
Definition: MultiPhase.cpp:444
Cantera::MultiPhase::temperature
doublereal temperature() const
Temperature [K].
Definition: MultiPhase.h:331
Cantera::MultiPhase::nElements
size_t nElements() const
Number of elements.
Definition: MultiPhase.h:100
Cantera::MultiPhase::~MultiPhase
virtual ~MultiPhase()
Destructor.
Definition: MultiPhase.h:71
Cantera::MultiPhase::m_temp_OK
std::vector< bool > m_temp_OK
Vector of bools indicating whether temperatures are ok for phases.
Definition: MultiPhase.h:644
Cantera::MultiPhase::phaseIndex
int phaseIndex(const std::string &pName) const
Returns the index, given the phase name.
Definition: MultiPhase.cpp:781
Cantera::MultiPhase::m_phase
std::vector< ThermoPhase * > m_phase
Vector of the ThermoPhase pointers.
Definition: MultiPhase.h:574
Cantera::MultiPhase::MultiPhase
MultiPhase()
Constructor.
Definition: MultiPhase.cpp:23
Cantera::MultiPhase::addPhase
void addPhase(ThermoPhase *p, doublereal moles)
Add a phase to the mixture.
Definition: MultiPhase.cpp:51
Cantera::MultiPhase::getChemPotentials
void getChemPotentials(doublereal *mu) const
Returns a vector of Chemical potentials.
Definition: MultiPhase.cpp:243
Cantera::MultiPhase::checkElementIndex
void checkElementIndex(size_t m) const
Check that the specified element index is in range.
Definition: MultiPhase.cpp:718
Cantera::MultiPhase::phaseCharge
doublereal phaseCharge(size_t p) const
Charge (Coulombs) of phase with index p.
Definition: MultiPhase.cpp:232
Cantera::MultiPhase::phase
ThermoPhase & phase(size_t n)
Return a reference to phase n.
Definition: MultiPhase.cpp:161
Cantera::MultiPhase::setTemperature
void setTemperature(const doublereal T)
Set the temperature [K].
Definition: MultiPhase.cpp:709
Cantera::ThermoPhase
Base class for a phase with thermodynamic properties.
Definition: ThermoPhase.h:102
Cantera::BasisOptimize
size_t BasisOptimize(int *usedZeroedSpecies, bool doFormRxn, MultiPhase *mphase, std::vector< size_t > &orderVectorSpecies, std::vector< size_t > &orderVectorElements, vector_fp &formRxnMatrix)
Choose the optimum basis of species for the equilibrium calculations.
Definition: BasisOptimize.cpp:20
Cantera::ElemRearrange
void ElemRearrange(size_t nComponents, const vector_fp &elementAbundances, MultiPhase *mphase, std::vector< size_t > &orderVectorSpecies, std::vector< size_t > &orderVectorElements)
Handles the potential rearrangement of the constraint equations represented by the Formula Matrix.
Definition: BasisOptimize.cpp:294
Cantera::MultiPhase::equilibrate
void equilibrate(const std::string &XY, const std::string &solver="auto", double rtol=1e-9, int max_steps=50000, int max_iter=100, int estimate_equil=0, int log_level=0)
Equilibrate a MultiPhase object.
Definition: MultiPhase.cpp:645
Cantera
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:557
Cantera::vector_int
std::vector< int > vector_int
Vector of ints.
Definition: ct_defs.h:186
Cantera::vector_fp
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:184
Cantera::BasisOptimize_print_lvl
int BasisOptimize_print_lvl
External int that is used to turn on debug printing for the BasisOptimize program.
Definition: BasisOptimize.cpp:17
Cantera::operator<<
std::ostream & operator<<(std::ostream &s, const Array2D &m)
Output the current contents of the Array2D object.
Definition: Array.cpp:106
Cantera::compositionMap
std::map< std::string, double > compositionMap
Map connecting a string name with a double.
Definition: ct_defs.h:176