1 // -*- C++ -*- 2 3 /* 4 * Gnome Chemistry Utils 5 * libs/gcu/chain.h 6 * 7 * Copyright (C) 2001-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_CHAIN_H 26 #define GCU_CHAIN_H 27 28 #include "object.h" 29 #include <map> 30 31 /*!\file*/ 32 namespace gcu { 33 34 class Atom; 35 class Bond; 36 class Molecule; 37 38 /*!\struct ChainElt gcu/chain.h 39 This structure stores the two bonds of sharing one atom in a chain. One 40 (or both) can be NULL if the atom is at start or end of the chain. 41 42 */ 43 typedef struct 44 { 45 /*! 46 The bond in the forward direction 47 */ 48 Bond *fwd; 49 /*! 50 The bond in the backward direction 51 */ 52 Bond *rev; 53 } ChainElt; 54 55 /*!\class Chain gcu/chain.h 56 This class is used to represent chains of atoms. 57 58 */ 59 class Chain: public Object 60 { 61 public: 62 /*! 63 @param pBond a bond. 64 @param pAtom an atom. 65 @param Type an optional type id used when constructing a derived type 66 (i. e. a cycle). 67 68 Constructs a Chain starting from a bond and an optional atom. Choosing the atom 69 forces the direction of the chain, otherwise, the first atom will be the 70 first atom of the bond. 71 */ 72 Chain (Bond* pBond, Atom* pAtom = NULL, TypeId Type = ChainType); 73 /*! 74 @param molecule a molecule. 75 @param pBond a bond in the molecule or NULL. 76 @param Type an optional type id used when constructing a derived type 77 78 Explores a molecule and find all cycles, starting from pBond or an empty chain 79 if pBond is NULL. 80 */ 81 Chain (Molecule* molecule, Bond* pBond, TypeId Type = ChainType); 82 /*! 83 @param molecule a molecule. 84 @param pAtom an atom in the molecule. 85 @param Type an optional type id used when constructing a derived type 86 87 Explores a molecule and find all cycles, starting from pAtom or an empty chain 88 if pAtom is NULL. 89 */ 90 Chain (Molecule* molecule, Atom* pAtom, TypeId Type = ChainType); 91 /*! 92 The destructor. 93 */ 94 virtual ~Chain(); 95 96 /*! 97 @param pAtom an atom. 98 99 Searches all cycles in a molecule starting from Atom pAtom. Found cycles are 100 added to the molecule cycles list. 101 */ 102 void FindCycles (Atom* pAtom); 103 /*! 104 @param pAtom an atom. 105 @param pBond a bond. 106 107 Searches for a cycle containing the atom pAtom and the bond pBond. pAtom must 108 be one of the ends of pBond. If a cycle is found, it is added to the molecule 109 cycles list. 110 @return true on success, false otherwise. 111 */ 112 bool FindCycle (Atom* pAtom, Bond* pBond); 113 /*! 114 @param pAtom1 an atom in the source chain. 115 @param pAtom2 an atom in the source chain. 116 117 Erases a sub-chain. One of the atoms must already be one of the chain ends. 118 */ 119 virtual void Erase (Atom* pAtom1, Atom* pAtom2); 120 /*! 121 @param pAtom1 an atom in the source chain. 122 @param pAtom2 an atom in the source chain. 123 @param chain the source chain. 124 125 Inserts a chain. One of the atoms must already be in the target chain. 126 */ 127 virtual void Insert (Atom* pAtom1, Atom* pAtom2, Chain& chain); 128 /*! 129 @param pAtom1 an atom in the chain. 130 @param pAtom2 an atom in the chain. 131 @param chain the target chain. 132 133 Extracts a sub-chain to the chain variable which should be empty before the call. 134 */ 135 void Extract (Atom* pAtom1, Atom* pAtom2, Chain& chain); 136 /*! 137 Reverses the chain order. 138 */ 139 void Reverse (); 140 void Append (Chain& chain); 141 /*! 142 @param start an atom. 143 @param end an atom. 144 145 Adds the two atoms and the bond between them to the chain. The two atoms must be bonded. 146 */ 147 void AddBond (Atom* start, Atom* end); 148 /*! 149 @return the number of multiple bonds in the chain so not really the unsaturations number. 150 */ 151 unsigned GetUnsaturations (); 152 /*! 153 @return the number of heteroatoms in the chain. 154 */ 155 unsigned GetHeteroatoms (); 156 /*! 157 @param pAtom an atom. 158 159 @return true if pAtom is in the chain. 160 */ 161 bool Contains (Atom* pAtom); 162 /*! 163 @param pBond a bond. 164 165 @return true if pBond is in the chain. 166 */ 167 bool Contains (Bond* pBond); 168 /*! 169 @return the number of bonds in the chain 170 */ 171 unsigned GetLength (); 172 /*! 173 @return the mean bond length in the chain. 174 */ 175 double GetMeanBondLength (); 176 /*! 177 @return the first atom in the chain if any. 178 */ 179 Atom* GetFirstAtom (); 180 /*! 181 @param pAtom an atom in the chain. 182 @return the next atom in the chain or NULL if pAtom is the last one. 183 */ 184 Atom* GetNextAtom (Atom* pAtom); 185 186 /*! 187 @return the localized object generic name. 188 */ 189 std::string Name (); 190 191 /*! 192 @param cycle_size where to store a cycle size if a cycle is encountered 193 @param cycle_pos where to store a cycle position if a cycle is encountered 194 195 Finds the longest chani starting from first bond and ending when a cycle is 196 found or at the chain end. 197 @return the evaluated chain length. 198 */ 199 unsigned BuildLength (unsigned *cycle_size = NULL, unsigned *cycle_pos = NULL); 200 201 protected: 202 /*! 203 The gcu::ChainElt elements in the chain indexed by their common atom. 204 */ 205 std::map<Atom*, ChainElt> m_Bonds; 206 /*! 207 The molecule which owns the chain. 208 */ 209 Molecule* m_Molecule; 210 }; 211 212 } // namespace gcu 213 214 #endif // GCHEMPAINT_CHAIN_H 215