RDKit: ForceFields::ForceField Class Reference

| RDKit Open-source cheminformatics and machine learning.

Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
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
| ~ForceField ()
| ForceField (const ForceField &other)
| copy ctor, copies contribs.
void | initialize ()
| does initialization
double | calcEnergy (std::vector< double > *contribs=nullptr) const
double | calcEnergy (double *pos)
| calculates and returns the energy of the position passed in
void | calcGrad (double *forces) const
| calculates the gradient of the energy at the current position
void | calcGrad (double *pos, double *forces)
| calculates the gradient of the energy at the provided position
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
int | minimize (unsigned int maxIts=200, double forceTol=1e-4, double energyTol=1e-6)
| minimizes the energy of the system by following gradients
RDGeom::PointPtrVect & | positions ()
| returns a reference to our points (a PointPtrVect)
const RDGeom::PointPtrVect & | positions () const
ContribPtrVect & | contribs ()
| returns a reference to our contribs (a ContribPtrVect)
const ContribPtrVect & | contribs () const
double | distance (unsigned int i, unsigned int j, double *pos=nullptr)
| returns the distance between two points
double | distance (unsigned int i, unsigned int j, double *pos=nullptr) const
| returns the distance between two points
double | distance2 (unsigned int i, unsigned int j, double *pos=nullptr) const
| returns the squared distance between two points
unsigned int | dimension () const
| returns the dimension of the forcefield
unsigned int | numPoints () const
| returns the number of points the ForceField is handling
INT_VECT & | fixedPoints ()
const INT_VECT & | fixedPoints () const

## Protected Member Functions
void | scatter (double *pos) const
| scatter our positions into an array
void | gather (double *pos)
| update our positions from an array
void | initDistanceMatrix ()
| initializes our internal distance matrix

## Protected Attributes
unsigned int | d_dimension
bool | df_init {false}
| whether or not we've been initialized
unsigned int | d_numPoints {0}
| the number of active points
double * | dp_distMat {nullptr}
| our internal distance matrix
RDGeom::PointPtrVect | d_positions
| pointers to the points we're using
ContribPtrVect | d_contribs
| contributions to the energy
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.

References d_dimension, and dimension().

Referenced by ForceField().

## ◆ ~ForceField()

ForceFields::ForceField::~ForceField | ( |  | ) |

## ◆ ForceField() [2/2]

ForceFields::ForceField::ForceField | ( | const ForceField & | other | ) |

copy ctor, copies contribs.

References ForceField().

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

References contribs().

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.

References d_contribs.

Referenced by calcEnergy().

## ◆ contribs() [2/2]

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

Definition at line 186 of file ForceField.h.

References d_contribs.

## ◆ dimension()

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

returns the dimension of the forcefield

Definition at line 235 of file ForceField.h.

References d_dimension.

Referenced by ForceField(), and DistGeom::FourthDimContribs::FourthDimContribs().

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

## ◆ distance2()

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

returns the squared 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 squared distance

Note: The internal distance matrix is not updated

## ◆ fixedPoints() [1/2]

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

Definition at line 240 of file ForceField.h.

References d_fixedPoints.

## ◆ fixedPoints() [2/2]

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

Definition at line 241 of file ForceField.h.

References d_fixedPoints.

## ◆ 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 238 of file ForceField.h.

References d_numPoints.

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

References d_positions.

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.

References d_positions.

## ◆ 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 249 of file ForceField.h.

Referenced by contribs(), and contribs().

## ◆ d_dimension

unsigned int ForceFields::ForceField::d_dimension
| protected

Definition at line 244 of file ForceField.h.

Referenced by dimension(), and ForceField().

## ◆ d_fixedPoints

INT_VECT ForceFields::ForceField::d_fixedPoints
| protected

Definition at line 250 of file ForceField.h.

Referenced by fixedPoints(), and fixedPoints().

## ◆ d_matSize

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

Definition at line 251 of file ForceField.h.

## ◆ d_numPoints

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

the number of active points

Definition at line 246 of file ForceField.h.

Referenced by numPoints().

## ◆ d_positions

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

pointers to the points we're using

Definition at line 248 of file ForceField.h.

Referenced by positions(), and positions().

## ◆ df_init

bool ForceFields::ForceField::df_init {false}
| protected

whether or not we've been initialized

Definition at line 245 of file ForceField.h.

## ◆ dp_distMat

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

our internal distance matrix

Definition at line 247 of file ForceField.h.

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

- ForceField.h