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=nullptr) const
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::PointPtrVect & | positions ()
| returns a reference to our points (a PointPtrVect) More...
const RDGeom::PointPtrVect & | positions () const
ContribPtrVect & | contribs ()
| returns a reference to our contribs (a ContribPtrVect) More...
const ContribPtrVect & | contribs () const
double | distance (unsigned int i, unsigned int j, double *pos=nullptr)
| returns the distance between two points More...
double | distance (unsigned int i, unsigned int j, double *pos=nullptr) 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_VECT & | fixedPoints ()
const INT_VECT & | fixedPoints () 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 {false}
| whether or not we've been initialized More...
unsigned int | d_numPoints {0}
| the number of active points More...
double * | dp_distMat {nullptr}
| 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

  pos | an 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 = `nullptr` | ) | const

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

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

  forces | an 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

  pos | an array of doubles. Should be `3*this->numPoints()` long.
  forces | an 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 185 of file ForceField.h.

## contribs() [2/2]

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

inline

Definition at line 186 of file ForceField.h.

## dimension()

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

inline

returns the dimension of the forcefield

Definition at line 220 of file ForceField.h.

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

## distance() [1/2]

double ForceFields::ForceField::distance | ( | unsigned int | i,
|  | unsigned int | j,
|  | double * | pos = `nullptr`
| ) |  |

returns the distance between two points

Parameters

  i | point index
  j | point 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 = `nullptr`
| ) |  | const

returns the distance between two points

Parameters

  i | point index
  j | point 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 225 of file ForceField.h.

## fixedPoints() [2/2]

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

inline

Definition at line 226 of file ForceField.h.

## gather()

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

protected

update our positions from an array

Parameters

  pos | should be `3*this->numPoints()` long;

## initDistanceMatrix()

void ForceFields::ForceField::initDistanceMatrix | ( |  | ) |

protected

initializes our internal distance matrix

## initialize()

void ForceFields::ForceField::initialize | ( |  | ) |

does initialization

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

## 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

  maxIts | the maximum number of iterations to try
  forceTol | the convergence criterion for forces
  energyTol | the convergence criterion for energies
  snapshotFreq | a snapshot of the minimization trajectory will be stored after as many steps as indicated through this parameter; defaults to 0 (no trajectory stored)
  snapshotVect | a 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

  maxIts | the maximum number of iterations to try
  forceTol | the convergence criterion for forces
  energyTol | the 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 223 of file ForceField.h.

## positions() [1/2]

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

inline

returns a reference to our points (a PointPtrVect)

Definition at line 181 of file ForceField.h.

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

## positions() [2/2]

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

inline

Definition at line 182 of file ForceField.h.

## scatter()

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

protected

scatter our positions into an array

Parameters

  pos | should be `3*this->numPoints()` long;

## Member Data Documentation

## d_contribs

ContribPtrVect ForceFields::ForceField::d_contribs

protected

contributions to the energy

Definition at line 234 of file ForceField.h.

## d_dimension

unsigned int ForceFields::ForceField::d_dimension

protected

Definition at line 229 of file ForceField.h.

## d_fixedPoints

INT_VECT ForceFields::ForceField::d_fixedPoints

protected

Definition at line 235 of file ForceField.h.

## d_matSize

unsigned int ForceFields::ForceField::d_matSize = 0

protected

Definition at line 236 of file ForceField.h.

## d_numPoints

unsigned int ForceFields::ForceField::d_numPoints {0}

protected

the number of active points

Definition at line 231 of file ForceField.h.

## d_positions

RDGeom::PointPtrVect ForceFields::ForceField::d_positions

protected

pointers to the points we're using

Definition at line 233 of file ForceField.h.

## df_init

bool ForceFields::ForceField::df_init {false}

protected

whether or not we've been initialized

Definition at line 230 of file ForceField.h.

## dp_distMat

double* ForceFields::ForceField::dp_distMat {nullptr}

protected

our internal distance matrix

Definition at line 232 of file ForceField.h.

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

- ForceField.h