1 // -*- C -*- 2 3 /* 4 * Gnome Chemisty Utils 5 * chemistry.h 6 * 7 * Copyright (C) 2003-2011 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 26 /*! \mainpage 27 \section intro Introduction 28 The Gnome Chemistry Utils Library provides some widgets and C++ classes related to chemistry. 29 30 Available widgets are: 31 - GcpFontSel: a font selector. 32 - GcuPeriodic: a periodic table of the elements. 33 - GcuComboPeriodic: a combo box with a dropdown periodic table widget. 34 - GcrCrystalViewer: a crystal structure viewer. 35 - GcuChem3DViewer: a 3D molecular structure viewer. 36 - GcuSpectrumViewer: a spectrum viewer. 37 38 The C++ classes are grouped in the gcu, gcugtk, gccv, gcr, and gcp namespaces. 39 A C interface exists to use some (not so many) of the functionalities offered 40 in these classes; the corresponding documentation is available in the 41 chemistry.h file. 42 */ 43 44 #ifndef GCU_CHEMISTRY_H 45 #define GCU_CHEMISTRY_H 46 47 /** \file 48 * C interface to the chemistry library. 49 50 To use this file, add the following line to your source file: 51 \code 52 #include <gcu/chemistry.h> 53 \endcode 54 */ 55 56 #ifdef __cplusplus 57 extern "C" { 58 #endif 59 60 /** 61 The greatest atomic number known in this version of the Gnome Chemictry Utils 62 */ 63 #define MAX_ELT 116 64 65 /** gcu_spin_state 66 * gcu_spin_state describes the spin state of a central atom in a complex. 67 * Possible values are: 68 * - GCU_N_A_SPIN: unknown, 69 * - GCU_LOW_SPIN: low spin, 70 * - GCU_HIGH_SPIN: high spin. 71 * 72 * This enumeration is used in the GcuAtomicRadius structure. 73 */ 74 enum gcu_spin_state 75 { 76 GCU_N_A_SPIN, 77 GCU_LOW_SPIN, 78 GCU_HIGH_SPIN 79 }; 80 81 /** gcu_radius_type 82 * gcu_radius_type describes the type of the atomic radius 83 * Possible values are: 84 * - GCU_RADIUS_UNKNOWN: unknown,. 85 * - GCU_ATOMIC: atomic radius, 86 * - GCU_IONIC: ionic radius, 87 * - GCU_METALLIC: metallic radius, 88 * - GCU_COVALENT: covalent radius, 89 * - GCU_VAN_DER_WAALS: van der Waals radius, 90 * 91 * This enumeration is used in the GcuAtomicRadius structure. 92 */ 93 enum gcu_radius_type 94 { 95 GCU_RADIUS_UNKNOWN, 96 GCU_ATOMIC, 97 GCU_IONIC, 98 GCU_METALLIC, 99 GCU_COVALENT, 100 GCU_VAN_DER_WAALS 101 }; 102 103 /** GcuValue 104 Structure used to store a numerical value. 105 */ 106 typedef struct 107 { 108 /** The value. */ 109 double value; 110 /** The precision (number of significative decimal figures). */ 111 int prec; 112 /** The standard error (* 10^prec). */ 113 int delta; 114 } GcuValue; 115 116 /** GcuDimensionalValue 117 Structure used to store a dimensional value. 118 */ 119 typedef struct 120 { 121 /** The value.*/ 122 double value; 123 /** The precision (number of significative decimal figures).*/ 124 int prec; 125 /** The standard error (* 10^prec). */ 126 int delta; 127 /** The unit symbol.*/ 128 const char *unit; 129 } GcuDimensionalValue; 130 131 /** GcuAtomicRadius 132 * Structure used to describe an atomic radius. 133 */ 134 typedef struct 135 { 136 /** The atomic number. */ 137 unsigned char Z; 138 /** The radius type (unknown, ionic, metallic, covalent, or van der Waals).*/ 139 enum gcu_radius_type type; 140 /** The radius value (the unit should always be pm). */ 141 GcuDimensionalValue value; 142 /** The charge of the atom (or ion). */ 143 char charge; 144 /** The scale name, e.g. "Pauling" or "Shannon". */ 145 char const* scale; 146 /** the coordination number of the atom or -1 if unknown. */ 147 char cn; //coordination number: -1: unspecified 148 /** The spin state (unknown, low or high).*/ 149 enum gcu_spin_state spin; 150 } GcuAtomicRadius; 151 152 /*! GcuElectronegativity 153 Structure used to describe an electronegativity value. 154 */ 155 typedef struct 156 { 157 /** The atomic number. */ 158 unsigned char Z; 159 /*! The electronegativity value.*/ 160 GcuValue value; 161 /** The scale name, e.g. "Pauling" or "Mulliken". */ 162 char const *scale; 163 } GcuElectronegativity; 164 165 /*! GcuIsotope 166 Structure used to describe an isotope 167 */ 168 typedef struct 169 { 170 /** The nucleon number. */ 171 unsigned char A; 172 /** The name of the isotope if any.*/ 173 char *name; 174 /*! The terrestrial percent abundance.*/ 175 GcuValue abundance; 176 /*! The mass of an atom in atomic units.*/ 177 GcuValue mass; 178 /*! The spin of an atom multipiled by 2.*/ 179 char spin; 180 /*! The decay modes as a comma separated list.*/ 181 char *decay_modes; 182 /*! The decay period.*/ 183 GcuDimensionalValue decay_period; 184 } GcuIsotope; 185 186 /*! 187 \param Z: the atomic number of the element. 188 189 Retrieves the default color used for the element. 190 \return an array of three double values for the red, green and blue components of the color. 191 */ 192 const double* gcu_element_get_default_color (int Z); 193 /*! 194 gcu_element_get_symbol: 195 \param Z: the atomic number of the element. 196 \return the symbol of the element. 197 */ 198 const char* gcu_element_get_symbol (int Z); 199 /*! 200 \param Z: the atomic number of the element. 201 \return the name of the element in the current locale or in english if the current locale is not supported in the database. 202 */ 203 const char* gcu_element_get_name (int Z); 204 /*! 205 gcu_element_get_Z: 206 \param symbol: the symbol of the element (e.g. "C" ot "Pt"). 207 \return the atomic number of the element. 208 */ 209 int gcu_element_get_Z (char const *symbol); 210 /*! 211 \param radius: a pointer to a GcuAtomicRadius structure. 212 213 Before calling this function, most fields in the GcuAtomicRadius structure must be filled: 214 - Z: the atomic number, mandatory 215 - type: the type of the radius searched 216 - charge: the charge of the atom. 0 for all radii except ionic radii. 217 - cn: the coordination number or -1 if not significant 218 - spin: the spin state or GCU_N_A_SPIN if not significant 219 - scale: the name of the scale (e.g. "Pauling") or NULL 220 221 The programs searches a value corresponding to the fields having a non default value. If one is found 222 the other fields are given the corresponding values f the first match before returning. 223 224 \return TRUE if a radius has been found and FALSE if not. 225 226 */ 227 int gcu_element_get_radius (GcuAtomicRadius* radius); 228 /*! 229 \param en: a pointer to a GcuElectronegativity structure. 230 231 Before calling this function, the following fields in the GcuElectronegativity structure must be filled: 232 - Z: the atomic number, mandatory 233 - scale: the name of the scale (e.g. "Pauling") or NULL 234 235 The programs searches an electronegativity value for the element in the scale if given. If one is found 236 the value and the scale (if NULL on calling) are given the corresponding values of the first match before returning. 237 238 \return TRUE if a match has been found and FALSE if not. 239 */ 240 int gcu_element_get_electronegativity (GcuElectronegativity* en); 241 /*! 242 \param Z: the atomic number. 243 \param N: the rank of the ionization. 244 245 The program searches for the Nth ionization energy value for the element and returns 246 it if found. 247 248 \return the ionization energy as a GcuDimensionalValue if known or NULL. 249 */ 250 GcuDimensionalValue const *gcu_element_get_ionization_energy (int Z, int N); 251 /*! 252 \param Z: the atomic number. 253 \param N: the rank of the extra electron. 254 255 For some elements, second and even third electron affinities have been estimated. 256 The program searches the Nth electron affinity value for the element and returns 257 it if found. 258 A value of 0 means that the anion is unstable in the gaseous phase and that no better 259 etimation is available. 260 261 \return the electronic affinity as a GcuDimensionalValue if known or NULL. 262 */ 263 GcuDimensionalValue const *gcu_element_get_electron_affinity (int Z, int N); 264 /*! 265 \param Z: the atomic number. 266 267 \return the atomic weight as a string without units which needs to be freed with a g_free() call. 268 */ 269 char *gcu_element_get_weight_as_string (int Z); 270 /*! 271 \param Z: the atomic number. 272 273 \return the atomic weight. 274 */ 275 double gcu_element_get_weight (int Z); 276 /*! 277 \param Z: the atomic number. 278 279 \return the electronic configuration as a pango markup. 280 */ 281 char const *gcu_element_get_electronic_configuration (int Z); 282 /*! 283 \param Z: the atomic number of the element. 284 285 \return a pointer to the array of pointers to GcuAtomicRadius structures for all known radii for the element. 286 Last value in the array is NULL. 287 */ 288 const GcuAtomicRadius** gcu_element_get_radii (int Z); 289 /*! 290 \param Z: the atomic number of the element. 291 292 \return a pointer to the array of pointers to GcuElectronegativity structures for all known electronegativities for the element. 293 Last value in the array is NULL. 294 */ 295 const GcuElectronegativity** gcu_element_get_electronegativities (int Z); 296 /*! 297 \param name: name of a database to load such as "radii", "elecprops", "isotopes", 298 the first name is followed by a list of other database terminated by NULL. 299 300 Loads the listed databases. 301 */ 302 void gcu_element_load_databases (char const *name, ...); 303 304 /*! 305 \param value: the GcuValue to represent as a string. 306 307 \return the GcuValue as a string taking into account the precision and 308 incertitude 309 */ 310 char* gcu_value_get_string (GcuValue const *value); 311 312 /*! 313 \param value: the GcuDimensionalValue to represent as a string. 314 315 \return the GcuDimensionalValue as a string taking into account the precision and 316 incertitude 317 */ 318 char* gcu_dimensional_value_get_string (GcuDimensionalValue const *value); 319 320 #ifdef __cplusplus 321 } // extern "C" 322 #endif 323 324 #endif //GCU_CHEMISTRY_H 325