Cantera  2.2.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Elements.h
Go to the documentation of this file.
1 /**
2  * @file Elements.h
3  * Contains the LookupWtElements function and the definitions of element
4  * constraint types.
5  */
6 // Copyright 2001 California Institute of Technology
7 
8 #ifndef CT_ELEMENTS_H
9 #define CT_ELEMENTS_H
10 
11 #include "cantera/base/ct_defs.h"
12 
13 namespace Cantera
14 {
15 
16 /*!
17  * @name Types of Element Constraint Equations
18  *
19  * There may be several different types of element constraints handled
20  * by the equilibrium program and by Cantera in other contexts.
21  * These defines are used to assign each constraint to one category.
22  * @{
23  */
24 
25 //! An element constraint that is current turned off
26 #define CT_ELEM_TYPE_TURNEDOFF -1
27 
28 //! Normal element constraint consisting of positive coefficients for the
29 //! formula matrix.
30 /*!
31  * All species have positive coefficients within the formula matrix.
32  * With this constraint, we may employ various strategies to handle
33  * small values of the element number successfully.
34  */
35 #define CT_ELEM_TYPE_ABSPOS 0
36 
37 //! This refers to conservation of electrons
38 /*!
39  * Electrons may have positive or negative values in the Formula matrix.
40  */
41 #define CT_ELEM_TYPE_ELECTRONCHARGE 1
42 
43 //! This refers to a charge neutrality of a single phase
44 /*!
45  * Charge neutrality may have positive or negative values in the Formula matrix.
46  */
47 #define CT_ELEM_TYPE_CHARGENEUTRALITY 2
48 
49 //! Constraint associated with maintaining a fixed lattice stoichiometry in a solid
50 /*!
51  * The constraint may have positive or negative values. The lattice 0 species will
52  * have negative values while higher lattices will have positive values
53  */
54 #define CT_ELEM_TYPE_LATTICERATIO 3
55 
56 //! Constraint associated with maintaining frozen kinetic equilibria in
57 //! some functional groups within molecules
58 /*!
59  * We seek here to say that some functional groups or ionic states should be
60  * treated as if they are separate elements given the time scale of the problem.
61  * This will be abs positive constraint. We have not implemented any examples yet.
62  * A requirement will be that we must be able to add and subtract these constraints.
63  */
64 #define CT_ELEM_TYPE_KINETICFROZEN 4
65 
66 //! Constraint associated with the maintenance of a surface phase
67 /*!
68  * We don't have any examples of this yet either. However, surfaces only exist
69  * because they are interfaces between bulk layers. If we want to treat surfaces
70  * within thermodynamic systems we must come up with a way to constrain their total
71  * number.
72  */
73 #define CT_ELEM_TYPE_SURFACECONSTRAINT 5
74 
75 //! Other constraint equations
76 /*!
77  * currently there are none
78  */
79 #define CT_ELEM_TYPE_OTHERCONSTRAINT 6
80 //@}
81 
82 //! Number indicating we don't know the entropy of the element in its most
83 //! stable state at 298.15 K and 1 bar.
84 #define ENTROPY298_UNKNOWN -123456789.
85 
86 //! Function to look up an atomic weight
87 //! This function looks up the argument string in the database above and
88 //! returns the associated molecular weight.
89 //! The data are from the periodic table.
90 //!
91 //! Note: The idea behind this function is to provide a unified source for the
92 //! element atomic weights. This helps to ensure that mass is conserved.
93 //! @param ename String, Only the first 3 characters are significant
94 //! @return The atomic weight of the element
95 //! @exception CanteraError If a match is not found, throws a CanteraError
96 double LookupWtElements(const std::string& ename);
97 
98 class XML_Node;
99 
100 //! Object containing the elements that make up species in a phase.
101 /*!
102  * Class Elements manages the elements that are part of a
103  * chemistry specification. This class may support calculations
104  * employing Multiple phases. In this case, a single Elements object may
105  * be shared by more than one Constituents class. Reactions between
106  * the phases may then be described using stoichiometry base on the
107  * same Elements class object.
108  *
109  * The member functions return information about the elements described
110  * in a particular instantiation of the class.
111  *
112  * @ingroup phases
113  * @deprecated. Functionality is now part of class Phase. To be removed after
114  * Cantera 2.2.
115  */
116 class Elements
117 {
118 
119 public:
120 
121  //! Default constructor for the elements class
122  Elements();
123 
124  //! Default destructor for the elements class
125  ~Elements();
126 
127 
128  //! copy constructor
129  /*!
130  * This copy constructor just calls the assignment operator for this
131  * class. It sets the number of subscribers to zer0.
132  *
133  * @param right Reference to the object to be copied.
134  */
135  Elements(const Elements& right);
136 
137  //! Assignment operator
138  /*!
139  * This is the assignment operator for the Elements class.
140  * Right now we pretty much do a straight uncomplicated
141  * assignment. However, subscribers are not mucked with, as they
142  * have to do with the address of the object to be subscribed to
143  *
144  * @param right Reference to the object to be copied.
145  */
146  Elements& operator=(const Elements& right);
147 
148 
149  //! Static function to look up an atomic weight
150  /*!
151  * This static function looks up the argument string in the
152  * database above and returns the associated molecular weight.
153  * The data are from the periodic table.
154  *
155  * Note: The idea behind this function is to provide a unified
156  * source for the element atomic weights. This helps to
157  * ensure that mass is conserved.
158  *
159  * @param ename String, Only the first 3 characters are significant
160  *
161  * @return
162  * Return value contains the atomic weight of the element
163  * If a match for the string is not found, a value of -1.0 is
164  * returned.
165  *
166  * @exception CanteraError
167  * If a match is not found, a CanteraError is thrown as well
168  */
169  static double LookupWtElements(const std::string& ename);
170  /// Atomic weight of element m.
171  /*!
172  * @param m element index
173  */
174  doublereal atomicWeight(int m) const {
175  return m_atomicWeights[m];
176  }
177 
178  /// Atomic number of element m.
179  /*!
180  * @param m element index
181  */
182  int atomicNumber(int m) const {
183  return m_atomicNumbers[m];
184  }
185 
186  //! Entropy at 298.15 K and 1 bar of stable state
187  //! of the element
188  /*!
189  * units J kmol-1 K-1
190  *
191  * @param m Element index
192  */
193  doublereal entropyElement298(int m) const;
194 
195  //! Return the element constraint type
196  /*!
197  * Possible types include:
198  *
199  * CT_ELEM_TYPE_ABSPOS 0
200  * CT_ELEM_TYPE_ELECTRONCHARGE 1
201  * CT_ELEM_TYPE_CHARGENEUTRALITY 2
202  * CT_ELEM_TYPE_LATTICERATIO 3
203  * CT_ELEM_TYPE_KINETICFROZEN 4
204  * CT_ELEM_TYPE_SURFACECONSTRAINT 5
205  * CT_ELEM_TYPE_OTHERCONSTRAINT 6
206  *
207  * The default is CT_ELEM_TYPE_ABSPOS
208  *
209  * @param m Element index
210  *
211  * @return Returns the element type
212  */
213  int elementType(int m) const;
214 
215  //! Change the element type of the mth constraint
216  /*!
217  * Reassigns an element type
218  *
219  * @param m Element index
220  * @param elem_type New elem type to be assigned
221  *
222  * @return Returns the old element type
223  */
224  int changeElementType(int m, int elem_type);
225 
226  /// vector of element atomic weights
227  const vector_fp& atomicWeights() const {
228  return m_atomicWeights;
229  }
230  /**
231  * Inline function that returns the number of elements in the object.
232  *
233  * @return
234  * \c int: The number of elements in the object.
235  */
236  int nElements() const {
237  return m_mm;
238  }
239 
240  //! Function that returns the index of an element.
241  /*!
242  * Index of element named \c name. The index is an integer
243  * assigned to each element in the order it was added,
244  * beginning with 0 for the first element. If \c name is not
245  * the name of an element in the set, then the value -1 is
246  * returned.
247  *
248  * @param name String containing the index.
249  */
250  int elementIndex(const std::string& name) const;
251 
252  //! Name of the element with index \c m.
253  /*!
254  * @param m Element index. If m < 0 or m >= nElements() an exception is thrown.
255  */
256  std::string elementName(int m) const;
257 
258  //! Returns a string vector containing the element names
259  /*!
260  * Returns a read-only reference to the vector of element names.
261  * @return <tt> const vector<string>& </tt>: The vector contains
262  * the element names in their indexed order.
263  */
264  const std::vector<std::string>& elementNames() const {
265  return m_elementNames;
266  }
267 
268  //! Add an element to the current set of elements in the current object.
269  /*!
270  * The default weight is a special value, which will cause the
271  * routine to look up the actual weight via a string lookup.
272  *
273  * There are two interfaces to this routine. The XML interface
274  * looks up the required parameters for the regular interface
275  * and then calls the base routine.
276  *
277  * @param symbol string symbol for the element.
278  * @param weight Atomic weight of the element. If no argument
279  * is provided, a lookup is attempted.
280  */
281  void addElement(const std::string& symbol,
282  doublereal weight = -12345.0);
283  //! Add an element to the current set of elements in the current object.
284  /*!
285  * @param e Reference to the XML_Node containing the element information
286  * The node name is the element symbol and the atomWt attribute
287  * is used as the atomic weight.
288  */
289  void addElement(const XML_Node& e);
290 
291  //! Add an element only if the element hasn't been added before.
292  /*!
293  * This is accomplished via a string match on symbol.
294  *
295  * @param symbol string symbol for the element.
296  * @param weight Atomic weight of the element. If no argument
297  * is provided, a lookup is attempted.
298  * @param atomicNumber defaults to 0
299  * @param entropy298 Value of the entropy at 298 and 1 bar of the
300  * element in its most stable form.
301  * The default is to specify an ENTROPY298_UNKNOWN value,
302  * which will cause a throw error if its ever
303  * needed.
304  * @param elem_type New elem type to be assigned.
305  * The default is a regular element, CT_ELEM_TYPE_ABSPOS
306  */
307  void addUniqueElement(const std::string& symbol,
308  doublereal weight = -12345.0, int atomicNumber = 0,
309  doublereal entropy298 = ENTROPY298_UNKNOWN, int elem_type = CT_ELEM_TYPE_ABSPOS);
310 
311  //! Add an element to the current set of elements in the current object.
312  /*!
313  * @param e Reference to the XML_Node containing the element information
314  * The node name is the element symbol and the atomWt attribute
315  * is used as the atomic weight.
316  */
317  void addUniqueElement(const XML_Node& e);
318 
319  //! Add multiple elements from a XML_Node phase description
320  /*!
321  * @param phase XML_Node reference to a phase
322  */
323  void addElementsFromXML(const XML_Node& phase);
324 
325  //! Prohibit addition of more elements, and prepare to add species.
326  void freezeElements();
327 
328  //! True if freezeElements has been called.
329  bool elementsFrozen() const;
330 
331  /// Remove all elements
332  void clear();
333 
334  /// True if both elements and species have been frozen
335  bool ready() const;
336 
337  //! subscribe to this object
338  /*!
339  * Increment by one the number of subscriptions to this object.
340  */
341  void subscribe();
342 
343  //! unsubscribe to this object
344  /*!
345  * decrement by one the number of subscriptions to this object.
346  */
347  int unsubscribe();
348 
349  //! report the number of subscriptions
350  int reportSubscriptions() const;
351 
352 protected:
353 
354  /******************************************************************/
355  /* Description of DATA in the Object */
356  /******************************************************************/
357 
358  //! Number of elements.
359  int m_mm;
360 
361  /* m_elementsFrozen: */
362  /** boolean indicating completion of object
363  *
364  * If this is true, then no elements may be added to the
365  * object.
366  */
368 
369  /**
370  * Vector of element atomic weights:
371  *
372  * units = kg / kmol
373  */
375 
376  /**
377  * Vector of element atomic numbers:
378  *
379  */
381 
382  /** Vector of strings containing the names of the elements
383  *
384  * Note, a string search is the primary way to identify elements.
385  */
386  std::vector<std::string> m_elementNames;
387 
388  //! Entropy at 298.15 K and 1 bar of stable state
389  /*!
390  * units J kmol-1
391  */
393 
394  //! Vector of element types
396  /**
397  * Number of Constituents Objects that use this object
398  *
399  * Number of Constituents Objects that require this Elements object
400  * to complete its definition.
401  * The destructor checks to see that this is equal to zero.
402  * when the element object is released.
403  */
405 
406  /********* GLOBAL STATIC SECTION *************/
407 
408 public:
409  /** Vector of pointers to Elements Objects
410  *
411  */
412  static std::vector<Elements*> Global_Elements_List;
413 
414  friend class Constituents;
415 };
416 
417 
418 } // namespace
419 
420 #endif
std::string elementName(int m) const
Name of the element with index m.
Definition: Elements.cpp:294
doublereal LookupWtElements(const std::string &ename)
Function to look up an atomic weight This function looks up the argument string in the database above...
Definition: Elements.cpp:171
void addUniqueElement(const std::string &symbol, doublereal weight=-12345.0, int atomicNumber=0, doublereal entropy298=ENTROPY298_UNKNOWN, int elem_type=CT_ELEM_TYPE_ABSPOS)
Add an element only if the element hasn't been added before.
Definition: Elements.cpp:404
void clear()
Remove all elements.
Definition: Elements.cpp:491
int atomicNumber(int m) const
Atomic number of element m.
Definition: Elements.h:182
void addElement(const std::string &symbol, doublereal weight=-12345.0)
Add an element to the current set of elements in the current object.
Definition: Elements.cpp:361
Elements()
Default constructor for the elements class.
Definition: Elements.cpp:205
const vector_fp & atomicWeights() const
vector of element atomic weights
Definition: Elements.h:227
Class XML_Node is a tree-based representation of the contents of an XML file.
Definition: xml.h:100
This file contains definitions of terms that are used in internal routines and are unlikely to need m...
bool elementsFrozen() const
True if freezeElements has been called.
Definition: Elements.cpp:481
void subscribe()
subscribe to this object
Definition: Elements.cpp:567
#define CT_ELEM_TYPE_ABSPOS
Normal element constraint consisting of positive coefficients for the formula matrix.
Definition: Elements.h:35
vector_int m_elem_type
Vector of element types.
Definition: Elements.h:395
void freezeElements()
Prohibit addition of more elements, and prepare to add species.
Definition: Elements.cpp:264
int reportSubscriptions() const
report the number of subscriptions
Definition: Elements.cpp:576
bool ready() const
True if both elements and species have been frozen.
Definition: Elements.cpp:506
std::vector< int > vector_int
Vector of ints.
Definition: ct_defs.h:159
bool m_elementsFrozen
boolean indicating completion of object
Definition: Elements.h:367
vector_fp m_atomicWeights
Vector of element atomic weights:
Definition: Elements.h:374
Object containing the elements that make up species in a phase.
Definition: Elements.h:116
int nElements() const
Inline function that returns the number of elements in the object.
Definition: Elements.h:236
static std::vector< Elements * > Global_Elements_List
Vector of pointers to Elements Objects.
Definition: Elements.h:412
#define ENTROPY298_UNKNOWN
Number indicating we don't know the entropy of the element in its most stable state at 298...
Definition: Elements.h:84
const std::vector< std::string > & elementNames() const
Returns a string vector containing the element names.
Definition: Elements.h:264
doublereal entropyElement298(int m) const
Entropy at 298.15 K and 1 bar of stable state of the element.
Definition: Elements.cpp:303
Elements & operator=(const Elements &right)
Assignment operator.
Definition: Elements.cpp:238
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
std::vector< std::string > m_elementNames
Vector of strings containing the names of the elements.
Definition: Elements.h:386
static double LookupWtElements(const std::string &ename)
Static function to look up an atomic weight.
Definition: Elements.cpp:158
void addElementsFromXML(const XML_Node &phase)
Add multiple elements from a XML_Node phase description.
Definition: Elements.cpp:512
vector_int m_atomicNumbers
Vector of element atomic numbers:
Definition: Elements.h:380
int m_mm
Number of elements.
Definition: Elements.h:359
int changeElementType(int m, int elem_type)
Change the element type of the mth constraint.
Definition: Elements.cpp:341
vector_fp m_entropy298
Entropy at 298.15 K and 1 bar of stable state.
Definition: Elements.h:392
int elementIndex(const std::string &name) const
Function that returns the index of an element.
Definition: Elements.cpp:279
~Elements()
Default destructor for the elements class.
Definition: Elements.cpp:223
doublereal atomicWeight(int m) const
Atomic weight of element m.
Definition: Elements.h:174
int numSubscribers
Number of Constituents Objects that use this object.
Definition: Elements.h:404
int unsubscribe()
unsubscribe to this object
Definition: Elements.cpp:571
int elementType(int m) const
Return the element constraint type.
Definition: Elements.cpp:327