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>
18 
19 namespace ForceFields {
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)
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
INT_VECT & fixedPoints()
Definition: ForceField.h:204
boost::shared_ptr< const ForceFieldContrib > ContribPtr
Definition: ForceField.h:22
ContribPtrVect & contribs()
returns a reference to our contribs (a ContribPtrVect)
Definition: ForceField.h:164
const ContribPtrVect & contribs() const
Definition: ForceField.h:165
RDGeom::PointPtrVect d_positions
pointers to the points we&#39;re using
Definition: ForceField.h:212
std::vector< RDGeom::Point * > PointPtrVect
Definition: point.h:492
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
ContribPtrVect d_contribs
contributions to the energy
Definition: ForceField.h:213
RDGeom::PointPtrVect & positions()
returns a reference to our points (a PointPtrVect)
Definition: ForceField.h:160
abstract base class for contributions to ForceFields
Definition: Contrib.h:17
unsigned int d_matSize
Definition: ForceField.h:215
void scatter(double *pos) const
scatter our positions into an array
std::vector< int > INT_VECT
Definition: ForceField.h:20
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:60
const RDGeom::PointPtrVect & positions() const
Definition: ForceField.h:161
void calcGrad(double *forces) const
calculates the gradient of the energy at the current position
std::vector< Snapshot > SnapshotVect
Definition: Snapshot.h:18
unsigned int numPoints() const
returns the number of points the ForceField is handling
Definition: ForceField.h:202
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:209
unsigned int d_dimension
Definition: ForceField.h:205
unsigned int dimension() const
returns the dimension of the forcefield
Definition: ForceField.h:199
double * dp_distMat
our internal distance matrix
Definition: ForceField.h:211
A class to store forcefields and handle minimization.
Definition: ForceField.h:57
const INT_VECT & fixedPoints() const
Definition: ForceField.h:205
double calcEnergy(std::vector< double > *contribs=NULL) const
calculates and returns the energy (in kcal/mol) based on existing
unsigned int d_numPoints
the number of active points
Definition: ForceField.h:210
std::vector< ContribPtr > ContribPtrVect
Definition: ForceField.h:23