RDKit
Open-source cheminformatics and machine learning.
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 {
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)
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
INT_VECT & fixedPoints()
Definition: ForceField.h:182
unsigned int numPoints() const
returns the number of points the ForceField is handling
Definition: ForceField.h:180
const ContribPtrVect & contribs() const
Definition: ForceField.h:143
boost::shared_ptr< const ForceFieldContrib > ContribPtr
Definition: ForceField.h:21
ContribPtrVect & contribs()
returns a reference to our contribs (a ContribPtrVect)
Definition: ForceField.h:142
RDGeom::PointPtrVect d_positions
pointers to the points we&#39;re using
Definition: ForceField.h:190
unsigned int dimension() const
returns the dimension of the forcefield
Definition: ForceField.h:177
void scatter(double *pos) const
scatter our positions into an array
std::vector< RDGeom::Point * > PointPtrVect
Definition: point.h:492
ContribPtrVect d_contribs
contributions to the energy
Definition: ForceField.h:191
RDGeom::PointPtrVect & positions()
returns a reference to our points (a PointPtrVect)
Definition: ForceField.h:138
abstract base class for contributions to ForceFields
Definition: Contrib.h:17
unsigned int d_matSize
Definition: ForceField.h:193
int minimize(unsigned int maxIts=200, double forceTol=1e-4, double energyTol=1e-6)
minimizes the energy of the system by following gradients
std::vector< int > INT_VECT
Definition: ForceField.h:19
void initialize()
does initialization
void gather(double *pos)
update our positions from an array
void initDistanceMatrix()
initializes our internal distance matrix
ForceField(unsigned int dimension=3)
construct with a dimension
Definition: ForceField.h:59
double calcEnergy() const
calculates and returns the energy (in kcal/mol) based on existing
double distance(unsigned int i, unsigned int j, double *pos=0)
returns the distance between two points
bool df_init
whether or not we&#39;ve been initialized
Definition: ForceField.h:187
unsigned int d_dimension
Definition: ForceField.h:183
const RDGeom::PointPtrVect & positions() const
Definition: ForceField.h:139
double * dp_distMat
our internal distance matrix
Definition: ForceField.h:189
A class to store forcefields and handle minimization.
Definition: ForceField.h:56
const INT_VECT & fixedPoints() const
Definition: ForceField.h:183
unsigned int d_numPoints
the number of active points
Definition: ForceField.h:188
void calcGrad(double *forces) const
calculates the gradient of the energy at the current position
std::vector< ContribPtr > ContribPtrVect
Definition: ForceField.h:22