|(NSArray *)||- allowedPairs|
|(NSValue *)||- pairList|
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 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 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 subclasses should observe AdSystemContentsDidChangeNotification's from their system and use the handlerDidHandleContentChange: method to notify their delegate. See the method documentation for more.
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
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?
|- (NSArray *) allowedPairs|
Returns the array of allowed pairs
|- (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.
Implemented in AdSimpleListHandler.
|- (double) cutoff|
Returns the cutoff.
|- (id) delegate|
Returns the current delegate
|- (id) initWithSystem:||(id)||aSystem|
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.
|aSystem||An AdSystem or AdInteractionSystem object.|
|anArray||An NSArray of NSIndexSets specifying the allowed pairs.|
|aDouble||The cutoff. Cannot be less than 0. If it is it defaults to 12.|
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.
|- (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.