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) : d_dimension(dimension), df_init(false),
60  d_numPoints(0), dp_distMat(0) {};
61 
62  ~ForceField();
63 
64  //! copy ctor, copies contribs.
65  ForceField(const ForceField &other);
66 
67 
68  //! does initialization
69  void initialize();
70 
71 
72  //! calculates and returns the energy (in kcal/mol) based on existing 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 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,double energyTol=1e-6);
132 
133  // ---------------------------
134  // setters and getters
135 
136  //! returns a reference to our points (a PointPtrVect)
138  const RDGeom::PointPtrVect &positions() const { return d_positions; };
139 
140  //! returns a reference to our contribs (a ContribPtrVect)
141  ContribPtrVect &contribs() { return d_contribs; };
142  const ContribPtrVect &contribs() const { return d_contribs; };
143 
144  //! returns the distance between two points
145  /*!
146  \param i point index
147  \param j point index
148  \param pos (optional) If this argument is provided, it will be used
149  to provide the positions of points. \c pos should be
150  \c 3*this->numPoints() long.
151 
152  \return the distance
153 
154  <b>Side effects:</b>
155  - if the distance between i and j has not previously been calculated,
156  our internal distance matrix will be updated.
157  */
158  double distance(unsigned int i,unsigned int j,double *pos=0);
159 
160  //! returns the distance between two points
161  /*!
162  \param i point index
163  \param j point index
164  \param pos (optional) If this argument is provided, it will be used
165  to provide the positions of points. \c pos should be
166  \c 3*this->numPoints() long.
167 
168  \return the distance
169 
170  <b>Note:</b>
171  The internal distance matrix is not updated in this case
172  */
173  double distance(unsigned int i,unsigned int j,double *pos=0) const;
174 
175  //! returns the dimension of the forcefield
176  unsigned int dimension() const {
177  return d_dimension;
178  }
179 
180  //! returns the number of points the ForceField is handling
181  unsigned int numPoints() const { return d_numPoints; };
182 
183  INT_VECT &fixedPoints() { return d_fixedPoints; };
184  const INT_VECT &fixedPoints() const { return d_fixedPoints; };
185 
186  protected:
187  unsigned int d_dimension;
188  bool df_init; //!< whether or not we've been initialized
189  unsigned int d_numPoints; //!< the number of active points
190  double *dp_distMat; //!< our internal distance matrix
191  RDGeom::PointPtrVect d_positions; //!< pointers to the points we're using
192  ContribPtrVect d_contribs; //!< contributions to the energy
193  INT_VECT d_fixedPoints;
194  unsigned int d_matSize;
195  //! scatter our positions into an array
196  /*!
197  \param pos should be \c 3*this->numPoints() long;
198  */
199  void scatter(double *pos) const;
200 
201  //! update our positions from an array
202  /*!
203  \param pos should be \c 3*this->numPoints() long;
204  */
205  void gather(double *pos);
206 
207  //! initializes our internal distance matrix
208  void initDistanceMatrix();
209 
210  };
211 }
212 #endif
INT_VECT & fixedPoints()
Definition: ForceField.h:183
boost::shared_ptr< const ForceFieldContrib > ContribPtr
Definition: ForceField.h:21
ContribPtrVect & contribs()
returns a reference to our contribs (a ContribPtrVect)
Definition: ForceField.h:141
const ContribPtrVect & contribs() const
Definition: ForceField.h:142
RDGeom::PointPtrVect d_positions
pointers to the points we&#39;re using
Definition: ForceField.h:191
double calcEnergy() const
calculates and returns the energy (in kcal/mol) based on existing positions in the forcefield ...
std::vector< RDGeom::Point * > PointPtrVect
Definition: point.h:514
ContribPtrVect d_contribs
contributions to the energy
Definition: ForceField.h:192
RDGeom::PointPtrVect & positions()
returns a reference to our points (a PointPtrVect)
Definition: ForceField.h:137
abstract base class for contributions to ForceFields
Definition: Contrib.h:17
unsigned int d_matSize
Definition: ForceField.h:194
void scatter(double *pos) const
scatter our positions into an array
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
const RDGeom::PointPtrVect & positions() const
Definition: ForceField.h:138
void calcGrad(double *forces) const
calculates the gradient of the energy at the current position
unsigned int numPoints() const
returns the number of points the ForceField is handling
Definition: ForceField.h:181
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:188
unsigned int d_dimension
Definition: ForceField.h:184
unsigned int dimension() const
returns the dimension of the forcefield
Definition: ForceField.h:176
double * dp_distMat
our internal distance matrix
Definition: ForceField.h:190
A class to store forcefields and handle minimization.
Definition: ForceField.h:56
const INT_VECT & fixedPoints() const
Definition: ForceField.h:184
unsigned int d_numPoints
the number of active points
Definition: ForceField.h:189
std::vector< ContribPtr > ContribPtrVect
Definition: ForceField.h:22