RDKit: ForceField.h Source File

| RDKit Open-source cheminformatics and machine learning.

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

ForceField.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2004-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 #ifndef __RD_FORCEFIELD_H__
11 #define __RD_FORCEFIELD_H__
12
13 #include <vector>
14 #include <boost/smart_ptr.hpp>
15 #include <boost/foreach.hpp>
16 #include <Geometry/point.h>
17
18 namespace ForceFields {
19 class ForceFieldContrib;
20 typedef std::vector<int> INT_VECT;
21 typedef boost::shared_ptr<const ForceFieldContrib> ContribPtr;
22 typedef std::vector<ContribPtr> ContribPtrVect;
23
24 //-------------------------------------------------------
25 //! A class to store forcefields and handle minimization
26 /*!
27 A force field is used like this (schematically):
28
29 \verbatim
30 ForceField ff;
31
32 // add contributions:
33 for contrib in contribs:
34 ff.contribs().push_back(contrib);
35
36 // set up the points:
37 for positionPtr in positions:
38 ff.positions().push_back(point);
39
40 // initialize:
41 ff.initialize()
42
43 // and minimize:
44 needsMore = ff.minimize();
45
46 \endverbatim
47
48 <b>Notes:</b>
49 - The ForceField owns its contributions, which are stored using smart
50 pointers.
51 - Distance calculations are currently lazy; the full distance matrix is
52 never generated. In systems where the distance matrix is not sparse,
53 this is almost certainly inefficient.
54
55 */
56 class ForceField {
57 public:
58 //! construct with a dimension
59 ForceField(unsigned int dimension = 3)
60 : d_dimension(dimension), df_init(false), d_numPoints(0), dp_distMat(0){};
61
62 ~ForceField();
63
64 //! copy ctor, copies contribs.
65 ForceField(const ForceField &other);
66
67 //! does initialization
68 void initialize();
69
70 //! calculates and returns the energy (in kcal/mol) based on existing
71 //positions in the forcefield
72 /*!
73
74 \return the current energy
75
76 <b>Note:</b>
77 This function is less efficient than calcEnergy with postions passed in as
78 double *
79 the positions need to be converted to double * here
80 */
81 double calcEnergy() const;
82
83 // these next two aren't const because they may update our
84 // distance matrix
85
86 //! calculates and returns the energy of the position passed in
87 /*!
88 \param pos an array of doubles. Should be \c 3*this->numPoints() long.
89
90 \return the current energy
91
92 <b>Side effects:</b>
93 - Calling this resets the current distance matrix
94 - The individual contributions may further update the distance matrix
95 */
96 double calcEnergy(double *pos);
97
98 //! calculates the gradient of the energy at the current position
99 /*!
100
101 \param forces an array of doubles. Should be \c 3*this->numPoints() long.
102
103 <b>Note:</b>
104 This function is less efficient than calcGrad with positions passed in
105 the positions need to be converted to double * here
106 */
107 void calcGrad(double *forces) const;
108
109 //! calculates the gradient of the energy at the provided position
110 /*!
111
112 \param pos an array of doubles. Should be \c 3*this->numPoints() long.
113 \param forces an array of doubles. Should be \c 3*this->numPoints() long.
114
115 <b>Side effects:</b>
116 - The individual contributions may modify the distance matrix
117 */
118 void calcGrad(double *pos, double *forces);
119
120 //! minimizes the energy of the system by following gradients
121 /*!
122 \param maxIts the maximum number of iterations to try
123 \param forceTol the convergence criterion for forces
124 \param energyTol the convergence criterion for energies
125
126 \return an integer value indicating whether or not the convergence
127 criteria were achieved:
128 - 0: indicates success
129 - 1: the minimization did not converge in \c maxIts iterations.
130 */
131 int minimize(unsigned int maxIts = 200, double forceTol = 1e-4,
132 double energyTol = 1e-6);
133
134 // ---------------------------
135 // setters and getters
136
137 //! returns a reference to our points (a PointPtrVect)
138 RDGeom::PointPtrVect &positions() { return d_positions; };
139 const RDGeom::PointPtrVect &positions() const { return d_positions; };
140
141 //! returns a reference to our contribs (a ContribPtrVect)
142 ContribPtrVect &contribs() { return d_contribs; };
143 const ContribPtrVect &contribs() const { return d_contribs; };
144
145 //! returns the distance between two points
146 /*!
147 \param i point index
148 \param j point index
149 \param pos (optional) If this argument is provided, it will be used
150 to provide the positions of points. \c pos should be
151 \c 3*this->numPoints() long.
152
153 \return the distance
154
155 <b>Side effects:</b>
156 - if the distance between i and j has not previously been calculated,
157 our internal distance matrix will be updated.
158 */
159 double distance(unsigned int i, unsigned int j, double *pos = 0);
160
161 //! returns the distance between two points
162 /*!
163 \param i point index
164 \param j point index
165 \param pos (optional) If this argument is provided, it will be used
166 to provide the positions of points. \c pos should be
167 \c 3*this->numPoints() long.
168
169 \return the distance
170
171 <b>Note:</b>
172 The internal distance matrix is not updated in this case
173 */
174 double distance(unsigned int i, unsigned int j, double *pos = 0) const;
175
176 //! returns the dimension of the forcefield
177 unsigned int dimension() const { return d_dimension; }
178
179 //! returns the number of points the ForceField is handling
180 unsigned int numPoints() const { return d_numPoints; };
181
182 INT_VECT &fixedPoints() { return d_fixedPoints; };
183 const INT_VECT &fixedPoints() const { return d_fixedPoints; };
184
185 protected:
186 unsigned int d_dimension;
187 bool df_init; //!< whether or not we've been initialized
188 unsigned int d_numPoints; //!< the number of active points
189 double *dp_distMat; //!< our internal distance matrix
190 RDGeom::PointPtrVect d_positions; //!< pointers to the points we're using
191 ContribPtrVect d_contribs; //!< contributions to the energy
192 INT_VECT d_fixedPoints;
193 unsigned int d_matSize;
194 //! scatter our positions into an array
195 /*!
196 \param pos should be \c 3*this->numPoints() long;
197 */
198 void scatter(double *pos) const;
199
200 //! update our positions from an array
201 /*!
202 \param pos should be \c 3*this->numPoints() long;
203 */
204 void gather(double *pos);
205
206 //! initializes our internal distance matrix
207 void initDistanceMatrix();
208 };
209 }
210 #endif
ForceFields::ForceField::fixedPoints
INT_VECT & fixedPoints()
Definition: ForceField.h:182
ForceFields::ContribPtr
boost::shared_ptr< const ForceFieldContrib > ContribPtr
Definition: ForceField.h:21
ForceFields::ForceField::contribs
ContribPtrVect & contribs()
returns a reference to our contribs (a ContribPtrVect)
Definition: ForceField.h:142
ForceFields::ForceField::contribs
const ContribPtrVect & contribs() const
Definition: ForceField.h:143
ForceFields::ForceField::d_positions
RDGeom::PointPtrVect d_positions
pointers to the points we're using
Definition: ForceField.h:190
ForceFields::ForceField::calcEnergy
double calcEnergy() const
calculates and returns the energy (in kcal/mol) based on existing
ForceFields::ForceField::~ForceField
~ForceField()
RDGeom::PointPtrVect
std::vector< RDGeom::Point * > PointPtrVect
Definition: point.h:492
ForceFields::ForceField::d_contribs
ContribPtrVect d_contribs
contributions to the energy
Definition: ForceField.h:191
ForceFields::ForceField::d_fixedPoints
INT_VECT d_fixedPoints
Definition: ForceField.h:192
point.h
ForceFields::ForceField::positions
RDGeom::PointPtrVect & positions()
returns a reference to our points (a PointPtrVect)
Definition: ForceField.h:138
ForceFields::ForceFieldContrib
abstract base class for contributions to ForceFields
Definition: Contrib.h:17
ForceFields::ForceField::d_matSize
unsigned int d_matSize
Definition: ForceField.h:193
ForceFields::ForceField::scatter
void scatter(double *pos) const
scatter our positions into an array
ForceFields::ForceField::minimize
int minimize(unsigned int maxIts=200, double forceTol=1e-4, double energyTol=1e-6)
minimizes the energy of the system by following gradients
ForceFields::INT_VECT
std::vector< int > INT_VECT
Definition: ForceField.h:19
ForceFields::ForceField::initialize
void initialize()
does initialization
ForceFields::ForceField::gather
void gather(double *pos)
update our positions from an array
ForceFields::ForceField::initDistanceMatrix
void initDistanceMatrix()
initializes our internal distance matrix
ForceFields
Definition: TorsionAngleM6.h:23
ForceFields::ForceField::ForceField
ForceField(unsigned int dimension=3)
construct with a dimension
Definition: ForceField.h:59
ForceFields::ForceField::positions
const RDGeom::PointPtrVect & positions() const
Definition: ForceField.h:139
ForceFields::ForceField::calcGrad
void calcGrad(double *forces) const
calculates the gradient of the energy at the current position
ForceFields::ForceField::numPoints
unsigned int numPoints() const
returns the number of points the ForceField is handling
Definition: ForceField.h:180
ForceFields::ForceField::distance
double distance(unsigned int i, unsigned int j, double *pos=0)
returns the distance between two points
ForceFields::ForceField::df_init
bool df_init
whether or not we've been initialized
Definition: ForceField.h:187
ForceFields::ForceField::d_dimension
unsigned int d_dimension
Definition: ForceField.h:183
ForceFields::ForceField::dimension
unsigned int dimension() const
returns the dimension of the forcefield
Definition: ForceField.h:177
ForceFields::ForceField::dp_distMat
double * dp_distMat
our internal distance matrix
Definition: ForceField.h:189
ForceFields::ForceField
A class to store forcefields and handle minimization.
Definition: ForceField.h:56
ForceFields::ForceField::fixedPoints
const INT_VECT & fixedPoints() const
Definition: ForceField.h:183
ForceFields::ForceField::d_numPoints
unsigned int d_numPoints
the number of active points
Definition: ForceField.h:188
ForceFields::ContribPtrVect
std::vector< ContribPtr > ContribPtrVect
Definition: ForceField.h:22