RDKit
Open-source cheminformatics and machine learning.
Bond.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2017 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 #include <RDGeneral/Invariant.h>
18 #include <Query/QueryObjects.h>
19 #include <RDGeneral/types.h>
20 #include <RDGeneral/RDProps.h>
21 #include <GraphMol/details.h>
22 #include <boost/foreach.hpp>
23 
24 namespace RDKit {
25 class ROMol;
26 class RWMol;
27 class Atom;
28 typedef boost::shared_ptr<Atom> ATOM_SPTR;
29 
30 //! class for representing a bond
31 /*!
32 
33  <b>Notes:</b>
34  - many of the methods of Atom require that the Atom be associated
35  with a molecule (an ROMol).
36  - each Bond maintains a Dict of \c properties:
37  - Each \c property is keyed by name and can store an
38  arbitrary type.
39  - \c Properties can be marked as \c calculated, in which case
40  they will be cleared when the \c clearComputedProps() method
41  is called.
42  - Because they have no impact upon chemistry, all \c property
43  operations are \c const, this allows extra flexibility for
44  clients who need to store extra data on Bond objects.
45 
46 */
47 class Bond : public RDProps {
48  friend class RWMol;
49  friend class ROMol;
50 
51  public:
52  typedef boost::shared_ptr<Bond> BOND_SPTR;
53  // FIX: grn...
55 
56  //! the type of Bond
57  typedef enum {
74  DATIVEONE, //!< one-electron dative (e.g. from a C in a Cp ring to a metal)
75  DATIVE, //!< standard two-electron dative
76  DATIVEL, //!< standard two-electron dative
77  DATIVER, //!< standard two-electron dative
79  ZERO //!< Zero-order bond (from
80  // http://pubs.acs.org/doi/abs/10.1021/ci200488k)
81  } BondType;
82 
83  //! the bond's direction (for chirality)
84  typedef enum {
85  NONE = 0, //!< no special style
86  BEGINWEDGE, //!< wedged: narrow at begin
87  BEGINDASH, //!< dashed: narrow at begin
88  // FIX: this may not really be adequate
89  ENDDOWNRIGHT, //!< for cis/trans
90  ENDUPRIGHT, //!< ditto
91  EITHERDOUBLE, //!< a "crossed" double bond
92  UNKNOWN, //!< intentionally unspecified stereochemistry
93  } BondDir;
94 
95  //! the nature of the bond's stereochem (for cis/trans)
96  typedef enum { // stereochemistry of double bonds
97  STEREONONE = 0, // no special style
98  STEREOANY, // intentionally unspecified
99  // -- Put any true specifications about this point so
100  // that we can do comparisons like if(bond->getStereo()>Bond::STEREOANY)
101  STEREOZ, // Z double bond
102  STEREOE, // E double bond
103  STEREOCIS, // cis double bond
104  STEREOTRANS // trans double bond
105  } BondStereo;
106 
107  Bond();
108  //! construct with a particular BondType
109  explicit Bond(BondType bT);
110  Bond(const Bond &other);
111  virtual ~Bond();
112  Bond &operator=(const Bond &other);
113 
114  //! returns a copy
115  /*!
116  <b>Note:</b> the caller is responsible for <tt>delete</tt>ing
117  the returned pointer.
118  */
119  virtual Bond *copy() const;
120 
121  //! returns our \c bondType
122  BondType getBondType() const { return static_cast<BondType>(d_bondType); };
123  //! sets our \c bondType
124  void setBondType(BondType bT) { d_bondType = bT; };
125  //! \brief returns our \c bondType as a double
126  //! (e.g. SINGLE->1.0, AROMATIC->1.5, etc.)
127  double getBondTypeAsDouble() const;
128 
129  //! returns our contribution to the explicit valence of an Atom
130  /*!
131  <b>Notes:</b>
132  - requires an owning molecule
133  */
134  double getValenceContrib(const Atom *at) const;
135  // \overload
136  double getValenceContrib(ATOM_SPTR at) const;
137 
138  //! sets our \c isAromatic flag
139  void setIsAromatic(bool what) { df_isAromatic = what; };
140  //! returns the status of our \c isAromatic flag
141  bool getIsAromatic() const { return df_isAromatic; };
142 
143  //! sets our \c isConjugated flag
144  void setIsConjugated(bool what) { df_isConjugated = what; };
145  //! returns the status of our \c isConjugated flag
146  bool getIsConjugated() const { return df_isConjugated; };
147 
148  //! returns a reference to the ROMol that owns this Bond
149  ROMol &getOwningMol() const {
150  PRECONDITION(dp_mol, "no owner");
151  return *dp_mol;
152  };
153  //! sets our owning molecule
154  void setOwningMol(ROMol *other);
155  //! sets our owning molecule
156  void setOwningMol(ROMol &other) { setOwningMol(&other); };
157 
158  //! returns our index within the ROMol
159  /*!
160  <b>Notes:</b>
161  - this makes no sense if we do not have an owning molecule
162 
163  */
164  unsigned int getIdx() const { return d_index; };
165  //! sets our index within the ROMol
166  /*!
167  <b>Notes:</b>
168  - this makes no sense if we do not have an owning molecule
169  - the index should be <tt>< this->getOwningMol()->getNumBonds()</tt>
170  */
171  void setIdx(unsigned int index) { d_index = index; };
172 
173  //! returns the index of our begin Atom
174  /*!
175  <b>Notes:</b>
176  - this makes no sense if we do not have an owning molecule
177  */
178  unsigned int getBeginAtomIdx() const { return d_beginAtomIdx; };
179 
180  //! returns the index of our end Atom
181  /*!
182  <b>Notes:</b>
183  - this makes no sense if we do not have an owning molecule
184  */
185  unsigned int getEndAtomIdx() const { return d_endAtomIdx; };
186 
187  //! given the index of one Atom, returns the index of the other
188  /*!
189  <b>Notes:</b>
190  - this makes no sense if we do not have an owning molecule
191  */
192  unsigned int getOtherAtomIdx(unsigned int thisIdx) const;
193 
194  //! sets the index of our begin Atom
195  /*!
196  <b>Notes:</b>
197  - requires an owning molecule
198  */
199  void setBeginAtomIdx(unsigned int what);
200  //! sets the index of our end Atom
201  /*!
202  <b>Notes:</b>
203  - requires an owning molecule
204  */
205  void setEndAtomIdx(unsigned int what);
206 
207  //! sets our begin Atom
208  /*!
209  <b>Notes:</b>
210  - requires an owning molecule
211  */
212  void setBeginAtom(Atom *at);
213  //! \overload
214  void setBeginAtom(ATOM_SPTR at);
215  //! sets our end Atom
216  /*!
217  <b>Notes:</b>
218  - requires an owning molecule
219  */
220  void setEndAtom(Atom *at);
221  //! \overload
222  void setEndAtom(ATOM_SPTR at);
223 
224  //! returns a pointer to our begin Atom
225  /*!
226  <b>Notes:</b>
227  - requires an owning molecule
228  */
229  Atom *getBeginAtom() const;
230  //! returns a pointer to our end Atom
231  /*!
232  <b>Notes:</b>
233  - requires an owning molecule
234  */
235  Atom *getEndAtom() const;
236  //! returns a pointer to the other Atom
237  /*!
238  <b>Notes:</b>
239  - requires an owning molecule
240  */
241  Atom *getOtherAtom(Atom const *what) const;
242 
243  // ------------------------------------
244  // Please see the note in Atom.h for some explanation
245  // of these methods
246  // ------------------------------------
247 
248  // This method can be used to distinguish query bonds from standard bonds
249  virtual bool hasQuery() const { return false; };
250 
251  // FIX: the const crap here is all mucked up.
252  //! NOT CALLABLE
253  virtual void setQuery(QUERYBOND_QUERY *what);
254  //! NOT CALLABLE
255  virtual QUERYBOND_QUERY *getQuery() const;
256 
257  //! NOT CALLABLE
258  virtual void expandQuery(
259  QUERYBOND_QUERY *what,
261  bool maintainOrder = true);
262 
263  //! returns whether or not we match the argument
264  /*!
265  <b>Notes:</b>
266  - for Bond objects, "match" means that either one of the Bonds
267  has \c bondType Bond::UNSPECIFIED or both Bonds have the
268  same \c bondType.
269  */
270  virtual bool Match(Bond const *what) const;
271  //! \overload
272  virtual bool Match(const Bond::BOND_SPTR what) const;
273 
274  //! sets our direction
275  void setBondDir(BondDir what) { d_dirTag = what; };
276  //! returns our direction
277  BondDir getBondDir() const { return static_cast<BondDir>(d_dirTag); };
278 
279  //! sets our stereo code
280  /*!
281  STEREONONE, STEREOANY, STEREOE and STEREOZ can be set without
282  neighboring atoms specified in getStereoAtoms since they are
283  defined by the topology of the molecular graph. In order to set
284  STEREOCIS or STEREOTRANS the neighboring atoms must be set first
285  (using setStereoBonds()) to know what atoms are being considered.
286 
287  <b>Notes:</b>
288  - MolOps::findPotentialStereoBonds can be used to set
289  getStereoAtoms before setting CIS/TRANS
290  */
291  void setStereo(BondStereo what) {
292  PRECONDITION(what <= STEREOE || getStereoAtoms().size() == 2,
293  "Stereo atoms should be specified before specifying CIS/TRANS "
294  "bond stereochemistry")
295  d_stereo = what;
296  };
297  //! returns our stereo code
298  BondStereo getStereo() const { return static_cast<BondStereo>(d_stereo); };
299 
300  //! sets the atoms to be considered as reference points for bond stereo
301  /*!
302  These do not necessarily need to be the highest 'ranking' atoms
303  like CIP stereo requires. They can be any arbitrary atoms
304  neighboring the begin and end atoms of this bond
305  respectively. STEREOCIS or STEREOTRANS is then set relative to
306  only these atoms.
307 
308  If CIP rankings are desired, use
309  MolOps::findPotentialStereoBonds, but this is a more costly
310  function as it takes the whole molecule topology into account.
311  */
312  void setStereoAtoms(unsigned int bgnIdx, unsigned int endIdx);
313 
314  //! returns the indices of our stereo atoms
315  const INT_VECT &getStereoAtoms() const {
316  if (!dp_stereoAtoms) {
317  const_cast<Bond *>(this)->dp_stereoAtoms = new INT_VECT();
318  }
319  return *dp_stereoAtoms;
320  };
321  //! \overload
323  if (!dp_stereoAtoms) dp_stereoAtoms = new INT_VECT();
324  return *dp_stereoAtoms;
325  };
326 
327  //! calculates any of our lazy \c properties
328  /*!
329  <b>Notes:</b>
330  - requires an owning molecule
331  */
332  void updatePropertyCache(bool strict = true) { (void)strict; }
333 
334  protected:
335  //! sets our owning molecule
336  // void setOwningMol(ROMol *other);
337  //! sets our owning molecule
338  // void setOwningMol(ROMol &other) {setOwningMol(&other);};
341  boost::uint8_t d_bondType;
342  boost::uint8_t d_dirTag;
343  boost::uint8_t d_stereo;
348 
349  void initBond();
350 };
351 };
352 
353 //! allows Bond objects to be dumped to streams
354 extern std::ostream &operator<<(std::ostream &target, const RDKit::Bond &b);
355 
356 #endif
void initBond()
void setBeginAtomIdx(unsigned int what)
sets the index of our begin Atom
boost::uint8_t d_stereo
Definition: Bond.h:343
double getValenceContrib(const Atom *at) const
returns our contribution to the explicit valence of an Atom
std::ostream & operator<<(std::ostream &target, const RDKit::Bond &b)
allows Bond objects to be dumped to streams
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
bool df_isAromatic
sets our owning molecule
Definition: Bond.h:339
BondDir getBondDir() const
returns our direction
Definition: Bond.h:277
Queries::Query< int, Bond const *, true > QUERYBOND_QUERY
Definition: Bond.h:54
BondStereo getStereo() const
returns our stereo code
Definition: Bond.h:298
boost::shared_ptr< Atom > ATOM_SPTR
Definition: Bond.h:27
ROMol * dp_mol
Definition: Bond.h:346
BondStereo
the nature of the bond&#39;s stereochem (for cis/trans)
Definition: Bond.h:96
void setIsConjugated(bool what)
sets our isConjugated flag
Definition: Bond.h:144
BondType
the type of Bond
Definition: Bond.h:57
void setBondType(BondType bT)
sets our bondType
Definition: Bond.h:124
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:106
unsigned int getBeginAtomIdx() const
returns the index of our begin Atom
Definition: Bond.h:178
intentionally unspecified stereochemistry
Definition: Bond.h:92
standard two-electron dative
Definition: Bond.h:77
void setIdx(unsigned int index)
sets our index within the ROMol
Definition: Bond.h:171
bool getIsConjugated() const
returns the status of our isConjugated flag
Definition: Bond.h:146
virtual bool hasQuery() const
Definition: Bond.h:249
Atom * getOtherAtom(Atom const *what) const
returns a pointer to the other Atom
INT_VECT * dp_stereoAtoms
Definition: Bond.h:347
virtual void expandQuery(QUERYBOND_QUERY *what, Queries::CompositeQueryType how=Queries::COMPOSITE_AND, bool maintainOrder=true)
NOT CALLABLE.
std::vector< int > INT_VECT
Definition: types.h:190
void setIsAromatic(bool what)
sets our isAromatic flag
Definition: Bond.h:139
boost::uint8_t d_bondType
Definition: Bond.h:341
Atom * getEndAtom() const
returns a pointer to our end Atom
Includes a bunch of functionality for handling Atom and Bond queries.
Definition: Atom.h:29
unsigned int getEndAtomIdx() const
returns the index of our end Atom
Definition: Bond.h:185
void updatePropertyCache(bool strict=true)
calculates any of our lazy properties
Definition: Bond.h:332
INT_VECT & getStereoAtoms()
Definition: Bond.h:322
virtual QUERYBOND_QUERY * getQuery() const
NOT CALLABLE.
atomindex_t d_index
Definition: Bond.h:344
void setStereo(BondStereo what)
sets our stereo code
Definition: Bond.h:291
standard two-electron dative
Definition: Bond.h:75
bool df_isConjugated
Definition: Bond.h:340
class for representing a bond
Definition: Bond.h:47
void setOwningMol(ROMol *other)
sets our owning molecule
Zero-order bond (from.
Definition: Bond.h:79
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:76
void setBeginAtom(Atom *at)
sets our begin Atom
BondDir
the bond&#39;s direction (for chirality)
Definition: Bond.h:84
atomindex_t d_beginAtomIdx
Definition: Bond.h:345
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:156
const INT_VECT & getStereoAtoms() const
returns the indices of our stereo atoms
Definition: Bond.h:315
one-electron dative (e.g. from a C in a Cp ring to a metal)
Definition: Bond.h:74
boost::uint8_t d_dirTag
Definition: Bond.h:342
#define PRECONDITION(expr, mess)
Definition: Invariant.h:107
bool getIsAromatic() const
returns the status of our isAromatic flag
Definition: Bond.h:141
boost::uint16_t atomindex_t
Definition: details.h:13
no special style
Definition: Bond.h:85
wedged: narrow at begin
Definition: Bond.h:86
a "crossed" double bond
Definition: Bond.h:91
Bond & operator=(const Bond &other)
boost::shared_ptr< Bond > BOND_SPTR
Definition: Bond.h:52
Pulls in all the query types.
void setEndAtom(Atom *at)
sets our end Atom
virtual Bond * copy() const
returns a copy
unsigned int getIdx() const
returns our index within the ROMol
Definition: Bond.h:164
Atom * getBeginAtom() const
returns a pointer to our begin Atom
void setBondDir(BondDir what)
sets our direction
Definition: Bond.h:275
ROMol & getOwningMol() const
returns a reference to the ROMol that owns this Bond
Definition: Bond.h:149
Base class for all queries.
Definition: Query.h:45
dashed: narrow at begin
Definition: Bond.h:87
The class for representing atoms.
Definition: Atom.h:68
atomindex_t d_endAtomIdx
Definition: Bond.h:345
BondType getBondType() const
returns our bondType
Definition: Bond.h:122
virtual void setQuery(QUERYBOND_QUERY *what)
NOT CALLABLE.
for cis/trans
Definition: Bond.h:89
void setStereoAtoms(unsigned int bgnIdx, unsigned int endIdx)
sets the atoms to be considered as reference points for bond stereo