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

#import <AdunListHandler.h>

Inheritance diagram for AdListHandler:
Inheritance graph
[legend]

List of all members.

Public Member Functions

(id) - initWithSystem:allowedPairs:cutoff:
(void) - createList
(void) - update
(double) - cutoff
(void) - setCutoff:
(void) - setSystem:
(id) - system
(void) - setAllowedPairs:
(NSArray *) - allowedPairs
(NSValue *) - pairList
(int) - numberOfListElements
(void) - setDelegate:
(id) - delegate

Detailed Description

AdListHandler is an abstract class that represents an object that creates and maintains a dynamic linked list of element pairs. The elements are distributed throughout a volume of space and the pairs allowed in the list are restricted by a cutoff condition. Since the positions of the elements can change the pairs meeting the condition can also change. Calling the update (AdListHandler) method of an AdListHandler subclass causes it to recalculate the list.

The problem of finding all the pairs of elements that are seperated by less than a given distance is $O(n^{2})$ if a brute search is used (assuming all pairs are allowed). Since such lists are common in molecular simulations and must be updated relatively frequently $O(n^{2})$ performance is not desirable. Hence there are various algorithms for speeding up the update process and each subclass of AdListHandler encapsulates one of these.

AdListHandler instances can have a delegate who is notified when the list is updated or invalidated. Delegate objects must conform to the AdListHandlerDelegate protocol.

AdListHandler subclasses should observe AdSystemContentsDidChangeNotification's from their system and use the handlerDidHandleContentChange: method to notify their delegate. See the method documentation for more.

Requirements

The position of the elements is given by the matrix returned by coordinates (AdSystem). Each element is assigned an index corresponding to its row in this matrix (starting with 0).

Each element can have an associated NSIndexSet that contains the indexes of the elements it can be paired with. Only elements with higher indexes should be included since pairs with lower index elements should be taken into account in their index sets. In practice AdListHandler objects require an array of these index sets. The first NSIndexSet in the array corresponds to the first element in the coordinate matrix and so on. Hence if an element has no allowed pairs but higher elements do an NSIndexSet still must be present in the array so the correct correspondance is maintained

Todo:

Desired Functionality - ListHandlers should be able to create lists inside or outside the specified cutoff

Desired Functionality - Possibly implement a method that returns a subset of the list matching a certain criteria? Although this would have to be an array and then you would need to create different functions for lists or array

Missing Functionality - Ability to specify no cutoff?


Member Function Documentation

- (NSArray *) allowedPairs

Returns the array of allowed pairs

Returns:
An NSArray of NSIndexSets.
- (void) createList

Creates the list. Does nothing if it has been already called for the current system and array of allowed pairs of it either of these is nil.

If the number of elements in the array returned by allowedPairs is greater than the number of elements in system an NSInternalInconsistencyException is raised.

Implemented in AdSimpleListHandler.

- (double) cutoff

Returns the cutoff.

- (id) delegate

Returns the current delegate

- (id) initWithSystem: (id)  aSystem
allowedPairs: (NSArray*)  anArray
cutoff: (double)  aDouble 

Returns a newly initialised AdListHandler instance that creates and manages a list of the pairs of elements of aSystem that are separated by less than aDouble. The allowed pairs are restricted to those specified by anArray.

Parameters:
aSystemAn AdSystem or AdInteractionSystem object.
anArrayAn NSArray of NSIndexSets specifying the allowed pairs.
aDoubleThe cutoff. Cannot be less than 0. If it is it defaults to 12.
Todo:
Missing functionality - If allowedPairs is nil the object should assume all pairs are allowed.

Implemented in AdCellListHandler.

- (int) numberOfListElements

Returns the number of objects in the linked list. Does not include the start and end elements.

- (NSValue *) pairList

Returns a pointer to the start of the linked list. This pointer may become invalidated e.g. due to setSystem: or setAllowedPairs: being called. Hence the object using this list should also be the AdListHandler objects delegate so it can recieve handlerDidInvalidateList: messages. If the list has not been created this method will return a NULL pointer.

- (void) setAllowedPairs: (NSArray*)  anArray

Sets the allowed pairs. The previous list is destroyed and a new list must be created by calling createList. The receivers delegate will receive a handlerDidInvalidateList: message.

- (void) setCutoff: (double)  aValue

Sets the cutoff used to aValue. The list is not updated until update is called. If cutoff is less than 0 an NSInvalidArgumentException is raised.

- (void) setDelegate: (id)  anObject

Sets the objects delegate to delegate. delegate must conform to the AdListHandlerDelegate protocol. If not an NSInvalidArgumentException is raised. anObject is not retained.

- (void) setSystem: (id)  aSystem

Sets the system to aSystem. The previous list is destroyed and a new list must be created by calling createList. The receivers delegate will receive a handlerDidInvalidateList: message.

The receiver observes AdSystemContentsDidChangeNotification from aSystem. On receiving such a notification the AdListHandler object invalidates its list and sends a handlerDidInvalidateList: message to its delegate. createList must be called to recreate the list.

- (id) system

Returns the system.

Returns:
An AdSystem or AdInteractionSystem instance.
- (void) update

Updates the lists removing pairs who have moved outside the cutoff and adding pairs that have moved inside. Has no effect if createList has not been called once with the current system and the current array of allowed pairs. In this case the delegate does not receive an handlerDidUpdateList: message.