Cantera 2.6.0

Classes | Functions
Classes and functions used for calculating

chemical equilibrium. More...

## Classes
class | MultiPhase
| A class for multiphase mixtures. More...
class | vcs_MultiPhaseEquil
| Cantera's Interface to the Multiphase chemical equilibrium solver. More...

## Functions
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. More...
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. More...
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. More...

## Chemical Equilibrium
Chemical equilibrium.
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 ThermoPhase object. More...
virtual void | setToEquilState (const doublereal *mu_RT)
| This method is used by the ChemEquil equilibrium solver. More...
virtual bool | compatibleWithMultiPhase () const
| Indicates whether this phase type can be used with class MultiPhase for equilibrium calculations. More...

## Detailed Description

chemical equilibrium.

## Function Documentation

## ◆ equilibrate() [1/2]

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.

Set this mixture to chemical equilibrium by calling one of Cantera's equilibrium solvers. The XY parameter indicates what two thermodynamic quantities are to be held constant during the equilibration process.

Parameters

  XY | String representation of what two properties are being held constant
  solver | Name of the solver to be used to equilibrate the phase. If solver = 'vcs', the vcs_MultiPhaseEquil solver will be used. If solver = 'gibbs', the MultiPhaseEquil solver will be used. If solver = 'auto', the 'vcs' solver will be tried first, followed by the 'gibbs' solver if the first one fails.
  rtol | Relative tolerance
  max_steps | Maximum number of steps to take to find the solution
  max_iter | The maximum number of outer temperature or pressure iterations to take when T and/or P is not held fixed.
  estimate_equil | integer indicating whether the solver should estimate its own initial condition. If 0, the initial mole fraction vector in the ThermoPhase object is used as the initial condition. If 1, the initial mole fraction vector is used if the element abundances are satisfied. If -1, the initial mole fraction vector is thrown out, and an estimate is formulated.
  log_level | loglevel Controls amount of diagnostic output. log_level=0 suppresses diagnostics, and increasingly-verbose messages are written as loglevel increases.

Definition at line 645 of file MultiPhase.cpp.

References Cantera::_equilflag(), Cantera::debuglog(), vcs_MultiPhaseEquil::equilibrate(), MultiPhase::equilibrate_MultiPhaseEquil(), MultiPhase::m_moleFractions, MultiPhase::m_moles, MultiPhase::m_press, MultiPhase::m_temp, and MultiPhase::updatePhases().

## ◆ 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.

This is done by choosing the species with the largest mole fraction not currently a linear combination of the previous components. Then, calculate the stoichiometric coefficient matrix for that basis.

Calculates the identity of the component species in the mechanism. Rearranges the solution data to put the component data at the front of the species list.

Then, calculates SC(J,I) the formation reactions for all noncomponent species in the mechanism.

Parameters

  [in] | mphase | Pointer to the multiphase object. Contains the species mole fractions, which are used to pick the current optimal species component basis.
  [in] | orderVectorElements | Order vector for the elements. The element rows in the formula matrix are rearranged according to this vector.
  [in] | orderVectorSpecies | Order vector for the species. The species are rearranged according to this formula. The first nComponents of this vector contain the calculated species components on exit.
  [in] | doFormRxn | If true, the routine calculates the formation reaction matrix based on the calculated component species. If false, this step is skipped.
  [out] | usedZeroedSpecies | = If true, then a species with a zero concentration was used as a component. The problem may be converged.
  [out] | formRxnMatrix |

Returns
  The number of components.

Definition at line 20 of file BasisOptimize.cpp.

References Cantera::BasisOptimize_print_lvl, Array2D::data(), MultiPhase::elementName(), MultiPhase::getMoles(), MultiPhase::nAtoms(), MultiPhase::nElements(), Cantera::npos, MultiPhase::nSpecies(), DenseMatrix::resize(), Cantera::solve(), MultiPhase::speciesName(), Cantera::writelog(), and Cantera::writelogf().

Referenced by ChemEquil::estimateElementPotentials().

## ◆ 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.

Rearrangement is only necessary when the number of components is less than the number of elements. For this case, some constraints can never be satisfied exactly, because the range space represented by the Formula Matrix of the components can't span the extra space. These constraints, which are out of the range space of the component Formula matrix entries, are migrated to the back of the Formula matrix.

