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

#import <AdunSystem.h>

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

List of all members.

Public Member Functions

(id) - initWithDataSource:
(id) - initWithDataSource:name:initialTemperature:seed:centre:removeTranslationalDOF:
(id) - initWithDictionary:
(void) - removeTranslationalDegreesOfFreedom
(void) - setCoordinates:
(void) - setVelocities:
(void) - reinitialiseVelocities
(void) - moveCentreOfMassToOrigin
(unsigned int) - seed
(void) - setSeed:
(NSArray *) - centre
(void) - setCentre:
(Vector3D- centreAsVector
(void) - centreOnPoint:
(void) - centreOnElement:
(double) - fitToConfiguration:usingSelection:
(double) - fitToConfiguration:
(NSString *) - systemName
(unsigned int) - numberOfElements
(double) - kineticEnergy
(double) - temperature
(unsigned int) - degreesOfFreedom
(AdMatrix *) - coordinates
(AdMatrix *) - velocities
(NSArray *) - elementMasses
(AdDataMatrix *) - elementProperties
(NSArray *) - elementTypes
(id) - dataSource
(void) - setDataSource:
(void) - reloadData
(void) - updateDataSourceConfiguration
(NSArray *) - availableInteractions
(AdDataMatrix *) - groupsForInteraction:
(AdDataMatrix *) - parametersForInteraction:
(NSArray *) - indexSetArrayForCategory:
(void) - registerInteractionSystem:
(void) - removeInteractionSystem:
(NSArray *) - interactionSystems
(BOOL) - validateMemento:
(void) - setCoordinatesOfAtomsInResidue:usingPDBResidue:ignoreMissingAtoms:
(void) - setCoordinatesOfAtomsInChain:usingPDBChain:startResidueIndex:matchMask:
(void) - setCoordinatesFromPDBStructure:usingChains:residueStartIndexes:matchMask:
(void) - setCoordinatesFromPDBStructure:
- Public Member Functions inherited from
(int) - captureMask
(void) - setCaptureMask:
(void) - returnToState:
(id) - captureState
- Public Member Functions inherited from
(BOOL) - allowsDirectModificationOfMatrix:
(BOOL) - matrixIsAvailableForModification:
(void) - object:willBeginWritingToMatrix:
(void) - object:didFinishWritingToMatrix:

Static Public Member Functions

(id) + systemWithDataSource:

Detailed Description

An AdSystem object represents a set of elements whose configuration can vary.

Two types of data are associated with the elements - static and variable. The variable data includes their coordinates & velocities. This data is stored by the AdSystem object and it provides methods to change and manipulate it.

The static data includes the topology and properties of the elements. AdSystem instances do not store this information themselves but retrieve it from a data source. The AdSystemDataSource protocol declares the methods used by AdSystem objects to access the contents of their data source.

AdSystem conforms to NSCoding but only supports keyed coding. The AdSystemScriptingExtensions category contains extra methods useful when using AdSystem from a scripting environment.


Principal Attributes


Mementos

Modification of an AdSystem objects variable data changes its state. Through the AdMemento protocol an AdSystem instances state can be fully or partially recorded and the result can be used at any time to return it (or another AdSystem instance) to the recorded state.

Mementos created by AdSystem can optionally contain the current coordinates and velocities. You set what a memento will contain using the setCaptureMask: (AdMemento-p) method. mask is a bitwise OR of the values defined by the AdSystemMementoValue enum.

For example, if you wish to record coordinates and velocities

int mask;
[system setCaptureMask: mask];

By default AdSystem objects only record coordinates in their mementos. You can get the current mask is using captureMask (AdMemento-p). A bitwise AND of the returned value and an option will be 1 if the option is set and 0 otherwise.

mask = [system captureMask];
//The system is recording coordinates in its mementos
else
//The system isn't record coordinated in its mementos

An AdSystem memento can only be used as long as the systems data source contains the same number of elements as when the memento was captured e.g. There are 200 elements in a system and a memento is recorded. If later some elements are removed from the system the memento cannot be used to return it to the previous state.


Notifications

AdSystem instances send the following notification after reloading their data

The notification object is the system and the userInfo is nil. Its important to note that this notification implies all the AdMatrix structs returned by the sender have become invalid. Hence objects should not retain references to these structures since methods that use such references may be called in the period between when the notification is sent and the object receives it e.g. by other objects that receive the notfication first.


Updating Interaction Systems

AdInteractionSystem instances need to know when the coordinates of their consituent AdSystem objects change so they can update their coordinate matrices. This necessitates that AdSystem instances maintain references to AdInteractionSystem objects that contain them. However, in order to avoid circular references, they must be weak-references.

This is handled in the following way. On creation an AdInteractionSystem object reigisters with its systems by sending registerInteractionSystem: (AdSystem) to each. On deallocation it notifies them by sending removeInteractionSystem: (AdSystem) to each. Each time setCoordinates: (AdSystem) is called, AdSystem objects notify the registered AdInteractionSystem objects using systemDidUpdateCoordinates: (AdSystemCoordinatesObserving-p)

Reloading Data

Often you will modify the contents of a system, for example by changing a property or interaction paramater, and wish all other objects using the system to update themselves accordingly e.g. force-fields. This complex process is achieved simply by calling reloadData (AdSystem) on the system. This causes an AdSystemContentsDidChangeNotification to be broadcast which is observed by all interested objects.

However there are a couple of caveats that must be noted when reloading.

Firstly when you call reloadData (AdSystem) the element coordinates will be set to the values returned by the systems data source (via AdDataSource::elementConfiguration). However AdSystem objects do not modify the data source configuration unless updateDataSourceConfiguration (AdSystem) is called. Therefore you must call this method before calling reloadData (AdSystem) - if you don't the systems coordinates will be reset.

Secondly updateDataSourceConfiguration (AdSystem) requires that the data source is mutable i.e. An instance of AdMutableDataSource. You must make sure the data source is mutable, for example by creating a mutable copy and using it, if you want to use updateDataSourceConfiguration (AdSystem)

Finally you should know how the various objects react to reloading data. For example a reload will cause AdCellListHandler to rebuild the list of nonbonded interactions which you may not want. Different classes will have different methods for customising their behaviour on receiving AdSystemContentsDidChangeNotification.

In AdunKernel Framework the following objects observe AdSystemContentsDidChangeNotification from AdSystem instances they work with.

AdNonbondedTerm subclasses are a special case as they learn about the reload from the AdListHandler instances they use. Note: AdContainerDataSource does not update itself if systems they contains change. This is important if you've radically changed the configuration of these contained systems. See AdContainerDataSource for more.

Todo:

Internal - Change notification defines to extern variables?

Missing docs - Information required to be in the data source e.g. masses? coordinates? element type?


Member Function Documentation

- (NSArray *) availableInteractions

Returns an array containing the names of the interactions that are present in the system. Returns nil if no data source has been set.

- (NSArray *) centre

Returns the centre of mass of the system as an NSArray of NSNumbers.

- (Vector3D) centreAsVector

Returns the centre of mass of the system as a Vector3D struct

- (void) centreOnElement: (unsigned int)  elementIndex

Moves the element identified by index to the origin

- (void) centreOnPoint: (double*)  point

As setCentre: but passing the coordinates as an c-array of doubles.

- (AdMatrix *) coordinates

Returns the configuration of the elements of the system as an AdMatrix structure. If no data source has been set this method returns NULL. The returned matrix is owned by the AdSystem object and will be freed when its released.

- (id) dataSource

Returns the systems data source

- (unsigned int) degreesOfFreedom

Returns the system degrees of freedom. If no data source has been set then this is -1.

- (NSArray *) elementMasses

Returns the masses of elements in the system.

- (AdDataMatrix *) elementProperties

Returns the properties of the elements in the system.

- (NSArray *) elementTypes

Returns the types of the elements in the system as given by the "ElementType" column of the data source element properties matrix.

- (double) fitToConfiguration: (AdDataMatrix*)  configuration

As fitToConfiguration:usingSelection: except passing nil for selection. Note the center of mass of the receiver is moved to the point defined by the selected elements.

- (double) fitToConfiguration: (AdDataMatrix*)  configuration
usingSelection: (AdElementSelection*)  selection 

Fits the coordinates of the receiver to the configuration defined by configuration using the kabsch method. The matrix configuration must represent a different configuration of the same system the receiver represents. That is the i^th row in configuration corresponds to the same element as the i^th row of the matrix returned by elementConfiguration().

If selection is not nil only the elements defined by it are used to do the fit e.g. all C-Alphas.

Note the center of mass of the receiver is moved to the point defined by configuration.

- (AdDataMatrix *) groupsForInteraction: (NSString*)  interaction

Returns the group matrix for the interaction interaction. If there is no group matrix and the interaction exists this method returns nil. Otherwise an NSInvalidArgumentException is raised. If no data source has been set this method returns nil.

- (NSArray *) indexSetArrayForCategory: (NSString*)  category

Description forthcomming

- (id) initWithDataSource: (id)  aDataSource

As initWithDataSource:name:initialTemperature:seed:centre:removeTranslationalDOF: with nil for name and centre, 300 for initialTemperature, 1 for seed and YES for removeDOF.

- (id) initWithDataSource: (id)  aDataSource
name: (NSString*)  name
initialTemperature: (double)  temperature
seed: (int)  rngSeed
centre: (NSArray*)  point
removeTranslationalDOF: (BOOL)  value 

Creates a new system using aDataSource as a data source.

Parameters:
aDataSourceAn object that conforms to the AdSystemDataSource protocol. If not an NSInvalidArgumentException is raised. Cannot be nil. name The name to be associated with the system. If nil this defaults to the data source name.
temperatureThe initial velocities of the system are drawn from a Maxwell-Boltzmann distribution at this temperature.
rngSeedValue used for initialising internal random number generators.
pointA NSArray specifying a point in cartesian space where the centre of mass of the system will be placed. If nil the centre of mass of the system is defined by the configuration supplied by the systems data source.
valueA boolean value. YES indicates that the AdSystem object should remove the translational degrees of freedom from the system after it generates its initial velocities. Has no effect if dataSource is nil.
- (id) initWithDictionary: (NSDictionary*)  aDict

Calls the designated initialiser with the values in aDict. The keys of aDict are defined by the names of each of the arguments in the designated initialiser i.e. dataSource, name, initialTemperature, seed, centre & removeTranslationalDOF. If a key is not present nil is passed for the corresponding argument in the designated initialiser.

- (NSArray *) interactionSystems

Returns the AdInteractionSystem objects the receiver is part of.

- (double) kineticEnergy

Returns the current kinetic energy of the system in simulation units. If no data source has been set this method returns -1.

- (void) moveCentreOfMassToOrigin

Moves the center of mass of the system to the origin. Same as setCentre: passing (0,0,0). No effect if no data source has been set.

- (unsigned int) numberOfElements

Returns the numner of elements in the system.

- (AdDataMatrix *) parametersForInteraction: (NSString*)  interaction

Returns the parameters matrix for the interaction interaction. If there are no parameters and the interaction exists this method returns nil. Otherwise an NSInvalidArgumentException is raised. If no data source has been set this method returns nil.

- (void) registerInteractionSystem: (AdInteractionSystem*)  anInteractionSystem

Sent by AdInteractionSystem instances to their constituent AdSystem objects on initialisation.

- (void) reinitialiseVelocities

Reinitialise the velocities drawining new values from a Maxwell-Boltzmann distribution at the current target temperature.

- (void) reloadData

Reloads the systems data source. This causes all AdMatrix references previously returned by the object to become invalid. When the data has been reloaded a #AdSystemContentsDidChangeNotification is sent. Reloading the data also has the effect of reinitialising the element velocities.

- (void) removeInteractionSystem: (AdInteractionSystem*)  anInteractionSystem

Sent by AdInteractionSystem instances to their constituent AdSystem objects on deallocation.

- (void) removeTranslationalDegreesOfFreedom

Removes the translational degress of freedom of the system. Does nothing if the systems status is passive.

Note:
Due to the discrete nature of a simulation it is possible that the translational deegres of freedom may reappear during a simulation.
- (unsigned int) seed

Returns the seed used to initialise the RNG for generating velocities

- (void) setCentre: (NSArray*)  point

Moves the center of mass of the system to the coordinates contained in the array point.

Parameters:
pointAn NSArray of NSNumbers.
- (void) setCoordinates: (AdMatrix*)  aMatrix

Copies the values in matrix into the systems coordinates matrix.

- (void) setCoordinatesFromPDBStructure: (MTStructure *)  structure

As setCoordinatesFromPDBStructure:usingChains:residueStartIndexes:matchMask: passing nil for chainIds and startIndexes and 0 for mask

- (void) setCoordinatesFromPDBStructure: (MTStructure *)  structure
usingChains: (NSArray *)  chainIds
residueStartIndexes: (NSArray *)  startIndexes
matchMask: (int)  mask 

Sets the coordinates of the atoms in the receiver using the specified chains in an MTStructure object. The ith chain in chainIds is matched with the ith chain in the receiver. Then setCoordinatesOfAtomsInChain:usingPDBChain:startResidueIndex:matchMask: is called for each pair of chains.

If chainIds is nil all chains in the structure are used. If startIndexes is nil the first residue in each chain in structure is used. The number of entries in chainIds and startIndexes must be the same, otherwise an NSInvalidArgumentException is raised.

If any exception is raised the coordinates in the receiver are not changed.

Match Mask

The matching behaviour is controlled by the mask parameter. This is a bitwise OR of 0 or more of the values of the AdSystemPDBMatchingBehaviourEnum. These values are AdSystemIgnoreMissingResidues and AdSystemIgnoreMissingAtoms. When one of these values is passed in the bitwise OR it is said to be 'set'. Otherwise it is unset.

For example the following sets both values - this (more or less) means missing residues and missing atoms will be ignored.

[aSystem setCoordinatesFromPDBStructure: structure 
        usingChains: nil
        startIndexes: nil
        matchMask: AdSystemIgnoreMissingResidues | AdSystemIgnoreMissingAtoms];

However you should check the documentation of the other methods in this category to understand exactly the effect of settin/not-setting these values

Chain Matching Rules

If there are more chains in the receiver than in the pdb an NSInvalidArgumentException will be raised if AdSystemIgnoreMissingResidues is not set.

The order of chains in the receiver is as they appear in the dataSource.

- (void) setCoordinatesOfAtomsInChain: (NSString *)  chainId
usingPDBChain: (MTChain *)  pdbChain
startResidueIndex: (unsigned int)  startResidueIndex
matchMask: (unsigned int)  mask 

Sets the coordinates of the atoms in chain chainId using the information in the MTChain object pdbChain.

Parameters:
chainIdAn NSString object idenfifying the chain in the receiver containing the atoms whose coordinates are to be set
pdbChainAn MTChain instance representing data for a specific chain in a PDB file
startResidueIndexThe residue in pdbChain where the matching should start
maskA bitwise OR of AdSystemPDBMatchingBehaviourEnum values - see Match Mask

Details

chainId is one of the values in the Chain column of the groupProperties (AdSystemDataSource-p) matrix of the receivers dataSource. It is usually an integer (although here it is passed as a string).

Note:
chainId is not compared to the id of the passed MTChain instance.

startResidueIndex specifies which residue in pdbChain should be paired with the first residue of chainId in the receiver. N.B. This is NOT the value of the 'Residue Number' field in the pdb. It is the position of the residue in the chain, counting the first residue as position 0.

value indicates how the residues and atoms should be matched. See the Match Mask section in setCoordinatesFromPDBStructure:usingChains:residueStartIndexes:matchMask:

Residue Matching Rules

If there are less residues in pdbChain then in the receiver the behaviour depends on the match mask. If AdSystemIgnoreMissingResidues was set, the method pairs residues until the pdbChain residues are exhausted. Otherwise it returns doing nothing.

Residues are paired starting with the first in the given chain in the receiver and the residue in pdbChain specifed by startResidueIndex. If the names (e.g. amino-acid types) of the residues don't match, the behaviour again depends on the match mask. If AdSystemIgnoreMissingResidues is set, it is assumed the pair for the system residue is missing. In this case no exception is raised, however no further pairs are made and the method exits. This essentially means missing residues are not tolerated in the middle of a chain. If AdSystemIgnoreMissingResidues is not set an NSInvalidArgumentException is raised.

If AdSystemIgnoreMissingAtoms is set, YES is passed as the value of the ignoreMissingAtoms parameter of setCoordinatesofAtomsInResidue:usingPDBResidue:ignoreMissingAtoms:(). Otherwise NO is passed.

Note: If any exception is raised no coordinates are changed.

- (void) setCoordinatesOfAtomsInResidue: (unsigned int)  residueIndex
usingPDBResidue: (MTResidue *)  pdbResidue
ignoreMissingAtoms: (BOOL)  value 

Sets the coordinates of the atoms in residue residueIndex using the information in the MTResidue object pdbResidue.

Parameters:
residueIndexThe index of the residue in the receiver containing the atoms whose coordinates are to be set
pdbResidueAn MTResidue instance representing data for a specific residue in a PDB file
valueA BOOL determining how atoms are matched - see Atom Matching Rules

Details

Here the term "residue" refers to the groups defined by the the groupProperties (AdSystemDataSource-p) matrix of the receivers dataSource. The value of residueIndex refers to the relevant row in this matrix.

Note:
The name (e.g. ALA) of the residue is not compared to the name of the specified in the receiver.

Atoms in the receiver are paired to atoms in pdbResidue by name. In the case of the receiver an atoms name is the value of the PDBName column for the row corresponding to the atom in the receivers elementProperties matrix. In the case of the MTResidue object it is the value returned by MTAtom::name().

Atom Matching Rules

If an atom in the reciever has no match in pdbResidue the resulting behaviour depends on the value parameter. If value is NO then an NSInvalidArgumentException is raised. Otherwise the problem is ignored and the atom retains its original coordiantes.

Atoms in pdbResidue which have no pairs in the receiver are always ignored. If an atom in the receiver matches more than one atom in pdbResidue an NSInvalidArgumentException is raised

If any exception is raised the coordinates of all atoms remain unchanged

- (void) setDataSource: (id)  dataSource

Sets the systems data source to be anObject. Note that this will not change the receivers name as set on initialisation as this is used by other classes to identify the object. Hence this method is mainly for replacing a immutable data source with a mutable copy.

- (void) setSeed: (unsigned int)  anInt

Sets the seed used to initialise the RNG for generating velocities

- (void) setVelocities: (AdMatrix*)  aMatrix

Copies the values in matrix into the systems velocties matrix.

- (NSString*) systemName

Returns the name of the system. This is the same as the name of the systems data source. If no data source has been set then this method returns nil.

+ (id) systemWithDataSource: (id)  aDataSource

Class method version of initWithDataSource:

- (double) temperature

Returns the current temperature of the system in simulation units. If no data source has been set this method returns -1.

- (void) updateDataSourceConfiguration

Updates the element configuration of the data source with the system current configuration. The data source must respond to setElementConfiguration. If it does not this method does nothing. You should usually call this method before modifying the data source.

Note:
If you add/remove elements from the data source and call this method before calling reloadData an exception will be raised.
- (BOOL) validateMemento: (id)  aMemento
Todo:
Partial Implementation - Always returns YES.

Reimplemented from <AdMemento>.

- (AdMatrix *) velocities

Returns the velocities of the elements of the system as an AdMatrix structure. If no data source has been set this method returns NULL. The returned matrix is owned by the AdSystem object and will be freed when its released.