RDKit
Open-source cheminformatics and machine learning.
Bond.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2014 Greg Landrum and Rational Discovery LLC
3 //
4 // @@ All Rights Reserved @@
5 // This file is part of the RDKit.
6 // The contents are covered by the terms of the BSD license
7 // which is included in the file license.txt, found at the root
8 // of the RDKit source tree.
9 //
10 #ifndef _RD_BOND_H
11 #define _RD_BOND_H
12 
13 // std stuff
14 #include <iostream>
15 
16 // Ours
17 // FIX: grn...
18 #include <Query/QueryObjects.h>
19 #include <RDGeneral/types.h>
20 #include <GraphMol/details.h>
21 #include <boost/foreach.hpp>
22 
23 namespace RDKit{
24  class ROMol;
25  class RWMol;
26  class Atom;
27  typedef boost::shared_ptr<Atom> ATOM_SPTR;
28 
29  //! class for representing a bond
30  /*!
31 
32  <b>Notes:</b>
33  - many of the methods of Atom require that the Atom be associated
34  with a molecule (an ROMol).
35  - each Bond maintains a Dict of \c properties:
36  - Each \c property is keyed by name and can store an
37  arbitrary type.
38  - \c Properties can be marked as \c calculated, in which case
39  they will be cleared when the \c clearComputedProps() method
40  is called.
41  - Because they have no impact upon chemistry, all \c property
42  operations are \c const, this allows extra flexibility for
43  clients who need to store extra data on Bond objects.
44 
45  */
46  class Bond {
47  friend class RWMol;
48  friend class ROMol;
49  public:
50  typedef boost::shared_ptr<Bond> BOND_SPTR;
51  // FIX: grn...
53 
54  //! the type of Bond
55  typedef enum {
72  DATIVEONE, //!< one-electron dative (e.g. from a C in a Cp ring to a metal)
73  DATIVE, //!< standard two-electron dative
74  DATIVEL, //!< standard two-electron dative
75  DATIVER, //!< standard two-electron dative
77  ZERO //!< Zero-order bond (from http://pubs.acs.org/doi/abs/10.1021/ci200488k)
78  } BondType;
79 
80  //! the bond's direction (for chirality)
81  typedef enum {
82  NONE=0, //!< no special style
83  BEGINWEDGE, //!< wedged: narrow at begin
84  BEGINDASH, //!< dashed: narrow at begin
85  // FIX: this may not really be adequate
86  ENDDOWNRIGHT, //!< for cis/trans
87  ENDUPRIGHT, //!< ditto
88  EITHERDOUBLE, //!< a "crossed" double bond
89  UNKNOWN, //!< intentionally unspecified stereochemistry
90  } BondDir;
91 
92  //! the nature of the bond's stereochem (for cis/trans)
93  typedef enum { // stereochemistry of double bonds
94  STEREONONE=0, // no special style
95  STEREOANY, // intentionally unspecified
96  // -- Put any true specifications about this point so
97  // that we can do comparisons like if(bond->getStereo()>Bond::STEREOANY)
98  STEREOZ, // Z double bond
99  STEREOE, // E double bond
100  } BondStereo;
101 
102  Bond();
103  //! construct with a particular BondType
104  explicit Bond(BondType bT);
105  Bond(const Bond &other);
106  virtual ~Bond();
107  Bond &operator=(const Bond &other);
108 
109  //! returns a copy
110  /*!
111  <b>Note:</b> the caller is responsible for <tt>delete</tt>ing
112  the returned pointer.
113  */
114  virtual Bond *copy() const;
115 
116  //! returns our \c bondType
117  BondType getBondType() const { return static_cast<BondType>(d_bondType); };
118  //! sets our \c bondType
119  void setBondType(BondType bT) { d_bondType = bT; };
120  //! \brief returns our \c bondType as a double
121  //! (e.g. SINGLE->1.0, AROMATIC->1.5, etc.)
122  double getBondTypeAsDouble() const;
123 
124  //! returns our contribution to the explicit valence of an Atom
125  /*!
126  <b>Notes:</b>
127  - requires an owning molecule
128  */
129  double getValenceContrib(const Atom *at) const;
130  // \overload
131  double getValenceContrib(ATOM_SPTR at) const;
132 
133  //! sets our \c isAromatic flag
134  void setIsAromatic( bool what ) { df_isAromatic = what; };
135  //! returns the status of our \c isAromatic flag
136  bool getIsAromatic() const { return df_isAromatic; };
137 
138  //! sets our \c isConjugated flag
139  void setIsConjugated(bool what) {df_isConjugated = what;};
140  //! returns the status of our \c isConjugated flag
141  bool getIsConjugated() const {return df_isConjugated;};
142 
143  //! returns a reference to the ROMol that owns this Bond
144  ROMol &getOwningMol() const { return *dp_mol; };
145  //! sets our owning molecule
146  void setOwningMol(ROMol *other);
147  //! sets our owning molecule
148  void setOwningMol(ROMol &other) {setOwningMol(&other);};
149 
150  //! returns our index within the ROMol
151  /*!
152  <b>Notes:</b>
153  - this makes no sense if we do not have an owning molecule
154 
155  */
156  unsigned int getIdx() const {return d_index;};
157  //! sets our index within the ROMol
158  /*!
159  <b>Notes:</b>
160  - this makes no sense if we do not have an owning molecule
161  - the index should be <tt>< this->getOwningMol()->getNumBonds()</tt>
162  */
163  void setIdx(unsigned int index) {d_index=index;};
164 
165  //! returns the index of our begin Atom
166  /*!
167  <b>Notes:</b>
168  - this makes no sense if we do not have an owning molecule
169  */
170  unsigned int getBeginAtomIdx() const { return d_beginAtomIdx; };
171 
172  //! returns the index of our end Atom
173  /*!
174  <b>Notes:</b>
175  - this makes no sense if we do not have an owning molecule
176  */
177  unsigned int getEndAtomIdx() const { return d_endAtomIdx; };
178 
179  //! given the index of one Atom, returns the index of the other
180  /*!
181  <b>Notes:</b>
182  - this makes no sense if we do not have an owning molecule
183  */
184  unsigned int getOtherAtomIdx(unsigned int thisIdx) const;
185 
186  //! sets the index of our begin Atom
187  /*!
188  <b>Notes:</b>
189  - requires an owning molecule
190  */
191  void setBeginAtomIdx(unsigned int what);
192  //! sets the index of our end Atom
193  /*!
194  <b>Notes:</b>
195  - requires an owning molecule
196  */
197  void setEndAtomIdx(unsigned int what);
198 
199  //! sets our begin Atom
200  /*!
201  <b>Notes:</b>
202  - requires an owning molecule
203  */
204  void setBeginAtom(Atom *at);
205  //! \overload
206  void setBeginAtom(ATOM_SPTR at);
207  //! sets our end Atom
208  /*!
209  <b>Notes:</b>
210  - requires an owning molecule
211  */
212  void setEndAtom(Atom *at);
213  //! \overload
214  void setEndAtom(ATOM_SPTR at);
215 
216 
217  //! returns a pointer to our begin Atom
218  /*!
219  <b>Notes:</b>
220  - requires an owning molecule
221  */
222  Atom *getBeginAtom() const;
223  //! returns a pointer to our end Atom
224  /*!
225  <b>Notes:</b>
226  - requires an owning molecule
227  */
228  Atom *getEndAtom() const;
229  //! returns a pointer to the other Atom
230  /*!
231  <b>Notes:</b>
232  - requires an owning molecule
233  */
234  Atom *getOtherAtom(Atom const *what) const;
235 
236  // ------------------------------------
237  // Please see the note in Atom.h for some explanation
238  // of these methods
239  // ------------------------------------
240 
241  // This method can be used to distinguish query bonds from standard bonds
242  virtual bool hasQuery() const { return false; };
243 
244  // FIX: the const crap here is all mucked up.
245  //! NOT CALLABLE
246  virtual void setQuery(QUERYBOND_QUERY *what);
247  //! NOT CALLABLE
248  virtual QUERYBOND_QUERY *getQuery() const;
249 
250  //! NOT CALLABLE
251  virtual void expandQuery(QUERYBOND_QUERY *what,
253  bool maintainOrder=true);
254 
255  //! returns whether or not we match the argument
256  /*!
257  <b>Notes:</b>
258  - for Bond objects, "match" means that either one of the Bonds
259  has \c bondType Bond::UNSPECIFIED or both Bonds have the
260  same \c bondType.
261  */
262  virtual bool Match(Bond const *what) const;
263  //! \overload
264  virtual bool Match(const Bond::BOND_SPTR what) const;
265 
266  //! sets our direction
267  void setBondDir(BondDir what) { d_dirTag = what; };
268  //! returns our direction
269  BondDir getBondDir() const { return static_cast<BondDir>(d_dirTag); };
270 
271  //! sets our stereo code
272  void setStereo(BondStereo what) { d_stereo = what; };
273  //! returns our stereo code
274  BondStereo getStereo() const { return static_cast<BondStereo>(d_stereo); };
275 
276  //! returns the indices of our stereo atoms
277  const INT_VECT &getStereoAtoms() const {
278  if(!dp_stereoAtoms){
279  const_cast<Bond *>(this)->dp_stereoAtoms = new INT_VECT();
280  }
281  return *dp_stereoAtoms;
282  };
283  //! \overload
286  return *dp_stereoAtoms;
287  };
288 
289  // ------------------------------------
290  // Local Property Dict functionality
291  // FIX: at some point this stuff should go in a mixin class
292  // ------------------------------------
293  //! returns a list with the names of our \c properties
295  return dp_props->keys();
296  }
297 
298  //! sets a \c property value
299  /*!
300  \param key the name under which the \c property should be stored.
301  If a \c property is already stored under this name, it will be
302  replaced.
303  \param val the value to be stored
304  \param computed (optional) allows the \c property to be flagged
305  \c computed.
306  */
307  template <typename T>
308  void setProp(const char *key,T val, bool computed=false) const{
309  //if(!dp_props) dp_props = new Dict();
310  std::string what(key);
311  setProp(what,val, computed);
312  }
313  //! \overload
314  template <typename T>
315  void setProp(const std::string &key,T val, bool computed=false ) const{
316  //setProp(key.c_str(),val);
317  if (computed) {
318  STR_VECT compLst;
320  if (std::find(compLst.begin(), compLst.end(), key) == compLst.end()) {
321  compLst.push_back(key);
323  }
324  }
325  dp_props->setVal(key,val);
326  }
327 
328  //! allows retrieval of a particular property value
329  /*!
330 
331  \param key the name under which the \c property should be stored.
332  If a \c property is already stored under this name, it will be
333  replaced.
334  \param res a reference to the storage location for the value.
335 
336  <b>Notes:</b>
337  - if no \c property with name \c key exists, a KeyErrorException will be thrown.
338  - the \c boost::lexical_cast machinery is used to attempt type conversions.
339  If this fails, a \c boost::bad_lexical_cast exception will be thrown.
340 
341  */
342  template <typename T>
343  void getProp(const char *key,T &res) const {
344  PRECONDITION(dp_props,"getProp called on empty property dict");
345  dp_props->getVal(key,res);
346  }
347  //! \overload
348  template <typename T>
349  void getProp(const std::string &key,T &res) const {
350  PRECONDITION(dp_props,"getProp called on empty property dict");
351  dp_props->getVal(key,res);
352  }
353 
354  //! \Overload
355  template <typename T>
356  T getProp(const char *key) const {
357  return dp_props->getVal<T>(key);
358  }
359  //! \overload
360  template <typename T>
361  T getProp(const std::string &key) const {
362  return dp_props->getVal<T>(key);
363  }
364 
365  //! returns whether or not we have a \c property with name \c key
366  //! and assigns the value if we do
367 
368  template <typename T>
369  bool getPropIfPresent(const char *key,T &res) const {
370  return dp_props->getValIfPresent(key,res);
371  }
372  //! \overload
373  template <typename T>
374  bool getPropIfPresent(const std::string &key,T &res) const {
375  return dp_props->getValIfPresent(key,res);
376  }
377 
378  //! returns whether or not we have a \c property with name \c key
379  bool hasProp(const char *key) const {
380  if(!dp_props) return false;
381  return dp_props->hasVal(key);
382  };
383  //! \overload
384  bool hasProp(const std::string &key) const {
385  if(!dp_props) return false;
386  return dp_props->hasVal(key);
387  };
388 
389  //! clears the value of a \c property
390  /*!
391  <b>Notes:</b>
392  - if no \c property with name \c key exists, a KeyErrorException
393  will be thrown.
394  - if the \c property is marked as \c computed, it will also be removed
395  from our list of \c computedProperties
396  */
397  void clearProp(const char *key) const {
398  std::string what(key);
399  clearProp(what);
400  };
401  //! \overload
402  void clearProp(const std::string &key) const {
403  STR_VECT compLst;
405  STR_VECT_I svi = std::find(compLst.begin(), compLst.end(), key);
406  if (svi != compLst.end()) {
407  compLst.erase(svi);
409  }
410  }
411  dp_props->clearVal(key);
412  }
413 
414  //! clears all of our \c computed \c properties
415  void clearComputedProps() const {
416  STR_VECT compLst;
418  BOOST_FOREACH(const std::string &sv,compLst){
419  dp_props->clearVal(sv);
420  }
421  compLst.clear();
423  }
424  }
425 
426  //! calculates any of our lazy \c properties
427  /*!
428  <b>Notes:</b>
429  - requires an owning molecule
430  */
431  void updatePropertyCache(bool strict=true) { (void)strict; }
432 
433  protected:
434  //! sets our owning molecule
435  //void setOwningMol(ROMol *other);
436  //! sets our owning molecule
437  //void setOwningMol(ROMol &other) {setOwningMol(&other);};
440  boost::uint8_t d_bondType;
441  boost::uint8_t d_dirTag;
442  boost::uint8_t d_stereo;
448 
449  void initBond();
450  };
451 
452 };
453 
454 //! allows Bond objects to be dumped to streams
455 extern std::ostream & operator<<(std::ostream& target, const RDKit::Bond &b);
456 
457 #endif
void initBond()
void setBeginAtomIdx(unsigned int what)
sets the index of our begin Atom
boost::uint8_t d_stereo
Definition: Bond.h:442
Queries::Query< int, Bond const *, true > QUERYBOND_QUERY
Definition: Bond.h:52
void setVal(const std::string &what, T &val)
Sets the value associated with a key.
Definition: Dict.h:170
double getValenceContrib(const Atom *at) const
returns our contribution to the explicit valence of an Atom
bool hasProp(const char *key) const
returns whether or not we have a property with name key
Definition: Bond.h:379
bool getPropIfPresent(const std::string &key, T &res) const
Definition: Bond.h:374
std::ostream & operator<<(std::ostream &target, const RDKit::Bond &b)
allows Bond objects to be dumped to streams
void setProp(const std::string &key, T val, bool computed=false) const
Definition: Bond.h:315
STR_VECT keys() const
Returns the set of keys in the dictionary.
Definition: Dict.h:63
CompositeQueryType
Definition: QueryObjects.h:35
RWMol is a molecule class that is intended to be edited.
Definition: RWMol.h:30
virtual bool Match(Bond const *what) const
returns whether or not we match the argument
STR_VECT getPropList() const
returns a list with the names of our properties
Definition: Bond.h:294
void getProp(const char *key, T &res) const
allows retrieval of a particular property value
Definition: Bond.h:343
bool df_isAromatic
sets our owning molecule
Definition: Bond.h:438
bool getValIfPresent(const std::string &what, T &res) const
Potentially gets the value associated with a particular key returns true on success/false on failure...
Definition: Dict.h:134
void clearComputedProps() const
clears all of our computed properties
Definition: Bond.h:415
void clearProp(const char *key) const
clears the value of a property
Definition: Bond.h:397
BondDir getBondDir() const
returns our direction
Definition: Bond.h:269
BondStereo getStereo() const
returns our stereo code
Definition: Bond.h:274
T getProp(const std::string &key) const
Definition: Bond.h:361
boost::shared_ptr< Atom > ATOM_SPTR
Definition: Bond.h:26
ROMol * dp_mol
Definition: Bond.h:445
BondStereo
the nature of the bond&#39;s stereochem (for cis/trans)
Definition: Bond.h:93
void getProp(const std::string &key, T &res) const
Definition: Bond.h:349
void setIsConjugated(bool what)
sets our isConjugated flag
Definition: Bond.h:139
BondType
the type of Bond
Definition: Bond.h:55
void setBondType(BondType bT)
sets our bondType
Definition: Bond.h:119
bool hasProp(const std::string &key) const
Definition: Bond.h:384
unsigned int getOtherAtomIdx(unsigned int thisIdx) const
given the index of one Atom, returns the index of the other
ROMol is a molecule class that is intended to have a fixed topology.
Definition: ROMol.h:105
unsigned int getBeginAtomIdx() const
returns the index of our begin Atom
Definition: Bond.h:170
intentionally unspecified stereochemistry
Definition: Bond.h:89
standard two-electron dative
Definition: Bond.h:75
void clearVal(const std::string &what)
Clears the value associated with a particular key, removing the key from the dictionary.
Definition: Dict.h:198
void getVal(const std::string &what, T &res) const
Gets the value associated with a particular key.
Definition: Dict.h:86
void setIdx(unsigned int index)
sets our index within the ROMol
Definition: Bond.h:163
bool getIsConjugated() const
returns the status of our isConjugated flag
Definition: Bond.h:141
virtual bool hasQuery() const
Definition: Bond.h:242
Atom * getOtherAtom(Atom const *what) const
returns a pointer to the other Atom
INT_VECT * dp_stereoAtoms
Definition: Bond.h:447
virtual void expandQuery(QUERYBOND_QUERY *what, Queries::CompositeQueryType how=Queries::COMPOSITE_AND, bool maintainOrder=true)
NOT CALLABLE.
T getProp(const char *key) const
Definition: Bond.h:356
void clearProp(const std::string &key) const
Definition: Bond.h:402
std::vector< int > INT_VECT
Definition: types.h:146
void setIsAromatic(bool what)
sets our isAromatic flag
Definition: Bond.h:134
boost::uint8_t d_bondType
Definition: Bond.h:440
Atom * getEndAtom() const
returns a pointer to our end Atom
Includes a bunch of functionality for handling Atom and Bond queries.
Definition: Atom.h:28
unsigned int getEndAtomIdx() const
returns the index of our end Atom
Definition: Bond.h:177
void updatePropertyCache(bool strict=true)
calculates any of our lazy properties
Definition: Bond.h:431
const std::string computedPropName
Definition: types.h:25
INT_VECT & getStereoAtoms()
Definition: Bond.h:284
virtual QUERYBOND_QUERY * getQuery() const
NOT CALLABLE.
atomindex_t d_index
Definition: Bond.h:443
void setStereo(BondStereo what)
sets our stereo code
Definition: Bond.h:272
standard two-electron dative
Definition: Bond.h:73
bool df_isConjugated
Definition: Bond.h:439
class for representing a bond
Definition: Bond.h:46
bool hasVal(const char *what) const
Returns whether or not the dictionary contains a particular key.
Definition: Dict.h:50
void setOwningMol(ROMol *other)
sets our owning molecule
Zero-order bond (from http://pubs.acs.org/doi/abs/10.1021/ci200488k)
Definition: Bond.h:77
double getBondTypeAsDouble() const
returns our bondType as a double (e.g. SINGLE->1.0, AROMATIC->1.5, etc.)
standard two-electron dative
Definition: Bond.h:74
void setBeginAtom(Atom *at)
sets our begin Atom
BondDir
the bond&#39;s direction (for chirality)
Definition: Bond.h:81
atomindex_t d_beginAtomIdx
Definition: Bond.h:444
void setEndAtomIdx(unsigned int what)
sets the index of our end Atom
virtual ~Bond()
void setOwningMol(ROMol &other)
sets our owning molecule
Definition: Bond.h:148
const INT_VECT & getStereoAtoms() const
returns the indices of our stereo atoms
Definition: Bond.h:277
one-electron dative (e.g. from a C in a Cp ring to a metal)
Definition: Bond.h:72
boost::uint8_t d_dirTag
Definition: Bond.h:441
#define PRECONDITION(expr, mess)
Definition: Invariant.h:119
bool getIsAromatic() const
returns the status of our isAromatic flag
Definition: Bond.h:136
boost::uint16_t atomindex_t
Definition: details.h:13
bool getPropIfPresent(const char *key, T &res) const
Definition: Bond.h:369
no special style
Definition: Bond.h:82
wedged: narrow at begin
Definition: Bond.h:83
a "crossed" double bond
Definition: Bond.h:88
Bond & operator=(const Bond &other)
boost::shared_ptr< Bond > BOND_SPTR
Definition: Bond.h:50
Dict * dp_props
Definition: Bond.h:446
Pulls in all the query types.
std::vector< std::string >::iterator STR_VECT_I
Definition: types.h:168
void setEndAtom(Atom *at)
sets our end Atom
virtual Bond * copy() const
returns a copy
void setProp(const char *key, T val, bool computed=false) const
sets a property value
Definition: Bond.h:308
unsigned int getIdx() const
returns our index within the ROMol
Definition: Bond.h:156
Atom * getBeginAtom() const
returns a pointer to our begin Atom
void setBondDir(BondDir what)
sets our direction
Definition: Bond.h:267
ROMol & getOwningMol() const
returns a reference to the ROMol that owns this Bond
Definition: Bond.h:144
Base class for all queries.
Definition: Query.h:46
dashed: narrow at begin
Definition: Bond.h:84
The Dict class can be used to store objects of arbitrary type keyed by strings.
Definition: Dict.h:33
The class for representing atoms.
Definition: Atom.h:67
atomindex_t d_endAtomIdx
Definition: Bond.h:444
BondType getBondType() const
returns our bondType
Definition: Bond.h:117
std::vector< std::string > STR_VECT
Definition: Dict.h:26
virtual void setQuery(QUERYBOND_QUERY *what)
NOT CALLABLE.
for cis/trans
Definition: Bond.h:86