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