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 #include <RDGeneral/export.h>
11 #ifndef _RD_BOND_H
12 #define _RD_BOND_H
13 
14 // std stuff
15 #include <iostream>
16 
17 // Ours
18 #include <RDGeneral/Invariant.h>
19 #include <Query/QueryObjects.h>
20 #include <RDGeneral/types.h>
21 #include <RDGeneral/RDProps.h>
22 #include <GraphMol/details.h>
23 #include <boost/foreach.hpp>
24 
25 namespace RDKit {
26 class ROMol;
27 class RWMol;
28 class Atom;
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 */
48  friend class RWMol;
49  friend class ROMol;
50 
51  public:
52  // FIX: grn...
54 
55  //! the type of Bond
56  typedef enum {
57  UNSPECIFIED = 0,
73  DATIVEONE, //!< one-electron dative (e.g. from a C in a Cp ring to a metal)
74  DATIVE, //!< standard two-electron dative
75  DATIVEL, //!< standard two-electron dative
76  DATIVER, //!< standard two-electron dative
78  ZERO //!< Zero-order bond (from
79  // http://pubs.acs.org/doi/abs/10.1021/ci200488k)
80  } BondType;
81 
82  //! the bond's direction (for chirality)
83  typedef enum {
84  NONE = 0, //!< no special style
85  BEGINWEDGE, //!< wedged: narrow at begin
86  BEGINDASH, //!< dashed: narrow at begin
87  // FIX: this may not really be adequate
88  ENDDOWNRIGHT, //!< for cis/trans
89  ENDUPRIGHT, //!< ditto
90  EITHERDOUBLE, //!< a "crossed" double bond
91  UNKNOWN, //!< intentionally unspecified stereochemistry
92  } BondDir;
93 
94  //! the nature of the bond's stereochem (for cis/trans)
95  typedef enum { // stereochemistry of double bonds
96  STEREONONE = 0, // no special style
97  STEREOANY, // intentionally unspecified
98  // -- Put any true specifications about this point so
99  // that we can do comparisons like if(bond->getStereo()>Bond::STEREOANY)
100  STEREOZ, // Z double bond
101  STEREOE, // E double bond
102  STEREOCIS, // cis double bond
103  STEREOTRANS // trans double bond
104  } BondStereo;
105 
106  Bond();
107  //! construct with a particular BondType
108  explicit Bond(BondType bT);
109  Bond(const Bond &other);
110  virtual ~Bond();
111  Bond &operator=(const Bond &other);
112 
113  //! returns a copy
114  /*!
115  <b>Note:</b> the caller is responsible for <tt>delete</tt>ing
116  the returned pointer.
117  */
118  virtual Bond *copy() const;
119 
120  //! returns our \c bondType
121  BondType getBondType() const { return static_cast<BondType>(d_bondType); };
122  //! sets our \c bondType
123  void setBondType(BondType bT) { d_bondType = bT; };
124  //! \brief returns our \c bondType as a double
125  //! (e.g. SINGLE->1.0, AROMATIC->1.5, etc.)
126  double getBondTypeAsDouble() const;
127 
128  //! returns our contribution to the explicit valence of an Atom
129  /*!
130  <b>Notes:</b>
131  - requires an owning molecule
132  */
133  double getValenceContrib(const Atom *at) const;
134 
135  //! sets our \c isAromatic flag
136  void setIsAromatic(bool what) { df_isAromatic = what; };
137  //! returns the status of our \c isAromatic flag
138  bool getIsAromatic() const { return df_isAromatic; };
139 
140  //! sets our \c isConjugated flag
141  void setIsConjugated(bool what) { df_isConjugated = what; };
142  //! returns the status of our \c isConjugated flag
143  bool getIsConjugated() const { return df_isConjugated; };
144 
145  //! returns whether or not this instance belongs to a molecule
146  bool hasOwningMol() const { return dp_mol != nullptr; };
147 
148  //! returns a reference to the ROMol that owns this instance
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  //! sets our end Atom
214  /*!
215  <b>Notes:</b>
216  - requires an owning molecule
217  */
218  void setEndAtom(Atom *at);
219 
220  //! returns a pointer to our begin Atom
221  /*!
222  <b>Notes:</b>
223  - requires an owning molecule
224  */
225  Atom *getBeginAtom() const;
226  //! returns a pointer to our end Atom
227  /*!
228  <b>Notes:</b>
229  - requires an owning molecule
230  */
231  Atom *getEndAtom() const;
232  //! returns a pointer to the other Atom
233  /*!
234  <b>Notes:</b>
235  - requires an owning molecule
236  */
237  Atom *getOtherAtom(Atom const *what) const;
238 
239  // ------------------------------------
240  // Please see the note in Atom.h for some explanation
241  // of these methods
242  // ------------------------------------
243 
244  // This method can be used to distinguish query bonds from standard bonds
245  virtual bool hasQuery() const { return false; };
246 
247  // FIX: the const crap here is all mucked up.
248  //! NOT CALLABLE
249  virtual void setQuery(QUERYBOND_QUERY *what);
250  //! NOT CALLABLE
251  virtual QUERYBOND_QUERY *getQuery() const;
252 
253  //! NOT CALLABLE
254  virtual void expandQuery(
255  QUERYBOND_QUERY *what,
257  bool maintainOrder = true);
258 
259  //! returns whether or not we match the argument
260  /*!
261  <b>Notes:</b>
262  - for Bond objects, "match" means that either one of the Bonds
263  has \c bondType Bond::UNSPECIFIED or both Bonds have the
264  same \c bondType.
265  */
266  virtual bool Match(Bond const *what) const;
267 
268  //! sets our direction
269  void setBondDir(BondDir what) { d_dirTag = what; };
270  //! returns our direction
271  BondDir getBondDir() const { return static_cast<BondDir>(d_dirTag); };
272 
273  //! sets our stereo code
274  /*!
275  STEREONONE, STEREOANY, STEREOE and STEREOZ can be set without
276  neighboring atoms specified in getStereoAtoms since they are
277  defined by the topology of the molecular graph. In order to set
278  STEREOCIS or STEREOTRANS the neighboring atoms must be set first
279  (using setStereoBonds()) to know what atoms are being considered.
280 
281  <b>Notes:</b>
282  - MolOps::findPotentialStereoBonds can be used to set
283  getStereoAtoms before setting CIS/TRANS
284  */
285  void setStereo(BondStereo what) {
286  PRECONDITION(what <= STEREOE || getStereoAtoms().size() == 2,
287  "Stereo atoms should be specified before specifying CIS/TRANS "
288  "bond stereochemistry")
289  d_stereo = what;
290  };
291  //! returns our stereo code
292  BondStereo getStereo() const { return static_cast<BondStereo>(d_stereo); };
293 
294  //! sets the atoms to be considered as reference points for bond stereo
295  /*!
296  These do not necessarily need to be the highest 'ranking' atoms
297  like CIP stereo requires. They can be any arbitrary atoms
298  neighboring the begin and end atoms of this bond
299  respectively. STEREOCIS or STEREOTRANS is then set relative to
300  only these atoms.
301 
302  If CIP rankings are desired, use
303  MolOps::findPotentialStereoBonds, but this is a more costly
304  function as it takes the whole molecule topology into account.
305  */
306  void setStereoAtoms(unsigned int bgnIdx, unsigned int endIdx);
307 
308  //! returns the indices of our stereo atoms
309  const INT_VECT &getStereoAtoms() const {
310  if (!dp_stereoAtoms) {
311  const_cast<Bond *>(this)->dp_stereoAtoms = new INT_VECT();
312  }
313  return *dp_stereoAtoms;
314  };
315  //! \overload
317  if (!dp_stereoAtoms) dp_stereoAtoms = new INT_VECT();
318  return *dp_stereoAtoms;
319  };
320 
321  //! calculates any of our lazy \c properties
322  /*!
323  <b>Notes:</b>
324  - requires an owning molecule
325  */
326  void updatePropertyCache(bool strict = true) { (void)strict; }
327 
328  protected:
329  //! sets our owning molecule
330  // void setOwningMol(ROMol *other);
331  //! sets our owning molecule
332  // void setOwningMol(ROMol &other) {setOwningMol(&other);};
335  std::uint8_t d_bondType;
336  std::uint8_t d_dirTag;
337  std::uint8_t d_stereo;
339  atomindex_t d_beginAtomIdx, d_endAtomIdx;
342 
343  void initBond();
344 };
345 }; // namespace RDKit
346 
347 //! allows Bond objects to be dumped to streams
348 RDKIT_GRAPHMOL_EXPORT extern std::ostream &operator<<(std::ostream &target,
349  const RDKit::Bond &b);
350 
351 #endif
RDKit::Bond::BEGINDASH
@ BEGINDASH
dashed: narrow at begin
Definition: Bond.h:86
RDKit::Bond::DATIVEL
@ DATIVEL
standard two-electron dative
Definition: Bond.h:75
RDKit::Bond::DATIVE
@ DATIVE
standard two-electron dative
Definition: Bond.h:74
RDKit::Bond::dp_mol
ROMol * dp_mol
Definition: Bond.h:340
RDKit::Bond::getStereo
BondStereo getStereo() const
returns our stereo code
Definition: Bond.h:292
RDKit::Bond::df_isAromatic
bool df_isAromatic
sets our owning molecule
Definition: Bond.h:333
RDKit::Bond::d_dirTag
std::uint8_t d_dirTag
Definition: Bond.h:336
Queries::COMPOSITE_AND
@ COMPOSITE_AND
Definition: QueryObjects.h:36
RDKit::Bond::DATIVER
@ DATIVER
standard two-electron dative
Definition: Bond.h:76
RDKit::INT_VECT
std::vector< int > INT_VECT
Definition: types.h:254
QueryObjects.h
Pulls in all the query types.
types.h
RDKit::Bond::THREEANDAHALF
@ THREEANDAHALF
Definition: Bond.h:66
RDKit::Bond::updatePropertyCache
void updatePropertyCache(bool strict=true)
calculates any of our lazy properties
Definition: Bond.h:326
RDKit::Bond::setIsConjugated
void setIsConjugated(bool what)
sets our isConjugated flag
Definition: Bond.h:141
RDKit::Bond::dp_stereoAtoms
INT_VECT * dp_stereoAtoms
Definition: Bond.h:341
RDKit::Bond::EITHERDOUBLE
@ EITHERDOUBLE
a "crossed" double bond
Definition: Bond.h:90
RDKit::Bond::hasOwningMol
bool hasOwningMol() const
returns whether or not this instance belongs to a molecule
Definition: Bond.h:146
RDKit::Bond::getStereoAtoms
INT_VECT & getStereoAtoms()
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: Bond.h:316
RDKit::Bond
class for representing a bond
Definition: Bond.h:47
Queries::CompositeQueryType
CompositeQueryType
Definition: QueryObjects.h:36
RDKit::Bond::setIdx
void setIdx(unsigned int index)
sets our index within the ROMol
Definition: Bond.h:171
RDKit::RWMol
RWMol is a molecule class that is intended to be edited.
Definition: RWMol.h:31
operator<<
RDKIT_GRAPHMOL_EXPORT std::ostream & operator<<(std::ostream &target, const RDKit::Bond &b)
allows Bond objects to be dumped to streams
RDKit::Bond::SINGLE
@ SINGLE
Definition: Bond.h:58
RDKit::Bond::setOwningMol
void setOwningMol(ROMol &other)
sets our owning molecule
Definition: Bond.h:156
RDKit::Bond::UNKNOWN
@ UNKNOWN
intentionally unspecified stereochemistry
Definition: Bond.h:91
RDKit::Bond::setBondDir
void setBondDir(BondDir what)
sets our direction
Definition: Bond.h:269
RDKit::Bond::d_index
atomindex_t d_index
Definition: Bond.h:338
RDKit::Bond::ENDUPRIGHT
@ ENDUPRIGHT
ditto
Definition: Bond.h:89
RDKit::Bond::BondType
BondType
the type of Bond
Definition: Bond.h:56
RDKit::Bond::IONIC
@ IONIC
Definition: Bond.h:70
RDKit::Bond::QUINTUPLE
@ QUINTUPLE
Definition: Bond.h:62
RDKit::Atom
The class for representing atoms.
Definition: Atom.h:69
RDKit::Bond::getEndAtomIdx
unsigned int getEndAtomIdx() const
returns the index of our end Atom
Definition: Bond.h:185
RDKit::Bond::getIdx
unsigned int getIdx() const
returns our index within the ROMol
Definition: Bond.h:164
RDKit::Bond::FIVEANDAHALF
@ FIVEANDAHALF
Definition: Bond.h:68
RDKit::Bond::QUADRUPLE
@ QUADRUPLE
Definition: Bond.h:61
RDKit::ROMol
Definition: ROMol.h:171
RDKit::Bond::DOUBLE
@ DOUBLE
Definition: Bond.h:59
RDKit::Bond::STEREOZ
@ STEREOZ
Definition: Bond.h:100
BondStereo
BondStereo
Definition: nmmolhash.h:49
RDKit::Bond::getStereoAtoms
const INT_VECT & getStereoAtoms() const
returns the indices of our stereo atoms
Definition: Bond.h:309
RDKIT_GRAPHMOL_EXPORT
#define RDKIT_GRAPHMOL_EXPORT
Definition: export.h:307
RDProps.h
RDKit::Bond::BEGINWEDGE
@ BEGINWEDGE
wedged: narrow at begin
Definition: Bond.h:85
Invariant.h
RDKit::Bond::TWOANDAHALF
@ TWOANDAHALF
Definition: Bond.h:65
RDKit::RDProps
Definition: RDProps.h:10
RDKit::Bond::THREECENTER
@ THREECENTER
Definition: Bond.h:72
RDKit::Bond::d_bondType
std::uint8_t d_bondType
Definition: Bond.h:335
RDKit::Bond::getBondDir
BondDir getBondDir() const
returns our direction
Definition: Bond.h:271
RDKit::Bond::HEXTUPLE
@ HEXTUPLE
Definition: Bond.h:63
RDKit::Bond::df_isConjugated
bool df_isConjugated
Definition: Bond.h:334
RDKit::Bond::FOURANDAHALF
@ FOURANDAHALF
Definition: Bond.h:67
RDKit::Bond::QUERYBOND_QUERY
Queries::Query< int, Bond const *, true > QUERYBOND_QUERY
Definition: Bond.h:53
RDKit
Std stuff.
Definition: Atom.h:30
RDKit::Bond::ENDDOWNRIGHT
@ ENDDOWNRIGHT
for cis/trans
Definition: Bond.h:88
RDKit::Bond::getIsConjugated
bool getIsConjugated() const
returns the status of our isConjugated flag
Definition: Bond.h:143
RDKit::Bond::setIsAromatic
void setIsAromatic(bool what)
sets our isAromatic flag
Definition: Bond.h:136
RDKit::Bond::setBondType
void setBondType(BondType bT)
sets our bondType
Definition: Bond.h:123
RDKit::Bond::STEREOE
@ STEREOE
Definition: Bond.h:101
RDKit::Bond::TRIPLE
@ TRIPLE
Definition: Bond.h:60
RDKit::Bond::ONEANDAHALF
@ ONEANDAHALF
Definition: Bond.h:64
RDKit::Bond::hasQuery
virtual bool hasQuery() const
Definition: Bond.h:245
PRECONDITION
#define PRECONDITION(expr, mess)
Definition: Invariant.h:109
Queries::Query
Base class for all queries.
Definition: Query.h:46
RDKit::atomindex_t
std::uint32_t atomindex_t
Definition: details.h:14
RDKit::Bond::getBondType
BondType getBondType() const
returns our bondType
Definition: Bond.h:121
details.h
RDKit::Bond::BondStereo
BondStereo
the nature of the bond's stereochem (for cis/trans)
Definition: Bond.h:95
RDKit::Bond::HYDROGEN
@ HYDROGEN
Definition: Bond.h:71
RDKit::Bond::OTHER
@ OTHER
Definition: Bond.h:77
RDKit::Bond::getOwningMol
ROMol & getOwningMol() const
returns a reference to the ROMol that owns this instance
Definition: Bond.h:149
RDKit::Bond::DATIVEONE
@ DATIVEONE
one-electron dative (e.g. from a C in a Cp ring to a metal)
Definition: Bond.h:73
RDKit::Bond::AROMATIC
@ AROMATIC
Definition: Bond.h:69
RDKit::Bond::STEREOANY
@ STEREOANY
Definition: Bond.h:97
RDKit::Bond::getIsAromatic
bool getIsAromatic() const
returns the status of our isAromatic flag
Definition: Bond.h:138
RDKit::Bond::d_stereo
std::uint8_t d_stereo
Definition: Bond.h:337
RDKit::Bond::BondDir
BondDir
the bond's direction (for chirality)
Definition: Bond.h:83
RDKit::Bond::getBeginAtomIdx
unsigned int getBeginAtomIdx() const
returns the index of our begin Atom
Definition: Bond.h:178
RDKit::Bond::setStereo
void setStereo(BondStereo what)
sets our stereo code
Definition: Bond.h:285
RDKit::Bond::d_endAtomIdx
atomindex_t d_endAtomIdx
Definition: Bond.h:339
RDKit::Bond::STEREOCIS
@ STEREOCIS
Definition: Bond.h:102
export.h