RDKit: SubstructMatch.h Source File

| RDKit Open-source cheminformatics and machine learning.

Loading...
Searching...
No Matches
SubstructMatch.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2025 Greg Landrum and other RDKit contributors
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#include <unordered_set>
18#include <functional>
19#include <unordered_map>
20#include <cstdint>
21#include <string>
22#include <span>
23
24#include <boost/dynamic_bitset.hpp>
25#if BOOST_VERSION >= 107100
26#define RDK_INTERNAL_BITSET_HAS_HASH
27#endif
28
29#include <GraphMol/StereoGroup.h>
30
31namespace RDKit {
32class ROMol;
33class Atom;
34class Bond;
35class ResonanceMolSupplier;
36class MolBundle;
37
38//! \brief used to return matches from substructure searching,
39//! The format is (queryAtomIdx, molAtomIdx)
40typedef std::vector<std::pair<int, int>> MatchVectType;
41
42 struct RDKIT_SUBSTRUCTMATCH_EXPORT SubstructMatchParameters {
43 bool useChirality = false; //!< Use chirality in determining whether or not
44 //!< atoms/bonds match
45 bool useEnhancedStereo = false; //!< Use enhanced stereochemistry in
46 //!< determining whether atoms/bonds match
47 bool aromaticMatchesConjugated = false; //!< Aromatic and conjugated bonds
48 //!< match each other
49 bool useQueryQueryMatches = false; //!< Consider query-query matches, not
50 //!< just simple matches
51 bool useGenericMatchers = false; //!< Looks for generic atoms in the query
52 //!< and uses them as part of the matching
53 bool recursionPossible = true; //!< Allow recursive queries
54 bool uniquify = true; //!< uniquify (by atom index) match results
55 unsigned int maxMatches = 1000; //!< maximum number of matches to return
56 int numThreads = 1; //!< number of threads to use when multi-threading
57 //!< is possible. 0 selects the number of
58 //!< concurrent threads supported by the hardware
59 //!< negative values are added to the number of
60 //!< concurrent threads supported by the hardware
61 std::vector<std::string> atomProperties; //!< atom properties that must be
62 //!< equivalent in order to match
63 std::vector<std::string> bondProperties; //!< bond properties that must be
64 //!< equivalent in order to match
65 std::function<bool(const ROMol &mol,
66 std::span<const unsigned int> match)>
67 extraFinalCheck; //!< a function to be called at the end to validate a
68 //!< match
69 unsigned int maxRecursiveMatches =
70 1000; //!< maximum number of matches that the recursive substructure
71 //!< matching should return
72 bool specifiedStereoQueryMatchesUnspecified =
73 false; //!< If set, query atoms and bonds with specified stereochemistry
74 //!< will match atoms and bonds with unspecified stereochemistry
75 bool aromaticMatchesSingleOrDouble = false; //!< Aromatic bonds match single
76 //!< or double bonds
77 std::function<bool(const Atom &queryAtom, const Atom &molAtom)>
78 extraAtomCheck; //!< a function to be called after other atom comparisons
79 //!< have passed
80 bool extraAtomCheckOverridesDefaultCheck =
81 false; //!< if set, only the extraAtomCheck will be used to determine
82 //!< whether or not atoms match
83 std::function<bool(const Bond &queryBond, const Bond &molBond)>
84 extraBondCheck; //!< a function to be called after other bond comparisons
85 //!< have passed
86 bool extraBondCheckOverridesDefaultCheck =
87 false; //!< if set, only the extraBondCheck will be used to determine
88 //!< whether or not bonds match
89 SubstructMatchParameters() {}
90};
91
92 RDKIT_SUBSTRUCTMATCH_EXPORT void updateSubstructMatchParamsFromJSON(
93 SubstructMatchParameters &params, const std::string &json);
94 RDKIT_SUBSTRUCTMATCH_EXPORT std::string substructMatchParamsToJSON(
95 const SubstructMatchParameters &params);
96
97//! Find a substructure match for a query in a molecule
98/*!
99 \param mol The ROMol to be searched
100 \param query The query ROMol
101 \param matchParams Parameters controlling the matching
102
103 \return The matches, if any
104
105*/
106 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
107 const ROMol &mol, const ROMol &query,
108 const SubstructMatchParameters &params = SubstructMatchParameters());
109
110//! Find all substructure matches for a query in a ResonanceMolSupplier object
111/*!
112 \param resMolSuppl The ResonanceMolSupplier object to be searched
113 \param query The query ROMol
114 \param matchParams Parameters controlling the matching
115
116 \return The matches, if any
117
118*/
119 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
120 ResonanceMolSupplier &resMolSuppl, const ROMol &query,
121 const SubstructMatchParameters &params = SubstructMatchParameters());
122
123 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
124 const MolBundle &bundle, const ROMol &query,
125 const SubstructMatchParameters &params = SubstructMatchParameters());
126 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
127 const ROMol &mol, const MolBundle &query,
128 const SubstructMatchParameters &params = SubstructMatchParameters());
129 RDKIT_SUBSTRUCTMATCH_EXPORT std::vector<MatchVectType> SubstructMatch(
130 const MolBundle &bundle, const MolBundle &query,
131 const SubstructMatchParameters &params = SubstructMatchParameters());
132
133//! Find a substructure match for a query
134/*!
135 \param mol The object to be searched
136 \param query The query
137 \param matchVect Used to return the match
138 (pre-existing contents will be deleted)
139 \param recursionPossible flags whether or not recursive matches are allowed
140 \param useChirality use atomic CIP codes as part of the comparison
141 \param useQueryQueryMatches if set, the contents of atom and bond queries
142 will be used as part of the matching
143
144 \return whether or not a match was found
145
146*/
147template <typename T1, typename T2>
148 bool SubstructMatch(T1 &mol, const T2 &query, MatchVectType &matchVect,
149 bool recursionPossible = true, bool useChirality = false,
150 bool useQueryQueryMatches = false) {
151 SubstructMatchParameters params;
152 params.recursionPossible = recursionPossible;
153 params.useChirality = useChirality;
154 params.useQueryQueryMatches = useQueryQueryMatches;
155 params.maxMatches = 1;
156 std::vector<MatchVectType> matchVects = SubstructMatch(mol, query, params);
157 if (matchVects.size()) {
158 matchVect = matchVects.front();
159 } else {
160 matchVect.clear();
161 }
162 return matchVect.size() != 0;
163};
164
165//! Find all substructure matches for a query
166/*!
167 \param mol The object to be searched
168 \param query The query
169 \param matchVect Used to return the matches
170 (pre-existing contents will be deleted)
171 \param uniquify Toggles uniquification (by atom index) of the results
172 \param recursionPossible flags whether or not recursive matches are allowed
173 \param useChirality use atomic CIP codes as part of the comparison
174 \param useQueryQueryMatches if set, the contents of atom and bond queries
175 will be used as part of the matching
176 \param maxMatches The maximum number of matches that will be returned.
177 In high-symmetry cases with medium-sized molecules, it is
178 very
179 easy to end up with a combinatorial explosion in the
180 number of
181 possible matches. This argument prevents that from having
182 unintended consequences
183
184 \return the number of matches found
185
186*/
187template <typename T1, typename T2>
188 unsigned int SubstructMatch(T1 &mol, const T2 &query,
189 std::vector<MatchVectType> &matchVect,
190 bool uniquify = true, bool recursionPossible = true,
191 bool useChirality = false,
192 bool useQueryQueryMatches = false,
193 unsigned int maxMatches = 1000,
194 int numThreads = 1) {
195 SubstructMatchParameters params;
196 params.uniquify = uniquify;
197 params.recursionPossible = recursionPossible;
198 params.useChirality = useChirality;
199 params.useQueryQueryMatches = useQueryQueryMatches;
200 params.maxMatches = maxMatches;
201 params.numThreads = numThreads;
202 matchVect = SubstructMatch(mol, query, params);
203 return static_cast<unsigned int>(matchVect.size());
204};
205
206// ----------------------------------------------
207//
208// find one match in ResonanceMolSupplier object
209//
210template <>
211 inline bool SubstructMatch(ResonanceMolSupplier &resMolSupplier,
212 const ROMol &query, MatchVectType &matchVect,
213 bool recursionPossible, bool useChirality,
214 bool useQueryQueryMatches) {
215 SubstructMatchParameters params;
216 params.recursionPossible = recursionPossible;
217 params.useChirality = useChirality;
218 params.useQueryQueryMatches = useQueryQueryMatches;
219 params.maxMatches = 1;
220 std::vector<MatchVectType> matchVects =
221 SubstructMatch(resMolSupplier, query, params);
222 if (matchVects.size()) {
223 matchVect = matchVects.front();
224 } else {
225 matchVect.clear();
226 }
227 return matchVect.size() != 0;
228}
229
230template <>
231 inline unsigned int SubstructMatch(ResonanceMolSupplier &resMolSupplier,
232 const ROMol &query,
233 std::vector<MatchVectType> &matchVect,
234 bool uniquify, bool recursionPossible,
235 bool useChirality, bool useQueryQueryMatches,
236 unsigned int maxMatches, int numThreads) {
237 SubstructMatchParameters params;
238 params.uniquify = uniquify;
239 params.recursionPossible = recursionPossible;
240 params.useChirality = useChirality;
241 params.useQueryQueryMatches = useQueryQueryMatches;
242 params.maxMatches = maxMatches;
243 params.numThreads = numThreads;
244 matchVect = SubstructMatch(resMolSupplier, query, params);
245 return static_cast<unsigned int>(matchVect.size());
246};
247
248//! Class used as a final step to confirm whether or not a given atom->atom
249//! mapping is a valid substructure match.
250 class RDKIT_SUBSTRUCTMATCH_EXPORT MolMatchFinalCheckFunctor {
251 public:
252 MolMatchFinalCheckFunctor(const ROMol &query, const ROMol &mol,
253 const SubstructMatchParameters &ps);
254
255 bool operator()(const std::uint32_t q_c[], const std::uint32_t m_c[]);
256
257 private:
258 const ROMol &d_query;
259 const ROMol &d_mol;
260 const SubstructMatchParameters &d_params;
261 std::unordered_map<unsigned int, StereoGroup const *> d_molStereoGroups;
262#ifdef RDK_INTERNAL_BITSET_HAS_HASH
263 // Boost 1.71 added support for std::hash with dynamic_bitset.
264 using HashedStorageType = boost::dynamic_bitset<>;
265#else
266 // otherwise we use a less elegant solution
267 using HashedStorageType = std::string;
268#endif
269 std::unordered_set<HashedStorageType> matchesSeen;
270};
271
272 struct RDKIT_SUBSTRUCTMATCH_EXPORT AtomCoordsMatchFunctor {
273 int d_refConfId = -1;
274 int d_queryConfId = -1;
275 double d_tol2 = 1e-8; //< squared distance tolerance
276 AtomCoordsMatchFunctor(int refConfId = -1, int queryConfId = -1,
277 double tol = 1e-4)
278 : d_refConfId(refConfId),
279 d_queryConfId(queryConfId),
280 d_tol2(tol * tol) {};
281
282 bool operator()(const Atom &queryAtom, const Atom &targetAtom) const;
283};
284
285} // namespace RDKit
286
287#endif
StereoGroup.h
Defines the class StereoGroup which stores relationships between the absolute configurations of atoms...
RDKit::Atom
The class for representing atoms.
Definition Atom.h:74
RDKit::Bond
class for representing a bond
Definition Bond.h:46
RDKit::MolBundle
MolBundle contains a collection of related ROMols.
Definition MolBundle.h:59
RDKit::MolMatchFinalCheckFunctor::MolMatchFinalCheckFunctor
MolMatchFinalCheckFunctor(const ROMol &query, const ROMol &mol, const SubstructMatchParameters &ps)
RDKit::MolMatchFinalCheckFunctor::operator()
bool operator()(const std::uint32_t q_c[], const std::uint32_t m_c[])
RDKit::ROMol
Definition ROMol.h:199
RDKit::ResonanceMolSupplier
Definition Resonance.h:86
export.h
RDKIT_SUBSTRUCTMATCH_EXPORT
#define RDKIT_SUBSTRUCTMATCH_EXPORT
Definition export.h:569
RDKit
Std stuff.
Definition Abbreviations.h:19
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
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::updateSubstructMatchParamsFromJSON
RDKIT_SUBSTRUCTMATCH_EXPORT void updateSubstructMatchParamsFromJSON(SubstructMatchParameters &params, const std::string &json)
RDKit::substructMatchParamsToJSON
RDKIT_SUBSTRUCTMATCH_EXPORT std::string substructMatchParamsToJSON(const SubstructMatchParameters &params)
RDKit::AtomCoordsMatchFunctor::d_queryConfId
int d_queryConfId
Definition SubstructMatch.h:274
RDKit::AtomCoordsMatchFunctor::operator()
bool operator()(const Atom &queryAtom, const Atom &targetAtom) const
RDKit::AtomCoordsMatchFunctor::AtomCoordsMatchFunctor
AtomCoordsMatchFunctor(int refConfId=-1, int queryConfId=-1, double tol=1e-4)
Definition SubstructMatch.h:276
RDKit::AtomCoordsMatchFunctor::d_tol2
double d_tol2
Definition SubstructMatch.h:275
RDKit::AtomCoordsMatchFunctor::d_refConfId
int d_refConfId
Definition SubstructMatch.h:273
RDKit::SubstructMatchParameters
Definition SubstructMatch.h:42
RDKit::SubstructMatchParameters::extraAtomCheckOverridesDefaultCheck
bool extraAtomCheckOverridesDefaultCheck
Definition SubstructMatch.h:80
RDKit::SubstructMatchParameters::extraFinalCheck
std::function< bool(const ROMol &mol, std::span< const unsigned int > match)> extraFinalCheck
Definition SubstructMatch.h:67
RDKit::SubstructMatchParameters::extraBondCheckOverridesDefaultCheck
bool extraBondCheckOverridesDefaultCheck
Definition SubstructMatch.h:86
RDKit::SubstructMatchParameters::maxMatches
unsigned int maxMatches
maximum number of matches to return
Definition SubstructMatch.h:55
RDKit::SubstructMatchParameters::uniquify
bool uniquify
uniquify (by atom index) match results
Definition SubstructMatch.h:54
RDKit::SubstructMatchParameters::useChirality
bool useChirality
Definition SubstructMatch.h:43
RDKit::SubstructMatchParameters::atomProperties
std::vector< std::string > atomProperties
Definition SubstructMatch.h:61
RDKit::SubstructMatchParameters::useEnhancedStereo
bool useEnhancedStereo
Definition SubstructMatch.h:45
RDKit::SubstructMatchParameters::bondProperties
std::vector< std::string > bondProperties
Definition SubstructMatch.h:63
RDKit::SubstructMatchParameters::numThreads
int numThreads
Definition SubstructMatch.h:56
RDKit::SubstructMatchParameters::recursionPossible
bool recursionPossible
Allow recursive queries.
Definition SubstructMatch.h:53
RDKit::SubstructMatchParameters::maxRecursiveMatches
unsigned int maxRecursiveMatches
matching should return
Definition SubstructMatch.h:69
RDKit::SubstructMatchParameters::useGenericMatchers
bool useGenericMatchers
Definition SubstructMatch.h:51
RDKit::SubstructMatchParameters::useQueryQueryMatches
bool useQueryQueryMatches
Definition SubstructMatch.h:49
RDKit::SubstructMatchParameters::specifiedStereoQueryMatchesUnspecified
bool specifiedStereoQueryMatchesUnspecified
Definition SubstructMatch.h:72
RDKit::SubstructMatchParameters::aromaticMatchesConjugated
bool aromaticMatchesConjugated
Definition SubstructMatch.h:47
RDKit::SubstructMatchParameters::aromaticMatchesSingleOrDouble
bool aromaticMatchesSingleOrDouble
Definition SubstructMatch.h:75
RDKit::SubstructMatchParameters::extraAtomCheck
std::function< bool(const Atom &queryAtom, const Atom &molAtom)> extraAtomCheck
Definition SubstructMatch.h:78
RDKit::SubstructMatchParameters::extraBondCheck
std::function< bool(const Bond &queryBond, const Bond &molBond)> extraBondCheck
Definition SubstructMatch.h:84
RDKit::SubstructMatchParameters::SubstructMatchParameters
SubstructMatchParameters()
Definition SubstructMatch.h:89