A prototypical example is an extra element column in FormulaMatrix[], which is identically zero. For example, let's say that argon is has an element column in FormulaMatrix[], but no species in the mechanism actually contains argon. Then, nc < ne. Unless the entry for desired element abundance vector for Ar is zero, then this element abundance constraint can never be satisfied. The constraint vector is not in the range space of the formula matrix.

Also, without perturbation of FormulaMatrix[], BasisOptimize[] would produce a zero pivot because the matrix would be singular (unless the argon element column was already the last column of FormulaMatrix[].

This routine borrows heavily from BasisOptimize algorithm. It finds nc constraints which span the range space of the Component Formula matrix, and assigns them as the first nc components in the formula matrix. This guarantees that BasisOptimize has a nonsingular matrix to invert.

Parameters

  [in] | nComponents | Number of components calculated previously.
  [in] | elementAbundances | Current value of the element abundances
  [in] | mphase | Input pointer to a MultiPhase object
  [in] | orderVectorSpecies | input vector containing the ordering of the global species in mphase. This is used to extract the component basis of the mphase object.
  [out] | orderVectorElements | Output vector containing the order of the elements that is necessary for calculation of the formula matrix.

Definition at line 294 of file BasisOptimize.cpp.

References Cantera::BasisOptimize_print_lvl, MultiPhase::elementName(), MultiPhase::nAtoms(), MultiPhase::nElements(), MultiPhase::nSpecies(), Cantera::writelog(), and Cantera::writelogf().

Referenced by ChemEquil::estimateElementPotentials().

## ◆ equilibrate() [2/2]

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 ThermoPhase object.

Set this phase to chemical equilibrium by calling one of several equilibrium solvers. The XY parameter indicates what two thermodynamic quantities are to be held constant during the equilibration process.

Parameters

  XY | String representation of what two properties are being held constant
  solver | Name of the solver to be used to equilibrate the phase. If solver = 'element_potential', the ChemEquil element potential solver will be used. If solver = 'vcs', the VCS solver will be used. If solver = 'gibbs', the MultiPhaseEquil solver will be used. If solver = 'auto', the solvers will be tried in order if the initial solver(s) fail.
  rtol | Relative tolerance
  max_steps | Maximum number of steps to take to find the solution
  max_iter | For the 'gibbs' and 'vcs' solvers, this is the maximum number of outer temperature or pressure iterations to take when T and/or P is not held fixed.
  estimate_equil | For MultiPhaseEquil solver, an integer indicating whether the solver should estimate its own initial condition. If 0, the initial mole fraction vector in the ThermoPhase object is used as the initial condition. If 1, the initial mole fraction vector is used if the element abundances are satisfied. If -1, the initial mole fraction vector is thrown out, and an estimate is formulated.
  log_level | loglevel Controls amount of diagnostic output. log_level=0 suppresses diagnostics, and increasingly-verbose messages are written as loglevel increases.

Definition at line 1308 of file ThermoPhase.cpp.

References Cantera::debuglog(), and Phase::saveState().

## ◆ setToEquilState()

virtual void setToEquilState | ( | const doublereal * | mu_RT | ) |
| inline virtual

This method is used by the ChemEquil equilibrium solver.

It sets the state such that the chemical potentials satisfy

\[ \frac{\mu_k}{\hat R T} = \sum_m A_{k,m} \left(\frac{\lambda_m} {\hat R T}\right) \]

where \( \lambda_m \) is the element potential of element m. The temperature is unchanged. Any phase (ideal or not) that implements this method can be equilibrated by ChemEquil.

Parameters

  mu_RT | Input vector of dimensionless chemical potentials The length is equal to nSpecies().

Reimplemented in IdealSolnGasVPSS, IdealGasPhase, and IdealSolidSolnPhase.

Definition at line 1466 of file ThermoPhase.h.

Referenced by ChemEquil::setToEquilState().

## ◆ compatibleWithMultiPhase()

virtual bool compatibleWithMultiPhase | ( |  | ) | const
| inline virtual

Indicates whether this phase type can be used with class MultiPhase for equilibrium calculations.

Returns `false` for special phase types which already represent multi-phase mixtures, namely PureFluidPhase.

Reimplemented in PureFluidPhase, and WaterSSTP.

Definition at line 1473 of file ThermoPhase.h.

Referenced by MultiPhase::addPhase().