<AdForceFieldTerm> Protocol Reference

#import <AdForceFieldTerm.h>

Inheritance diagram for <AdForceFieldTerm>:

List of all members.

Public Member Functions
(id)	- initWithSystem:
(void)	- evaluateForces
(void)	- evaluateEnergy
(double)	- energy
(AdMatrix *)	- forces
(void)	- setExternalForceMatrix:
(BOOL)	- usesExternalForceMatrix
(void)	- setSystem:
(id)	- system
(BOOL)	- canEvaluateEnergy
(BOOL)	- canEvaluateForces
(NSArray *)	- potentials
(double)	- valueForPotential:
(NSArray *)	- arrayOfValuesForPotentials:notFoundMarker:
(NSDictionary *)	- dictionaryOfValuesForPotentials:

---

Detailed Description

This protocol defines the interface for objects that represent custom terms in a force-field. Objects conforming to this protocol can be added to AdForceField objects thus extending the force field.

AdForceFieldTerm complient objects operate on a system i.e. an AdSystem or AdInteractionSystem object, calculating the energy and/or force due to the interaction which they represent. The potential energy calculated by the term can be broken into multiple components and the value of each reported individually. For example a term representing an implicit solvent interaction could calculate both polar and non-polar solvation energies.

Objects conforming to this protocol can accumulate their forces into an external ::AdMatrix structure instead of using an internal one. This feature increases calculation speed (more efficent memory usage, less additions) at the cost of not always being able to retrieve the interactions contribution to the total force.

AdForceField assumes such objects observe AdSystemContentsDidChangeNotification from their systems if necessary and can update themselves on receiving such a notification.

Note:

Objects that conform to AdForceFieldTerm do not have to calculate both forces and energies. Though obviously they must at least calculate one or the other to be useful.

---

Member Function Documentation

- (NSArray*) arrayOfValuesForPotentials:		(NSArray *)	array
notFoundMarker:		(id)	anObject

Returns an NSArray containing the last calculated energies for the potentials contained in array. The order of values in the returned array corresponds to the order of potentials in array. If a potential in array is not present in the array returned by potentials then anObject is inserted in its place.

- (BOOL) canEvaluateEnergy

Returns YES if the object can calculate energy.

- (BOOL) canEvaluateForces

Return YES if the object can calculate forces.

- (NSDictionary*) dictionaryOfValuesForPotentials:

(NSArray *)

array

Returns a dictionary whose keys are the potential names contained in array and whose values are the last calculated value for each potential. If a potential in array is not present in the array returned by potentials then it is not included in the returned dictionary.

- (double) energy

Returns the last calculated value for the total energy. Should return 0 if no energy has been calculated or if the object cannot calculate the energy. The value returned by this method may be sum of a number of component energies. In this case the methods potentials and valueForPotential: can be used to obtain the values of these components.

Note:

If the conforming object calculates more than one potential the sum of these potentials must be equal to the value returned by this method.

- (void) evaluateEnergy

Evalutes the energy of the interaction The result is obtained using energy. Has no effect if the object can't calculate the energy.

- (void) evaluateForces

Evaluates the forces due to the interaction term. Has no effect if the object can't calculate forces.

- (AdMatrix*) forces

Returns the objects force matrix. If usesExternalForceMatrix returns YES then this matrix is not owned by the reciever. Otherwise it is and will be deallocated when the reciever is released or if setExternalForceMatrix: is used. Returns NULL if the object cannot calculate forces.

- (id) initWithSystem:

(id)

system

Initialises the object to operate on system

Reimplemented in AdHarmonicConstraintTerm, AdSelfTerm, AdAmberCGNonbondedTerm, AdGRFNonbondedTerm, AdHbondedTerm, AdPureNonbondedTerm, AdCGNonbondedTerm, AdShiftedNonbondedTerm, AdMainChainTerm, and AdCMAPTerm.

- (NSArray*) potentials

Returns an array containing the names of all the potential energies the custom term can compute.

- (void) setExternalForceMatrix:

(AdMatrix *)

matrix

The object should accumulate forces into matrix instead of using an internal matrix. The cumulative force on each system element is added to the corresponding row in the matrix. If the matrix does not have the correct dimensions i.e. one row for each atom in the system, an exception is raised. Has no effect if the object cannot calculate the forces. Does nothing if matrix is NULL.

Note:

Its is up to the sender to handle the event that matrix is deallocated.

Reimplemented in AdSCAAS.

- (void) setSystem:

(id)

system

Sets the system the object should be calculated on.

- (id) system

Returns the system the object operates on.

- (BOOL) usesExternalForceMatrix

Returns YES if the object writes its forces to an external matrix. NO otherwise.

Reimplemented in AdSCAAS.

- (double) valueForPotential:

(NSString *)

potential

Returns the last calculated energy for potential. Raises an NSInvalidArgumentException if potential is not calculated by the reciever.