BALL::ForceField Class Reference
[General Force Field Classes.]

#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.
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::AmberFF, BALL::CharmmFF, 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 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.

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.

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 [inline, virtual]

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

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

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 const System* BALL::ForceField::getSystem ( ) const

Returns a const pointer to the system

BALL_INLINE System* BALL::ForceField::getSystem ( )

Returns a 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::AmberFF, and BALL::MMFF94.

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_ ( ) [protected, virtual]

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

void BALL::ForceField::removeComponent ( const String & name )

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

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::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,
		const Options &	options
	)

Sets up the force field and its components.

bool BALL::ForceField::setup ( System & system )

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::AmberFF, BALL::CharmmFF, 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.