1 //
2 //  Copyright (C) 2004-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_DISTGEOMUTILS_H_
12 #define _RD_DISTGEOMUTILS_H_
13 
14 #include "BoundsMatrix.h"
15 #include <Numerics/SymmMatrix.h>
16 #include <map>
17 #include <Geometry/point.h>
18 #include "ChiralSet.h"
19 #include <RDGeneral/utils.h>
20 #include <boost/dynamic_bitset.hpp>
21 
22 namespace ForceFields {
23 class ForceField;
24 namespace CrystalFF {
25 struct CrystalFFDetails;
26 }
27 }  // namespace ForceFields
28 
29 namespace DistGeom {
30 
31 //! Pick a distance matrix at random such that the
32 //!  distance satisfy the bounds in the BoundsMatrix
33 /*!
34   \param mmat     Bounds matrix
35   \param distmat  Storage for randomly chosen distances
36   \param seed     the random number seed to use
37 
38   \return the largest element of the distance matrix
39  */
40 RDKIT_DISTGEOMETRY_EXPORT double pickRandomDistMat(
41     const BoundsMatrix &mmat, RDNumeric::SymmMatrix<double> &distmat,
42     int seed = -1);
43 //! \overload
44 RDKIT_DISTGEOMETRY_EXPORT double pickRandomDistMat(
45     const BoundsMatrix &mmat, RDNumeric::SymmMatrix<double> &distmat,
46     RDKit::double_source_type &rng);
47 
48 //! Compute an initial embedded in 3D based on a distance matrix
49 /*!
50   This function follows the embed algorithm mentioned in
51   "Distance Geometry and Molecular Conformation" by G.M.Crippen and T.F.Havel
52   (pages 312-313)
53 
54   \param distmat     Distance matrix
55   \param positions     A vector of pointers to Points to write out the resulting
56   coordinates
57   \param randNegEig  If set to true and if any of the eigen values are negative,
58   we will
59                      pick the corresponding components of the coordinates at
60   random
61   \param numZeroFail Fail embedding is more this many (or more) eigen values are
62   zero
63   \param seed        the random number seed to use
64 
65   \return true if the embedding was successful
66 */
67 RDKIT_DISTGEOMETRY_EXPORT bool computeInitialCoords(
68     const RDNumeric::SymmMatrix<double> &distmat,
69     RDGeom::PointPtrVect &positions, bool randNegEig = false,
70     unsigned int numZeroFail = 2, int seed = -1);
71 //! \overload
72 RDKIT_DISTGEOMETRY_EXPORT bool computeInitialCoords(
73     const RDNumeric::SymmMatrix<double> &distmat,
74     RDGeom::PointPtrVect &positions, RDKit::double_source_type &rng,
75     bool randNegEig = false, unsigned int numZeroFail = 2);
76 
77 //! places atoms randomly in a box
78 /*!
79   \param positions     A vector of pointers to Points to write out the resulting
80   coordinates
81   \param boxSize     the side-length of the cubic box
82   \param seed        the random number seed to use
83 
84   \return true if the coordinate generation was successful
85 */
86 RDKIT_DISTGEOMETRY_EXPORT bool computeRandomCoords(
87     RDGeom::PointPtrVect &positions, double boxSize, int seed = -1);
88 //! \overload
89 RDKIT_DISTGEOMETRY_EXPORT bool computeRandomCoords(
90     RDGeom::PointPtrVect &positions, double boxSize,
91     RDKit::double_source_type &rng);
92 
93 //! Setup the error function for violation of distance bounds as a forcefield
94 /*!
95   This is based on function E3 on page 311 of "Distance Geometry in Molecular
96   Modeling" Jeffrey M.Blaney and J.Scott Dixon, Review in Computational
97   Chemistry,
98   Volume V
99 
100   \param mmat            Distance bounds matrix
101   \param positions       A vector of pointers to Points to write out the
102   resulting coordinates
103   \param csets           The vector of chiral points (type: ChiralSet)
104   \param weightChiral    weight to be used to enforce chirality
105   \param weightFourthDim another chiral weight
106   \param extraWeights    an optional set of weights for distance bounds
107   violations
108   \param basinSizeTol  Optional: any distance bound with a basin (distance
109   between max and
110                        min bounds) larger than this value will not be included
111   in the force
112                        field used to cleanup the structure.
113 
114   \return a pointer to a ForceField suitable for cleaning up the violations.
115     <b>NOTE:</b> the caller is responsible for deleting this force field.
116 
117 */
118 RDKIT_DISTGEOMETRY_EXPORT ForceFields::ForceField *constructForceField(
119     const BoundsMatrix &mmat, RDGeom::PointPtrVect &positions,
120     const VECT_CHIRALSET &csets, double weightChiral = 1.0,
121     double weightFourthDim = 0.1,
122     std::map<std::pair<int, int>, double> *extraWeights = nullptr,
123     double basinSizeTol = 5.0, boost::dynamic_bitset<> *fixedPts = nullptr);
124 
125 //! Force field with experimental torsion angle preferences and 1-2/1-3 distance
126 // constraints
127 /*!
128 
129   \param mmat            Distance bounds matrix
130   \param positions       A vector of pointers to 3D Points to write out the
131   resulting coordinates
132   \param etkdgDetails    Contains information about the ETKDG force field
133 
134   <b>NOTE:</b> the caller is responsible for deleting this force field.
135 
136 */
137 RDKIT_DISTGEOMETRY_EXPORT ForceFields::ForceField *construct3DForceField(
138     const BoundsMatrix &mmat, RDGeom::Point3DPtrVect &positions,
139     const ForceFields::CrystalFF::CrystalFFDetails &etkdgDetails);
140 //! Force field with experimental torsion angle preferences and 1-2/1-3 distance
141 // constraints, as well as atom pairwise Columbic interactions
142 /*!
143 
144   \param mmat            Distance bounds matrix
145   \param positions       A vector of pointers to 3D Points to write out the
146   resulting coordinates
147   \param etkdgDetails    Contains information about the ETKDG force field
148   \param CPCI            Contains which atom pair(s) have what strength of
149   attractive/repulsive electrostatic interaction(s)
150 
151   <b>NOTE:</b> the caller is responsible for deleting this force field.
152 
153 */
154 RDKIT_DISTGEOMETRY_EXPORT ForceFields::ForceField *construct3DForceField(
155     const BoundsMatrix &mmat, RDGeom::Point3DPtrVect &positions,
156     const ForceFields::CrystalFF::CrystalFFDetails &etkdgDetails,
157     const std::map<std::pair<unsigned int, unsigned int>, double> &CPCI);
158 //! Force field with experimental torsion angle preferences and 1-2/1-3 distance
159 // constraints
160 /*!
161 
162   \param mmat            Distance bounds matrix
163   \param positions       A vector of pointers to 3D Points to write out the
164   resulting coordinates
165   \param etkdgDetails    Contains information about the ETKDG force field
166 
167   <b>NOTE:</b> the caller is responsible for deleting this force field.
168 
169 */
170 RDKIT_DISTGEOMETRY_EXPORT ForceFields::ForceField *constructPlain3DForceField(
171     const BoundsMatrix &mmat, RDGeom::Point3DPtrVect &positions,
172     const ForceFields::CrystalFF::CrystalFFDetails &etkdgDetails);
173 
174 //! Force field with only improper terms
175 /*!
176 
177   \param mmat            Distance bounds matrix
178   \param positions       A vector of pointers to 3D Points to write out the
179   resulting coordinates \param improperAtoms   A list of groups of 4 atom
180   indices for inversion terms \param atomNums        A list of atomic numbers
181   for all atoms in the molecule
182 
183   \return a pointer to a ForceField with improper terms
184     <b>NOTE:</b> the caller is responsible for deleting this force field.
185 
186 */
187 RDKIT_DISTGEOMETRY_EXPORT ForceFields::ForceField *
188 construct3DImproperForceField(
189     const BoundsMatrix &mmat, RDGeom::Point3DPtrVect &positions,
190     const std::vector<std::vector<int>> &improperAtoms,
191     const std::vector<int> &atomNums);
192 
193 }  // namespace DistGeom
194 
195 #endif
196