Open Babel: OBForceField Class Reference

The OBForceField class is the base class for molecular mechanics in Open Babel. Classes derived from the OBForceField implement specific force fields (Ghemical, MMFF94, ...). Other classes such as OBFFParameter, OBFFCalculation and its derived classes are only for internal use. As a user interested in using the available force fields in Open Babel, you don't need these classes. The rest of this short introduction is aimed at these users. For information on how to implement additional force fields, see the wiki pages or post your questions to the openbabel-devel mailing list.

Before we can start using a force field, we must first select it and set it up. This is illustrated in the first example below. The Setup procedure assigns atom types, charges and parameters. There are several reasons why this may fail, a log message will be written to the logfile before Setup() returns false.

The force field classes use their own logging functions. You can set the logfile using SetLogFile() and set the log level using SetLogLevel(). If needed you can also write to the logfile using OBFFLog(). There are four log levels: BFF_LOGLVL_NONE, OBFF_LOGLVL_LOW, OBFF_LOGLVL_MEDIUM, OBFF_LOGLVL_HIGH. See the API documentation to know what kind of output each function writes to the logfile for the different log levels.

      #include <openbabel/forcefield.h>
      #include <openbabel/mol.h>

      // See OBConversion class to fill the mol object.
      OBMol mol;
      // Select the forcefield, this returns a pointer that we 
      // will later use to access the forcefield functions.
      OBForceField* pFF = OBForceField::FindForceField("Ghemical");

      // Make sure we have a valid pointer
      if (!pFF)
      // exit...
     
      // Set the logfile (can also be &cout or &cerr)
      pFF->SetLogFile(&cerr);
      // Set the log level. See indivual functions to know
      // what kind of output each function produces for the
      // different log levels.
      pFF->SetLogLevel(OBFF_LOGLVL_HIGH);

      // We need to setup the forcefield before we can use it. Setup()
      // returns false if it failes to find the atom types, parameters, ...
      if (!pFF->Setup(mol)) {
      cerr << "ERROR: could not setup force field." << endl;
      }
      
      // Calculate the energy. The output will be written to the
      // logfile specified by SetLogFile()
      pFF->Energy();

Constructor & Destructor Documentation

virtual ~OBForceField ( ) [inline, virtual]

Destructor.

Member Function Documentation

OBFFParameter * GetParameter	(	int	a,
		int	b,
		int	c,
		int	d,
		std::vector< OBFFParameter > &	parameter
	)			`[protected]`

Get the correct OBFFParameter from a OBFFParameter vector.

 vector<OBFFParameter> parameters;

this vector is filled with entries (as OBFFParameter) from a parameter file. This happens in the Setup() function.

 GetParameter(a, 0, 0, 0, parameters);

returns the first OBFFParameter from vector<OBFFParameter> parameters where: pa = a (pa = parameter.a)

use: vdw parameters, ...

 GetParameter(a, b, 0, 0, parameters);

returns the first OBFFParameter from vector<OBFFParameter> parameters where: pa = a & pb = b (ab) or: pa = b & pb = a (ba)

use: bond parameters, vdw parameters (pairs), ...

 GetParameter(a, b, c, 0, parameters);

returns the first OBFFParameter from vector<OBFFParameter> parameters where: pa = a & pb = b & pc = c (abc) or: pa = c & pb = b & pc = a (cba)

use: angle parameters, ...

 GetParameter(a, b, c, d, parameters);

returns the first OBFFParameter from vector<OBFFParameter> parameters where: pa = a & pb = b & pc = c & pd = d (abcd) or: pa = d & pb = b & pc = c & pd = a (dbca) or: pa = a & pb = c & pc = b & pd = d (acbd) or: pa = d & pb = c & pc = b & pd = a (dcba)

use: torsion parameters, ...

OBFFParameter * GetParameter	(	const char *	a,
		const char *	b,
		const char *	c,
		const char *	d,
		std::vector< OBFFParameter > &	parameter
	)			`[protected]`

see GetParameter(int a, int b, int c, int d, std::vector<OBFFParameter> &parameter)

vector3 NumericalDerivative	(	OBAtom *	a,
		int	terms = `OBFF_ENERGY`
	)			`[protected]`

Calculate the potential energy function derivative numerically with repect to the coordinates of atom with index a (this vector is the gradient).

Parameters:

	a	provides coordinates
	terms	OBFF_ENERGY, OBFF_EBOND, OBFF_EANGLE, OBFF_ESTRBND, OBFF_ETORSION, OBFF_EOOP, OBFF_EVDW, OBFF_ELECTROSTATIC

Returns:: the negative gradient of atom a

vector3 NumericalSecondDerivative	(	OBAtom *	a,
		int	terms = `OBFF_ENERGY`
	)			`[protected]`

OB 3.0.

virtual vector3 GetGradient	(	OBAtom *	a,
		int	terms = `OBFF_ENERGY`
	)			`[inline, protected, virtual]`

Calculate the potential energy function derivative analyticaly with repect to the coordinates of atom with index a (this vector is the gradient)

If the currently selected forcefield doesn't have analytical gradients, we can still call this function which will return the result of NumericalDerivative()

Parameters:

	a	provides coordinates
	terms	OBFF_ENERGY, OBFF_EBOND, OBFF_EANGLE, OBFF_ESTRBND, OBFF_ETORSION, OBFF_EOOP, OBFF_EVDW, OBFF_ELECTROSTATIC

Returns:: the negative gradient of atom a

bool IsInSameRing	(	OBAtom *	a,
		OBAtom *	b
	)			`[protected]`

Check if two atoms are in the same ring

Parameters:

	a	atom a
	b	atom b

Returns:: true if atom a and b are in the same ring

static OBForceField* FindForceField ( const std::string & ID ) [inline, static]

short description of the force field type.

Parameters:

forcefield id (Ghemical, ...)

Returns:: A pointer to a forcefield (the default if ID is empty), or NULL if not available

static OBForceField* FindForceField ( const char * ID ) [inline, static]

Parameters:

forcefield id (Ghemical, ...)

Returns:: A pointer to a forcefield (the default if ID is empty), or NULL if not available

virtual std::string GetUnit ( ) [inline, virtual]

Returns:: The unit (kcal/mol, kJ/mol, ...) in which the energy is expressed as std::string

virtual bool Setup ( OBMol & mol ) [inline, virtual]

Setup the forcefield for mol (assigns atom types, charges, etc.)

Parameters:

mol

the OBMol object that contains the atoms and bonds

Returns:: True if succesfull

bool UpdateCoordinates ( OBMol & mol )

Update coordinates for current conformer

Parameters:

mol

the OBMol object to copy the coordinates to

Returns:: true if succesfull

bool UpdateConformers ( OBMol & mol )

Update coordinates for all conformers

Parameters:

mol

the OBMol object to copy the coordinates to

Returns:: true if succesfull

void OBFFLog ( std::string msg ) [inline]

Print msg to the logfile

Parameters:

msg

the message

void OBFFLog ( const char * msg ) [inline]

Print msg to the logfile

Parameters:

msg

the message

virtual double Energy ( bool gradients = true ) [inline, virtual]

Parameters:

gradients