BALL::ForceField Class Reference

#include <BALL/MOLMEC/COMMON/forceField.h>

Inheritance diagram for BALL::ForceField:

Public Types
Type Definitions
typedef std::vector< std::pair < Atom *, Atom * > >	PairVector

Public Member Functions
Constructors and Destructors
	ForceField ()
	ForceField (System &system)
	ForceField (System &system, const Options &options)
	ForceField (const ForceField &force_field)
virtual	~ForceField ()
virtual void	clear ()
Assignments
ForceField &	operator= (const ForceField &force_field)
Debugging and Diagnostics
bool	isValid () const
Setup methods
bool	setup (System &system)
bool	setup (System &system, const Options &options)
virtual bool	specificSetup () throw (Exception::TooManyErrors)
void	setMaximumNumberOfErrors (Size nr)
Size	getMaximumNumberOfErrors () const
HashSet< const Atom * > &	getUnassignedAtoms ()
	Get the atoms, for which the force field setup failed. More...
Accessors
void	setName (const String &name)
String	getName () const
Size	getNumberOfAtoms () const
Size	getNumberOfMovableAtoms () const
BALL_INLINE const AtomVector &	getAtoms () const
BALL_INLINE System *	getSystem ()
BALL_INLINE const System *	getSystem () const
BALL_INLINE bool	getUseSelection () const
BALL_INLINE void	disableSelection ()
BALL_INLINE void	enableSelection ()
BALL_INLINE bool	isSelectionEnabled () const
ForceFieldParameters &	getParameters ()
Size	countComponents () const
const TimeStamp &	getUpdateTime () const
const TimeStamp &	getSetupTime () const
void	insertComponent (ForceFieldComponent *force_field_component)
void	removeComponent (const ForceFieldComponent *force_field_component)
void	removeComponent (const String &name)
ForceFieldComponent *	getComponent (const Size index) const
ForceFieldComponent *	getComponent (const String &name) const
double	getEnergy () const
double	updateEnergy ()
void	updateForces ()
double	getRMSGradient () const
virtual Size	getUpdateFrequency () const
virtual void	update () throw (Exception::TooManyErrors)
virtual String	getResults () const
std::ostream &	error () throw (Exception::TooManyErrors)

Public Attributes
Public Attributes
Options	options
PeriodicBoundary	periodic_boundary

Protected Member Functions
void	collectAtoms_ (const System &system)
void	sortSelectedAtomVector_ ()
virtual void	performRequiredUpdates_ ()

Protected Attributes
System *	system_
AtomVector	atoms_
ForceFieldParameters	parameters_
bool	valid_
String	name_
double	energy_
vector< ForceFieldComponent * >	components_
Size	number_of_movable_atoms_
bool	use_selection_
bool	selection_enabled_
TimeStamp	update_time_stamp_
TimeStamp	setup_time_stamp_
HashSet< const Atom * >	unassigned_atoms_
Size	max_number_of_errors_
Size	number_of_errors_

Friends
class	ForceFieldComponent

Detailed Description

Force field class. This class is used to represent a general force field. Each force field by itself is composed by several different force field components which are represented by ForceFieldComponent objects.

Each ForceField object provides a list of components which may be manipulated by the user to generate the force field he needs.

ForceField only represents a baseclass to the specific force field implementations (e.g. AMBER ) and implements the common interface and the neccessary mechanisms to administer the force field components.

