RDKit
Open-source cheminformatics and machine learning.
AlignMolecules.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2006 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_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 specied conformation in the probe
43 molecule
44 to a specified conformation in the reference molecule is computed so that the
45 root mean
46 squared distance between a specified set of atoms is minimized
47
48 \param prbMol molecule that is to be aligned
49 \param refMol molecule used as the reference for the alignment
50 \param trans storage for the computed transform
51 \param prbCid ID of the conformation in the probe to be used
52 for the alignment (defaults to first conformation)
53 \param refCid ID of the conformation in the ref molecule to which
54 the alignment is computed (defaults to first conformation)
55 \param atomMap a vector of pairs of atom IDs (probe AtomId, ref AtomId)
56 used to compute the alignments. If this mapping is
57 not specified an attempt is made to generate on by
58 substructure matching
59 \param weights Optionally specify weights for each of the atom pairs
60 \param reflect if true reflect the conformation of the probe molecule
61 \param maxIters maximum number of iteration used in mimizing the RMSD
62
63 <b>Returns</b>
64 RMSD value
65*/
67 const ROMol &prbMol, const ROMol &refMol, RDGeom::Transform3D &trans,
68 int prbCid = -1, int refCid = -1, const MatchVectType *atomMap = nullptr,
69 const RDNumeric::DoubleVector *weights = nullptr, bool reflect = false,
70 unsigned int maxIters = 50);
71
72//! Optimally (minimum RMSD) align a molecule to another molecule
73/*!
74 The 3D transformation required to align the specied conformation in the probe
75 molecule
76 to a specified conformation in the reference molecule is computed so that the
77 root mean
78 squared distance between a specified set of atoms is minimized. This
79 transforms is them
80 applied to the specified conformation in the probe molecule
81
82 \param prbMol molecule that is to be aligned
83 \param refMol molecule used as the reference for the alignment
84 \param prbCid ID of the conformation in the probe to be used
85 for the alignment (defaults to first conformation)
86 \param refCid ID of the conformation in the ref molecule to which
87 the alignment is computed (defaults to first conformation)
88 \param atomMap a vector of pairs of atom IDs (probe AtomId, ref AtomId)
89 used to compute the alignments. If this mapping is
90 not specified an attempt is made to generate on by
91 substructure matching
92 \param weights Optionally specify weights for each of the atom pairs
93 \param reflect if true reflect the conformation of the probe molecule
94 \param maxIters maximum number of iteration used in mimizing the RMSD
95
96 <b>Returns</b>
97 RMSD value
98*/
100 ROMol &prbMol, const ROMol &refMol, int prbCid = -1, int refCid = -1,
101 const MatchVectType *atomMap = nullptr,
102 const RDNumeric::DoubleVector *weights = nullptr, bool reflect = false,
103 unsigned int maxIters = 50);
104
105//! Returns the optimal RMS for aligning two molecules, taking
106/// symmetry into account. As a side-effect, the probe molecule is
107/// left in the aligned state.
108/*!
109 This function will attempt to align all permutations of matching atom
110 orders in both molecules, for some molecules it will lead to 'combinatorial
111 explosion' especially if hydrogens are present.
112 Use 'RDKit::MolAlign::alignMol' to align molecules without changing the
113 atom order.
114
115 \param probeMol the molecule to be aligned to the reference
116 \param refMol the reference molecule
117 \param probeId (optional) probe conformation to use
118 \param refId (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
126 <b>Returns</b>
127 Best RMSD value found
128*/
130 ROMol &probeMol, ROMol &refMol, int probeId = -1, int refId = -1,
131 const std::vector<MatchVectType> &map = std::vector<MatchVectType>(),
132 int maxMatches = 1e6);
133
134//! Returns the RMS between two molecules, taking symmetry into account.
135/*!
136 This function will attempt to align all permutations of matching atom
137 orders in both molecules, for some molecules it will lead to 'combinatorial
138 explosion' especially if hydrogens are present.
139
140 \param probeMol the molecule to be aligned to the reference
141 \param refMol the reference molecule
142 \param probeId (optional) probe conformation to use
143 \param refId (optional) reference conformation to use
144 \param map (optional) a vector of vectors of pairs of atom IDs
145 (probe AtomId, ref AtomId) used to compute the alignments.
146 If not provided, these will be generated using a
147 substructure search.
148 \param maxMatches (optional) if map is empty, this will be the max number of
149 matches found in a SubstructMatch().
150 \param weights (optional) weights for each pair of atom.
151
152 <b>Returns</b>
153 Best RMSD value found
154*/
156 ROMol &probeMol, const ROMol &refMol, int prbCid = -1, int refCid = -1,
157 const std::vector<MatchVectType> &map = std::vector<MatchVectType>(),
158 int maxMatches = 1e6, const RDNumeric::DoubleVector *weights = nullptr);
159
160//! Align the conformations of a molecule using a common set of atoms. If
161/// the molecules contains queries, then the queries must also match exactly.
162
163/*!
164 \param mol The molecule of interest.
165 \param atomIds vector of atoms to be used to generate the alignment.
166 All atoms will be used is not specified
167 \param confIds vector of conformations to align - defaults to all
168 \param weights vector of weights to applied to particular atom pairs
169 defaults to all weights = 1
170 \param reflect toggles reflecting (about the origin) the alignment
171 \param maxIters the maximum number of iterations to attempt
172 \param RMSlist if nonzero, this will be used to return the RMS values
173 between the reference conformation and the other aligned
174 conformations
175*/
177 ROMol &mol, const std::vector<unsigned int> *atomIds = nullptr,
178 const std::vector<unsigned int> *confIds = nullptr,
179 const RDNumeric::DoubleVector *weights = nullptr, bool reflect = false,
180 unsigned int maxIters = 50, std::vector<double> *RMSlist = nullptr);
181} // namespace MolAlign
182} // namespace RDKit
183#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:249
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 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 double getBestRMS(ROMol &probeMol, ROMol &refMol, int probeId=-1, int refId=-1, const std::vector< MatchVectType > &map=std::vector< MatchVectType >(), int maxMatches=1e6)
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)
RDKIT_MOLALIGN_EXPORT double CalcRMS(ROMol &probeMol, const ROMol &refMol, int prbCid=-1, int refCid=-1, const std::vector< MatchVectType > &map=std::vector< MatchVectType >(), int maxMatches=1e6, const RDNumeric::DoubleVector *weights=nullptr)
Returns the RMS between two molecules, taking symmetry into account.
RDKIT_MOLALIGN_EXPORT const RDGeom::POINT3D_VECT * reflect(const Conformer &conf)
Std stuff.
Definition: Abbreviations.h:18
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