Cantera's Interface to the Multiphase chemical equilibrium solver. More...

#include <vcs_MultiPhaseEquil.h>

Collaboration diagram for vcs_MultiPhaseEquil:

Public Member Functions
	vcs_MultiPhaseEquil (MultiPhase *mix, int printLvl)
	Constructor for the multiphase equilibrium solver. More...

size_t	component (size_t m) const
	Return the index of the ith component. More...

void	getStoichVector (size_t rxn, vector_fp &nu)
	Get the stoichiometric reaction coefficients for a single reaction index. More...

int	iterations () const
	return the number of iterations More...

int	equilibrate (int XY, int estimateEquil=0, int printLvl=0, doublereal err=1.0e-6, int maxsteps=VCS_MAXSTEPS, int loglevel=-99)
	Equilibrate the solution using the current element abundances stored in the MultiPhase object. More...

int	equilibrate_TP (int estimateEquil=0, int printLvl=0, doublereal err=1.0e-6, int maxsteps=VCS_MAXSTEPS, int loglevel=-99)
	Equilibrate the solution using the current element abundances stored in the MultiPhase object using constant T and P. More...

int	equilibrate_HP (doublereal Htarget, int XY, double Tlow, double Thigh, int estimateEquil=0, int printLvl=0, doublereal err=1.0E-6, int maxsteps=VCS_MAXSTEPS, int loglevel=-99)
	Equilibrate the solution using the current element abundances stored in the MultiPhase object using either constant H and P or constant U and P. More...

int	equilibrate_SP (doublereal Starget, double Tlow, double Thigh, int estimateEquil=0, int printLvl=0, doublereal err=1.0E-6, int maxsteps=VCS_MAXSTEPS, int loglevel=-99)
	Equilibrate the solution using the current element abundances stored in the MultiPhase object using constant S and P. More...

int	equilibrate_TV (int XY, doublereal xtarget, int estimateEquil=0, int printLvl=0, doublereal err=1.0E-6, int maxsteps=VCS_MAXSTEPS, int logLevel=-99)
	Equilibrate the solution using the current element abundances stored in the MultiPhase object using constant V and constant T, H, U or S. More...

int	determine_PhaseStability (int iph, double &funcStab, int printLvl=0, int logLevel=-99)
	Determine the phase stability of a phase at the current conditions. More...

void	reportCSV (const std::string &reportFile)
	Report the equilibrium answer in a comma separated table format. More...

size_t	numComponents () const
	reports the number of components in the equilibration problem More...

size_t	numElemConstraints () const
	Reports the number of element constraints in the equilibration problem. More...

Protected Attributes
vector_int	m_order
	Vector that takes into account of the current sorting of the species. More...

VCS_PROB	m_vprob
	Object which contains the problem statement. More...

MultiPhase *	m_mix
	Pointer to the MultiPhase mixture that will be equilibrated. More...

int	m_printLvl
	Print level from the VCSnonlinear package. More...

DenseMatrix	m_N
	Stoichiometric matrix. More...

int	m_iter
	Iteration Count. More...

vector_int	m_species
	Vector of indices for species that are included in the calculation. More...

VCS_SOLVE	m_vsolve
	The object that does all of the equilibration work. More...

Friends
int	vcs_Cantera_to_vprob (MultiPhase mphase, VCS_PROB vprob)
	Translate a MultiPhase object into a VCS_PROB problem definition object. More...

int	vcs_Cantera_update_vprob (MultiPhase mphase, VCS_PROB vprob)
	Translate a MultiPhase information into a VCS_PROB problem definition object. More...

Detailed Description

Cantera's Interface to the Multiphase chemical equilibrium solver.

Class vcs_MultiPhaseEquil is designed to be used to set a mixture containing one or more phases to a state of chemical equilibrium.

Note, as currently constructed, the underlying ThermoPhase objects are shared between the MultiPhase object and this object. Therefore, mix is not a const argument, and the return parameters are contained in underlying ThermoPhase objects.

