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,
65  const SubstructMatchParameters &params = SubstructMatchParameters());
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,
78  const SubstructMatchParameters &params = SubstructMatchParameters());
79 
80 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
81  const MolBundle &bundle, const ROMol &query,
82  const SubstructMatchParameters &params = SubstructMatchParameters());
83 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
84  const ROMol &mol, const MolBundle &query,
85  const SubstructMatchParameters &params = SubstructMatchParameters());
86 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
87  const MolBundle &bundle, const MolBundle &query,
88  const SubstructMatchParameters &params = SubstructMatchParameters());
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 <>
168 inline bool SubstructMatch(ResonanceMolSupplier &resMolSupplier,
169  const ROMol &query, MatchVectType &matchVect,
170  bool recursionPossible, bool useChirality,
171  bool useQueryQueryMatches) {
173  params.recursionPossible = recursionPossible;
174  params.useChirality = useChirality;
175  params.useQueryQueryMatches = useQueryQueryMatches;
176  params.maxMatches = 1;
177  std::vector<MatchVectType> matchVects =
178  SubstructMatch(resMolSupplier, query, params);
179  if (matchVects.size()) {
180  matchVect = matchVects.front();
181  } else {
182  matchVect.clear();
183  }
184  return matchVect.size() != 0;
185 }
186 
187 template <>
188 inline unsigned int SubstructMatch(ResonanceMolSupplier &resMolSupplier,
189  const ROMol &query,
190  std::vector<MatchVectType> &matchVect,
191  bool uniquify, bool recursionPossible,
192  bool useChirality, bool useQueryQueryMatches,
193  unsigned int maxMatches, int numThreads) {
195  params.uniquify = uniquify;
196  params.recursionPossible = recursionPossible;
197  params.useChirality = useChirality;
198  params.useQueryQueryMatches = useQueryQueryMatches;
199  params.maxMatches = maxMatches;
200  params.numThreads = numThreads;
201  matchVect = SubstructMatch(resMolSupplier, query, params);
202  return matchVect.size();
203 };
204 
205 } // namespace RDKit
206 
207 #endif
RDKit::SubstructMatchParameters::uniquify
bool uniquify
uniquify (by atom index) match results
Definition: SubstructMatch.h:36
RDKit::SubstructMatchParameters::useQueryQueryMatches
bool useQueryQueryMatches
Definition: SubstructMatch.h:33
RDKit::SubstructMatch
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.
RDKit::SubstructMatchParameters::maxMatches
unsigned int maxMatches
maximum number of matches to return
Definition: SubstructMatch.h:37
RDKit::SubstructMatchParameters::aromaticMatchesConjugated
bool aromaticMatchesConjugated
Definition: SubstructMatch.h:31
RDKit::ROMol
Definition: ROMol.h:171
RDKit::SubstructMatchParameters::SubstructMatchParameters
SubstructMatchParameters()
Definition: SubstructMatch.h:44
RDKit::SubstructMatchParameters::numThreads
int numThreads
Definition: SubstructMatch.h:38
RDKit::SubstructMatchParameters::recursionPossible
bool recursionPossible
Allow recursive queries.
Definition: SubstructMatch.h:35
RDKit
Std stuff.
Definition: Atom.h:30
RDKit::SubstructMatchParameters::useChirality
bool useChirality
Definition: SubstructMatch.h:29
RDKit::SubstructMatchParameters
Definition: SubstructMatch.h:28
RDKIT_SUBSTRUCTMATCH_EXPORT
#define RDKIT_SUBSTRUCTMATCH_EXPORT
Definition: export.h:684
RDKit::ResonanceMolSupplier
Definition: Resonance.h:33
RDKit::MatchVectType
std::vector< std::pair< int, int > > MatchVectType
used to return matches from substructure searching, The format is (queryAtomIdx, molAtomIdx)
Definition: FragFPGenerator.h:24
export.h