Adun  0.83
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Public Member Functions | Static Public Member Functions | Protected Attributes
AdMolecularMechanicsForceField Class Reference

#import <AdunMolecularMechanicsForceField.h>

Inheritance diagram for AdMolecularMechanicsForceField:
Inheritance graph
[legend]
Collaboration diagram for AdMolecularMechanicsForceField:
Collaboration graph
[legend]

List of all members.

Public Member Functions

(id) - initWithDictionary:
(id) - init
(id) - initWithSystem:
(id) - initWithSystem:nonbondedTerm:
(id) - initWithSystem:nonbondedTerm:customTerms:
(AdDataMatrix *) - evaluateFiniteDifferenceForcesForTerm:
(void) - evaluateFiniteDifferenceForces
(void) - setSystem:
(void) - setNonbondedTerm:
(AdNonbondedTerm *) - nonbondedTerm
(NSString *) - vdwInteractionType
(void) - logForceSaveMatrix:
(void) - _clearForceSaveMatrix
(void) - _saveForcesForStep:forForce:
(bool) - savesForces
(void) - setOptions:
(NSArray *) - allTerms
(NSArray *) - allEnergies
(NSArray *) - arrayOfEnergiesForTerms:notFoundMarker:
(NSArray *) - arrayOfCoreTermEnergies
(NSDictionary *) - dictionaryOfCoreTermEnergies
(void) - _systemCleanUp
(void) - _updateAccelerations
(void) - _initialisationForSystem
(void) - _createReciprocalMassArray
(void) - _handleSystemContentsChange:
(AdMatrix *) - _internalDataStorageForGroups:parameters:
- Public Member Functions inherited from AdForceField
(void) - evaluateEnergies
(void) - evaluateEnergiesUsingInteractionsInvolvingElements:
(double) - totalEnergy
(void) - evaluateForces
(void) - evaluateForcesDueToElements:
(AdMatrix *) - forces
(void) - setForces:
(AdMatrix *) - accelerations
(void) - setAccelerations:
(void) - clearForces
(id) - system
(id) - availableTerms
- Public Member Functions inherited from
(BOOL) - allowsDirectModificationOfMatrix:
(BOOL) - matrixIsAvailableForModification:
(void) - object:willBeginWritingToMatrix:
(void) - object:didFinishWritingToMatrix:

Static Public Member Functions

(id) + forceFieldForSystem:

Protected Attributes

NSMutableArray * availableTerms
NSArray * coreTerms

Detailed Description

AdMolecularMechanicsForceField is an abstract class that defines the interface for objects that calculate the energy and forces associated with the elements of an AdSystem or AdInteractionSystem object using a molecular mechanics type potential function.

A molecular mechanics force field is usually defined by a function which is the sum of a number of independant mathematical terms.

\[ U(\vec r) = \sum T_{1} + \sum T_{2} + ... + \sum T_{n} \]

Each term represents an interaction that can occur between the elements of a system e.g. bonded, electrostatic etc. Applying the force field function to a set of elements gives their energy.

The application of a force field involves identifying all occurances of each interaction type in the system. Then the corresponding mathematical term is used to evaluate each occurances energy and finally all the results are summed. It is usual that the individual terms are parameterisable functions with the parameters depending on the element types involved in the interaction.

Each AdMolecularMechanicsForceField subclass represents a different force field function i.e. a different combination of terms. It is important to note that they only represent the mathematical function and contain no parameter information. The lists of occurances of each interaction along with the parameters are provided by AdSystem or AdInteractionSystem objects. AdMolecularMechanicsForceField subclassses associate a name with each of their terms. The coreTerms() method returns an array containing the names.

When given a system an AdMolecularMechanicsForceField object checks which interactions are present in it using availableInteractions (AdSystem). It then extracts information for those interactions which correspond to terms in its force field using the methods defined by the AdSystemDataSource protocol. The information required for each term depends on the force field. For example for calculating the bonded term a force field may require a list of all bonded elements aswell as parameters for each. The individual subclasses detail what exactly they require.

Note:
This class implementes a lot of common functionality for its current subclasses since they are very similar. This means that it is tightly coupled to a force field which has the following core terms : HarmonicBond, HarmonicAngle, FourierTorsion, HarmonicImproperTorsion, CoulombElectrostatic and an VdW interaction. If other subclasses are implemented it may be necessary to refactor this class to be more general (e.g move some functionality back to the current subclasses).
Note:
Important: This class also implements the following protocols

Member Function Documentation

- (void) _clearForceSaveMatrix

private method to clear a temporary matrix that is used to calculate "individual" forces

- (void) _createReciprocalMassArray

Allocates an array for holding the reciprocals of the masses of the system. Held in instance variable reciprocalMasses

- (void) _handleSystemContentsChange: (NSNotification *)  aNotification

Performs updates necessary when reloadData is called on a AdMolecularMechanicsForceField instances system.

- (void) _initialisationForSystem

Allocates the force and acceleration matrices. Initialises the internal structure representations for the standard MM force-field interactions if they are present i.e. bond, angle, torsion, improper torsion, standard nonbonded.

- (AdMatrix*) _internalDataStorageForGroups: (AdDataMatrix *)  groups
parameters: (AdDataMatrix *)  parameters 

Convience method for creating the internal AdMatrix structs used to store the group and parameter information for each interaction.

