RDKit
Open-source cheminformatics and machine learning.
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 
14 #include <Geometry/Transform3D.h>
15 #include <Numerics/Vector.h>
16 #include <vector>
17 
18 namespace RDKit {
19 typedef std::vector<std::pair<int, int>> MatchVectType;
20 
21 class Conformer;
22 class ROMol;
23 namespace MolAlign {
24 class 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 */
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 */
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 */
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 */
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 */
237 RDKIT_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 */
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
RDKIT_MOLALIGN_EXPORT double getAlignmentTransform(const ROMol &prbMol, const ROMol &refMol, RDGeom::Transform3D &trans, int prbCid=-1, int refCid=-1, const MatchVectType *atomMap=nullptr, const RDNumeric::DoubleVector *weights=nullptr, bool reflect=false, unsigned int maxIters=50)
Alignment functions.
RDKIT_MOLALIGN_EXPORT double getBestRMS(ROMol &prbMol, const ROMol &refMol, int prbCid=-1, int refCid=-1, const std::vector< MatchVectType > &map=std::vector< MatchVectType >(), int maxMatches=1e6, bool symmetrizeConjugatedTerminalGroups=true, const RDNumeric::DoubleVector *weights=nullptr)
RDKIT_MOLALIGN_EXPORT double alignMol(ROMol &prbMol, const ROMol &refMol, int prbCid=-1, int refCid=-1, const MatchVectType *atomMap=nullptr, const RDNumeric::DoubleVector *weights=nullptr, bool reflect=false, unsigned int maxIters=50)
Optimally (minimum RMSD) align a molecule to another molecule.
RDKIT_MOLALIGN_EXPORT const RDGeom::POINT3D_VECT * reflect(const Conformer &conf)
RDKIT_MOLALIGN_EXPORT double CalcRMS(ROMol &prbMol, const ROMol &refMol, int prbCid=-1, int refCid=-1, const std::vector< MatchVectType > &map=std::vector< MatchVectType >(), int maxMatches=1e6, bool symmetrizeConjugatedTerminalGroups=true, const RDNumeric::DoubleVector *weights=nullptr)
RDKIT_MOLALIGN_EXPORT double getBestAlignmentTransform(const ROMol &prbMol, const ROMol &refMol, RDGeom::Transform3D &bestTrans, MatchVectType &bestMatch, int prbCid=-1, int refCid=-1, const std::vector< MatchVectType > &map=std::vector< MatchVectType >(), int maxMatches=1e6, bool symmetrizeConjugatedTerminalGroups=true, const RDNumeric::DoubleVector *weights=nullptr, bool reflect=false, unsigned int maxIters=50)
RDKIT_MOLALIGN_EXPORT void alignMolConformers(ROMol &mol, const std::vector< unsigned int > *atomIds=nullptr, const std::vector< unsigned int > *confIds=nullptr, const RDNumeric::DoubleVector *weights=nullptr, bool reflect=false, unsigned int maxIters=50, std::vector< double > *RMSlist=nullptr)
Std stuff.
Definition: Abbreviations.h:19
std::vector< std::pair< int, int > > MatchVectType
used to return matches from substructure searching, The format is (queryAtomIdx, molAtomIdx)
Vector< double > DoubleVector
Definition: Vector.h:296