RDKit
Open-source cheminformatics and machine learning.
Loading...
Searching...
No Matches
AlignMolecules.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2022 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_ALIGNMOLECULES_H_
12#define _RD_ALIGNMOLECULES_H_
13
15#include <Numerics/Vector.h>
16#include <vector>
17
18namespace RDKit {
19typedef std::vector<std::pair<int, int>> MatchVectType;
20
21class Conformer;
22class ROMol;
23namespace MolAlign {
24class RDKIT_MOLALIGN_EXPORT MolAlignException : public std::exception {
25 public:
26 //! construct with an error message
27 MolAlignException(const char *msg) : _msg(msg) {}
28 //! construct with an error message
29 MolAlignException(const std::string msg) : _msg(msg) {}
30 //! get the error message
31 const char *what() const noexcept override { return _msg.c_str(); }
32 ~MolAlignException() noexcept override = default;
33
34 private:
35 std::string _msg;
36};
37
38//! Alignment functions
39
40//! Compute the transformation required to align a molecule
41/*!
42 The 3D transformation required to align the specified conformation in the
43 probe molecule to a specified conformation in the reference molecule is
44 computed so that the root mean squared distance between a specified set of
45 atoms is minimized
46
47 \param prbMol molecule that is to be aligned
48 \param refMol molecule used as the reference for the alignment
49 \param trans storage for the computed transform
50 \param prbCid ID of the conformation in the probe to be used
51 for the alignment (defaults to first conformation)
52 \param refCid ID of the conformation in the ref molecule to which
53 the alignment is computed (defaults to first conformation)
54 \param atomMap a vector of pairs of atom IDs (probe AtomId, ref AtomId)
55 used to compute the alignments. If this mapping is
56 not specified an attempt is made to generate on by
57 substructure matching
58 \param weights Optionally specify weights for each of the atom pairs
59 \param reflect if true reflect the conformation of the probe molecule
60 \param maxIters maximum number of iterations used in minimizing the RMSD
61
62 <b>Returns</b>
63 RMSD value
64*/
65RDKIT_MOLALIGN_EXPORT double getAlignmentTransform(
66 const ROMol &prbMol, const ROMol &refMol, RDGeom::Transform3D &trans,
67 int prbCid = -1, int refCid = -1, const MatchVectType *atomMap = nullptr,
68 const RDNumeric::DoubleVector *weights = nullptr, bool reflect = false,
69 unsigned int maxIters = 50);
70
71//! Optimally (minimum RMSD) align a molecule to another molecule
72/*!
73 The 3D transformation required to align the specified conformation in the
74 probe molecule to a specified conformation in the reference molecule is
75 computed so that the root mean squared distance between a specified set of
76 atoms is minimized. This transform is then applied to the specified
77 conformation in the probe molecule
78
79 \param prbMol molecule that is to be aligned
80 \param refMol molecule used as the reference for the alignment
81 \param prbCid ID of the conformation in the probe to be used
82 for the alignment (defaults to first conformation)
83 \param refCid ID of the conformation in the ref molecule to which
84 the alignment is computed (defaults to first conformation)
85 \param atomMap a vector of pairs of atom IDs (probe AtomId, ref AtomId)
86 used to compute the alignments. If this mapping is
87 not specified an attempt is made to generate on by
88 substructure matching
89 \param weights Optionally specify weights for each of the atom pairs
90 \param reflect if true reflect the conformation of the probe molecule
91 \param maxIters maximum number of iterations used in minimizing the RMSD
92
93 <b>Returns</b>
94 RMSD value
95*/
96RDKIT_MOLALIGN_EXPORT double alignMol(
97 ROMol &prbMol, const ROMol &refMol, int prbCid = -1, int refCid = -1,
98 const MatchVectType *atomMap = nullptr,
99 const RDNumeric::DoubleVector *weights = nullptr, bool reflect = false,
100 unsigned int maxIters = 50);
101
102//! Compute the optimal RMS, transformation and atom map for aligning
103//! two molecules, taking symmetry into account. Molecule coordinates
104//! are left unaltered.
105/*!
106 This function will attempt to align all permutations of matching atom
107 orders in both molecules, for some molecules it will lead to 'combinatorial
108 explosion' especially if hydrogens are present.
109 Use 'RDKit::MolAlign::getAlignmentTransform' to align molecules
110 without changing the atom order.
111
112 \param prbMol the molecule to be aligned to the reference
113 \param refMol the reference molecule
114 \param bestTrans storage for the best computed transform
115 \param bestMatch storage for the MatchVectType corresponding to
116 the best match found.
117 \param prbCid (optional) probe conformation to use
118 \param refCid (optional) reference conformation to use
119 \param map (optional) a vector of vectors of pairs of atom IDs
120 (probe AtomId, ref AtomId) used to compute the alignments.
121 If not provided, these will be generated using a
122 substructure search.
123 \param maxMatches (optional) if map is empty, this will be the max number of
124 matches found in a SubstructMatch().
125 \param symmetrizeConjugatedTerminalGroups (optional) if set, conjugated
126 terminal functional groups (like nitro or carboxylate)
127 will be considered symmetrically
128 \param weights (optional) weights for each pair of atoms.
129 \param reflect if true reflect the conformation of the probe molecule
130 \param maxIters maximum number of iterations used in minimizing the RMSD
131
132 <b>Returns</b>
133 Best RMSD value found
134*/
135RDKIT_MOLALIGN_EXPORT double getBestAlignmentTransform(
136 const ROMol &prbMol, const ROMol &refMol, RDGeom::Transform3D &bestTrans,
137 MatchVectType &bestMatch, int prbCid = -1, int refCid = -1,
138 const std::vector<MatchVectType> &map = std::vector<MatchVectType>(),
139 int maxMatches = 1e6, bool symmetrizeConjugatedTerminalGroups = true,
140 const RDNumeric::DoubleVector *weights = nullptr, bool reflect = false,
141 unsigned int maxIters = 50);
142
143//! Returns the optimal RMS for aligning two molecules, taking
144/// symmetry into account. As a side-effect, the probe molecule is
145/// left in the aligned state.
146/*!
147 This function will attempt to align all permutations of matching atom
148 orders in both molecules, for some molecules it will lead to 'combinatorial
149 explosion' especially if hydrogens are present.
150 Use 'RDKit::MolAlign::alignMol' to align molecules without changing the
151 atom order.
152
153 \param prbMol the molecule to be aligned to the reference
154 \param refMol the reference molecule
155 \param trans storage for the computed transform
156 \param prbCid (optional) probe conformation to use
157 \param refCid (optional) reference conformation to use
158 \param map (optional) a vector of vectors of pairs of atom IDs
159 (probe AtomId, ref AtomId) used to compute the alignments.
160 If not provided, these will be generated using a
161 substructure search.
162 \param maxMatches (optional) if map is empty, this will be the max number of
163 matches found in a SubstructMatch().
164 \param symmetrizeConjugatedTerminalGroups (optional) if set, conjugated
165 terminal functional groups (like nitro or carboxylate)
166 will be considered symmetrically
167 \param weights (optional) weights for each pair of atoms.
168
169 <b>Returns</b>
170 Best RMSD value found
171*/
172RDKIT_MOLALIGN_EXPORT double getBestRMS(
173 ROMol &prbMol, const ROMol &refMol, int prbCid = -1, int refCid = -1,
174 const std::vector<MatchVectType> &map = std::vector<MatchVectType>(),
175 int maxMatches = 1e6, bool symmetrizeConjugatedTerminalGroups = true,
176 const RDNumeric::DoubleVector *weights = nullptr);
177
178//! Returns the RMS between two molecules, taking symmetry into account.
179//! In contrast to getBestRMS, the RMS is computed "in place", i.e.
180//! probe molecules are not aligned to the reference ahead of the
181//! RMS calculation. This is useful, for example, to compute
182//! the RMSD between docking poses and the co-crystallized ligand.
183/*!
184 This function will attempt to match all permutations of matching atom
185 orders in both molecules, for some molecules it will lead to 'combinatorial
186 explosion' especially if hydrogens are present.
187
188 \param prbMol the molecule to be aligned to the reference
189 \param refMol the reference molecule
190 \param prbCid (optional) probe conformation to use
191 \param refCid (optional) reference conformation to use
192 \param map (optional) a vector of vectors of pairs of atom IDs
193 (probe AtomId, ref AtomId) used to compute the alignments.
194 If not provided, these will be generated using a
195 substructure search.
196 \param maxMatches (optional) if map is empty, this will be the max number of
197 matches found in a SubstructMatch().
198 \param symmetrizeConjugatedTerminalGroups (optional) if set, conjugated
199 terminal functional groups (like nitro or carboxylate) will
200 be considered symmetrically
201 \param weights (optional) weights for each pair of atoms.
202
203 <b>Returns</b>
204 Best RMSD value found
205*/
207 ROMol &prbMol, const ROMol &refMol, int prbCid = -1, int refCid = -1,
208 const std::vector<MatchVectType> &map = std::vector<MatchVectType>(),
209 int maxMatches = 1e6, bool symmetrizeConjugatedTerminalGroups = true,
210 const RDNumeric::DoubleVector *weights = nullptr);
211
212//! Returns the RMS between two molecules, taking symmetry into account.
213//! In contrast to getBestRMS, the RMS is computed "in place", i.e.
214//! probe molecules are not aligned to the reference ahead of the
215//! RMS calculation. This is useful, for example, to compute
216//! the RMSD between docking poses and the co-crystallized ligand.
217/*!
218 This function will attempt to match all permutations of matching atom
219 orders in both molecules, for some molecules it will lead to 'combinatorial
220 explosion' especially if hydrogens are present.
221
222 \param prbMol the molecule to be aligned to the reference
223 \param refMol the reference molecule
224 \param prbCid (optional) probe conformation to use
225 \param refCid (optional) reference conformation to use
226 \param map (optional) a vector of vectors of pairs of atom IDs
227 (probe AtomId, ref AtomId) used to compute the alignments.
228 If not provided, these will be generated using a
229 substructure search.
230 \param maxMatches (optional) if map is empty, this will be the max number of
231 matches found in a SubstructMatch().
232 \param weights (optional) weights for each pair of atoms.
233
234 <b>Returns</b>
235 Best RMSD value found
236*/
237RDKIT_MOLALIGN_EXPORT double CalcRMS(ROMol &prbMol, const ROMol &refMol,
238 int prbCid, int refCid,
239 const std::vector<MatchVectType> &map,
240 int maxMatches,
241 const RDNumeric::DoubleVector *weights);
242
243//! Align the conformations of a molecule using a common set of atoms. If
244/// the molecules contains queries, then the queries must also match exactly.
245
246/*!
247 \param mol The molecule of interest.
248 \param atomIds vector of atoms to be used to generate the alignment.
249 All atoms will be used is not specified
250 \param confIds vector of conformations to align - defaults to all
251 \param weights (optional) weights for each pair of atoms.
252 \param reflect toggles reflecting (about the origin) the alignment
253 \param maxIters the maximum number of iterations to attempt
254 \param RMSlist if nonzero, this will be used to return the RMS values
255 between the reference conformation and the other aligned
256 conformations
257*/
258RDKIT_MOLALIGN_EXPORT void alignMolConformers(
259 ROMol &mol, const std::vector<unsigned int> *atomIds = nullptr,
260 const std::vector<unsigned int> *confIds = nullptr,
261 const RDNumeric::DoubleVector *weights = nullptr, bool reflect = false,
262 unsigned int maxIters = 50, std::vector<double> *RMSlist = nullptr);
263} // namespace MolAlign
264} // namespace RDKit
265#endif
~MolAlignException() noexcept override=default
MolAlignException(const char *msg)
construct with an error message
MolAlignException(const std::string msg)
construct with an error message
const char * what() const noexcept override
get the error message
#define RDKIT_MOLALIGN_EXPORT
Definition export.h:257
Std stuff.
std::vector< std::pair< int, int > > MatchVectType
used to return matches from substructure searching, The format is (queryAtomIdx, molAtomIdx)