- (void) _saveForcesForStep: (int)  step
forForce: (int)  i 

private method to save "individual" forces

- (void) _systemCleanUp

Resets all system dependant ivars. Use on a change of system.

- (void) _updateAccelerations

Updates the acceleration matrix with using the current forces

- (NSArray*) allEnergies
Deprecated:
Use arrayOfValuesForPotentials:notFoundMarker: (AdForceFieldPotentials-p)

Returns an array containing the energies of all the terms that can be computed by the receiver. The order corresponds to the order of terms returned by allTerms.

- (NSArray*) allTerms
Deprecated:
Use potentials (AdForceFieldPotentials-p)

Returns an array containing the names of all the energy terms the force field can compute.

Note:
The first n entries correspond to the array returned by coreTerms(). The subsequent entries are custom terms.
- (NSArray*) arrayOfCoreTermEnergies
Deprecated:
Use arrayOfCorePotentialValues (AdForceFieldPotentials-p)

Returns an array containing the last calculated energies associated with each core term. The order of the returned array corresponds to the order of the array returned by coreTerms().

- (NSArray*) arrayOfEnergiesForTerms: (NSArray *)  terms
notFoundMarker: (id)  anObject 
- (NSDictionary*) dictionaryOfCoreTermEnergies
Deprecated:
Use dictionaryOfCorePotentialValues (AdForceFieldPotentials-p)

Returns a dictionary whose keys are core term names and whose values are the energies for each.

- (void) evaluateFiniteDifferenceForces

Evaluates the forces acting on the system using finite difference method

- (AdDataMatrix *) evaluateFiniteDifferenceForcesForTerm: (NSString*)  aTerm

Evaluates forces due to aTerm using central finite difference. If aTerm is a custom term it must return yes for canEvaluateForces. If it cannot evaluate forces this method return nil

+ (id) forceFieldForSystem: (AdSystem*)  system

This method determines the correct AdMolecularMechanicsForceField subclass for system. It then creates and returns an instance of it using initWithSystem: passing system as the parameter. The correct force field is determined from the value of the ForceField metadata key of the systems data source. If this key is missing or is not recognised this method returns nil. The currently recognised values are Enzymix, Charmm and Amber.

- (id) init

As initWithSystem: passing nil for system

- (id) initWithDictionary: (NSDictionary*)  dictionary

Special intialiser for use with AdTemplateProcessor. It instantiates the correct AdMolecularMechanicsForceField subclass for the system passed in dictionary. Dictionary has some/all of the following keys

  • system: An AdSystem instance - required.
  • nonbondedTerm: An AdNonbondedTerm instance
  • customTerms: A dictionary of custom terms

Note: The returned object is an instance of an AdMolecularMechanicsForceField subclass. The receiver is released by this method.

- (id) initWithSystem: (id)  system

As initWithSystem:nobondedTerm() passing nil for anObject

Implements AdForceField.

- (id) initWithSystem: (id)  system
nonbondedTerm: (AdNonbondedTerm*)  anObject 

As initWithSystem:nonbondedTerm:customTerms: passing nil for aDict.

- (id) initWithSystem: (id)  system
nonbondedTerm: (AdNonbondedTerm*)  anObject
customTerms: (NSDictionary*)  aDict 

Initialises an new AdMolecularMechanicsForceField instance for calculating the force and energies of system using the enzymix force field.

Parameters:
systemAn AdSystem or AdInteractionSystem object.
anObjectAn AdNonbondedTerm object that will handle the nonbonded terms of the force field. If the system associated with anObject is not the same as system it is replaced by it. In addition the lennard jones type used by anObject is automatically set to "A". If anObject is nil and is not nil a default nonbonded term object is created. This is an AdPureNonbondedTerm instance with a cutoff of 12 and update interval of 20.
aDictAn optional dictionary whose keys are term names and whose values are objects that conform to the AdForceFieldTerm protocol. They will be added to the force field using addCustomTerms:().
- (void) logForceSaveMatrix: (NSString *)  fileName

outputs the force matrix for the last X frames

- (AdNonbondedTerm*) nonbondedTerm

Returns the object used to calculate the nonbonded terms of the force field.

- (bool) savesForces

returns true if the forcefield is able to save a force matrix (and as such stores forces)

- (void) setNonbondedTerm: (AdNonbondedTerm*)  anObject

Sets the receiver to use anObject for calculating the nonbonded terms of the force field. If the system associated with anObject is not the same as the revceivers system then it is replaced with it. The lennard jones type used by anObject is set to "A" if it is not already.

- (void) setOptions: (NSDictionary *)  opt

sets options to control (for now, but is not limited to) force saving

- (void) setSystem: (id)  anObject
Bug:
  • Does not handle the case where system does not contain the necessary parameters. Such an occurance will produce a segmentation fault.

Implements AdForceField.

- (NSString*) vdwInteractionType

Returns the vdw function type used by receiver


Member Data Documentation

- (NSArray *) availableTerms
protected

The core terms that the current system provides information for.

Returns an array containing the names of all the terms object used by the force field to compute potentials

- (NSArray *) coreTerms
protected

The core terms of the force field.

Returns the names of the core terms of the force field. These are the terms it can use without extension.

NOTE: This ABI of this method has changed in version 0.82. The new method corePotentials() implements the previous behaviour.