Definition at line 194 of file vcs_MultiPhaseEquil.h.

Constructor & Destructor Documentation

vcs_MultiPhaseEquil	(	MultiPhase *	mix,
		int	printLvl
	)

Constructor for the multiphase equilibrium solver.

This constructor will initialize the object with a MultiPhase object, setting up the internal equilibration problem. Note, as currently constructed, the underlying ThermoPhase objects are shared between the MultiPhase object and this object. Therefore, mix is not a const argument, and the return parameters are contained in underlying ThermoPhase objects.

Parameters

mix	Object containing the MultiPhase object
printLvl	Determines the amount of printing to stdout that occurs for each call: 0: No printing 1: Only printing to the .csv file 2: print the soln only 3: Print the setup and then the soln only 4: Print a table for each iteration 5: Print more than a table for each iteration

Definition at line 34 of file vcs_MultiPhaseEquil.cpp.

References vcs_MultiPhaseEquil::m_mix, VCS_PROB::m_printLvl, vcs_MultiPhaseEquil::m_printLvl, vcs_MultiPhaseEquil::m_vprob, plogf, and vcs_MultiPhaseEquil::vcs_Cantera_to_vprob.

Member Function Documentation

size_t component ( size_t m ) const

Return the index of the ith component.

Returns the index of the ith component in the equilibrium calculation. The index refers to the ordering of the species in the MultiPhase object.

Parameters

m	Index of the component. Must be between 0 and the number of components, which can be obtained from the numComponents() command.

Definition at line 1296 of file vcs_MultiPhaseEquil.cpp.

References VCS_SOLVE::m_speciesMapIndex, vcs_MultiPhaseEquil::m_vsolve, Cantera::npos, and vcs_MultiPhaseEquil::numComponents().

void getStoichVector	(	size_t	rxn,
		vector_fp &	nu
	)

Get the stoichiometric reaction coefficients for a single reaction index.

This returns a stoichiometric reaction vector for a single formation reaction for a noncomponent species. There are (nSpecies() - nComponents) formation reactions. Each formation reaction will have a value of 1.0 for the species that is being formed, and the other non-zero coefficients will all involve the components of the mixture.

Parameters

rxn	Reaction number.
nu	Vector of coefficients for the formation reaction. Length is equal to the number of species in the MultiPhase object.

Definition at line 1265 of file vcs_MultiPhaseEquil.cpp.

References VCS_SOLVE::m_numSpeciesTot, VCS_SOLVE::m_speciesMapIndex, VCS_SOLVE::m_stoichCoeffRxnMatrix, vcs_MultiPhaseEquil::m_vsolve, and vcs_MultiPhaseEquil::numComponents().

int iterations ( ) const

inline

return the number of iterations

Definition at line 251 of file vcs_MultiPhaseEquil.h.

References vcs_MultiPhaseEquil::m_iter.

int equilibrate	(	int	XY,
		int	estimateEquil = `0`,
		int	printLvl = `0`,
		doublereal	err = `1.0e-6`,
		int	maxsteps = `VCS_MAXSTEPS`,
		int	loglevel = `-99`
	)

Equilibrate the solution using the current element abundances stored in the MultiPhase object.

Use the vcs algorithm to equilibrate the current multiphase mixture.

Parameters

XY	Integer representing what two thermo quantities are held constant during the equilibration
estimateEquil	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.
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).
err	Internal error level
maxsteps	max steps allowed.
loglevel	Determines the amount of printing to the output file.

Definition at line 411 of file vcs_MultiPhaseEquil.cpp.

References MultiPhase::enthalpy(), MultiPhase::entropy(), vcs_MultiPhaseEquil::equilibrate_HP(), vcs_MultiPhaseEquil::equilibrate_SP(), vcs_MultiPhaseEquil::equilibrate_TP(), vcs_MultiPhaseEquil::equilibrate_TV(), MultiPhase::IntEnergy(), vcs_MultiPhaseEquil::m_mix, MultiPhase::maxTemp(), MultiPhase::minTemp(), and MultiPhase::temperature().

