Cantera  2.3.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
8
9 #ifndef VCS_MULTIPHASEEQUIL_H
10 #define VCS_MULTIPHASEEQUIL_H
11
12 #include "MultiPhase.h"
13 #include "vcs_solve.h"
14 #include "vcs_prob.h"
15
16 namespace Cantera
17 {
18
19 //! Translate a MultiPhase object into a VCS_PROB problem definition object
20 /*!
21  * @param mphase MultiPhase object that is the source for all of the information
22  * @param vprob VCS_PROB problem definition that gets all of the information
23  *
24  * Note, both objects share the underlying ThermoPhase objects. So, neither can
25  * be const objects.
26  */
27 int vcs_Cantera_to_vprob(MultiPhase* mphase, VCS_PROB* vprob);
28
29 //! Translate a MultiPhase information into a VCS_PROB problem definition object
30 /*!
31  * This version updates the problem statement information only. All species and
32  * phase definitions remain the same.
33  *
34  * @param mphase MultiPhase object that is the source for all of the information
35  * @param vprob VCS_PROB problem definition that gets all of the information
36  */
37 int vcs_Cantera_update_vprob(MultiPhase* mphase, VCS_PROB* vprob);
38
39 //! %Cantera's Interface to the Multiphase chemical equilibrium solver.
40 /*!
41  * Class vcs_MultiPhaseEquil is designed to be used to set a mixture containing
42  * one or more phases to a state of chemical equilibrium.
43  *
44  * Note, as currently constructed, the underlying ThermoPhase objects are shared
45  * between the MultiPhase object and this object. Therefore, mix is not a const
46  * argument, and the return parameters are contained in underlying ThermoPhase
47  * objects.
48  *
49  * @ingroup equilfunctions
50  */
52 {
53 public:
55
56  //! Constructor for the multiphase equilibrium solver
57  /*!
58  * This constructor will initialize the object with a MultiPhase object,
59  * setting up the internal equilibration problem. Note, as currently
60  * constructed, the underlying ThermoPhase objects are shared between the
61  * MultiPhase object and this object. Therefore, mix is not a const
62  * argument, and the return parameters are contained in underlying
63  * ThermoPhase objects.
64  *
65  * @param mix Object containing the MultiPhase object
66  * @param printLvl Determines the amount of printing to stdout
67  * that occurs for each call:
68  * - 0: No printing
69  * - 1: Only printing to the .csv file
70  * - 2: print the soln only
71  * - 3: Print the setup and then the soln only
72  * - 4: Print a table for each iteration
73  * - 5: Print more than a table for each iteration
74  */
75  vcs_MultiPhaseEquil(MultiPhase* mix, int printLvl);
76
77  virtual ~vcs_MultiPhaseEquil() {}
78
79  //! Return the index of the ith component
80  /*!
81  * Returns the index of the ith component in the equilibrium calculation.
82  * The index refers to the ordering of the species in the MultiPhase object.
83  *
84  * @param m Index of the component. Must be between 0 and the number of
85  * components, which can be obtained from the numComponents() command.
86  * @deprecated Unused. To be removed after Cantera 2.3.
87  */
88  size_t component(size_t m) const;
89
90  //! Get the stoichiometric reaction coefficients for a single
91  //! reaction index
92  /*!
93  * This returns a stoichiometric reaction vector for a single formation
94  * reaction for a noncomponent species. There are (nSpecies() - nComponents)
95  * formation reactions. Each formation reaction will have a value of 1.0 for
96  * the species that is being formed, and the other non-zero coefficients
97  * will all involve the components of the mixture.
98  *
99  * @param rxn Reaction number.
100  * @param nu Vector of coefficients for the formation reaction. Length is
101  * equal to the number of species in the MultiPhase object.
102  * @deprecated Unused. To be removed after Cantera 2.3.
103  */
104  void getStoichVector(size_t rxn, vector_fp& nu);
105
106  //! return the number of iterations
107  int iterations() const {
108  return m_iter;
109  }
110
111  //! Equilibrate the solution using the current element abundances
112  //! stored in the MultiPhase object
113  /*!
114  * Use the vcs algorithm to equilibrate the current multiphase mixture.
115  *
116  * @param XY Integer representing what two thermo quantities are
117  * held constant during the equilibration
118  * @param estimateEquil integer indicating whether the solver should
119  * estimate its own initial condition.
120  * - If 0, the initial mole fraction vector in the ThermoPhase object is
121  * used as the initial condition.
122  * - If 1, the initial mole fraction vector is used if the element
123  * abundances are satisfied.
124  * - if -1, the initial mole fraction vector is thrown out, and an
125  * estimate is formulated.
126  * @param printLvl Determines the amount of printing that gets sent to
127  * stdout from the vcs package (Note, you may have to compile with debug
128  * flags to get some printing).
129  * @param err Internal error level
130  * @param maxsteps max steps allowed.
131  * @param loglevel Determines the amount of printing to the output file.
132  */
133  int equilibrate(int XY, int estimateEquil = 0,
134  int printLvl= 0, doublereal err = 1.0e-6,
135  int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
136
137  //! Equilibrate the solution using the current element abundances
138  //! stored in the MultiPhase object using constant T and P
139  /*!
140  * Use the vcs algorithm to equilibrate the current multiphase mixture.
141  *
142  * @param estimateEquil integer indicating whether the solver should
143  * estimate its own initial condition.
144  * - If 0, the initial mole fraction vector in the ThermoPhase object is
145  * used as the initial condition.
146  * - If 1, the initial mole fraction vector is used if the element
147  * abundances are satisfied.
148  * - if -1, the initial mole fraction vector is thrown out, and an
149  * estimate is formulated.
150  * @param printLvl Determines the amount of printing that gets sent to
151  * stdout from the vcs package (Note, you may have to compile with debug
152  * flags to get some printing).
153  * @param err Internal error level
154  * @param maxsteps max steps allowed.
155  * @param loglevel Determines the amount of printing to the output file.
156  */
157  int equilibrate_TP(int estimateEquil = 0,
158  int printLvl= 0, doublereal err = 1.0e-6,
159  int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
160
161  //! Equilibrate the solution using the current element abundances
162  //! stored in the MultiPhase object using either constant H and P
163  //! or constant U and P.
164  /*!
165  * Use the vcs algorithm to equilibrate the current multiphase mixture. The
166  * pressure of the calculation is taken from the current pressure stored
167  * with the MultiPhase object.
168  *
169  * @param Htarget Value of the total mixture enthalpy or total internal
170  * energy that will be kept constant. Note, this is and must be an
171  * extensive quantity. units = Joules
172  * @param XY Integer flag indicating what is held constant. Must be
173  * either HP or UP.
174  * @param Tlow Lower limit of the temperature. It's an error condition
175  * if the temperature falls below Tlow.
176  * @param Thigh Upper limit of the temperature. It's an error condition
177  * if the temperature goes higher than Thigh.
178  * @param estimateEquil integer indicating whether the solver
179  * should estimate its own initial condition.
180  * - If 0, the initial mole fraction vector in the ThermoPhase object is
181  * used as the initial condition.
182  * - If 1, the initial mole fraction vector is used if the element
183  * abundances are satisfied.
184  * - if -1, the initial mole fraction vector is thrown out, and an
185  * estimate is formulated.
186  * @param printLvl Determines the amount of printing that gets sent to
187  * stdout from the vcs package (Note, you may have to
188  * compile with debug flags to get some printing). See main
189  * constructor call for meaning of the levels.
190  * @param err Internal error level
191  * @param maxsteps max steps allowed.
192  * @param loglevel Determines the amount of printing to the output file.
193  */
194  int equilibrate_HP(doublereal Htarget, int XY, double Tlow, double Thigh,
195  int estimateEquil = 0,
196  int printLvl = 0, doublereal err = 1.0E-6,
197  int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
198
199  //! Equilibrate the solution using the current element abundances stored in
200  //! the MultiPhase object using constant S and P.
201  /*!
202  * Use the vcs algorithm to equilibrate the current multiphase mixture. The
203  * pressure of the calculation is taken from the current pressure stored
204  * with the MultiPhase object.
205  *
206  * @param Starget Value of the total mixture entropy that will be kept
207  * constant. Note, this is and must be an extensive quantity.
208  * units = Joules/K
209  * @param Tlow Lower limit of the temperature. It's an error condition if
210  * the temperature falls below Tlow.
211  * @param Thigh Upper limit of the temperature. It's an error condition if
212  * the temperature goes higher than Thigh.
213  * @param estimateEquil integer indicating whether the solver should
214  * estimate its own initial condition.
215  * - If 0, the initial mole fraction vector in the ThermoPhase object is
216  * used as the initial condition.
217  * - If 1, the initial mole fraction vector is used if the element
218  * abundances are satisfied.
219  * - If -1, the initial mole fraction vector is thrown out, and an
220  * estimate is formulated.
221  * @param printLvl Determines the amount of printing that gets sent to
222  * stdout from the vcs package (Note, you may have to
223  * compile with debug flags to get some printing). See main
224  * constructor call for meaning of the levels.
225  * @param err Internal error level
226  * @param maxsteps max steps allowed.
227  * @param loglevel Determines the amount of printing to the output file.
228  */
229  int equilibrate_SP(doublereal Starget, double Tlow, double Thigh,
230  int estimateEquil = 0,
231  int printLvl = 0, doublereal err = 1.0E-6,
232  int maxsteps = VCS_MAXSTEPS, int loglevel=-99);
233
234  //! Equilibrate the solution using the current element abundances stored
235  //! in the MultiPhase object using constant V and constant T, H, U or S.
236  /*!
237  * Use the vcs algorithm to equilibrate the current multiphase mixture. The
238  * pressure of the calculation is taken from the current pressure stored
239  * with the MultiPhase object.
240  *
241  * @param XY Integer flag indicating what is held constant.
242  * Must be either TV, HV, UV, or SV.
243  * @param xtarget Value of the total thermodynamic parameter to be held
244  * constant in addition to V. Note, except for T, this must be an
245  * extensive quantity. units = Joules/K or Joules
246  * @param estimateEquil integer indicating whether the solver should
247  * estimate its own initial condition.
248  * - If 0, the initial mole fraction vector in the ThermoPhase object is
249  * used as the initial condition.
250  * - If 1, the initial mole fraction vector is used if the element
251  * abundances are satisfied.
252  * - if -1, the initial mole fraction vector is thrown out, and an
253  * estimate is formulated.
254  * @param printLvl Determines the amount of printing that gets sent to
255  * stdout from the vcs package (Note, you may have to compile with debug
256  * flags to get some printing). See main constructor call for meaning of
257  * the levels.
258  * @param err Internal error level
259  * @param maxsteps max steps allowed.
260  * @param logLevel Determines the amount of printing to the output file.
261  */
262  int equilibrate_TV(int XY, doublereal xtarget,
263  int estimateEquil = 0,
264  int printLvl = 0, doublereal err = 1.0E-6,
265  int maxsteps = VCS_MAXSTEPS, int logLevel = -99);
266
267  //! Determine the phase stability of a phase at the current conditions
268  /*!
269  * Equilibration of the solution is not done before the determination is
271  *
272  * @param iph Phase number to determine the equilibrium. If the phase
273  * has a non-zero mole number....
274  * @param funcStab Value of the phase pop function
275  * @param printLvl Determines the amount of printing that gets sent to
276  * stdout from the vcs package (Note, you may have to compile with debug
277  * flags to get some printing).
278  * @param logLevel Determines the amount of printing to the output file.
279  * @deprecated Broken and unused. To be removed after Cantera 2.3.
280  */
281  int determine_PhaseStability(int iph, double& funcStab, int printLvl= 0, int logLevel = -99);
282
283  //! Report the equilibrium answer in a comma separated table format
284  /*!
285  * This routine is used for in the test suite.
286  *
287  * @param reportFile Base name of the file to get the report. File name is
288  * incremented by 1 for each report.
289  */
290  void reportCSV(const std::string& reportFile);
291
292  //! reports the number of components in the equilibration problem
293  /*!
294  * @returns the number of components. If an equilibrium
295  * problem hasn't been solved yet, it returns -1.
296  * @deprecated Unused. To be removed after Cantera 2.3.
297  */
298  size_t numComponents() const;
299
300  //! Reports the number of element constraints in the equilibration problem
301  /*!
302  * @returns the number of element constraints. If an equilibrium problem
303  * hasn't been solved yet, it returns -1.
304  * @deprecated Unused. To be removed after Cantera 2.3.
305  */
306  size_t numElemConstraints() const;
307
308  // Friend functions
309  friend int vcs_Cantera_to_vprob(MultiPhase* mphase, VCS_PROB* vprob);
310  friend int vcs_Cantera_update_vprob(MultiPhase* mphase, VCS_PROB* vprob);
311
312 protected:
313  //! Vector that takes into account of the current sorting of the species
314  /*!
315  * The index of m_order is the original k value of the species in the
316  * multiphase. The value of m_order, k_sorted, is the current value of the
317  * species index.
318  *
319  * m_order[korig] = k_sorted
320  */
322
323  //! Object which contains the problem statement
324  /*!
325  * The problem statement may contain some subtleties. For example, the
326  * element constraints may be different than just an element conservation
327  * contraint equations. There may be kinetically frozen degrees of freedom.
328  * There may be multiple electrolyte phases with zero charge constraints.
329  * All of these make the problem statement different than the simple element
330  * conservation statement.
331  */
333
334  //! Pointer to the MultiPhase mixture that will be equilibrated.
335  /*!
336  * Equilibrium solutions will be returned via this variable.
337  */
339
340  //! Print level from the VCSnonlinear package
341  /*!
342  * (Note, you may have to compile with debug flags to get some printing).
343  *
344  * - 0: No IO from the routine whatsoever
345  * - 1: file IO from reportCSV() carried out. One line print statements
346  * from equilibrate_XY() functions
347  * - 2: Problem statement information from vcs_Cantera_update_vprob();
348  * Final state of the system from vcs_solve_TP()
349  * - 3: Several more setup tables; Problem initialization routine
350  * - 4: One table for each iteration within vcs_solve_Tp()
351  * - 5: Multiple tables for each iteration within vcs_solve_TP()
352  */
354
355  //! Stoichiometric matrix
357
358  //! Iteration Count
359  int m_iter;
360
361  //! Vector of indices for species that are included in the calculation. This
362  //! is used to exclude pure-phase species with invalid thermo data
364
365  //! The object that does all of the equilibration work.
366  /*!
367  * VCS_SOLVE will have different ordering for species and element constraints
368  * than this object or the VCS_PROB object.
369  */
371 };
372
373 //! Global hook for turning on and off time printing.
374 /*!
375  * Default is to allow printing. But, you can assign this to zero globally to
376  * turn off all time printing. This is helpful for test suite purposes where
377  * you are interested in differences in text files.
378  * @deprecated Call VCS_SOLVE::disable_timing() instead. To be removed after
379  * Cantera 2.3.
380  */
381 extern int vcs_timing_print_lvl;
382
383 }
384
385 #endif
vector_int m_order
Vector that takes into account of the current sorting of the species.
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...
MultiPhase * m_mix
Pointer to the MultiPhase mixture that will be equilibrated.
int iterations() const
return the number of iterations
size_t numComponents() const
reports the number of components in the equilibration problem
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...
size_t component(size_t m) const
Return the index of the ith component.
#define VCS_MAXSTEPS
Maximum steps in the inner loop.
Definition: vcs_defs.h:84
friend int vcs_Cantera_update_vprob(MultiPhase *mphase, VCS_PROB *vprob)
Translate a MultiPhase information into a VCS_PROB problem definition object.
int m_printLvl
Print level from the VCSnonlinear package.
int vcs_timing_print_lvl
Global hook for turning on and off time printing.
Definition: vcs_solve.cpp:22
Headers for the MultiPhase object that is used to set up multiphase equilibrium problems (see Equilfu...
void reportCSV(const std::string &reportFile)
Report the equilibrium answer in a comma separated table format.
int vcs_Cantera_update_vprob(MultiPhase *mphase, VCS_PROB *vprob)
Translate a MultiPhase information into a VCS_PROB problem definition object.
int vcs_Cantera_to_vprob(MultiPhase *mphase, VCS_PROB *vprob)
Translate a MultiPhase object into a VCS_PROB problem definition object.
std::vector< int > vector_int
Vector of ints.
Definition: ct_defs.h:159
Header file for the internal object that holds the vcs equilibrium problem (see Class VCS_SOLVE and E...
size_t numElemConstraints() const
Reports the number of element constraints in the equilibration problem.
Cantera&#39;s Interface to the Multiphase chemical equilibrium solver.
A class for multiphase mixtures.
Definition: MultiPhase.h:57
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...
Header for the Interface class for the vcs thermo equilibrium solver package,.
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...
void getStoichVector(size_t rxn, vector_fp &nu)
Get the stoichiometric reaction coefficients for a single reaction index.
int determine_PhaseStability(int iph, double &funcStab, int printLvl=0, int logLevel=-99)
Determine the phase stability of a phase at the current conditions.
VCS_SOLVE m_vsolve
The object that does all of the equilibration work.
std::vector< double > vector_fp
Turn on the use of stl vectors for the basic array type within cantera Vector of doubles.
Definition: ct_defs.h:157
VCS_PROB m_vprob
Object which contains the problem statement.
friend int vcs_Cantera_to_vprob(MultiPhase *mphase, VCS_PROB *vprob)
Translate a MultiPhase object into a VCS_PROB problem definition object.
DenseMatrix m_N
Stoichiometric matrix.
Namespace for the Cantera kernel.
Definition: application.cpp:29
vector_int m_species
Vector of indices for species that are included in the calculation.
Interface class for the vcs thermo equilibrium solver package, which generally describes the problem ...
Definition: vcs_prob.h:22
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...
A class for full (non-sparse) matrices with Fortran-compatible data storage, which adds matrix operat...
Definition: DenseMatrix.h:72
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:44