Cantera  2.5.1
vcs_defs.h
Go to the documentation of this file.
1 /**
2  * @file vcs_defs.h
3  * Defines and definitions within the vcs package
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_DEFS_H
10 #define VCS_DEFS_H
11 
12 namespace Cantera
13 {
14 /*!
15  * ERROR CODES
16  */
17 //@{
18 #define VCS_SUCCESS 0
19 #define VCS_NOMEMORY 1
20 #define VCS_FAILED_CONVERGENCE -1
21 #define VCS_SHOULDNT_BE_HERE -2
22 #define VCS_PUB_BAD -3
23 #define VCS_THERMO_OUTOFRANGE -4
24 #define VCS_FAILED_LOOKUP -5
25 #define VCS_MP_FAIL -6
26 //@}
27 
28 /*!
29  * @name Sizes of Phases and Cutoff Mole Numbers
30  *
31  * All size parameters are listed here
32  * @{
33  */
34 
35 //! Cutoff relative mole fraction value, below which species are deleted from
36 //! the equilibrium problem.
37 #ifndef VCS_RELDELETE_SPECIES_CUTOFF
38 #define VCS_RELDELETE_SPECIES_CUTOFF 1.0e-64
39 #endif
40 
41 //! Cutoff relative mole number value, below which species are deleted from the
42 //! equilibrium problem.
43 #ifndef VCS_DELETE_MINORSPECIES_CUTOFF
44 #define VCS_DELETE_MINORSPECIES_CUTOFF 1.0e-140
45 #endif
46 
47 //! Relative value of multiphase species mole number for a multiphase species
48 //! which is small.
49 #ifndef VCS_SMALL_MULTIPHASE_SPECIES
50 #define VCS_SMALL_MULTIPHASE_SPECIES 1.0e-25
51 #endif
52 
53 //! Cutoff relative moles below which a phase is deleted
54 //! from the equilibrium problem.
55 #ifndef VCS_DELETE_PHASE_CUTOFF
56 #define VCS_DELETE_PHASE_CUTOFF 1.0e-13
57 #endif
58 
59 //! Relative mole number of species in a phase that is created We want this to
60 //! be comfortably larger than the VCS_DELETE_PHASE_CUTOFF value so that the
61 //! phase can have a chance to survive.
62 #ifndef VCS_POP_PHASE_MOLENUM
63 #define VCS_POP_PHASE_MOLENUM 1.0e-11
64 #endif
65 
66 
67 //! Cutoff moles below which a phase or species which comprises the bulk of an
68 //! element's total concentration is deleted.
69 #ifndef VCS_DELETE_ELEMENTABS_CUTOFF
70 #define VCS_DELETE_ELEMENTABS_CUTOFF 1.0e-280
71 #endif
72 
73 //! Maximum steps in the inner loop
74 #ifndef VCS_MAXSTEPS
75 #define VCS_MAXSTEPS 50000
76 #endif
77 
78 //@}
79 
80 //! @name Species Categories used during the iteration
81 /*!
82  * These defines are valid values for spStatus()
83  */
84 //@{
85 
86 //! Species is a component which can never be nonzero because of a
87 //! stoichiometric constraint
88 /*!
89  * An example of this would be a species that contains Ni. But,
90  * the amount of Ni elements is exactly zero.
91  */
92 #define VCS_SPECIES_COMPONENT_STOICHZERO 3
93 
94 //! Species is a component which can be nonzero
95 #define VCS_SPECIES_COMPONENT 2
96 
97 //! Species is a major species
98 /*!
99  * A major species is either a species in a multicomponent phase with
100  * significant concentration or it's a Stoich Phase
101  */
102 #define VCS_SPECIES_MAJOR 1
103 
104 //! Species is a major species
105 /*!
106  * A major species is either a species in a multicomponent phase with
107  * significant concentration or it's a Stoich Phase
108  */
109 #define VCS_SPECIES_MINOR 0
110 
111 //! Species lies in a multicomponent phase, with a small phase concentration
112 /*!
113  * The species lies in a multicomponent phase that exists. It concentration is
114  * currently very low, necessitating a different method of calculation.
115  */
116 #define VCS_SPECIES_SMALLMS -1
117 
118 //! Species lies in a multicomponent phase with concentration zero
119 /*!
120  * The species lies in a multicomponent phase which currently doesn't exist.
121  * It concentration is currently zero.
122  */
123 #define VCS_SPECIES_ZEROEDMS -2
124 
125 //! Species is a SS phase, that is currently zeroed out.
126 /*!
127  * The species lies in a single-species phase which is currently zeroed out.
128  */
129 #define VCS_SPECIES_ZEROEDSS -3
130 
131 //! Species has such a small mole fraction it is deleted even though its
132 //! phase may possibly exist.
133 /*!
134  * The species is believed to have such a small mole fraction that it best to
135  * throw the calculation of it out. It will be added back in at the end of the
136  * calculation.
137  */
138 #define VCS_SPECIES_DELETED -4
139 
140 //! Species refers to an electron in the metal.
141 /*!
142  * The unknown is equal to the electric potential of the phase in which it
143  * exists.
144  */
145 #define VCS_SPECIES_INTERFACIALVOLTAGE -5
146 
147 //! Species lies in a multicomponent phase that is zeroed atm
148 /*!
149  * The species lies in a multicomponent phase that is currently deleted and will
150  * stay deleted due to a choice from a higher level. These species will formally
151  * always have zero mole numbers in the solution vector.
152  */
153 #define VCS_SPECIES_ZEROEDPHASE -6
154 
155 //! Species lies in a multicomponent phase that is active, but species
156 //! concentration is zero
157 /*!
158  * The species lies in a multicomponent phase which currently does exist. It
159  * concentration is currently identically zero, though the phase exists. Note,
160  * this is a temporary condition that exists at the start of an equilibrium
161  * problem. The species is soon "birthed" or "deleted".
162  */
163 #define VCS_SPECIES_ACTIVEBUTZERO -7
164 
165 //! Species lies in a multicomponent phase that is active,
166 //! but species concentration is zero due to stoich constraint
167 /*!
168  * The species lies in a multicomponent phase which currently does exist. Its
169  * concentration is currently identically zero, though the phase exists. This is
170  * a permanent condition due to stoich constraints.
171  *
172  * An example of this would be a species that contains Ni. But, the amount of Ni
173  * elements in the current problem statement is exactly zero.
174  */
175 #define VCS_SPECIES_STOICHZERO -8
176 
177 //@}
178 
179 //! @name Phase Categories used during the iteration
180 /*!
181  * These defines are valid values for the phase existence flag
182  */
183 //@{
184 //! Always exists because it contains inerts which can't exist in any other phase
185 #define VCS_PHASE_EXIST_ALWAYS 3
186 
187 //! Phase is a normal phase that currently exists
188 #define VCS_PHASE_EXIST_YES 2
189 
190 //! Phase is a normal phase that exists in a small concentration
191 /*!
192  * Concentration is so small that it must be calculated using an alternate
193  * method
194  */
195 #define VCS_PHASE_EXIST_MINORCONC 1
196 
197 //! Phase doesn't currently exist in the mixture
198 #define VCS_PHASE_EXIST_NO 0
199 
200 //! Phase currently is zeroed due to a programmatic issue
201 /*!
202  * We zero phases because we want to follow phase stability boundaries.
203  */
204 #define VCS_PHASE_EXIST_ZEROEDPHASE -6
205 
206 //@}
207 
208 /*!
209  * @name Types of Element Constraint Equations
210  *
211  * There may be several different types of element constraints handled by the
212  * equilibrium program. These defines are used to assign each constraint to one
213  * category.
214  * @{
215  */
216 
217 
218 //! An element constraint that is current turned off
219 #define VCS_ELEM_TYPE_TURNEDOFF -1
220 
221 //! Normal element constraint consisting of positive coefficients for the
222 //! formula matrix.
223 /*!
224  * All species have positive coefficients within the formula matrix. With this
225  * constraint, we may employ various strategies to handle small values of the
226  * element number successfully.
227  */
228 #define VCS_ELEM_TYPE_ABSPOS 0
229 
230 //! This refers to conservation of electrons
231 /*!
232  * Electrons may have positive or negative values in the Formula matrix.
233  */
234 #define VCS_ELEM_TYPE_ELECTRONCHARGE 1
235 
236 //! This refers to a charge neutrality of a single phase
237 /*!
238  * Charge neutrality may have positive or negative values in the Formula matrix.
239  */
240 #define VCS_ELEM_TYPE_CHARGENEUTRALITY 2
241 
242 //! Constraint associated with maintaining a fixed lattice stoichiometry in the
243 //! solids
244 /*!
245  * The constraint may have positive or negative values. The lattice 0 species
246  * will have negative values while higher lattices will have positive values
247  */
248 #define VCS_ELEM_TYPE_LATTICERATIO 3
249 
250 //! Constraint associated with maintaining frozen kinetic equilibria in
251 //! some functional groups within molecules
252 /*!
253  * We seek here to say that some functional groups or ionic states should be
254  * treated as if they are separate elements given the time scale of the problem.
255  * This will be abs positive constraint. We have not implemented any examples
256  * yet. A requirement will be that we must be able to add and subtract these
257  * constraints.
258  */
259 #define VCS_ELEM_TYPE_KINETICFROZEN 4
260 
261 //! Constraint associated with the maintenance of a surface phase
262 /*!
263  * We don't have any examples of this yet either. However, surfaces only exist
264  * because they are interfaces between bulk layers. If we want to treat surfaces
265  * within thermodynamic systems we must come up with a way to constrain their
266  * total number.
267  */
268 #define VCS_ELEM_TYPE_SURFACECONSTRAINT 5
269 //! Other constraint equations
270 /*!
271  * currently there are none
272  */
273 #define VCS_ELEM_TYPE_OTHERCONSTRAINT 6
274 //@}
275 
276 /*!
277  * @name Types of Species Unknowns in the problem
278  * @{
279  */
280 //! Unknown refers to mole number of a single species
281 #define VCS_SPECIES_TYPE_MOLNUM 0
282 
283 //! Unknown refers to the voltage level of a phase
284 /*!
285  * Typically, these species are electrons in metals. There is an infinite supply
286  * of them. However, their electrical potential is sometimes allowed to vary,
287  * for example if the open circuit voltage is sought after.
288  */
289 #define VCS_SPECIES_TYPE_INTERFACIALVOLTAGE -5
290 //@}
291 
292 /*!
293  * @name Types of State Calculations within VCS. These values determine where
294  * the results are stored within the VCS_SOLVE object.
295  * @{
296  */
297 //! State Calculation is currently in an unknown state
298 #define VCS_STATECALC_UNKNOWN -1
299 //! State Calculation based on the old or base mole numbers
300 #define VCS_STATECALC_OLD 0
301 
302 //! State Calculation based on the new or tentative mole numbers
303 #define VCS_STATECALC_NEW 1
304 
305 //! State Calculation based on tentative mole numbers for a phase which is
306 //! currently zeroed, but is being evaluated for whether it should pop back into
307 //! existence
308 #define VCS_STATECALC_PHASESTABILITY 2
309 
310 //! State Calculation based on a temporary set of mole numbers
311 #define VCS_STATECALC_TMP 3
312 //@}
313 
314 }
315 
316 // namespace alias for backward compatibility
317 namespace VCSnonideal = Cantera;
318 
319 #endif
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:264