Referenced by MultiPhase::equilibrate(), and Cantera::vcs_equilibrate_1().

int equilibrate_TP	(	int	estimateEquil = `0`,
		int	printLvl = `0`,
		doublereal	err = `1.0e-6`,
		int	maxsteps = `VCS_MAXSTEPS`,
		int	loglevel = `-99`
	)

Equilibrate the solution using the current element abundances stored in the MultiPhase object using constant T and P.

Use the vcs algorithm to equilibrate the current multiphase mixture.

Parameters

estimateEquil	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.
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).
err	Internal error level
maxsteps	max steps allowed.
loglevel	Determines the amount of printing to the output file.

Definition at line 456 of file vcs_MultiPhaseEquil.cpp.

References VCS_PROB::iest, VCS_PROB::m_gibbsSpecies, vcs_MultiPhaseEquil::m_mix, VCS_PROB::m_printLvl, vcs_MultiPhaseEquil::m_printLvl, VCS_SOLVE::m_timing_print_lvl, VCS_PROB::m_VCS_UnitsFormat, vcs_MultiPhaseEquil::m_vprob, vcs_MultiPhaseEquil::m_vsolve, VCS_PROB::mf, VCS_PROB::NPhase, VCS_PROB::nspecies, Phase::nSpecies(), vcs_VolPhase::nSpecies(), MultiPhase::phase(), VCS_PROB::PhaseID, plogf, VCS_PROB::PresPA, MultiPhase::pressure(), VCS_PROB::prob_report(), clockWC::secondsWC(), MultiPhase::setPhaseMoles(), VCS_PROB::SpeciesUnknownType, VCS_PROB::SpName, VCS_PROB::T, MultiPhase::temperature(), MultiPhase::uploadMoleFractionsFromPhases(), VCS_SOLVE::vcs(), vcs_MultiPhaseEquil::vcs_Cantera_update_vprob, VCS_SPECIES_TYPE_INTERFACIALVOLTAGE, VCS_PROB::VPhaseList, and VCS_PROB::w.

Referenced by vcs_MultiPhaseEquil::equilibrate(), vcs_MultiPhaseEquil::equilibrate_HP(), vcs_MultiPhaseEquil::equilibrate_SP(), and vcs_MultiPhaseEquil::equilibrate_TV().

int equilibrate_HP	(	doublereal	Htarget,
		int	XY,
		double	Tlow,
		double	Thigh,
		int	estimateEquil = `0`,
		int	printLvl = `0`,
		doublereal	err = `1.0E-6`,
		int	maxsteps = `VCS_MAXSTEPS`,
		int	loglevel = `-99`
	)

Equilibrate the solution using the current element abundances stored in the MultiPhase object using either constant H and P or constant U and P.

Use the vcs algorithm to equilibrate the current multiphase mixture. The pressure of the calculation is taken from the current pressure stored with the MultiPhase object.

Parameters

Htarget	Value of the total mixture enthalpy or total internal energy that will be kept constant. Note, this is and must be an extensive quantity. units = Joules
XY	Integer flag indicating what is held constant. Must be either HP or UP.
Tlow	Lower limit of the temperature. It's an error condition if the temperature falls below Tlow.
Thigh	Upper limit of the temperature. It's an error condition if the temperature goes higher than Thigh.
estimateEquil	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.
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). See main constructor call for meaning of the levels.
err	Internal error level
maxsteps	max steps allowed.
loglevel	Determines the amount of printing to the output file.

Definition at line 156 of file vcs_MultiPhaseEquil.cpp.

