Cantera
2.2.1

Classes  
class  MultiPhase 
A class for multiphase mixtures. More...  
class  vcs_MultiPhaseEquil 
Cantera's Interface to the Multiphase chemical equilibrium solver. More...  
Functions  
int  equilibrate (thermo_t &s, const char *XY, int solver=1, doublereal rtol=1.0e9, int maxsteps=VCS_MAXSTEPS, int maxiter=100, int loglevel=99) 
Equilibrate a ThermoPhase object. More...  
doublereal  equilibrate (MultiPhase &s, const char *XY, doublereal rtol=1.0e9, int maxsteps=5000, int maxiter=100, int loglevel=99) 
Equilibrate a MultiPhase object. More...  
void  equilibrate (const std::string &XY, const std::string &solver="auto", double rtol=1e9, 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...  
size_t  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...  
int  vcs_equilibrate (thermo_t &s, const char *XY, int estimateEquil=0, int printLvl=0, int solver=1, doublereal rtol=1.0e9, int maxsteps=VCS_MAXSTEPS, int maxiter=100, int loglevel=99) 
Set a singlephase chemical solution to chemical equilibrium. More...  
int  vcs_equilibrate (MultiPhase &s, const char *XY, int estimateEquil=0, int printLvl=0, int solver=2, doublereal rtol=1.0e9, int maxsteps=VCS_MAXSTEPS, int maxiter=100, int loglevel=99) 
Set a multiphase chemical solution to chemical equilibrium. More...  
int  vcs_equilibrate_1 (MultiPhase &s, int ixy, int estimateEquil=0, int printLvl=0, int solver=2, doublereal rtol=1.0e9, int maxsteps=VCS_MAXSTEPS, int maxiter=100, int loglevel=99) 
Set a multiphase chemical solution to chemical equilibrium. More...  
Chemical Equilibrium  
void  equilibrate (const std::string &XY, const std::string &solver="auto", double rtol=1e9, 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 *lambda_RT) 
This method is used by the ChemEquil equilibrium solver. More...  
void  setElementPotentials (const vector_fp &lambda) 
Stores the element potentials in the ThermoPhase object. More...  
bool  getElementPotentials (doublereal *lambda) const 
Returns the element potentials stored in the ThermoPhase object. More...  
Cantera has several different equilibrium routines.
int equilibrate  (  thermo_t &  s, 
const char *  XY,  
int  solver = 1 , 

doublereal  rtol = 1.0e9 , 

int  maxsteps = VCS_MAXSTEPS , 

int  maxiter = 100 , 

int  loglevel = 99 

) 
Equilibrate a ThermoPhase object.
Set a singlephase chemical solution to chemical equilibrium. This is a convenience function that uses one or the other of the two chemical equilibrium solvers. The XY parameter indicates what two thermodynamic quantities, other than element composition, are to be held constant during the equilibration process.
s  ThermoPhase object that will be equilibrated. 
XY  String representation of what two properties are being held constant 
solver  ID of the solver to be used to equilibrate the phase. If solver = 0, the ChemEquil solver will be used, and if solver = 1, the MultiPhaseEquil solver will be used (slower than ChemEquil, but more stable). If solver < 0 (default, then ChemEquil will be tried first, and if it fails MultiPhaseEquil will be tried. 
rtol  Relative tolerance 
maxsteps  Maximum number of steps to take to find the solution 
maxiter  For the MultiPhaseEquil solver only, this is the maximum number of outer temperature or pressure iterations to take when T and/or P is not held fixed. 
loglevel  loglevel Controls amount of diagnostic output. loglevel = 0 suppresses diagnostics, and increasinglyverbose messages are written as loglevel increases. 
Definition at line 34 of file equilibrate.cpp.
References MultiPhase::addPhase(), Cantera::equilibrate(), ChemEquil::equilibrate(), MultiPhase::init(), EquilOpt::maxIterations, ChemEquil::options, EquilOpt::relTolerance, CanteraError::save(), ThermoPhase::setElementPotentials(), Cantera::vcs_equilibrate(), and Cantera::warn_deprecated().
doublereal equilibrate  (  MultiPhase &  s, 
const char *  XY,  
doublereal  rtol = 1.0e9 , 

int  maxsteps = 5000 , 

int  maxiter = 100 , 

int  loglevel = 99 

) 
Equilibrate a MultiPhase object.
Equilibrate a MultiPhase object. The XY parameter indicates what two thermodynamic quantities, other than element composition, are to be held constant during the equilibration process.
This is the toplevel driver for multiphase equilibrium. It doesn't do much more than call the equilibrate method of class MultiPhase, except that it adds some messages to the logfile, if loglevel is set > 0.
s  MultiPhase object that will be equilibrated. 
XY  String representation of what is being held constant 
rtol  Relative tolerance 
maxsteps  Maximum number of steps 
maxiter  Maximum iterations 
loglevel  loglevel 
Definition at line 11 of file equilibrate.cpp.
References Cantera::_equilflag(), MultiPhase::equilibrate(), MultiPhase::init(), CanteraError::save(), and Cantera::warn_deprecated().
Referenced by Cantera::equilibrate(), and Cantera::vcs_equilibrate().
void equilibrate  (  const std::string &  XY, 
const std::string &  solver = "auto" , 

double  rtol = 1e9 , 

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.
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 increasinglyverbose messages are written as loglevel increases. 
Definition at line 757 of file MultiPhase.cpp.
References Cantera::_equilflag(), vcs_MultiPhaseEquil::equilibrate(), MultiPhase::equilibrate_MultiPhaseEquil(), Cantera::int2str(), MultiPhase::m_moleFractions, MultiPhase::m_moles, MultiPhase::m_press, MultiPhase::m_temp, MultiPhase::updatePhases(), and Cantera::writelog().
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.
[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 nCompoments 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 
Definition at line 28 of file BasisOptimize.cpp.
References Cantera::BasisOptimize_print_lvl, DATA_PTR, MultiPhase::elementName(), MultiPhase::getMoles(), MultiPhase::nAtoms(), MultiPhase::nElements(), Cantera::npos, MultiPhase::nSpecies(), print_stringTrunc(), MultiPhase::speciesName(), Cantera::writelog(), and Cantera::writelogf().
Referenced by ChemEquil::estimateElementPotentials().
size_t 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.
[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 424 of file BasisOptimize.cpp.
References Cantera::BasisOptimize_print_lvl, MultiPhase::elementName(), MultiPhase::nAtoms(), MultiPhase::nElements(), Cantera::npos, MultiPhase::nSpecies(), Cantera::writelog(), and Cantera::writelogf().
Referenced by ChemEquil::estimateElementPotentials().
int vcs_equilibrate  (  thermo_t &  s, 
const char *  XY,  
int  estimateEquil = 0 , 

int  printLvl = 0 , 

int  solver = 1 , 

doublereal  rtol = 1.0e9 , 

int  maxsteps = VCS_MAXSTEPS , 

int  maxiter = 100 , 

int  loglevel = 99 

) 
Set a singlephase chemical solution to chemical equilibrium.
The function uses the element abundance vector that is currently consistent with the composition within the phase itself. Two other thermodynamic quantities, determined by the XY string, are held constant during the equilibration. This is a convenience function that uses one or the other of the two chemical equilibrium solvers.
s  The object to set to an equilibrium state 
XY  An integer specifying the two properties to be held constant. 
estimateEquil  integer indicating whether the solver should estimate its own initial condition.

printLvl  Determines the amount of printing that gets sent to stdout from the vcs package (Note, you may have to compile with debug flags to get some printing). 
solver  The equilibrium solver to use. If solver = 0, the ChemEquil solver will be used, and if solver = 1, the vcs_MultiPhaseEquil solver will be used (slower than ChemEquil, but more stable). If solver < 0 (default, then ChemEquil will be tried first, and if it fails vcs_MultiPhaseEquil will be tried. 
rtol  Relative tolerance of the solve. Defaults to 1.0E9. 
maxsteps  The maximum number of steps to take to find the solution. 
maxiter  For the MultiPhaseEquil solver only, this is the maximum number of outer temperature or pressure iterations to take when T and/or P is not held fixed. 
loglevel  Controls amount of diagnostic output. loglevel = 0 suppresses diagnostics, and increasinglyverbose messages are written as loglevel increases. 
Definition at line 20 of file vcs_equilibrate.cpp.
References MultiPhase::addPhase(), Cantera::equilibrate(), ChemEquil::equilibrate(), MultiPhase::init(), EquilOpt::maxIterations, ChemEquil::options, EquilOpt::relTolerance, CanteraError::save(), ThermoPhase::setElementPotentials(), Cantera::vcs_equilibrate(), and Cantera::warn_deprecated().
Referenced by Cantera::equilibrate().
int vcs_equilibrate  (  MultiPhase &  s, 
const char *  XY,  
int  estimateEquil = 0 , 

int  printLvl = 0 , 

int  solver = 2 , 

doublereal  rtol = 1.0e9 , 

int  maxsteps = VCS_MAXSTEPS , 

int  maxiter = 100 , 

int  loglevel = 99 

) 
Set a multiphase chemical solution to chemical equilibrium.
This function uses the vcs_MultiPhaseEquil interface to the vcs solver. The function uses the element abundance vector that is currently consistent with the composition within the phases themselves. Two other thermodynamic quantities, determined by the XY string, are held constant during the equilibration.
s  The object to set to an equilibrium state 
XY  A character string representing the unknowns to be held constant 
estimateEquil  integer indicating whether the solver should estimate its own initial condition.

printLvl  Determines the amount of printing that gets sent to stdout from the vcs package (Note, you may have to compile with debug flags to get some printing). 
solver  Determines which solver is used.

rtol  Relative tolerance of the solve. Defaults to 1.0E9. 
maxsteps  The maximum number of steps to take to find the solution. 
maxiter  For the MultiPhaseEquil solver only, this is the maximum number of outer temperature or pressure iterations to take when T and/or P is not held fixed. 
loglevel  Controls amount of diagnostic output. loglevel = 0 suppresses diagnostics, and increasinglyverbose messages are written as loglevel increases. 
Definition at line 97 of file vcs_equilibrate.cpp.
References Cantera::_equilflag(), and Cantera::vcs_equilibrate_1().
Referenced by Cantera::vcs_equilibrate().
int vcs_equilibrate_1  (  MultiPhase &  s, 
int  ixy,  
int  estimateEquil = 0 , 

int  printLvl = 0 , 

int  solver = 2 , 

doublereal  rtol = 1.0e9 , 

int  maxsteps = VCS_MAXSTEPS , 

int  maxiter = 100 , 

int  loglevel = 99 

) 
Set a multiphase chemical solution to chemical equilibrium.
This function uses the vcs_MultiPhaseEquil interface to the vcs solver. The function uses the element abundance vector that is currently consistent with the composition within the phases themselves. Two other thermodynamic quantities, determined by the XY string, are held constant during the equilibration.
s  The MultiPhase object to be set to an equilibrium state 
ixy  An integer specifying the two properties to be held constant. 
estimateEquil  integer indicating whether the solver should estimate its own initial condition.

printLvl  Determines the amount of printing that gets sent to stdout from the vcs package (Note, you may have to compile with debug flags to get some printing). 
solver  Determines which solver is used.

rtol  Relative tolerance of the solve. Defaults to 1.0E9. 
maxsteps  The maximum number of steps to take to find the solution. 
maxiter  For the MultiPhaseEquil solver only, this is the maximum number of outer temperature or pressure iterations to take when T and/or P is not held fixed. 
loglevel  Controls amount of diagnostic output. loglevel = 0 suppresses diagnostics, and increasinglyverbose messages are written as loglevel increases. 
Definition at line 108 of file vcs_equilibrate.cpp.
References vcs_MultiPhaseEquil::equilibrate(), MultiPhase::equilibrate(), MultiPhase::init(), Cantera::int2str(), vcs_MultiPhaseEquil::reportCSV(), CanteraError::save(), and Cantera::warn_deprecated().
Referenced by Cantera::vcs_equilibrate().
void equilibrate  (  const std::string &  XY, 
const std::string &  solver = "auto" , 

double  rtol = 1e9 , 

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.
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  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 increasinglyverbose messages are written as loglevel increases. 
Definition at line 748 of file ThermoPhase.cpp.
References MultiPhase::addPhase(), ChemEquil::equilibrate(), MultiPhase::equilibrate(), MultiPhase::init(), Cantera::int2str(), EquilOpt::maxIterations, ChemEquil::options, EquilOpt::relTolerance, Phase::restoreState(), Phase::saveState(), ThermoPhase::setElementPotentials(), and Cantera::writelog().

inlinevirtual 
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.
lambda_RT  Input vector of dimensionless element potentials The length is equal to nElements(). 
Reimplemented in HMWSoln, DebyeHuckel, IdealGasPhase, IdealSolidSolnPhase, MolalityVPSSTP, IdealMolalSoln, RedlichKwongMFTP, IdealSolnGasVPSS, and ConstDensityThermo.
Definition at line 1186 of file ThermoPhase.h.
Referenced by ChemEquil::setToEquilState().
void setElementPotentials  (  const vector_fp &  lambda  ) 
Stores the element potentials in the ThermoPhase object.
Called by the ChemEquil equilibrium solver to transfer the element potentials to this object after every successful equilibration routine. The element potentials are stored in their dimensionless forms, calculated by dividing by RT.
lambda  Input vector containing the element potentials. Length = nElements. Units are Joules/kmol. 
Definition at line 796 of file ThermoPhase.cpp.
References Cantera::GasConstant, ThermoPhase::m_hasElementPotentials, ThermoPhase::m_lambdaRRT, Phase::nElements(), Cantera::scale(), and Phase::temperature().
Referenced by Cantera::equilibrate(), ChemEquil::equilibrate(), ThermoPhase::equilibrate(), and Cantera::vcs_equilibrate().
bool getElementPotentials  (  doublereal *  lambda  )  const 
Returns the element potentials stored in the ThermoPhase object.
Returns the stored element potentials. The element potentials are retrieved from their stored dimensionless forms by multiplying by RT.
lambda  Output vector containing the element potentials. Length = nElements. Units are Joules/kmol. 
Definition at line 809 of file ThermoPhase.cpp.
References Cantera::GasConstant, ThermoPhase::m_hasElementPotentials, ThermoPhase::m_lambdaRRT, Cantera::scale(), and Phase::temperature().
Referenced by ChemEquil::equilibrate().