RDKit
Open-source cheminformatics and machine learning.
ROMol.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2003-2015 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 /*! \file ROMol.h
11 
12  \brief Defines the primary molecule class \c ROMol as well as associated
13  typedefs
14 
15 */
16 
17 #ifndef __RD_ROMOL_H__
18 #define __RD_ROMOL_H__
19 
20 /// Std stuff
21 #include <utility>
22 #include <map>
23 
24 // boost stuff
26 #include <boost/graph/adjacency_list.hpp>
27 #include <boost/smart_ptr.hpp>
29 
30 // our stuff
31 #include <RDGeneral/types.h>
32 #include "Atom.h"
33 #include "Bond.h"
34 
35 #include "Conformer.h"
36 
37 namespace RDKit {
38 class Atom;
39 class Bond;
40 typedef boost::shared_ptr<Atom> ATOM_SPTR;
41 typedef boost::shared_ptr<Bond> BOND_SPTR;
42 
43 //! This is the BGL type used to store the topology:
44 typedef boost::adjacency_list<boost::vecS, boost::vecS, boost::undirectedS,
45  ATOM_SPTR, BOND_SPTR>
47 class MolPickler;
48 class RWMol;
49 class QueryAtom;
50 class QueryBond;
51 class RingInfo;
52 
53 template <class T1, class T2>
54 class AtomIterator_;
55 class BondIterator_;
56 class ConstBondIterator_;
57 
58 template <class T1, class T2>
60 template <class T1, class T2>
62 template <class T1, class T2>
63 class QueryAtomIterator_;
64 template <class T1, class T2>
66 
67 extern const int ci_RIGHTMOST_ATOM;
68 extern const int ci_LEADING_BOND;
69 extern const int ci_ATOM_HOLDER;
70 
71 //! ROMol is a molecule class that is intended to have a fixed topology
72 /*!
73  This is the primary class for most molecule operations.
74 
75  If you need to be manipulating the molecule (e.g. adding or deleting
76  atoms or bonds, use an RWMol instead.
77 
78  <b>Notes:</b>
79  - each ROMol maintains a Dict of \c properties:
80  - Each \c property is keyed by name and can store an
81  arbitrary type.
82  - \c Properties can be marked as \c calculated, in which case
83  they will be cleared when the \c clearComputedProps() method
84  is called.
85  - Because they have no impact upon chemistry, all \c property
86  operations are \c const, this allows extra flexibility for
87  clients who need to store extra data on ROMol objects.
88 
89  - each ROMol has collections of \c bookmarks for Atoms and Bonds:
90  - the Atom bookmarks and Bond bookmarks are stored separately
91  from each other
92  - each \c bookmark, an integer, can map to more than one
93  Atom or Bond
94  - these are currently used in molecule construction, but
95  could also be useful for reaction mapping and the like
96 
97  - information about rings (SSSR and the like) is stored in the
98  molecule's RingInfo pointer.
99 
100  */
101 
102 class ROMol {
103  public:
104  friend class MolPickler;
105  friend class RWMol;
106 
107  //! \cond TYPEDEFS
108 
109  //! \name typedefs
110  //@{
111  typedef MolGraph::vertex_descriptor vertex_descriptor;
112  typedef MolGraph::edge_descriptor edge_descriptor;
113 
114  typedef MolGraph::edge_iterator EDGE_ITER;
115  typedef MolGraph::out_edge_iterator OEDGE_ITER;
116  typedef MolGraph::vertex_iterator VERTEX_ITER;
117  typedef MolGraph::adjacency_iterator ADJ_ITER;
118  typedef std::pair<EDGE_ITER, EDGE_ITER> BOND_ITER_PAIR;
119  typedef std::pair<OEDGE_ITER, OEDGE_ITER> OBOND_ITER_PAIR;
120  typedef std::pair<VERTEX_ITER, VERTEX_ITER> ATOM_ITER_PAIR;
121  typedef std::pair<ADJ_ITER, ADJ_ITER> ADJ_ITER_PAIR;
122 
123  typedef std::vector<ATOM_SPTR> ATOM_SPTR_VECT;
124  typedef ATOM_SPTR_VECT::iterator ATOM_SPTR_VECT_I;
125  typedef ATOM_SPTR_VECT::const_iterator ATOM_SPTR_VECT_CI;
126  typedef std::vector<BOND_SPTR> BOND_SPTR_VECT;
127  typedef BOND_SPTR_VECT::iterator BOND_SPTR_VECT_I;
128  typedef BOND_SPTR_VECT::const_iterator BOND_SPTR_VECT_CI;
129 
130  typedef std::vector<Atom *> ATOM_PTR_VECT;
131  typedef ATOM_PTR_VECT::iterator ATOM_PTR_VECT_I;
132  typedef ATOM_PTR_VECT::const_iterator ATOM_PTR_VECT_CI;
133  typedef std::vector<Bond *> BOND_PTR_VECT;
134  typedef BOND_PTR_VECT::iterator BOND_PTR_VECT_I;
135  typedef BOND_PTR_VECT::const_iterator BOND_PTR_VECT_CI;
136 
137  typedef std::list<Atom *> ATOM_PTR_LIST;
138  typedef ATOM_PTR_LIST::iterator ATOM_PTR_LIST_I;
139  typedef ATOM_PTR_LIST::const_iterator ATOM_PTR_LIST_CI;
140  typedef std::list<Bond *> BOND_PTR_LIST;
141  typedef BOND_PTR_LIST::iterator BOND_PTR_LIST_I;
142  typedef BOND_PTR_LIST::const_iterator BOND_PTR_LIST_CI;
143 
144  // list of conformations
145  typedef std::list<CONFORMER_SPTR> CONF_SPTR_LIST;
146  typedef CONF_SPTR_LIST::iterator CONF_SPTR_LIST_I;
147  typedef CONF_SPTR_LIST::const_iterator CONF_SPTR_LIST_CI;
148  typedef std::pair<CONF_SPTR_LIST_I, CONF_SPTR_LIST_I> CONFS_I_PAIR;
149 
150  // ROFIX: these will need to be readonly somehow?
151  typedef std::map<int, ATOM_PTR_LIST> ATOM_BOOKMARK_MAP;
152  typedef std::map<int, BOND_PTR_LIST> BOND_BOOKMARK_MAP;
153 
154  typedef class AtomIterator_<Atom, ROMol> AtomIterator;
155  typedef class AtomIterator_<const Atom, const ROMol> ConstAtomIterator;
156  typedef class BondIterator_ BondIterator;
157  typedef class ConstBondIterator_ ConstBondIterator;
158  typedef class AromaticAtomIterator_<Atom, ROMol> AromaticAtomIterator;
159  typedef class AromaticAtomIterator_<const Atom, const ROMol>
160  ConstAromaticAtomIterator;
161  typedef class HeteroatomIterator_<Atom, ROMol> HeteroatomIterator;
162  typedef class HeteroatomIterator_<const Atom, const ROMol>
163  ConstHeteroatomIterator;
164  typedef class QueryAtomIterator_<Atom, ROMol> QueryAtomIterator;
165  typedef class QueryAtomIterator_<const Atom, const ROMol>
166  ConstQueryAtomIterator;
167  typedef class MatchingAtomIterator_<Atom, ROMol> MatchingAtomIterator;
168  typedef class MatchingAtomIterator_<const Atom, const ROMol>
169  ConstMatchingAtomIterator;
170 
171  typedef CONF_SPTR_LIST_I ConformerIterator;
172  typedef CONF_SPTR_LIST_CI ConstConformerIterator;
173 
174  //@}
175  //! \endcond
176 
177  ROMol() { initMol(); }
178 
179  //! copy constructor with a twist
180  /*!
181  \param other the molecule to be copied
182  \param quickCopy (optional) if this is true, the resulting ROMol will not
183  copy any of the properties or bookmarks and conformers from \c other.
184  This can
185  make the copy substantially faster (thus the name).
186  \param confId (optional) if this is >=0, the resulting ROMol will contain
187  only
188  the specified conformer from \c other.
189  */
190  ROMol(const ROMol &other, bool quickCopy = false, int confId = -1) {
191  dp_props = 0;
192  dp_ringInfo = 0;
193  initFromOther(other, quickCopy, confId);
194  };
195  //! construct a molecule from a pickle string
196  ROMol(const std::string &binStr);
197 
198  virtual ~ROMol() { destroy(); };
199 
200  //! \name Atoms
201  //@{
202 
203  //! returns our number of atoms
204  unsigned int getNumAtoms(bool onlyExplicit = 1) const;
205  //! returns our number of heavy atoms (atomic number > 1)
206  unsigned int getNumHeavyAtoms() const;
207  //! returns a pointer to a particular Atom
208  Atom *getAtomWithIdx(unsigned int idx);
209  //! \overload
210  const Atom *getAtomWithIdx(unsigned int idx) const;
211  //! \overload
212  template <class U>
213  Atom *getAtomWithIdx(const U idx) {
214  return getAtomWithIdx(rdcast<unsigned int>(idx));
215  }
216  //! \overload
217  template <class U>
218  const Atom *getAtomWithIdx(const U idx) const {
219  return getAtomWithIdx(rdcast<unsigned int>(idx));
220  }
221  //! returns the degree (number of neighbors) of an Atom in the graph
222  unsigned int getAtomDegree(const Atom *at) const;
223  //! \overload
224  unsigned int getAtomDegree(ATOM_SPTR at) const;
225  //@}
226 
227  //! \name Bonds
228  //@{
229 
230  //! returns our number of Bonds
231  unsigned int getNumBonds(bool onlyHeavy = 1) const;
232  //! returns a pointer to a particular Bond
233  Bond *getBondWithIdx(unsigned int idx);
234  //! \overload
235  const Bond *getBondWithIdx(unsigned int idx) const;
236  //! \overload
237  template <class U>
238  Bond *getBondWithIdx(const U idx) {
239  return getBondWithIdx(rdcast<unsigned int>(idx));
240  }
241  //! \overload
242  template <class U>
243  const Bond *getBondWithIdx(const U idx) const {
244  return getBondWithIdx(rdcast<unsigned int>(idx));
245  }
246  //! returns a pointer to the bond between two atoms, Null on failure
247  Bond *getBondBetweenAtoms(unsigned int idx1, unsigned int idx2);
248  //! \overload
249  const Bond *getBondBetweenAtoms(unsigned int idx1, unsigned int idx2) const;
250  //! \overload
251  template <class U, class V>
252  Bond *getBondBetweenAtoms(const U idx1, const V idx2) {
253  return getBondBetweenAtoms(rdcast<unsigned int>(idx1),
254  rdcast<unsigned int>(idx2));
255  }
256  //! \overload
257  template <class U, class V>
258  const Bond *getBondBetweenAtoms(const U idx1, const V idx2) const {
259  return getBondBetweenAtoms(rdcast<unsigned int>(idx1),
260  rdcast<unsigned int>(idx2));
261  }
262 
263  //@}
264 
265  //! \name Bookmarks
266  //@{
267 
268  //! associates an Atom pointer with a bookmark
269  void setAtomBookmark(ATOM_SPTR at, int mark) {
270  d_atomBookmarks[mark].push_back(at.get());
271  };
272  //! \overload
273  void setAtomBookmark(Atom *at, int mark) {
274  d_atomBookmarks[mark].push_back(at);
275  };
276  //! associates an Atom pointer with a bookmark
277  void replaceAtomBookmark(ATOM_SPTR at, int mark) {
278  d_atomBookmarks[mark].clear();
279  d_atomBookmarks[mark].push_back(at.get());
280  };
281  //! \overload
282  void replaceAtomBookmark(Atom *at, int mark) {
283  d_atomBookmarks[mark].clear();
284  d_atomBookmarks[mark].push_back(at);
285  };
286  //! returns the first Atom associated with the \c bookmark provided
287  Atom *getAtomWithBookmark(int mark);
288  //! returns all Atoms associated with the \c bookmark provided
289  ATOM_PTR_LIST &getAllAtomsWithBookmark(int mark);
290  //! removes a \c bookmark from our collection
291  void clearAtomBookmark(const int mark);
292  //! removes a particular Atom from the list associated with the \c bookmark
293  void clearAtomBookmark(const int mark, const Atom *atom);
294  //! \overload
295  void clearAtomBookmark(const int mark, ATOM_SPTR atom) {
296  clearAtomBookmark(mark, atom.get());
297  };
298  //! blows out all atomic \c bookmarks
299  void clearAllAtomBookmarks() { d_atomBookmarks.clear(); };
300  //! queries whether or not any atoms are associated with a \c bookmark
301  bool hasAtomBookmark(int mark) const { return d_atomBookmarks.count(mark); };
302  //! returns a pointer to all of our atom \c bookmarks
303  ATOM_BOOKMARK_MAP *getAtomBookmarks() { return &d_atomBookmarks; };
304 
305  //! associates a Bond pointer with a bookmark
306  void setBondBookmark(BOND_SPTR bond, int mark) {
307  d_bondBookmarks[mark].push_back(bond.get());
308  };
309  //! \overload
310  void setBondBookmark(Bond *bond, int mark) {
311  d_bondBookmarks[mark].push_back(bond);
312  };
313  //! returns the first Bond associated with the \c bookmark provided
314  Bond *getBondWithBookmark(int mark);
315  //! returns all bonds associated with the \c bookmark provided
316  BOND_PTR_LIST &getAllBondsWithBookmark(int mark);
317  //! removes a \c bookmark from our collection
318  void clearBondBookmark(int mark);
319  //! removes a particular Bond from the list associated with the \c bookmark
320  void clearBondBookmark(int mark, const Bond *bond);
321  //! \overload
322  void clearBondBookmark(int mark, BOND_SPTR bond) {
323  clearBondBookmark(mark, bond.get());
324  };
325  //! blows out all bond \c bookmarks
326  void clearAllBondBookmarks() { d_bondBookmarks.clear(); };
327  //! queries whether or not any bonds are associated with a \c bookmark
328  bool hasBondBookmark(int mark) const { return d_bondBookmarks.count(mark); };
329  //! returns a pointer to all of our bond \c bookmarks
330  BOND_BOOKMARK_MAP *getBondBookmarks() { return &d_bondBookmarks; };
331 
332  //@}
333 
334  //! \name Conformers
335  //@{
336 
337  //! return the conformer with a specified ID
338  //! if the ID is negative the first conformation will be returned
339  const Conformer &getConformer(int id = -1) const;
340 
341  //! return the conformer with a specified ID
342  //! if the ID is negative the first conformation will be returned
343  Conformer &getConformer(int id = -1);
344 
345  //! Delete the conformation with the specified ID
346  void removeConformer(unsigned int id);
347 
348  //! Clear all the conformations on the molecule
349  void clearConformers() { d_confs.clear(); }
350 
351  //! Add a new conformation to the molecule
352  /*!
353  \param conf - conformation to be added to the molecule, this molecule takes
354  ownership
355  of the conformer
356  \param assignId - a unique ID will be assigned to the the conformation if
357  true
358  otherwise it is assumed that the conformation already has
359  an (unique) ID set
360  */
361  unsigned int addConformer(Conformer *conf, bool assignId = false);
362 
363  inline unsigned int getNumConformers() const {
364  return rdcast<unsigned int>(d_confs.size());
365  }
366 
367  //@}
368 
369  //! \name Topology
370  //@{
371 
372  //! returns a pointer to our RingInfo structure
373  //! <b>Note:</b> the client should not delete this.
374  RingInfo *getRingInfo() const { return dp_ringInfo; };
375 
376  //! provides access to all neighbors around an Atom
377  /*!
378  \param at the atom whose neighbors we are looking for
379 
380  <b>Usage</b>
381  \code
382  ... molPtr is a const ROMol & ...
383  ... atomPtr is a const Atom * ...
384  ROMol::ADJ_ITER nbrIdx,endNbrs;
385  boost::tie(nbrIdx,endNbrs) = molPtr.getAtomNeighbors(atomPtr);
386  while(nbrIdx!=endNbrs){
387  const ATOM_SPTR at=molPtr[*nbrIdx];
388  ... do something with the Atom ...
389  ++nbrIdx;
390  }
391  \endcode
392 
393  */
394  ADJ_ITER_PAIR getAtomNeighbors(Atom const *at) const;
395  //! \overload
396  ADJ_ITER_PAIR getAtomNeighbors(ATOM_SPTR at) const;
397 
398  //! provides access to all Bond objects connected to an Atom
399  /*!
400  \param at the atom whose neighbors we are looking for
401 
402  <b>Usage</b>
403  \code
404  ... molPtr is a const ROMol * ...
405  ... atomPtr is a const Atom * ...
406  ROMol::OEDGE_ITER beg,end;
407  boost::tie(beg,end) = molPtr->getAtomBonds(atomPtr);
408  while(beg!=end){
409  const BOND_SPTR bond=(*molPtr)[*beg];
410  ... do something with the Bond ...
411  ++beg;
412  }
413  \endcode
414  or, if you need a non-const Bond *:
415  \code
416  ... molPtr is a ROMol * ...
417  ... atomPtr is a const Atom * ...
418  ROMol::OEDGE_ITER beg,end;
419  boost::tie(beg,end) = molPtr->getAtomBonds(atomPtr);
420  while(beg!=end){
421  BOND_SPTR bond=(*molPtr)[*beg];
422  ... do something with the Bond ...
423  ++beg;
424  }
425  \endcode
426 
427 
428  */
429  OBOND_ITER_PAIR getAtomBonds(Atom const *at) const;
430 
431  //! returns an iterator pair for looping over all Atoms
432  /*!
433 
434  <b>Usage</b>
435  \code
436 
437  ROMol::VERTEX_ITER atBegin,atEnd;
438  boost::tie(atBegin,atEnd) = mol.getVertices();
439  while(atBegin!=atEnd){
440  ATOM_SPTR at2=mol[*atBegin];
441  ... do something with the Atom ...
442  ++atBegin;
443  }
444  \endcode
445  */
446  ATOM_ITER_PAIR getVertices();
447  //! returns an iterator pair for looping over all Bonds
448  /*!
449 
450  <b>Usage</b>
451  \code
452 
453  ROMol::EDGE_ITER firstB,lastB;
454  boost::tie(firstB,lastB) = mol.getEdges();
455  while(firstB!=lastB){
456  BOND_SPTR bond = mol[*firstB];
457  ... do something with the Bond ...
458  ++firstB;
459  }
460  \endcode
461  */
462  BOND_ITER_PAIR getEdges();
463  //! \overload
464  ATOM_ITER_PAIR getVertices() const;
465  //! \overload
466  BOND_ITER_PAIR getEdges() const;
467 
468  //! brief returns a pointer to our underlying BGL object
469  /*!
470  This can be useful if you need to call other BGL algorithms:
471 
472  Here's an example:
473  \code
474  ... mol is a const ROMol ...
475  ... mapping is an INT_VECT ...
476  mapping.resize(mol.getNumAtoms());
477  const MolGraph &G_p = mol.getTopology();
478  int res = boost::connected_components(G_p,&mapping[0]);
479  \endcode
480  */
481  MolGraph const &getTopology() const { return d_graph; };
482  //@}
483 
484  //! \name Iterators
485  //@{
486 
487  //! get an AtomIterator pointing at our first Atom
488  AtomIterator beginAtoms();
489  //! \overload
490  ConstAtomIterator beginAtoms() const;
491  //! get an AtomIterator pointing at the end of our Atoms
492  AtomIterator endAtoms();
493  //! \overload
494  ConstAtomIterator endAtoms() const;
495  //! get a BondIterator pointing at our first Bond
496  BondIterator beginBonds();
497  //! \overload
498  ConstBondIterator beginBonds() const;
499  //! get a BondIterator pointing at the end of our Bonds
500  BondIterator endBonds();
501  //! \overload
502  ConstBondIterator endBonds() const;
503 
504  //! get an AtomIterator pointing at our first aromatic Atom
505  AromaticAtomIterator beginAromaticAtoms();
506  //! \overload
507  ConstAromaticAtomIterator beginAromaticAtoms() const;
508  //! get an AtomIterator pointing at the end of our Atoms
509  AromaticAtomIterator endAromaticAtoms();
510  //! \overload
511  ConstAromaticAtomIterator endAromaticAtoms() const;
512 
513  //! get an AtomIterator pointing at our first hetero Atom
514  HeteroatomIterator beginHeteros();
515  //! \overload
516  ConstHeteroatomIterator beginHeteros() const;
517  //! get an AtomIterator pointing at the end of our Atoms
518  HeteroatomIterator endHeteros();
519  //! \overload
520  ConstHeteroatomIterator endHeteros() const;
521 
522  //! get an AtomIterator pointing at our first Atom that matches \c query
523  QueryAtomIterator beginQueryAtoms(QueryAtom const *query);
524  //! \overload
525  ConstQueryAtomIterator beginQueryAtoms(QueryAtom const *) const;
526  //! get an AtomIterator pointing at the end of our Atoms
527  QueryAtomIterator endQueryAtoms();
528  //! \overload
529  ConstQueryAtomIterator endQueryAtoms() const;
530 
531  //! get an AtomIterator pointing at our first Atom that matches \c query
532  MatchingAtomIterator beginMatchingAtoms(bool (*query)(Atom *));
533  //! \overload
534  ConstMatchingAtomIterator beginMatchingAtoms(
535  bool (*query)(const Atom *)) const;
536  //! get an AtomIterator pointing at the end of our Atoms
537  MatchingAtomIterator endMatchingAtoms();
538  //! \overload
539  ConstMatchingAtomIterator endMatchingAtoms() const;
540 
541  inline ConformerIterator beginConformers() { return d_confs.begin(); }
542 
543  inline ConformerIterator endConformers() { return d_confs.end(); }
544 
545  inline ConstConformerIterator beginConformers() const {
546  return d_confs.begin();
547  }
548 
549  inline ConstConformerIterator endConformers() const { return d_confs.end(); }
550 
551  //@}
552 
553  //! \name Properties
554  //@{
555 
556  //! returns a list with the names of our \c properties
557  STR_VECT getPropList(bool includePrivate = true,
558  bool includeComputed = true) const {
559  const STR_VECT &tmp = dp_props->keys();
560  STR_VECT res, computed;
561  if (!includeComputed &&
563  computed.push_back(detail::computedPropName);
564  }
565 
566  STR_VECT::const_iterator pos = tmp.begin();
567  while (pos != tmp.end()) {
568  if ((includePrivate || (*pos)[0] != '_') &&
569  std::find(computed.begin(), computed.end(), *pos) == computed.end()) {
570  res.push_back(*pos);
571  }
572  pos++;
573  }
574  return res;
575  }
576 
577  //! sets a \c property value
578  /*!
579  \param key the name under which the \c property should be stored.
580  If a \c property is already stored under this name, it will be
581  replaced.
582  \param val the value to be stored
583  \param computed (optional) allows the \c property to be flagged
584  \c computed.
585  */
586  template <typename T>
587  void setProp(const char *key, T val, bool computed = false) const {
588  std::string what(key);
589  setProp(what, val, computed);
590  }
591  //! \overload
592  template <typename T>
593  void setProp(const std::string &key, T val, bool computed = false) const {
594  if (computed) {
595  STR_VECT compLst;
596  dp_props->getVal(detail::computedPropName, compLst);
597  if (std::find(compLst.begin(), compLst.end(), key) == compLst.end()) {
598  compLst.push_back(key);
599  dp_props->setVal(detail::computedPropName, compLst);
600  }
601  }
602  dp_props->setVal(key, val);
603  }
604 
605  //! allows retrieval of a particular property value
606  /*!
607 
608  \param key the name under which the \c property should be stored.
609  If a \c property is already stored under this name, it will be
610  replaced.
611  \param res a reference to the storage location for the value.
612 
613  <b>Notes:</b>
614  - if no \c property with name \c key exists, a KeyErrorException will be
615  thrown.
616  - the \c boost::lexical_cast machinery is used to attempt type
617  conversions.
618  If this fails, a \c boost::bad_lexical_cast exception will be thrown.
619 
620  */
621  template <typename T>
622  void getProp(const char *key, T &res) const {
623  dp_props->getVal(key, res);
624  }
625  //! \overload
626  template <typename T>
627  void getProp(const std::string &key, T &res) const {
628  dp_props->getVal(key, res);
629  }
630  //! \overload
631  template <typename T>
632  T getProp(const char *key) const {
633  return dp_props->getVal<T>(key);
634  }
635  //! \overload
636  template <typename T>
637  T getProp(const std::string &key) const {
638  return dp_props->getVal<T>(key);
639  }
640 
641  //! returns whether or not we have a \c property with name \c key
642  //! and assigns the value if we do
643  template <typename T>
644  bool getPropIfPresent(const char *key, T &res) const {
645  return dp_props->getValIfPresent(key, res);
646  }
647  //! \overload
648  template <typename T>
649  bool getPropIfPresent(const std::string &key, T &res) const {
650  return dp_props->getValIfPresent(key, res);
651  }
652 
653  //! returns whether or not we have a \c property with name \c key
654  bool hasProp(const char *key) const {
655  if (!dp_props) return false;
656  return dp_props->hasVal(key);
657  }
658  //! \overload
659  bool hasProp(const std::string &key) const {
660  if (!dp_props) return false;
661  return dp_props->hasVal(key);
662  // return hasProp(key.c_str());
663  }
664 
665  //! clears the value of a \c property
666  /*!
667  <b>Notes:</b>
668  - if no \c property with name \c key exists, a KeyErrorException
669  will be thrown.
670  - if the \c property is marked as \c computed, it will also be removed
671  from our list of \c computedProperties
672  */
673  void clearProp(const char *key) const {
674  std::string what(key);
675  clearProp(what);
676  };
677  //! \overload
678  void clearProp(const std::string &key) const {
679  STR_VECT compLst;
681  STR_VECT_I svi = std::find(compLst.begin(), compLst.end(), key);
682  if (svi != compLst.end()) {
683  compLst.erase(svi);
684  dp_props->setVal(detail::computedPropName, compLst);
685  }
686 
687  dp_props->clearVal(key);
688  };
689 
690  //! clears all of our \c computed \c properties
691  void clearComputedProps(bool includeRings = true) const;
692  //! calculates any of our lazy \c properties
693  /*!
694  <b>Notes:</b>
695  - this calls \c updatePropertyCache() on each of our Atoms and Bonds
696  */
697  void updatePropertyCache(bool strict = true);
698 
699  bool needsUpdatePropertyCache() const;
700 
701  //@}
702 
703  //! \name Misc
704  //@{
705  //! sends some debugging info to a stream
706  void debugMol(std::ostream &str) const;
707  //@}
708 
709  ATOM_SPTR operator[](const vertex_descriptor &v) { return d_graph[v]; };
710  const ATOM_SPTR operator[](const vertex_descriptor &v) const {
711  return d_graph[v];
712  };
713 
714  BOND_SPTR operator[](const edge_descriptor &e) { return d_graph[e]; };
715  const BOND_SPTR operator[](const edge_descriptor &e) const {
716  return d_graph[e];
717  };
718 
719  private:
720  MolGraph d_graph;
721  ATOM_BOOKMARK_MAP d_atomBookmarks;
722  BOND_BOOKMARK_MAP d_bondBookmarks;
723  Dict *dp_props;
724  RingInfo *dp_ringInfo;
725  CONF_SPTR_LIST d_confs;
726  ROMol &operator=(
727  const ROMol &); // disable assignment, RWMol's support assignment
728 
729 #ifdef WIN32
730  protected:
731 #endif
732  void initMol();
733  virtual void destroy();
734  //! adds an Atom to our collection
735  /*!
736  \param atom pointer to the Atom to add
737  \param updateLabel (optional) if this is true, the new Atom will be
738  our \c activeAtom
739  \param takeOwnership (optional) if this is true, we take ownership of \c
740  atom
741  instead of copying it.
742 
743  \return the new number of atoms
744  */
745  unsigned int addAtom(Atom *atom, bool updateLabel = true,
746  bool takeOwnership = false);
747  //! adds an Atom to our collection
748  /*!
749  \param atom pointer to the Atom to add
750  \param updateLabel (optional) if this is true, the new Atom will be
751  our \c activeAtom
752 
753 
754  \return the new number of atoms
755 
756  <b>Note:</b> since this is using a smart pointer, we don't need to worry
757  about
758  issues of ownership.
759 
760  */
761  unsigned int addAtom(ATOM_SPTR, bool updateLabel = true);
762  //! adds a Bond to our collection
763  /*!
764  \param bond pointer to the Bond to add
765  \param takeOwnership (optional) if this is true, we take ownership of \c
766  bond
767  instead of copying it.
768 
769  \return the new number of bonds
770  */
771  unsigned int addBond(Bond *bond, bool takeOwnership = false);
772  //! adds a Bond to our collection
773  /*!
774  \param bond pointer to the Bond to add
775 
776  \return the new number of bonds
777 
778  <b>Note:</b> since this is using a smart pointer, we don't need to worry
779  about
780  issues of ownership.
781  */
782  unsigned int addBond(BOND_SPTR bsp);
783 
784  //! initializes from the contents of another molecule
785  /*!
786  \param other the molecule to be copied
787  \param quickCopy if this is true, we will not
788  copy any of the properties or bookmarks and conformers from \c other.
789  This can
790  make the copy substantially faster (thus the name).
791  \param confId if this is >=0, the resulting ROMol will contain only
792  the specified conformer from \c other.
793  */
794  void initFromOther(const ROMol &other, bool quickCopy, int confId);
795 };
796 
797 typedef std::vector<ROMol> MOL_VECT;
798 typedef boost::shared_ptr<ROMol> ROMOL_SPTR;
799 typedef std::vector<ROMol *> MOL_PTR_VECT;
800 typedef std::vector<ROMOL_SPTR> MOL_SPTR_VECT;
801 
802 typedef MOL_PTR_VECT::const_iterator MOL_PTR_VECT_CI;
803 typedef MOL_PTR_VECT::iterator MOL_PTR_VECT_I;
804 
805 }; // end of RDKit namespace
806 #endif
Bond * getBondWithBookmark(int mark)
returns the first Bond associated with the bookmark provided
AtomIterator endAtoms()
get an AtomIterator pointing at the end of our Atoms
boost::shared_ptr< Bond > BOND_SPTR
Definition: ROMol.h:41
const Conformer & getConformer(int id=-1) const
const ATOM_SPTR operator[](const vertex_descriptor &v) const
Definition: ROMol.h:710
ATOM_PTR_LIST & getAllAtomsWithBookmark(int mark)
returns all Atoms associated with the bookmark provided
T getProp(const std::string &key) const
Definition: ROMol.h:637
void setVal(const std::string &what, T &val)
Sets the value associated with a key.
Definition: Dict.h:169
void removeConformer(unsigned int id)
Delete the conformation with the specified ID.
ATOM_ITER_PAIR getVertices()
returns an iterator pair for looping over all Atoms
const int ci_RIGHTMOST_ATOM
ATOM_BOOKMARK_MAP * getAtomBookmarks()
returns a pointer to all of our atom bookmarks
Definition: ROMol.h:303
void setBondBookmark(BOND_SPTR bond, int mark)
associates a Bond pointer with a bookmark
Definition: ROMol.h:306
std::vector< ROMol > MOL_VECT
Definition: ROMol.h:797
void replaceAtomBookmark(Atom *at, int mark)
Definition: ROMol.h:282
Iterate over aromatic atoms, this is bidirectional.
MOL_PTR_VECT::iterator MOL_PTR_VECT_I
Definition: ROMol.h:803
void setBondBookmark(Bond *bond, int mark)
Definition: ROMol.h:310
void debugMol(std::ostream &str) const
sends some debugging info to a stream
std::vector< ROMol * > MOL_PTR_VECT
Definition: ROMol.h:799
void setAtomBookmark(Atom *at, int mark)
Definition: ROMol.h:273
RWMol is a molecule class that is intended to be edited.
Definition: RWMol.h:30
const Bond * getBondBetweenAtoms(const U idx1, const V idx2) const
Definition: ROMol.h:258
unsigned int getNumAtoms(bool onlyExplicit=1) const
returns our number of atoms
bool hasVal(const char *what) const
Returns whether or not the dictionary contains a particular key.
Definition: Dict.h:48
BondIterator endBonds()
get a BondIterator pointing at the end of our Bonds
boost::adjacency_list< boost::vecS, boost::vecS, boost::undirectedS, ATOM_SPTR, BOND_SPTR > MolGraph
This is the BGL type used to store the topology:
Definition: ROMol.h:46
Iterate over atoms matching a query. This is bidirectional.
const int ci_ATOM_HOLDER
AromaticAtomIterator beginAromaticAtoms()
get an AtomIterator pointing at our first aromatic Atom
bool hasAtomBookmark(int mark) const
queries whether or not any atoms are associated with a bookmark
Definition: ROMol.h:301
ROMol(const ROMol &other, bool quickCopy=false, int confId=-1)
copy constructor with a twist
Definition: ROMol.h:190
boost::shared_ptr< Atom > ATOM_SPTR
Definition: Bond.h:26
unsigned int getNumBonds(bool onlyHeavy=1) const
returns our number of Bonds
Class for storing atomic queries.
Definition: QueryAtom.h:26
HeteroatomIterator beginHeteros()
get an AtomIterator pointing at our first hetero Atom
const Atom * getAtomWithIdx(const U idx) const
Definition: ROMol.h:218
unsigned int getNumConformers() const
Definition: ROMol.h:363
bool getPropIfPresent(const char *key, T &res) const
Definition: ROMol.h:644
void clearBondBookmark(int mark)
removes a bookmark from our collection
ADJ_ITER_PAIR getAtomNeighbors(Atom const *at) const
provides access to all neighbors around an Atom
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
iterator for a molecule&#39;s bonds, currently BiDirectional, but it theoretically ought to be RandomAcce...
Definition: BondIterators.h:26
ROMol is a molecule class that is intended to have a fixed topology.
Definition: ROMol.h:102
std::vector< boost::shared_ptr< ROMol > > MOL_SPTR_VECT
Definition: FragCatParams.h:19
void clearBondBookmark(int mark, BOND_SPTR bond)
Definition: ROMol.h:322
unsigned int getAtomDegree(const Atom *at) const
returns the degree (number of neighbors) of an Atom in the graph
void getVal(const std::string &what, T &res) const
Gets the value associated with a particular key.
Definition: Dict.h:84
void clearVal(const std::string &what)
Clears the value associated with a particular key, removing the key from the dictionary.
Definition: Dict.h:195
QueryAtomIterator endQueryAtoms()
get an AtomIterator pointing at the end of our Atoms
void getProp(const std::string &key, T &res) const
Definition: ROMol.h:627
BOND_SPTR operator[](const edge_descriptor &e)
Definition: ROMol.h:714
RingInfo * getRingInfo() const
Definition: ROMol.h:374
MOL_PTR_VECT::const_iterator MOL_PTR_VECT_CI
Definition: ROMol.h:802
Bond * getBondBetweenAtoms(unsigned int idx1, unsigned int idx2)
returns a pointer to the bond between two atoms, Null on failure
bool hasBondBookmark(int mark) const
queries whether or not any bonds are associated with a bookmark
Definition: ROMol.h:328
QueryAtomIterator beginQueryAtoms(QueryAtom const *query)
get an AtomIterator pointing at our first Atom that matches query
void clearComputedProps(bool includeRings=true) const
clears all of our computed properties
STR_VECT getPropList(bool includePrivate=true, bool includeComputed=true) const
returns a list with the names of our properties
Definition: ROMol.h:557
void updatePropertyCache(bool strict=true)
calculates any of our lazy properties
const Bond * getBondWithIdx(const U idx) const
Definition: ROMol.h:243
BOND_PTR_LIST & getAllBondsWithBookmark(int mark)
returns all bonds associated with the bookmark provided
MatchingAtomIterator endMatchingAtoms()
get an AtomIterator pointing at the end of our Atoms
void setProp(const char *key, T val, bool computed=false) const
sets a property value
Definition: ROMol.h:587
T getProp(const char *key) const
Definition: ROMol.h:632
void clearProp(const char *key) const
clears the value of a property
Definition: ROMol.h:673
void setProp(const std::string &key, T val, bool computed=false) const
Definition: ROMol.h:593
MatchingAtomIterator beginMatchingAtoms(bool(*query)(Atom *))
get an AtomIterator pointing at our first Atom that matches query
ConstConformerIterator beginConformers() const
Definition: ROMol.h:545
Bond * getBondWithIdx(unsigned int idx)
returns a pointer to a particular Bond
const iterator for a molecule&#39;s bonds, currently BiDirectional, but it theoretically ought to be Rand...
Definition: BondIterators.h:51
boost::shared_ptr< ROMol > ROMOL_SPTR
virtual ~ROMol()
Definition: ROMol.h:198
BOND_BOOKMARK_MAP * getBondBookmarks()
returns a pointer to all of our bond bookmarks
Definition: ROMol.h:330
Includes a bunch of functionality for handling Atom and Bond queries.
Definition: Atom.h:28
A general random access iterator.
Definition: AtomIterators.h:30
const BOND_SPTR operator[](const edge_descriptor &e) const
Definition: ROMol.h:715
A class to store information about a molecule&#39;s rings.
Definition: RingInfo.h:21
void clearProp(const std::string &key) const
Definition: ROMol.h:678
STR_VECT keys() const
Returns the set of keys in the dictionary.
Definition: Dict.h:61
void clearConformers()
Clear all the conformations on the molecule.
Definition: ROMol.h:349
void replaceAtomBookmark(ATOM_SPTR at, int mark)
associates an Atom pointer with a bookmark
Definition: ROMol.h:277
const std::string computedPropName
Definition: types.h:25
void clearAtomBookmark(const int mark, ATOM_SPTR atom)
Definition: ROMol.h:295
ATOM_SPTR operator[](const vertex_descriptor &v)
Definition: ROMol.h:709
OBOND_ITER_PAIR getAtomBonds(Atom const *at) const
provides access to all Bond objects connected to an Atom
const int ci_LEADING_BOND
bool hasProp(const std::string &key) const
Definition: ROMol.h:659
class for representing a bond
Definition: Bond.h:46
void clearAllAtomBookmarks()
blows out all atomic bookmarks
Definition: ROMol.h:299
HeteroatomIterator endHeteros()
get an AtomIterator pointing at the end of our Atoms
Iterate over atoms matching a query function. This is bidirectional.
BondIterator beginBonds()
get a BondIterator pointing at our first Bond
BOND_ITER_PAIR getEdges()
returns an iterator pair for looping over all Bonds
ConstConformerIterator endConformers() const
Definition: ROMol.h:549
handles pickling (serializing) molecules
Definition: MolPickler.h:46
AtomIterator beginAtoms()
get an AtomIterator pointing at our first Atom
MolGraph const & getTopology() const
brief returns a pointer to our underlying BGL object
Definition: ROMol.h:481
Atom * getAtomWithIdx(const U idx)
Definition: ROMol.h:213
The class for representing 2D or 3D conformation of a molecule.
Definition: Conformer.h:41
Bond * getBondBetweenAtoms(const U idx1, const V idx2)
Definition: ROMol.h:252
void getProp(const char *key, T &res) const
allows retrieval of a particular property value
Definition: ROMol.h:622
ConformerIterator endConformers()
Definition: ROMol.h:543
void clearAtomBookmark(const int mark)
removes a bookmark from our collection
Atom * getAtomWithIdx(unsigned int idx)
returns a pointer to a particular Atom
Defines the Atom class and associated typedefs.
bool hasProp(const char *key) const
returns whether or not we have a property with name key
Definition: ROMol.h:654
bool needsUpdatePropertyCache() const
std::vector< std::string >::iterator STR_VECT_I
Definition: types.h:168
ConformerIterator beginConformers()
Definition: ROMol.h:541
Atom * getAtomWithBookmark(int mark)
returns the first Atom associated with the bookmark provided
unsigned int getNumHeavyAtoms() const
returns our number of heavy atoms (atomic number > 1)
bool getPropIfPresent(const std::string &key, T &res) const
Definition: ROMol.h:649
Bond * getBondWithIdx(const U idx)
Definition: ROMol.h:238
void clearAllBondBookmarks()
blows out all bond bookmarks
Definition: ROMol.h:326
Class for storing Bond queries.
Definition: QueryBond.h:27
The Dict class can be used to store objects of arbitrary type keyed by strings.
Definition: Dict.h:33
Iterate over heteroatoms, this is bidirectional.
Definition: AtomIterators.h:72
The class for representing atoms.
Definition: Atom.h:67
std::vector< std::string > STR_VECT
Definition: Dict.h:26
AromaticAtomIterator endAromaticAtoms()
get an AtomIterator pointing at the end of our Atoms
void setAtomBookmark(ATOM_SPTR at, int mark)
associates an Atom pointer with a bookmark
Definition: ROMol.h:269
unsigned int addConformer(Conformer *conf, bool assignId=false)
Add a new conformation to the molecule.