References Cantera::clip(), MultiPhase::enthalpy(), vcs_MultiPhaseEquil::equilibrate_TP(), Cantera::int2str(), MultiPhase::IntEnergy(), vcs_MultiPhaseEquil::m_mix, MultiPhase::maxTemp(), MultiPhase::minTemp(), MultiPhase::phaseMoles(), plogendl, plogf, MultiPhase::setTemperature(), MultiPhase::temperature(), and Cantera::Undef.

Referenced by vcs_MultiPhaseEquil::equilibrate(), and vcs_MultiPhaseEquil::equilibrate_TV().

int equilibrate_SP	(	doublereal	Starget,
		double	Tlow,
		double	Thigh,
		int	estimateEquil = `0`,
		int	printLvl = `0`,
		doublereal	err = `1.0E-6`,
		int	maxsteps = `VCS_MAXSTEPS`,
		int	loglevel = `-99`
	)

Equilibrate the solution using the current element abundances stored in the MultiPhase object using constant S and P.

Use the vcs algorithm to equilibrate the current multiphase mixture. The pressure of the calculation is taken from the current pressure stored with the MultiPhase object.

Parameters

Starget	Value of the total mixture entropy that will be kept constant. Note, this is and must be an extensive quantity. units = Joules/K
Tlow	Lower limit of the temperature. It's an error condition if the temperature falls below Tlow.
Thigh	Upper limit of the temperature. It's an error condition if the temperature goes higher than Thigh.
estimateEquil	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.
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). See main constructor call for meaning of the levels.
err	Internal error level
maxsteps	max steps allowed.
loglevel	Determines the amount of printing to the output file.

Definition at line 281 of file vcs_MultiPhaseEquil.cpp.

References MultiPhase::entropy(), vcs_MultiPhaseEquil::equilibrate_TP(), vcs_MultiPhaseEquil::m_mix, MultiPhase::maxTemp(), MultiPhase::minTemp(), MultiPhase::phaseMoles(), plogf, MultiPhase::setTemperature(), MultiPhase::temperature(), and Cantera::Undef.

Referenced by vcs_MultiPhaseEquil::equilibrate(), and vcs_MultiPhaseEquil::equilibrate_TV().

int equilibrate_TV	(	int	XY,
		doublereal	xtarget,
		int	estimateEquil = `0`,
		int	printLvl = `0`,
		doublereal	err = `1.0E-6`,
		int	maxsteps = `VCS_MAXSTEPS`,
		int	logLevel = `-99`
	)

Equilibrate the solution using the current element abundances stored in the MultiPhase object using constant V and constant T, H, U or S.

Use the vcs algorithm to equilibrate the current multiphase mixture. The pressure of the calculation is taken from the current pressure stored with the MultiPhase object.

Parameters

XY	Integer flag indicating what is held constant. Must be either TV, HV, UV, or SV.
xtarget	Value of the total thermodynamic parameter to be held constant in addition to V. Note, except for T, this must be an extensive quantity. units = Joules/K or Joules
estimateEquil	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.
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). See main constructor call for meaning of the levels.
err	Internal error level
maxsteps	max steps allowed.
logLevel	Determines the amount of printing to the output file.

Definition at line 51 of file vcs_MultiPhaseEquil.cpp.

References vcs_MultiPhaseEquil::equilibrate_HP(), vcs_MultiPhaseEquil::equilibrate_SP(), vcs_MultiPhaseEquil::equilibrate_TP(), Cantera::int2str(), vcs_MultiPhaseEquil::m_mix, MultiPhase::maxTemp(), MultiPhase::minTemp(), MultiPhase::pressure(), MultiPhase::setPressure(), MultiPhase::setTemperature(), and MultiPhase::volume().

Referenced by vcs_MultiPhaseEquil::equilibrate().

int determine_PhaseStability	(	int	iph,
		double &	funcStab,
		int	printLvl = `0`,
		int	logLevel = `-99`
	)

Determine the phase stability of a phase at the current conditions.

