RDKit
Open-source cheminformatics and machine learning.
ForceFields::ForceField Class Reference

A class to store forcefields and handle minimization. More...

#include <ForceField.h>

Public Member Functions

 ForceField (unsigned int dimension=3)
 construct with a dimension More...
 
 ~ForceField ()
 
 ForceField (const ForceField &other)
 copy ctor, copies contribs. More...
 
void initialize ()
 does initialization More...
 
double calcEnergy (std::vector< double > *contribs=NULL) const
 calculates and returns the energy (in kcal/mol) based on existing More...
 
double calcEnergy (double *pos)
 calculates and returns the energy of the position passed in More...
 
void calcGrad (double *forces) const
 calculates the gradient of the energy at the current position More...
 
void calcGrad (double *pos, double *forces)
 calculates the gradient of the energy at the provided position More...
 
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 More...
 
int minimize (unsigned int maxIts=200, double forceTol=1e-4, double energyTol=1e-6)
 minimizes the energy of the system by following gradients More...
 
RDGeom::PointPtrVectpositions ()
 returns a reference to our points (a PointPtrVect) More...
 
const RDGeom::PointPtrVectpositions () const
 
ContribPtrVectcontribs ()
 returns a reference to our contribs (a ContribPtrVect) More...
 
const ContribPtrVectcontribs () const
 
double distance (unsigned int i, unsigned int j, double *pos=0)
 returns the distance between two points More...
 
double distance (unsigned int i, unsigned int j, double *pos=0) const
 returns the distance between two points More...
 
unsigned int dimension () const
 returns the dimension of the forcefield More...
 
unsigned int numPoints () const
 returns the number of points the ForceField is handling More...
 
INT_VECTfixedPoints ()
 
const INT_VECTfixedPoints () const
 

Protected Member Functions

void scatter (double *pos) const
 scatter our positions into an array More...
 
void gather (double *pos)
 update our positions from an array More...
 
void initDistanceMatrix ()
 initializes our internal distance matrix More...
 

Protected Attributes

unsigned int d_dimension
 
bool df_init
 whether or not we've been initialized More...
 
unsigned int d_numPoints
 the number of active points More...
 
double * dp_distMat
 our internal distance matrix More...
 
RDGeom::PointPtrVect d_positions
 pointers to the points we're using More...
 
ContribPtrVect d_contribs
 contributions to the energy More...
 
INT_VECT d_fixedPoints
 
unsigned int d_matSize = 0
 

Detailed Description

A class to store forcefields and handle minimization.

A force field is used like this (schematically):

  ForceField ff;

  // add contributions:
  for contrib in contribs:
    ff.contribs().push_back(contrib);

  // set up the points:
  for positionPtr in positions:
    ff.positions().push_back(point);

  // initialize:
  ff.initialize()

  // and minimize:
  needsMore = ff.minimize();

Notes:

  • The ForceField owns its contributions, which are stored using smart pointers.
  • Distance calculations are currently lazy; the full distance matrix is never generated. In systems where the distance matrix is not sparse, this is almost certainly inefficient.

Definition at line 79 of file ForceField.h.

Constructor & Destructor Documentation

◆ ForceField() [1/2]

ForceFields::ForceField::ForceField ( unsigned int  dimension = 3)
inline

construct with a dimension

Definition at line 82 of file ForceField.h.

◆ ~ForceField()

ForceFields::ForceField::~ForceField ( )

◆ ForceField() [2/2]

ForceFields::ForceField::ForceField ( const ForceField other)

copy ctor, copies contribs.

Member Function Documentation

◆ calcEnergy() [1/2]

double ForceFields::ForceField::calcEnergy ( double *  pos)

calculates and returns the energy of the position passed in

Parameters
posan array of doubles. Should be 3*this->numPoints() long.
Returns
the current energy

Side effects:

  • Calling this resets the current distance matrix
  • The individual contributions may further update the distance matrix

◆ calcEnergy() [2/2]

double ForceFields::ForceField::calcEnergy ( std::vector< double > *  contribs = NULL) const

calculates and returns the energy (in kcal/mol) based on existing

Returns
the current energy

Note: This function is less efficient than calcEnergy with postions passed in as double * the positions need to be converted to double * here

Referenced by RDKit::ForceFieldsHelper::OptimizeMolecule(), and RDKit::ForceFieldsHelper::detail::OptimizeMoleculeConfsST().

◆ calcGrad() [1/2]

void ForceFields::ForceField::calcGrad ( double *  forces) const

calculates the gradient of the energy at the current position

Parameters
forcesan array of doubles. Should be 3*this->numPoints() long.

Note: This function is less efficient than calcGrad with positions passed in the positions need to be converted to double * here

◆ calcGrad() [2/2]

void ForceFields::ForceField::calcGrad ( double *  pos,
double *  forces 
)

calculates the gradient of the energy at the provided position

Parameters
posan array of doubles. Should be 3*this->numPoints() long.
forcesan array of doubles. Should be 3*this->numPoints() long.

Side effects:

  • The individual contributions may modify the distance matrix

◆ contribs() [1/2]

ContribPtrVect& ForceFields::ForceField::contribs ( )
inline

returns a reference to our contribs (a ContribPtrVect)

Definition at line 186 of file ForceField.h.

