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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ForceField() [1/2]

◆ ~ForceField()

◆ ForceField() [2/2]

Member Function Documentation

◆ calcEnergy() [1/2]

◆ calcEnergy() [2/2]

◆ calcGrad() [1/2]

◆ calcGrad() [2/2]

◆ contribs() [1/2]

◆ contribs() [2/2]

◆ dimension()

◆ distance() [1/2]

◆ distance() [2/2]

◆ distance2()

◆ fixedPoints() [1/2]

◆ fixedPoints() [2/2]

◆ gather()

◆ initDistanceMatrix()

◆ initialize()

◆ minimize() [1/2]

◆ minimize() [2/2]

◆ numPoints()

◆ positions() [1/2]

◆ positions() [2/2]

◆ scatter()

Member Data Documentation

◆ d_contribs

◆ d_dimension

◆ d_fixedPoints

◆ d_matSize

◆ d_numPoints

◆ d_positions

◆ df_init

◆ dp_distMat