1 // -*- C++ -*- 2 3 /* 4 * Gnome Chemistry Utils 5 * element.h 6 * 7 * Copyright (C) 2002-2012 Jean Bréfort <jean.brefort@normalesup.org> 8 * 9 * This program is free software; you can redistribute it and/or 10 * modify it under the terms of the GNU General Public License as 11 * published by the Free Software Foundation; either version 3 of the 12 * License, or (at your option) any later version. 13 * 14 * This program is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 * GNU General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License 20 * along with this program; if not, write to the Free Software 21 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 22 * USA 23 */ 24 25 #ifndef GCU_ELEMENT_H 26 #define GCU_ELEMENT_H 27 28 #include <map> 29 #include <string> 30 #include <vector> 31 #include "chemistry.h" 32 #include "isotope.h" 33 #include "value.h" 34 #include "macros.h" 35 36 /*!\file */ 37 /*!\def GCU_ERROR 38 Defines a standard error value. 39 */ 40 #define GCU_ERROR (1 << (sizeof(int) - 1)) 41 42 /*!\namespace gcu 43 \brief The Gnome Chemistry Utils C++ classes 44 45 The namespace used for all C++ classes provided by the Gnome Chemistry Utils base library. 46 */ 47 namespace gcu 48 { 49 50 class EltTable; 51 52 /*!\class Element gcu/element.h 53 @brief Chemical element. 54 55 Represents a chemical element. 56 This class has no public constructor or destructor. The instances are created by the framework 57 from data in the elements.xml file and 58 a user cannot create a new element. 59 */ 60 class Element 61 { 62 friend class EltTable; 63 private: 64 /*! 65 \param Z: the atomic number corresponding to the element 66 \param Symbol: the atomic symbol of the element 67 68 This constructor is private and cannot be used ouside of this class. 69 */ 70 Element (int Z, const char* Symbol); 71 /*! 72 The destructor. 73 */ 74 virtual ~Element (); 75 76 public: 77 /*! 78 @param Z: the atomic number of a chemical element. 79 @return The chemical symbol of the element whose atomic number is Z or NULL if the element is unknown. 80 */ 81 static const char* Symbol (int Z); 82 /*! 83 @param Z: the atomic number of a chemical element. 84 85 This static method is used to know on what side of the symbol of the element whose atomic number is Z 86 attached hydrogens should be written. 87 @return true if hydrogens should be written on the right and false when it should be written on the left side. 88 */ 89 static bool BestSide (int Z); 90 /*! 91 @param symbol: the symbol of a chemical element. 92 @return The atomic number of the element whose chemical symbol is used as parameter or 0 if the element is unknown. 93 */ 94 static int Z (const char* symbol); 95 /*! 96 @param Z: the atomic number of a chemical element. 97 @return a pointer to the Element whose atomic number is Z or NULL if the element is unknown. 98 */ 99 static Element* GetElement (int Z); 100 /*! 101 @param symbol: the symbol of a chemical element. 102 @return a pointer to the Element whose symbol is used as parameter or NULL if the element is unknown. 103 */ 104 static Element* GetElement (const char* symbol); 105 /*! 106 @param radius: a pointer to a GcuAtomicRadius structure. 107 108 Before calling this function, most fields in the GcuAtomicRadius structure must be filled: 109 - Z: the atomic number, mandatory 110 - type: the type of the radius searched 111 - charge: the charge of the atom. 0 for all radii except ionic radii. 112 - cn: the coordination number or -1 if not significant 113 - spin: the spin state or GCU_N_A_SPIN if not significant 114 - scale: the name of the scale (e.g. "Pauling") or NULL 115 116 The programs searches a value corresponding to the fields having a non default value. If one is found 117 the other fields are given the corresponding values f the first match before returning. 118 119 @return true if a radius has been found and false if not. 120 */ 121 static bool GetRadius (GcuAtomicRadius* radius); 122 /*! 123 @param en: a pointer to a GcuElectronegativity structure. 124 125 Before calling this function, the following fields in the GcuElectronegativity structure must be filled: 126 - Z: the atomic number, mandatory 127 - type: the gcu_radius_type, mandatory 128 - charge: the charge of the atom, mandatory; must be 0 for non ionic radii 129 and non null for ionic radii. 130 - scale: the name of the scale (e.g. "Pauling") or NULL 131 132 The programs searches an electronegativity value for the element in the scale if given. If one is found 133 the value and the scale (if NULL on calling) are given the corresponding values of the first match before returning. 134 135 @return true if a match has been found and false if not. 136 */ 137 static bool GetElectronegativity (GcuElectronegativity* en); 138 /*! 139 @param Z: the atomic number of a chemical element. 140 141 The value returned by this method might be too low in some cases and is only indicative. Instances of the Atom class 142 accept any number of bonds. This behavior might change in future versions. 143 @return the maximum number of bonds an atom of the element can be involved in. 144 */ 145 static unsigned GetMaxBonds (int Z); 146 /*! 147 Loads the atomic radii database. 148 */ 149 static void LoadRadii (); 150 /*! 151 Loads the atomic electronic properties database. 152 */ 153 static void LoadElectronicProps (); 154 /*! 155 Loads the isotopes database. 156 */ 157 static void LoadIsotopes (); 158 /*! 159 Loads the Blue Obelisk Database. 160 */ 161 static void LoadBODR (); 162 /*! 163 Loads all databases. 164 */ 165 static void LoadAllData (); 166 /*! 167 Intialize the element database. There is no need to call this method if 168 any of the Load*() method is called. 169 */ 170 static void Init (); 171 172 /*! 173 \return The atomic number of the chemical element. 174 */ GetZ()175 int GetZ () {return m_Z;} 176 /*! 177 \return The chemical symbol of the element. 178 */ GetSymbol()179 const char* GetSymbol () {return m_Symbol;} 180 /*! 181 \return The default valence of the element for some elements, mainly non metals. For others, the returned value is -1 182 and should not be taken into account. 183 */ GetDefaultValence()184 char GetDefaultValence () {return m_DefaultValence;} 185 /*! 186 The value returned by this method might be too low in some cases and is only indicative. Instances of the Atom class 187 accept any number of bonds. This behavior might change in future versions. 188 @return the maximum number of bonds an atom of the element can be involved in. 189 */ GetMaxBonds()190 unsigned GetMaxBonds () {return m_MaxBonds;} 191 /*! 192 This static method is used to know on what side of the symbol of the element 193 attached hydrogens should be written. 194 @return true if hydrogens should be written on the right and false when it should be written on the left side. 195 */ GetBestSide()196 bool GetBestSide () {return m_BestSide;} 197 /*! 198 Retrieves the default color used for the element. 199 @return an array of three double values for the red, green and blue components of the color. 200 */ GetDefaultColor()201 double* GetDefaultColor () {return m_DefaultColor;} 202 /*! 203 @return the name of the element in the current locale or in english if the current locale is not supported in the database. 204 */ GetName()205 const char* GetName () {return name.c_str();} 206 /*! 207 @return a pointer to the array of pointers to GcuAtomicRadius structures for all known radii for the element. 208 Last value in the array is NULL. 209 */ 210 const GcuAtomicRadius** GetRadii (); 211 /*! 212 @return a pointer to the array of pointers to GcuElectronegativity structures for all known electronegativities for the element. 213 Last value in the array is NULL. 214 */ 215 const GcuElectronegativity** GetElectronegativities (); 216 /*! 217 @return the number of valence electrons of the neutral atom. 218 */ GetValenceElectrons()219 unsigned GetValenceElectrons () {return m_nve;} 220 /*! 221 @return the number of valence electrons of the neutral atom, 222 including d and f electrons. 223 */ GetTotalValenceElectrons()224 unsigned GetTotalValenceElectrons () {return m_tve;} 225 /*! 226 @return the maximume number of valence electrons of the neutral atom, 227 including d and f electrons. 228 */ GetMaxValenceElectrons()229 unsigned GetMaxValenceElectrons () {return m_maxve;} 230 /*! 231 @return the atomic molar mass of the element. 232 */ 233 DimensionalValue const *GetWeight (); 234 /*! 235 @param natoms: atoms count. 236 237 @return the isotopic pattern correponding to a fragment containing n atoms of the 238 element. 239 */ 240 IsotopicPattern *GetIsotopicPattern (unsigned natoms); 241 /*! 242 @return the fundamental electronic configuration for the element. The 243 returned string is formated as a pango markup, with electron numbers 244 for each sublevel as superscript. 245 */ GetElectronicConfiguration()246 std::string const& GetElectronicConfiguration () {return ElecConfig;} 247 /*! 248 @return the map of known names for the element indexed by language. 249 */ GetNames()250 std::map<std::string, std::string> const& GetNames () {return names;} 251 /*! 252 @param rank: the rank of the ionization. 253 254 @return the requested ionization energy as a &GcuDimensionalValue. 255 */ 256 GcuDimensionalValue const *GetIonizationEnergy (unsigned rank = 1); 257 /*! 258 @param rank: the rank of the electron affinity. 259 260 @return the requested electron affinity as a &GcuDimensionalValue. 261 For most elements, only the first is known. 262 */ 263 GcuDimensionalValue const *GetElectronAffinity (unsigned rank = 1); 264 /*! 265 @param property_name: the name of the property as used in the Blue 266 Obelisk Data Repository (without the "bo:" prefix). 267 268 @return the requested property if known, or NULL. 269 */ 270 Value const *GetProperty (char const *property_name); 271 /*! 272 @param property_name: the name of the property as used in the Blue 273 Obelisk Data Repository (without the "bo:" prefix). 274 275 @return the requested string property if known as a reference or an empty string. 276 */ 277 std::string &GetStringProperty (char const *property_name); 278 /*! 279 @param property_name: the name of the property as used in the Blue 280 Obelisk Data Repository (without the "bo:" prefix). 281 282 @return the requested integer property if known, or G_MININT32. 283 */ 284 int GetIntegerProperty (char const *property_name); 285 286 /*! 287 @return true if the element is a metal, false otherwise. 288 */ 289 bool IsMetallic (); 290 291 private: 292 unsigned char m_Z, m_nve, m_tve, m_maxve; 293 char m_Symbol[4]; 294 DimensionalValue const *m_AtomicWeight; 295 char m_DefaultValence; 296 unsigned char m_MaxBonds; 297 bool m_BestSide, m_Metallic, m_MetallicCached; 298 double m_DefaultColor[3]; 299 std::string name; 300 std::vector<GcuAtomicRadius*> m_radii; 301 std::vector<GcuElectronegativity*> m_en; 302 std::vector<Isotope*> m_isotopes; 303 std::vector<IsotopicPattern*> m_patterns; 304 std::vector<GcuDimensionalValue> m_ei; 305 std::vector<GcuDimensionalValue> m_ae; 306 std::map<std::string, std::string> names; 307 std::map<std::string, Value*> props; 308 std::map<std::string, std::string> sprops; 309 std::map<std::string, int> iprops; 310 std::string ElecConfig; 311 /*!\fn GetStability() 312 @return true if the element has at least one stable isotope, false otherwise. 313 */ 314 GCU_RO_PROP (bool, Stability) 315 }; 316 317 } // namespace gcu 318 319 #endif // GCU_ELEMENT_H 320