Equilibration of the solution is not done before the determination is made.

Parameters

iph	Phase number to determine the equilibrium. If the phase has a non-zero mole number....
funcStab	Value of the phase pop function
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).
logLevel	Determines the amount of printing to the output file.

Definition at line 1306 of file vcs_MultiPhaseEquil.cpp.

References DATA_PTR, MultiPhase::getChemPotentials(), VCS_PROB::m_gibbsSpecies, vcs_MultiPhaseEquil::m_mix, VCS_PROB::m_printLvl, vcs_MultiPhaseEquil::m_printLvl, VCS_SOLVE::m_timing_print_lvl, VCS_PROB::m_VCS_UnitsFormat, vcs_MultiPhaseEquil::m_vprob, vcs_MultiPhaseEquil::m_vsolve, VCS_PROB::mf, VCS_PROB::nspecies, MultiPhase::phaseName(), plogf, VCS_PROB::PresPA, MultiPhase::pressure(), VCS_PROB::prob_report(), clockWC::secondsWC(), VCS_PROB::SpeciesUnknownType, VCS_PROB::SpName, VCS_PROB::T, MultiPhase::temperature(), MultiPhase::uploadMoleFractionsFromPhases(), vcs_MultiPhaseEquil::vcs_Cantera_update_vprob, VCS_SPECIES_TYPE_INTERFACIALVOLTAGE, and VCS_PROB::w.

Referenced by Cantera::vcs_determine_PhaseStability().

void reportCSV ( const std::string & reportFile )

Report the equilibrium answer in a comma separated table format.

This routine is used for in the test suite.

Parameters

reportFile Base name of the file to get the report. File name is incremented by 1 for each report.

Definition at line 599 of file vcs_MultiPhaseEquil.cpp.

References ThermoPhase::activityConvention(), ThermoPhase::getActivities(), ThermoPhase::getActivityCoefficients(), ThermoPhase::getChemPotentials(), MolalityVPSSTP::getMolalities(), ThermoPhase::getPartialMolarVolumes(), ThermoPhase::getStandardChemPotentials(), VCS_PROB::m_gibbsSpecies, VCS_PROB::m_Iterations, vcs_MultiPhaseEquil::m_mix, VCS_PROB::m_NumBasisOptimizations, vcs_MultiPhaseEquil::m_vprob, VCS_PROB::mf, Phase::name(), VCS_PROB::NPhase, Phase::nSpecies(), MultiPhase::phase(), MultiPhase::pressure(), MultiPhase::speciesIndex(), Phase::speciesName(), MultiPhase::temperature(), vcs_VolPhase::totalMoles(), VCS_DATA_PTR, Cantera::vcs_doubleEqual(), and VCS_PROB::VPhaseList.

Referenced by Cantera::vcs_determine_PhaseStability(), and Cantera::vcs_equilibrate_1().

size_t numComponents ( ) const

reports the number of components in the equilibration problem

Returns: returns the number of components. If an equilibrium problem hasn't been solved yet, it returns -1.

Definition at line 1286 of file vcs_MultiPhaseEquil.cpp.

References VCS_SOLVE::m_numComponents, and vcs_MultiPhaseEquil::m_vsolve.

Referenced by vcs_MultiPhaseEquil::component(), and vcs_MultiPhaseEquil::getStoichVector().

size_t numElemConstraints ( ) const

Reports the number of element constraints in the equilibration problem.

Returns: returns the number of element constraints. If an equilibrium problem hasn't been solved yet, it returns -1.

Definition at line 1291 of file vcs_MultiPhaseEquil.cpp.

References VCS_SOLVE::m_numElemConstraints, and vcs_MultiPhaseEquil::m_vsolve.

Friends And Related Function Documentation

int vcs_Cantera_to_vprob	(	MultiPhase *	mphase,
		VCS_PROB *	vprob
	)

friend

