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