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