RDKit
Open-source cheminformatics and machine learning.
SubstructMatch.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2019 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_SUBSTRUCTMATCH_H
12 #define RD_SUBSTRUCTMATCH_H
13 
14 // std bits
15 #include <vector>
16 
17 namespace RDKit {
18 class ROMol;
19 class Atom;
20 class Bond;
21 class ResonanceMolSupplier;
22 class MolBundle;
23 
24 //! \brief used to return matches from substructure searching,
25 //! The format is (queryAtomIdx, molAtomIdx)
26 typedef std::vector<std::pair<int, int>> MatchVectType;
27 
29  bool useChirality; //!< Use chirality in determining whether or not
30  //!< atoms/bonds match
31  bool aromaticMatchesConjugated; //!< Aromatic and conjugated bonds match each
32  //!< other
33  bool useQueryQueryMatches; //!< Consider query-query matches, not just simple
34  //!< matches
35  bool recursionPossible; //!< Allow recursive queries
36  bool uniquify; //!< uniquify (by atom index) match results
37  unsigned int maxMatches; //!< maximum number of matches to return
38  int numThreads; //!< number of threads to use when multi-threading
39  //!< is possible. 0 selects the number of
40  //!< concurrent threads supported by the hardware
41  //!< negative values are added to the number of
42  //!< concurrent threads supported by the hardware
43 
45  : useChirality(false),
46  aromaticMatchesConjugated(false),
47  useQueryQueryMatches(false),
48  recursionPossible(true),
49  uniquify(true),
50  maxMatches(1000),
51  numThreads(1){};
52 };
53 
54 //! Find a substructure match for a query in a molecule
55 /*!
56  \param mol The ROMol to be searched
57  \param query The query ROMol
58  \param matchParams Parameters controlling the matching
59 
60  \return The matches, if any
61 
62 */
63 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
64  const ROMol &mol, const ROMol &query,
66 
67 //! Find all substructure matches for a query in a ResonanceMolSupplier object
68 /*!
69  \param resMolSuppl The ResonanceMolSupplier object to be searched
70  \param query The query ROMol
71  \param matchParams Parameters controlling the matching
72 
73  \return The matches, if any
74 
75 */
76 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
77  ResonanceMolSupplier &resMolSuppl, const ROMol &query,
79 
80 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
81  const MolBundle &bundle, const ROMol &query,
83 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
84  const ROMol &mol, const MolBundle &query,
86 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
87  const MolBundle &bundle, const MolBundle &query,
89 
90 //! Find a substructure match for a query
91 /*!
92  \param mol The object to be searched
93  \param query The query
94  \param matchVect Used to return the match
95  (pre-existing contents will be deleted)
96  \param recursionPossible flags whether or not recursive matches are allowed
97  \param useChirality use atomic CIP codes as part of the comparison
98  \param useQueryQueryMatches if set, the contents of atom and bond queries
99  will be used as part of the matching
100 
101  \return whether or not a match was found
102 
103 */
104 template <typename T1, typename T2>
105 bool SubstructMatch(T1 &mol, const T2 &query, MatchVectType &matchVect,
106  bool recursionPossible = true, bool useChirality = false,
107  bool useQueryQueryMatches = false) {
109  params.recursionPossible = recursionPossible;
110  params.useChirality = useChirality;
111  params.useQueryQueryMatches = useQueryQueryMatches;
112  params.maxMatches = 1;
113  std::vector<MatchVectType> matchVects = SubstructMatch(mol, query, params);
114  if (matchVects.size()) {
115  matchVect = matchVects.front();
116  } else {
117  matchVect.clear();
118  }
119  return matchVect.size() != 0;
120 };
121 
122 //! Find all substructure matches for a query
123 /*!
124  \param mol The object to be searched
125  \param query The query
126  \param matchVect Used to return the matches
127  (pre-existing contents will be deleted)
128  \param uniquify Toggles uniquification (by atom index) of the results
129  \param recursionPossible flags whether or not recursive matches are allowed
130  \param useChirality use atomic CIP codes as part of the comparison
131  \param useQueryQueryMatches if set, the contents of atom and bond queries
132  will be used as part of the matching
133  \param maxMatches The maximum number of matches that will be returned.
134  In high-symmetry cases with medium-sized molecules, it is
135  very
136  easy to end up with a combinatorial explosion in the
137  number of
138  possible matches. This argument prevents that from having
139  unintended consequences
140 
141  \return the number of matches found
142 
143 */
144 template <typename T1, typename T2>
145 unsigned int SubstructMatch(T1 &mol, const T2 &query,
146  std::vector<MatchVectType> &matchVect,
147  bool uniquify = true, bool recursionPossible = true,
148  bool useChirality = false,
149  bool useQueryQueryMatches = false,
150  unsigned int maxMatches = 1000,
151  int numThreads = 1) {
153  params.uniquify = uniquify;
154  params.recursionPossible = recursionPossible;
155  params.useChirality = useChirality;
156  params.useQueryQueryMatches = useQueryQueryMatches;
157  params.maxMatches = maxMatches;
158  params.numThreads = numThreads;
159  matchVect = SubstructMatch(mol, query, params);
160  return matchVect.size();
161 };
162 
163 // ----------------------------------------------
164 //
165 // find one match in ResonanceMolSupplier object
166 //
167 template <> inline
168 bool SubstructMatch(ResonanceMolSupplier &resMolSupplier, const ROMol &query,
169  MatchVectType &matchVect, bool recursionPossible,
170  bool useChirality, bool useQueryQueryMatches) {
172  params.recursionPossible = recursionPossible;
173  params.useChirality = useChirality;
174  params.useQueryQueryMatches = useQueryQueryMatches;
175  params.maxMatches = 1;
176  std::vector<MatchVectType> matchVects =
177  SubstructMatch(resMolSupplier, query, params);
178  if (matchVects.size()) {
179  matchVect = matchVects.front();
180  } else {
181  matchVect.clear();
182  }
183  return matchVect.size() != 0;
184 }
185 
186 template <> inline
187 unsigned int SubstructMatch(ResonanceMolSupplier &resMolSupplier,
188  const ROMol &query,
189  std::vector<MatchVectType> &matchVect,
190  bool uniquify, bool recursionPossible,
191  bool useChirality, bool useQueryQueryMatches,
192  unsigned int maxMatches, int numThreads) {
194  params.uniquify = uniquify;
195  params.recursionPossible = recursionPossible;
196  params.useChirality = useChirality;
197  params.useQueryQueryMatches = useQueryQueryMatches;
198  params.maxMatches = maxMatches;
199  params.numThreads = numThreads;
200  matchVect = SubstructMatch(resMolSupplier, query, params);
201  return matchVect.size();
202 };
203 
204 } // namespace RDKit
205 
206 #endif
std::vector< std::pair< int, int > > MatchVectType
used to return matches from substructure searching, The format is (queryAtomIdx, molAtomIdx) ...
unsigned int maxMatches
maximum number of matches to return
#define RDKIT_SUBSTRUCTMATCH_EXPORT
Definition: export.h:671
bool uniquify
uniquify (by atom index) match results
Std stuff.
Definition: Atom.h:30
bool recursionPossible
Allow recursive queries.
RDKIT_SUBSTRUCTMATCH_EXPORT std::vector< MatchVectType > SubstructMatch(const ROMol &mol, const ROMol &query, const SubstructMatchParameters &params=SubstructMatchParameters())
Find a substructure match for a query in a molecule.