Translate a MultiPhase object into a VCS_PROB problem definition object.

Parameters

mphase	MultiPhase object that is the source for all of the information
vprob	VCS_PROB problem definition that gets all of the information

Note, both objects share the underlying ThermoPhase objects. So, neither can be const objects.

Definition at line 753 of file vcs_MultiPhaseEquil.cpp.

Referenced by vcs_MultiPhaseEquil::vcs_MultiPhaseEquil().

int vcs_Cantera_update_vprob	(	MultiPhase *	mphase,
		VCS_PROB *	vprob
	)

friend

Translate a MultiPhase information into a VCS_PROB problem definition object.

This version updates the problem statement information only. All species and phase definitions remain the same.

Parameters

mphase	MultiPhase object that is the source for all of the information
vprob	VCS_PROB problem definition that gets all of the information

Definition at line 1142 of file vcs_MultiPhaseEquil.cpp.

Referenced by vcs_MultiPhaseEquil::determine_PhaseStability(), and vcs_MultiPhaseEquil::equilibrate_TP().

Member Data Documentation

vector_int m_order

protected

Vector that takes into account of the current sorting of the species.

The index of m_order is the original k value of the species in the multiphase. The value of m_order, k_sorted, is the current value of the species index.

m_order[korig] = k_sorted

Definition at line 464 of file vcs_MultiPhaseEquil.h.

VCS_PROB m_vprob

protected

Object which contains the problem statement.

The problem statement may contain some subtleties. For example, the element constraints may be different than just an element conservation contraint equations. There may be kinetically frozen degrees of freedom. There may be multiple electrolyte phases with zero charge constraints. All of these make the problem statement different than the simple element conservation statement.

Definition at line 475 of file vcs_MultiPhaseEquil.h.

Referenced by vcs_MultiPhaseEquil::determine_PhaseStability(), vcs_MultiPhaseEquil::equilibrate_TP(), vcs_MultiPhaseEquil::reportCSV(), and vcs_MultiPhaseEquil::vcs_MultiPhaseEquil().

MultiPhase* m_mix

protected

Pointer to the MultiPhase mixture that will be equilibrated.

Equilibrium solutions will be returned via this variable.

Definition at line 481 of file vcs_MultiPhaseEquil.h.

Referenced by vcs_MultiPhaseEquil::determine_PhaseStability(), vcs_MultiPhaseEquil::equilibrate(), vcs_MultiPhaseEquil::equilibrate_HP(), vcs_MultiPhaseEquil::equilibrate_SP(), vcs_MultiPhaseEquil::equilibrate_TP(), vcs_MultiPhaseEquil::equilibrate_TV(), vcs_MultiPhaseEquil::reportCSV(), and vcs_MultiPhaseEquil::vcs_MultiPhaseEquil().

int m_printLvl

protected

Print level from the VCSnonlinear package.

(Note, you may have to compile with debug flags to get some printing).

0: No IO from the routine whatsoever
1: file IO from reportCSV() carried out. One line print statements from equilibrate_XY() functions
2: Problem statement information from vcs_Cantera_update_vprob(); Final state of the system from vcs_solve_TP()
3: Several more setup tables; Problem initialization routine
4: One table for each iteration within vcs_solve_Tp()
5: Multiple tables for each iteration within vcs_solve_TP()

Definition at line 496 of file vcs_MultiPhaseEquil.h.

Referenced by vcs_MultiPhaseEquil::determine_PhaseStability(), vcs_MultiPhaseEquil::equilibrate_TP(), and vcs_MultiPhaseEquil::vcs_MultiPhaseEquil().

DenseMatrix m_N

protected

Stoichiometric matrix.

Definition at line 499 of file vcs_MultiPhaseEquil.h.

int m_iter

protected

Iteration Count.

Definition at line 502 of file vcs_MultiPhaseEquil.h.

Referenced by vcs_MultiPhaseEquil::iterations().

vector_int m_species