1 // -*- C++ -*- 2 3 /* 4 * Gnome Chemistry Utils 5 * atom.h 6 * 7 * Copyright (C) 2002-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 #ifndef GCU_ATOM_H 26 #define GCU_ATOM_H 27 28 #include "object.h" 29 #include <glib.h> 30 #include <map> 31 #include <vector> 32 33 /*!\file*/ 34 namespace gcu 35 { 36 37 class Bond; 38 class Cycle; 39 class AtomMatchState; 40 class Vector; 41 42 /*!\class Atom gcu/atom.h 43 This class is used to represent atoms. 44 45 */ 46 class Atom: public Object 47 { 48 public: 49 /*! 50 The default constructor. Creates an atom with atomic number set to -1. 51 */ 52 Atom (); 53 /*! 54 @param Z the atomic number of the new atom. 55 @param x the x coordinate of the new atom. 56 @param y the y coordinate of the new atom. 57 @param z the z coordinate of the new atom. 58 59 Creates an atom. 60 */ 61 Atom (int Z, double x, double y, double z = 0.); 62 /*! 63 @param a the Atom to duplicate. 64 65 Creates a new atom identical to a without any bond. 66 */ 67 Atom (Atom& a); 68 /*! 69 @param a the Atom to copy. 70 71 @return an Atom identical to a without any bond. 72 */ 73 Atom& operator= (Atom& a); 74 /*! 75 The destructor of Atom. It removes bonds but do not delete the associated Bond instances. 76 */ 77 virtual ~Atom (); 78 79 public : 80 /*! 81 @param pAtom a pointer to an Atom. 82 @return the distance between the Atom at pAtom and this Atom. 83 */ 84 double Distance (Atom* pAtom); 85 /*! 86 @param ZoomFactor the zoom factor. 87 88 Multiplies all three coordinates of this Atom by ZoomFactor. 89 */ 90 void zoom (double ZoomFactor); 91 /*! 92 @param x a pointer to the double value which will receive the x coordinate of the Atom. 93 @param y a pointer to the double value which will receive the y coordinate of the Atom. 94 @param z a pointer to the double value which will receive the z coordinate of the Atom or NULL for 2D representations. 95 96 Retrieves the coordinates of this Atom. 97 @return true if successful and false if an error occurs (if x or y is NULL). 98 */ 99 bool GetCoords (double *x, double *y, double *z = NULL) const; 100 /*! 101 @param x the new x coordinate of the Atom. 102 @param y the new y coordinate of the Atom. 103 @param z the new z coordinate of the Atom. 104 105 Changes the position of this Atom. 106 */ 107 void SetCoords (double x, double y, double z = 0) {m_x = x; m_y = y; m_z = z;} 108 /*! 109 @return the atomic number of the atom. 110 */ GetZ()111 int GetZ () const {return m_Z;} 112 /*! 113 @param Z the new atomic number of the Atom. 114 115 This method might be overrided by derived class since changing the atomic number generally changes most properties. 116 The default behavior is just to change the atomic number and nothing else. 117 */ 118 virtual void SetZ (int Z); 119 /*! 120 @param Charge the new formal charge of the Atom. 121 122 Changes the formal charge of this Atom. 123 */ SetCharge(char Charge)124 virtual void SetCharge (char Charge) {m_Charge = Charge;} 125 /*! 126 @return the formal charge of this Atom. 127 */ GetCharge()128 char GetCharge () {return m_Charge;} 129 /*! 130 @return the atomic symbol of this Atom or NULL if the element is unknown. 131 */ 132 virtual const gchar* GetSymbol () const; 133 /*! 134 @param pBond a pointer to the new Bond to this Atom. 135 136 Adds a Bond. 137 */ 138 virtual void AddBond (Bond* pBond); 139 /*! 140 @param pBond a pointer to the Bond to remove from this Atom. 141 142 Removes a Bond. 143 */ 144 virtual void RemoveBond (Bond* pBond); 145 /*! 146 @return the x coordinate of this Atom. 147 */ x()148 double x () const {return m_x;} x()149 double &x () {return m_x;} 150 /*! 151 @return the y coordinate of this Atom. 152 */ y()153 double y () const {return m_y;} y()154 double &y () {return m_y;} 155 /*! 156 @return the z coordinate of this Atom. 157 */ z()158 double z () const {return m_z;} z()159 double &z () {return m_z;} 160 /*! 161 @return a Vector with the three Atom space coordinates. 162 */ 163 Vector GetVector () const; 164 /*! 165 @param i a C++ std::map iterator. 166 167 Use this function to retrieve the first Bond of this Atom and initialize the iterator. 168 @return the first Bond of this Atom or NULL if the Atom has is not bonded. 169 */ 170 Bond *GetFirstBond (std::map < Atom *, Bond * >::iterator& i); 171 /*! 172 @param i a C++ std::map constant iterator. 173 174 Use this function to retrieve the first Bond of this constant Atom and initialize the iterator. 175 @return the first Bond of this Atom or NULL if the Atom has is not bonded. 176 */ 177 Bond const *GetFirstBond (std::map< Atom *, Bond * >::const_iterator& i) const; 178 /*! 179 @param i a C++ std::map iterator initialized by Atom::GetFirstBond. 180 181 Use this method to iterate through the list of Bond instances of this Atom. 182 @return the next Bond of this Atom or NULL. 183 */ 184 Bond *GetNextBond (std::map<Atom*, Bond*>::iterator& i); 185 /*! 186 @param i a C++ std::map constant iterator initialized by Atom::GetFirstBond(std::map< Atom *, Bond * >::const_iterator&). 187 188 Use this method to iterate through the list of Bond instances of this Atom. 189 @return the next Bond of this Atom or NULL. 190 */ 191 Bond const *GetNextBond (std::map< Atom *, Bond * >::const_iterator& i) const; 192 /*! 193 @param pAtom a pointer to an Atom instance. 194 @return a pointer to the Bond shared by pAtom and this Atom if it exists or NULL. 195 */ 196 Bond* GetBond (Atom* pAtom) const; 197 /*! 198 @return the number of Bond instances shared by this Atom. It does not take multiplicity of bonds into account. 199 */ GetBondsNumber()200 int GetBondsNumber () const {return m_Bonds.size();} 201 /*! 202 @param xml the xmlDoc used to save the document. 203 @return a pointer to the xmlNode representing this Atom or NULL if an error occured. 204 */ 205 virtual xmlNodePtr Save (xmlDocPtr xml) const; 206 /*! 207 @param node a pointer to the xmlNode containing the serialized Atom. 208 209 Loads an atom from an xmlNode. 210 */ 211 virtual bool Load (xmlNodePtr node); 212 /*! 213 @param node a pointer to the xmlNode containing the serialized Atom. 214 215 This virtual method is called at the end of the Atom::Load method. The default behavior is to do nothing. 216 It might be overrided for derived class when it is not convenient to override the Atom::Load method. 217 */ 218 virtual bool LoadNode (xmlNodePtr node); 219 /*! 220 @param xml the xmlDoc used to save the document. 221 @param node a pointer to the xmlNode to which this Atom is serialized. 222 223 This virtual method is called at the end of the Atom::Save method. The default behavior is to do nothing. 224 It might be overrided for derived class when it is not convenient to override the Atom::Save method. 225 */ 226 virtual bool SaveNode (xmlDocPtr xml, xmlNodePtr node) const; 227 /*! 228 @param x the x component of the transation vector. 229 @param y the y component of the transation vector. 230 @param z the z component of the transation vector. 231 232 Used to move an Atom. 233 */ 234 virtual void Move (double x, double y, double z = 0.); 235 /*! 236 @param m the 2D Matrix of the transformation. 237 @param x the x component of the center of the transformation. 238 @param y the y component of the center of the transformation. 239 240 Used to move and/or transform an atom. 241 */ 242 virtual void Transform2D (Matrix2D& m, double x, double y); 243 244 /*! 245 @param property the identity of the property as defined in objprops.h. 246 @param value the value of the property as a string. 247 248 Used by the gcu::Loader mechanism to load properties of atoms. 249 @return true on success. 250 */ 251 bool SetProperty (unsigned property, char const *value); 252 253 /*! 254 @param property the identity of the property as defined in objprops.h. 255 256 Used by the gcu::Loader mechanism to retrieve properties of atoms. 257 @return the value of the property as a string. 258 */ 259 std::string GetProperty (unsigned property) const; 260 261 /*! 262 @param pCycle a cycle in which the atom might be. 263 264 @return true if the atom lies in the cycle, false otherwise. 265 */ 266 bool IsInCycle (Cycle* pCycle); 267 268 /*! 269 @param atom the atom to which the this instance is to be compared. 270 @param state the AtomMatchState representing the current comparison state. 271 272 Try to match atoms from two molecules which are compared. This function calls 273 itself recursively until all atoms from the two molecules have been matched or 274 until an difference is found. Overriden methods should call this base function 275 and return its result. 276 @return true if the atoms match, false otherwise. 277 */ 278 virtual bool Match (Atom *atom, AtomMatchState &state); 279 280 /*! 281 @return the localized object generic name. 282 */ 283 std::string Name (); 284 285 /*! 286 @param a: the a parameter of the unit cell. 287 @param b: the b parameter of the unit cell. 288 @param c: the c parameter of the unit cell. 289 @param alpha: the alpha angle of the unit cell. 290 @param beta: the beta angle of the unit cell. 291 @param gamma: the gamma angle of the unit cell. 292 293 Converts the coordinates of the atom from net related ones to cartesian. Initially, atoms are defined by their 294 position relative to the unit cell and the coordinates must be transformed to the cartesian ones before 295 displaying the atom. 296 */ 297 void NetToCartesian (double a, double b, double c, double alpha, double beta, double gamma); 298 299 protected: 300 /*! 301 The atomic number of the Atom. 302 */ 303 int m_Z; 304 /*! 305 The x coordinate of the Atom. 306 */ 307 double m_x; 308 /*! 309 The x coordinate of the Atom. 310 */ 311 double m_y; 312 /*! 313 The x coordinate of the Atom. 314 */ 315 double m_z; 316 /*! 317 The charge of the Atom. 318 */ 319 char m_Charge; 320 /*! 321 The Bond instances of the Atom. The index of the map is a pointer to the other end of the Bond. 322 */ 323 std::map<Atom*, Bond*> m_Bonds; 324 }; 325 326 /*!\class AtomPair gcu/atom.h 327 This class stores atoms pairs. It is used when comparing two molecules. 328 329 */ 330 331 class AtomPair { 332 public: 333 334 /*! 335 @param at1 the first atom in the pair. 336 @param at2 the second atom in the pair. 337 338 Constructs the atoms pair from two atoms. 339 */ AtomPair(Atom * at1,Atom * at2)340 AtomPair (Atom *at1, Atom *at2) {atom1 = at1; atom2 = at2;} 341 342 /*! 343 The first atom of the pair. 344 */ 345 Atom *atom1; 346 347 /*! 348 The second atom of the pair. 349 */ 350 Atom *atom2; 351 }; 352 353 /*!\class AtomMatchState gcu/atom.h 354 This class is used when comparing molecules to store lists of corresponding atoms. 355 356 */ 357 358 class AtomMatchState 359 { 360 public: 361 362 /*! 363 This map gives the index of atoms from the first molecule in gcu::AtomMatchState::atoms. 364 */ 365 std::map <Atom*, int> mol1; 366 367 /*! 368 This map gives the index of atoms from the second molecule in gcu::AtomMatchState::atoms. 369 */ 370 std::map <Atom*, int> mol2; 371 372 /*! 373 The array of matched atoms. 374 */ 375 std::vector <AtomPair> atoms; 376 }; 377 378 } //namespace gcu 379 #endif // GCU_ATOM_H 380