Cantera 2.6.0

vcs_MultiPhaseEquil.h
Go to the documentation of this file.
1/**
2 * @file vcs_MultiPhaseEquil.h
3 * Interface class for the vcsnonlinear solver
4 */
5
6// This file is part of Cantera. See License.txt in the top-level directory or
7// at https://cantera.org/license.txt for license and copyright information.
8
9#ifndef VCS_MULTIPHASEEQUIL_H
10#define VCS_MULTIPHASEEQUIL_H
11
12#include "MultiPhase.h"
13#include "vcs_solve.h"
14
15 namespace Cantera
16{
17
18//! %Cantera's Interface to the Multiphase chemical equilibrium solver.
19/*!
20 * Class vcs_MultiPhaseEquil is designed to be used to set a mixture containing
21 * one or more phases to a state of chemical equilibrium.
22 *
23 * Note, as currently constructed, the underlying ThermoPhase objects are shared
24 * between the MultiPhase object and this object. Therefore, mix is not a const
25 * argument, and the return parameters are contained in underlying ThermoPhase
26 * objects.
27 *
28 * @ingroup equilfunctions
29 */
30 class vcs_MultiPhaseEquil
31{
32 public:
33 //! Constructor for the multiphase equilibrium solver
34 /*!
35 * This constructor will initialize the object with a MultiPhase object,
36 * setting up the internal equilibration problem. Note, as currently
37 * constructed, the underlying ThermoPhase objects are shared between the
38 * MultiPhase object and this object. Therefore, mix is not a const
39 * argument, and the return parameters are contained in underlying
40 * ThermoPhase objects.
41 *
42 * @param mix Object containing the MultiPhase object
43 * @param printLvl Determines the amount of printing to stdout
44 * that occurs for each call:
45 * - 0: No printing
46 * - 1: Only printing to the .csv file
47 * - 2: print the soln only
48 * - 3: Print the setup and then the soln only
49 * - 4: Print a table for each iteration
50 * - 5: Print more than a table for each iteration
51 */
52 vcs_MultiPhaseEquil(MultiPhase* mix, int printLvl);
53
54 virtual ~vcs_MultiPhaseEquil() {}
55
56 //! return the number of iterations
57 int iterations() const {
58 return m_iter;
59 }
60
61 //! Equilibrate the solution using the current element abundances
62 //! stored in the MultiPhase object
63 /*!
64 * Use the vcs algorithm to equilibrate the current multiphase mixture.
65 *
66 * @param XY Integer representing what two thermo quantities are
67 * held constant during the equilibration
68 * @param estimateEquil integer indicating whether the solver should
69 * estimate its own initial condition.
70 * - If 0, the initial mole fraction vector in the ThermoPhase object is
71 * used as the initial condition.
72 * - If 1, the initial mole fraction vector is used if the element
73 * abundances are satisfied.
74 * - if -1, the initial mole fraction vector is thrown out, and an
75 * estimate is formulated.
76 * @param printLvl Determines the amount of printing that gets sent to
77 * stdout from the vcs package (Note, you may have to compile with debug
78 * flags to get some printing).
79 * @param err Internal error level
80 * @param maxsteps max steps allowed.
81 * @param loglevel Determines the amount of printing to the output file.
82 */
83 int equilibrate(int XY, int estimateEquil = 0,
84 int printLvl= 0, doublereal err = 1.0e-6,
85 int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
86
87 //! Equilibrate the solution using the current element abundances
88 //! stored in the MultiPhase object using constant T and P
89 /*!
90 * Use the vcs algorithm to equilibrate the current multiphase mixture.
91 *
92 * @param estimateEquil integer indicating whether the solver should
93 * estimate its own initial condition.
94 * - If 0, the initial mole fraction vector in the ThermoPhase object is
95 * used as the initial condition.
96 * - If 1, the initial mole fraction vector is used if the element
97 * abundances are satisfied.
98 * - if -1, the initial mole fraction vector is thrown out, and an
99 * estimate is formulated.
100 * @param printLvl Determines the amount of printing that gets sent to
101 * stdout from the vcs package (Note, you may have to compile with debug
102 * flags to get some printing).
103 * @param err Internal error level
104 * @param maxsteps max steps allowed.
105 * @param loglevel Determines the amount of printing to the output file.
106 */
107 int equilibrate_TP(int estimateEquil = 0,
108 int printLvl= 0, doublereal err = 1.0e-6,
109 int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
110
111 //! Equilibrate the solution using the current element abundances
112 //! stored in the MultiPhase object using either constant H and P
113 //! or constant U and P.
114 /*!
115 * Use the vcs algorithm to equilibrate the current multiphase mixture. The
116 * pressure of the calculation is taken from the current pressure stored
117 * with the MultiPhase object.
118 *
119 * @param Htarget Value of the total mixture enthalpy or total internal
120 * energy that will be kept constant. Note, this is and must be an
121 * extensive quantity. units = Joules
122 * @param XY Integer flag indicating what is held constant. Must be
123 * either HP or UP.
124 * @param Tlow Lower limit of the temperature. It's an error condition
125 * if the temperature falls below Tlow.
126 * @param Thigh Upper limit of the temperature. It's an error condition
127 * if the temperature goes higher than Thigh.
128 * @param estimateEquil integer indicating whether the solver
129 * should estimate its own initial condition.
130 * - If 0, the initial mole fraction vector in the ThermoPhase object is
131 * used as the initial condition.
132 * - If 1, the initial mole fraction vector is used if the element
133 * abundances are satisfied.
134 * - if -1, the initial mole fraction vector is thrown out, and an
135 * estimate is formulated.
136 * @param printLvl Determines the amount of printing that gets sent to
137 * stdout from the vcs package (Note, you may have to
138 * compile with debug flags to get some printing). See main
139 * constructor call for meaning of the levels.
140 * @param err Internal error level
141 * @param maxsteps max steps allowed.
142 * @param loglevel Determines the amount of printing to the output file.
143 */
144 int equilibrate_HP(doublereal Htarget, int XY, double Tlow, double Thigh,
145 int estimateEquil = 0,
146 int printLvl = 0, doublereal err = 1.0E-6,
147 int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
148
149 //! Equilibrate the solution using the current element abundances stored in
150 //! the MultiPhase object using constant S and P.
151 /*!
152 * Use the vcs algorithm to equilibrate the current multiphase mixture. The
153 * pressure of the calculation is taken from the current pressure stored
154 * with the MultiPhase object.
155 *
156 * @param Starget Value of the total mixture entropy that will be kept
157 * constant. Note, this is and must be an extensive quantity.
158 * units = Joules/K
159 * @param Tlow Lower limit of the temperature. It's an error condition if
160 * the temperature falls below Tlow.
161 * @param Thigh Upper limit of the temperature. It's an error condition if
162 * the temperature goes higher than Thigh.
163 * @param estimateEquil integer indicating whether the solver should
164 * estimate its own initial condition.
165 * - If 0, the initial mole fraction vector in the ThermoPhase object is
166 * used as the initial condition.
167 * - If 1, the initial mole fraction vector is used if the element
168 * abundances are satisfied.
169 * - If -1, the initial mole fraction vector is thrown out, and an
170 * estimate is formulated.
171 * @param printLvl Determines the amount of printing that gets sent to
172 * stdout from the vcs package (Note, you may have to
173 * compile with debug flags to get some printing). See main
174 * constructor call for meaning of the levels.
175 * @param err Internal error level
176 * @param maxsteps max steps allowed.
177 * @param loglevel Determines the amount of printing to the output file.
178 */
179 int equilibrate_SP(doublereal Starget, double Tlow, double Thigh,
180 int estimateEquil = 0,
181 int printLvl = 0, doublereal err = 1.0E-6,
182 int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
183
184 //! Equilibrate the solution using the current element abundances stored
185 //! in the MultiPhase object using constant V and constant T, H, U or S.
186 /*!
187 * Use the vcs algorithm to equilibrate the current multiphase mixture. The
188 * pressure of the calculation is taken from the current pressure stored
189 * with the MultiPhase object.
190 *
191 * @param XY Integer flag indicating what is held constant.
192 * Must be either TV, HV, UV, or SV.
193 * @param xtarget Value of the total thermodynamic parameter to be held
194 * constant in addition to V. Note, except for T, this must be an
195 * extensive quantity. units = Joules/K or Joules
196 * @param estimateEquil integer indicating whether the solver should
197 * estimate its own initial condition.
198 * - If 0, the initial mole fraction vector in the ThermoPhase object is
199 * used as the initial condition.
200 * - If 1, the initial mole fraction vector is used if the element
201 * abundances are satisfied.
202 * - if -1, the initial mole fraction vector is thrown out, and an
203 * estimate is formulated.
204 * @param printLvl Determines the amount of printing that gets sent to
205 * stdout from the vcs package (Note, you may have to compile with debug
206 * flags to get some printing). See main constructor call for meaning of
207 * the levels.
208 * @param err Internal error level
209 * @param maxsteps max steps allowed.
210 * @param logLevel Determines the amount of printing to the output file.
211 */
212 int equilibrate_TV(int XY, doublereal xtarget,
213 int estimateEquil = 0,
214 int printLvl = 0, doublereal err = 1.0E-6,
215 int maxsteps = VCS_MAXSTEPS, int logLevel = -99);
216
217 //! Report the equilibrium answer in a comma separated table format
218 /*!
219 * This routine is used for in the test suite.
220 *
221 * @param reportFile Base name of the file to get the report. File name is
222 * incremented by 1 for each report.
223 */
224 void reportCSV(const std::string& reportFile);
225
226 protected:
227 //! Vector that takes into account of the current sorting of the species
228 /*!
229 * The index of m_order is the original k value of the species in the
230 * multiphase. The value of m_order, k_sorted, is the current value of the
231 * species index.
232 *
233 * `m_order[korig] = k_sorted`
234 */
235 vector_int m_order;
236
237 //! Pointer to the MultiPhase mixture that will be equilibrated.
238 /*!
239 * Equilibrium solutions will be returned via this variable.
240 */
241 MultiPhase* m_mix;
242
243 //! Print level from the VCSnonlinear package
244 /*!
245 * (Note, you may have to compile with debug flags to get some printing).
246 *
247 * - 0: No IO from the routine whatsoever
248 * - 1: file IO from reportCSV() carried out. One line print statements
249 * from equilibrate_XY() functions
250 * - 2: Problem statement information from vcs_Cantera_update_vprob();
251 * Final state of the system from vcs_solve_TP()
252 * - 3: Several more setup tables; Problem initialization routine
253 * - 4: One table for each iteration within vcs_solve_Tp()
254 * - 5: Multiple tables for each iteration within vcs_solve_TP()
255 */
256 int m_printLvl;
257
258 //! Stoichiometric matrix
259 DenseMatrix m_N;
260
261 //! Iteration Count
262 int m_iter;
263
264 //! Vector of indices for species that are included in the calculation. This
265 //! is used to exclude pure-phase species with invalid thermo data
266 vector_int m_species;
267
268 //! The object that contains the problem statement and does all of the equilibration work
269 /*!
270 * The problem statement may contain some subtleties. For example, the
271 * element constraints may be different than just an element conservation
272 * contraint equations. There may be kinetically frozen degrees of freedom.
273 * There may be multiple electrolyte phases with zero charge constraints.
274 * All of these make the problem statement different than the simple element
275 * conservation statement.
276 *
277 * VCS_SOLVE will have different ordering for species and element constraints
278 * than this object.
279 */
280 VCS_SOLVE m_vsolve;
281};
282
283}
284
285#endif
MultiPhase.h
Headers for the MultiPhase object that is used to set up multiphase equilibrium problems (see Classes...
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::VCS_SOLVE
This is the main structure used to hold the internal data used in vcs_solve_TP(), and to solve TP sys...
Definition: vcs_solve.h:45
Cantera::vcs_MultiPhaseEquil
Cantera's Interface to the Multiphase chemical equilibrium solver.
Definition: vcs_MultiPhaseEquil.h:31
Cantera::vcs_MultiPhaseEquil::m_vsolve
VCS_SOLVE m_vsolve
The object that contains the problem statement and does all of the equilibration work.
Definition: vcs_MultiPhaseEquil.h:280
Cantera::vcs_MultiPhaseEquil::iterations
int iterations() const
return the number of iterations
Definition: vcs_MultiPhaseEquil.h:57
Cantera::vcs_MultiPhaseEquil::equilibrate_HP
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 e...
Definition: vcs_MultiPhaseEquil.cpp:128
Cantera::vcs_MultiPhaseEquil::m_iter
int m_iter
Iteration Count.
Definition: vcs_MultiPhaseEquil.h:262
Cantera::vcs_MultiPhaseEquil::reportCSV
void reportCSV(const std::string &reportFile)
Report the equilibrium answer in a comma separated table format.
Definition: vcs_MultiPhaseEquil.cpp:493
Cantera::vcs_MultiPhaseEquil::vcs_MultiPhaseEquil
vcs_MultiPhaseEquil(MultiPhase *mix, int printLvl)
Constructor for the multiphase equilibrium solver.
Definition: vcs_MultiPhaseEquil.cpp:24
Cantera::vcs_MultiPhaseEquil::equilibrate_TP
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 c...
Definition: vcs_MultiPhaseEquil.cpp:415
Cantera::vcs_MultiPhaseEquil::m_species
vector_int m_species
Vector of indices for species that are included in the calculation.
Definition: vcs_MultiPhaseEquil.h:266
Cantera::vcs_MultiPhaseEquil::equilibrate_SP
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 c...
Definition: vcs_MultiPhaseEquil.cpp:244
Cantera::vcs_MultiPhaseEquil::equilibrate
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.
Definition: vcs_MultiPhaseEquil.cpp:370
Cantera::vcs_MultiPhaseEquil::m_order
vector_int m_order
Vector that takes into account of the current sorting of the species.
Definition: vcs_MultiPhaseEquil.h:235
Cantera::vcs_MultiPhaseEquil::m_N
DenseMatrix m_N
Stoichiometric matrix.
Definition: vcs_MultiPhaseEquil.h:259
Cantera::vcs_MultiPhaseEquil::m_printLvl
int m_printLvl
Print level from the VCSnonlinear package.
Definition: vcs_MultiPhaseEquil.h:256
Cantera::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 c...
Definition: vcs_MultiPhaseEquil.cpp:31
Cantera::vcs_MultiPhaseEquil::m_mix
MultiPhase * m_mix
Pointer to the MultiPhase mixture that will be equilibrated.
Definition: vcs_MultiPhaseEquil.h:241
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
VCS_MAXSTEPS
#define VCS_MAXSTEPS
Maximum steps in the inner loop.
Definition: vcs_defs.h:79
vcs_solve.h
Header file for the internal object that holds the vcs equilibrium problem (see Class VCS_SOLVE and C...