Cantera  2.5.1
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  */
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  */
236 
237  //! Pointer to the MultiPhase mixture that will be equilibrated.
238  /*!
239  * Equilibrium solutions will be returned via this variable.
240  */
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  */
257 
258  //! Stoichiometric matrix
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
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  */
281 };
282 
283 }
284 
285 #endif
Headers for the MultiPhase object that is used to set up multiphase equilibrium problems (see Equilfu...
A class for full (non-sparse) matrices with Fortran-compatible data storage, which adds matrix operat...
Definition: DenseMatrix.h:51
A class for multiphase mixtures.
Definition: MultiPhase.h:58
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's Interface to the Multiphase chemical equilibrium solver.
VCS_SOLVE m_vsolve
The object that contains the problem statement and does all of the equilibration work.
int iterations() const
return the number of iterations
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...
void reportCSV(const std::string &reportFile)
Report the equilibrium answer in a comma separated table format.
vcs_MultiPhaseEquil(MultiPhase *mix, int printLvl)
Constructor for the multiphase equilibrium solver.
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...
vector_int m_species
Vector of indices for species that are included in the calculation.
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...
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.
vector_int m_order
Vector that takes into account of the current sorting of the species.
DenseMatrix m_N
Stoichiometric matrix.
int m_printLvl
Print level from the VCSnonlinear package.
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...
MultiPhase * m_mix
Pointer to the MultiPhase mixture that will be equilibrated.
std::vector< int > vector_int
Vector of ints.
Definition: ct_defs.h:182
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:264
#define VCS_MAXSTEPS
Maximum steps in the inner loop.
Definition: vcs_defs.h:75
Header file for the internal object that holds the vcs equilibrium problem (see Class VCS_SOLVE and E...