A typical force field contains a small number of components (e.g. bond stretch, bend, torsion and non-bonding interactions). A specialized forcefield has to implement each of these components (by deriving them from ForceFieldComponent and must be derived from ForceField. Basically only the default constructor for the new forcefield has to be modified to create an instance of each of the components and register them by calling insertComponent . But in order to implement the setup methods of the force field components efficiently, jobs like assigning atom types, reading parameter files and the such should be provided for all force field components by the corrseponding ForceField object. This should be implemented in the force field-specific specificSetup method.

For an efficient and easy to use implementation of a forcefield parameter file, please refer to ForceFieldParameters and its related objects.

Each force field provides as well energy and its derivatives, the force on each atom. A calculation of the energy is done by calling updateEnergy . This method iterates over the list of force field components and invokes the updateEnergy method of each of these components. The total energy may then be retrieved by calling getEnergy .

Analogously, a force calculation is performed by invoking updateForces . getForces returns a pointer to an array containing the forces for each atom.

Definition at line 85 of file forceField.h.

Member Typedef Documentation

typedef std::vector<std::pair<Atom*, Atom*> > BALL::ForceField::PairVector

Atom pair vector. This type is used to represent "pair lists". In fact, it is a vector of pairs of atom pointers.

Definition at line 99 of file forceField.h.

Constructor & Destructor Documentation

BALL::ForceField::ForceField

(

)

Default constructor. A default-constructed force field is not valid! It becomes valid after a successful call to setup.

BALL::ForceField::ForceField

(

System &

system

)

Constructor. The successful setup of the force field can be verified by the isValid method.

BALL::ForceField::ForceField	(	System &	system,
		const Options &	options
	)

Constructor. The successful setup of the force field can be verified by the isValid method.

BALL::ForceField::ForceField

(

const ForceField &

force_field

)

Copy constructor

virtual BALL::ForceField::~ForceField ( )

virtual

Destructor.

Member Function Documentation

virtual void BALL::ForceField::clear ( )

virtual

Clear method.

Reimplemented in BALL::CharmmFF, BALL::AmberFF, and BALL::MMFF94.

void BALL::ForceField::collectAtoms_ ( const System &  system )

protected

Size BALL::ForceField::countComponents

(

)

const

Returns the number of components registered by the force field.

BALL_INLINE void BALL::ForceField::disableSelection

(

)

Set the status of the selection mechanism

BALL_INLINE void BALL::ForceField::enableSelection

(

)

Set the status of the selection mechanism

std::ostream& BALL::ForceField::error	(		)
throw	(	Exception::TooManyErrors
	)

BALL_INLINE const AtomVector& BALL::ForceField::getAtoms

(

)

const

Returns a reference to the atom vector

ForceFieldComponent* BALL::ForceField::getComponent

(

const Size

index

)

const

Return a pointer to the specified force field component. If the specified index does not exist, 0 is returned. The given index should be smaller than the value returned by countComponents. The first component in the list has the index zero.

ForceFieldComponent* BALL::ForceField::getComponent

(

const String &

name

)

const

Return a pointer to the specified force field component. If a component with the specified name does not exist, 0 is returned.

double BALL::ForceField::getEnergy

(

)

const

Return the sum of energies of all registered force field components. No calculation will be performed. This method simply returns the last value for the total energy calculated by updateEnergy.

Returns

double - energy in kJ/mol

Size BALL::ForceField::getMaximumNumberOfErrors

(

)

const

Get the number of atoms, for which the setup of the forcefield can fail, until the setup() methods aborts and return false.

String BALL::ForceField::getName

(

)

const

Returns the force field name

Size BALL::ForceField::getNumberOfAtoms

(

)

const

Returns the number of atoms stored in the force field

Size BALL::ForceField::getNumberOfMovableAtoms

(

)

const

Returns the number of non-fixed atoms stored in the force field. If the option SELECTION_FIXED is set to true or SELECTION_MOVABLE is set to true the atom array is split. The first section (indices 0 to getNumberOfMovableAtoms ) contains the atoms that are to be moved, the rest of the array contains the fixed atoms.

ForceFieldParameters& BALL::ForceField::getParameters

(

)

Returns a pointer to the parameter file

virtual String BALL::ForceField::getResults ( ) const

inlinevirtual

Get the current results in String form (Generic function to be overloaded in derived classes.)

Reimplemented in BALL::CharmmFF, BALL::MMFF94, and BALL::AmberFF.

Definition at line 347 of file forceField.h.

double BALL::ForceField::getRMSGradient

(

)

const

Calculates the RMS of the current gradient

const TimeStamp& BALL::ForceField::getSetupTime

(

)

const

Return the point of time of the last call to setup. ForceField contains a time stamp which is used to determine whether the selection or even the topology of the system has changed. Every time update is called, the update_time_stamp_ is updated. Similarly, all setup methods update the setup_time_stamp_

BALL_INLINE System* BALL::ForceField::getSystem

(

)

Returns a pointer to the system

BALL_INLINE const System* BALL::ForceField::getSystem

(

)

const

Returns a const pointer to the system

HashSet<const Atom*>& BALL::ForceField::getUnassignedAtoms

(

)

Get the atoms, for which the force field setup failed.

virtual Size BALL::ForceField::getUpdateFrequency ( ) const

virtual

Return the update frequency for pair lists etc. This method is used by minimizers or the MD simulation to determine the number of iterations between two calls to update .

Reimplemented in BALL::MMFF94, and BALL::AmberFF.

const TimeStamp& BALL::ForceField::getUpdateTime

(

)

const

Return the point of time of the last call to update. ForceField contains a time stamp which is used to determine whether the selection or even the topology of the system has changed. Every time update is called, the update_time_stamp_ is updated. Similarly, all setup methods update the setup_time_stamp_

BALL_INLINE bool BALL::ForceField::getUseSelection

(

)

const

Return the status of the selection mechanism

void BALL::ForceField::insertComponent

(

ForceFieldComponent *

force_field_component

)

Insert a new component into the force field's component list. Responsability for the destruction of the component is passed on to the ForceField instance.

BALL_INLINE bool BALL::ForceField::isSelectionEnabled

(

)

const

Return the status of the selection mechanism

bool BALL::ForceField::isValid

(

)

const

Check the force field's validity. A force field is valid if it is bound to a system and setup was successful.

ForceField& BALL::ForceField::operator=

(

const ForceField &

force_field

)

Assignment operator

virtual void BALL::ForceField::performRequiredUpdates_ ( )

protectedvirtual

Check whether the force field needs to be updated and perform the necessary steps

void BALL::ForceField::removeComponent

(

const ForceFieldComponent *

force_field_component

)

Remove a component from the force field's component list. The ForceFieldComponent will be destructed and removed from the component list.

void BALL::ForceField::removeComponent

(

const String &

name

)

Remove a component from the force field's component list.

void BALL::ForceField::setMaximumNumberOfErrors

(

Size

nr

)

Set the number of atoms, for which the setup of the forcefield can fail, until the setup() methods aborts and return false. By default, there is no limit set.

void BALL::ForceField::setName

(

const String &

name

)

Sets the force field name.

bool BALL::ForceField::setup

(

System &

system

)

Sets up the force field and its components.

bool BALL::ForceField::setup	(	System &	system,
		const Options &	options
	)

Sets up the force field and its components.

void BALL::ForceField::sortSelectedAtomVector_ ( )

protected

virtual bool BALL::ForceField::specificSetup ( ) throw ( Exception::TooManyErrors )

virtual

Force field specific setup. This method is called by setup.

Reimplemented in BALL::CharmmFF, BALL::AmberFF, and BALL::MMFF94.

virtual void BALL::ForceField::update ( ) throw ( Exception::TooManyErrors )

virtual

Update internal data structures. The force field may use this method to update internal data structures (e.g. pair lists) periodically. The MD simulation class as well as the minimizer classes use getUpdateFrequency to determine the number of iterations between two calls to update.

The default implementation calls ForceFieldComponent::update for each component in the force field.

double BALL::ForceField::updateEnergy

(

)

Calculate the sum of energies of all force field components and returns its value.

void BALL::ForceField::updateForces

(

)

Calculate the forces caused by each component and updates the current forces.

Friends And Related Function Documentation

friend class ForceFieldComponent

friend

Definition at line 89 of file forceField.h.

Member Data Documentation

AtomVector BALL::ForceField::atoms_

protected

Definition at line 392 of file forceField.h.

vector<ForceFieldComponent*> BALL::ForceField::components_

protected

Definition at line 412 of file forceField.h.

double BALL::ForceField::energy_

protected

Definition at line 408 of file forceField.h.

Size BALL::ForceField::max_number_of_errors_

protected

Definition at line 438 of file forceField.h.

String BALL::ForceField::name_

protected

Definition at line 404 of file forceField.h.

Size BALL::ForceField::number_of_errors_

protected

Definition at line 440 of file forceField.h.

Size BALL::ForceField::number_of_movable_atoms_

protected

Definition at line 416 of file forceField.h.

Options BALL::ForceField::options

Force field options

Definition at line 360 of file forceField.h.

ForceFieldParameters BALL::ForceField::parameters_

protected

Definition at line 396 of file forceField.h.

PeriodicBoundary BALL::ForceField::periodic_boundary

Periodic boundary

Definition at line 364 of file forceField.h.

bool BALL::ForceField::selection_enabled_

protected

Definition at line 424 of file forceField.h.

TimeStamp BALL::ForceField::setup_time_stamp_

protected

Definition at line 432 of file forceField.h.

System* BALL::ForceField::system_

protected

Definition at line 388 of file forceField.h.

HashSet<const Atom*> BALL::ForceField::unassigned_atoms_

protected

Definition at line 435 of file forceField.h.

TimeStamp BALL::ForceField::update_time_stamp_

protected

Definition at line 428 of file forceField.h.

bool BALL::ForceField::use_selection_

protected

Definition at line 420 of file forceField.h.

bool BALL::ForceField::valid_

protected

Definition at line 400 of file forceField.h.