◆ contribs() [2/2]

const ContribPtrVect& ForceFields::ForceField::contribs ( ) const
inline

Definition at line 187 of file ForceField.h.

◆ dimension()

unsigned int ForceFields::ForceField::dimension ( ) const
inline

returns the dimension of the forcefield

Definition at line 221 of file ForceField.h.

Referenced by DistGeom::FourthDimContrib::FourthDimContrib().

◆ distance() [1/2]

double ForceFields::ForceField::distance ( unsigned int  i,
unsigned int  j,
double *  pos = 0 
)

returns the distance between two points

Parameters
ipoint index
jpoint index
pos(optional) If this argument is provided, it will be used to provide the positions of points. pos should be 3*this->numPoints() long.
Returns
the distance

Side effects:

  • if the distance between i and j has not previously been calculated, our internal distance matrix will be updated.

◆ distance() [2/2]

double ForceFields::ForceField::distance ( unsigned int  i,
unsigned int  j,
double *  pos = 0 
) const

returns the distance between two points

Parameters
ipoint index
jpoint index
pos(optional) If this argument is provided, it will be used to provide the positions of points. pos should be 3*this->numPoints() long.
Returns
the distance

Note: The internal distance matrix is not updated in this case

◆ fixedPoints() [1/2]

INT_VECT& ForceFields::ForceField::fixedPoints ( )
inline

Definition at line 226 of file ForceField.h.

◆ fixedPoints() [2/2]

const INT_VECT& ForceFields::ForceField::fixedPoints ( ) const
inline

Definition at line 227 of file ForceField.h.

◆ gather()

void ForceFields::ForceField::gather ( double *  pos)
protected

update our positions from an array

Parameters
posshould be 3*this->numPoints() long;

◆ initDistanceMatrix()

void ForceFields::ForceField::initDistanceMatrix ( )
protected

initializes our internal distance matrix

◆ initialize()

void ForceFields::ForceField::initialize ( )

◆ minimize() [1/2]

int ForceFields::ForceField::minimize ( unsigned int  maxIts = 200,
double  forceTol = 1e-4,
double  energyTol = 1e-6 
)

minimizes the energy of the system by following gradients

Parameters
maxItsthe maximum number of iterations to try
forceTolthe convergence criterion for forces
energyTolthe convergence criterion for energies
snapshotFreqa snapshot of the minimization trajectory will be stored after as many steps as indicated through this parameter; defaults to 0 (no trajectory stored)
snapshotVecta pointer to a std::vector<Snapshot> where coordinates and energies will be stored
Returns
an integer value indicating whether or not the convergence criteria were achieved:
  • 0: indicates success
  • 1: the minimization did not converge in maxIts iterations.

◆ minimize() [2/2]

int ForceFields::ForceField::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

Parameters
maxItsthe maximum number of iterations to try
forceTolthe convergence criterion for forces
energyTolthe convergence criterion for energies
Returns
an integer value indicating whether or not the convergence criteria were achieved:
  • 0: indicates success
  • 1: the minimization did not converge in maxIts iterations.

Referenced by RDKit::ForceFieldsHelper::OptimizeMolecule(), and RDKit::ForceFieldsHelper::detail::OptimizeMoleculeConfsST().

◆ numPoints()

unsigned int ForceFields::ForceField::numPoints ( ) const
inline

returns the number of points the ForceField is handling

Definition at line 224 of file ForceField.h.

◆ positions() [1/2]

RDGeom::PointPtrVect& ForceFields::ForceField::positions ( )
inline

returns a reference to our points (a PointPtrVect)

Definition at line 182 of file ForceField.h.

Referenced by RDKit::ForceFieldsHelper::detail::OptimizeMoleculeConfsST().

◆ positions() [2/2]

const RDGeom::PointPtrVect& ForceFields::ForceField::positions ( ) const
inline

Definition at line 183 of file ForceField.h.

◆ scatter()

void ForceFields::ForceField::scatter ( double *  pos) const
protected

scatter our positions into an array

Parameters
posshould be 3*this->numPoints() long;

Member Data Documentation

◆ d_contribs

ContribPtrVect ForceFields::ForceField::d_contribs
protected

contributions to the energy

Definition at line 235 of file ForceField.h.

◆ d_dimension

unsigned int ForceFields::ForceField::d_dimension
protected

Definition at line 227 of file ForceField.h.

◆ d_fixedPoints

INT_VECT ForceFields::ForceField::d_fixedPoints
protected

Definition at line 236 of file ForceField.h.

◆ d_matSize

unsigned int ForceFields::ForceField::d_matSize = 0
protected

Definition at line 237 of file ForceField.h.

◆ d_numPoints

unsigned int ForceFields::ForceField::d_numPoints
protected

the number of active points

Definition at line 232 of file ForceField.h.

◆ d_positions

RDGeom::PointPtrVect ForceFields::ForceField::d_positions
protected

pointers to the points we're using

Definition at line 234 of file ForceField.h.

◆ df_init

bool ForceFields::ForceField::df_init
protected

whether or not we've been initialized

Definition at line 231 of file ForceField.h.

◆ dp_distMat

double* ForceFields::ForceField::dp_distMat
protected

our internal distance matrix

Definition at line 233 of file ForceField.h.


The documentation for this class was generated from the following file: