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

#import <AdunTrajectory.h>

Inherits <AdTrajectoryMethods>.

Collaboration diagram for AdMutableTrajectory:
Collaboration graph
[legend]

List of all members.

Public Member Functions

(id) - initWithLocation:error:
(id) - initWithLocation:systems:forceFields:iterationHeader:error:
(void) - setForceFields:
(void) - openFrame:
(BOOL) - isOpenFrame
(void) - closeFrame
(int) - lastFrame
(unsigned int) - lastEnergyCheckpoint
(unsigned int) - lastTrajectoryCheckpoint
(unsigned int) - lastTopologyCheckpoint
(NSNumber *) - lastIterationNumber
(void) - addTopologyCheckpoint
(void) - addTopologyCheckpointForSystem:
(void) - addTrajectoryCheckpoint
(void) - addEnergyCheckpoint
(void) - rollBackToFrame:
(void) - synchToStore
(id) - dataStorage
- Public Member Functions inherited from
(AdSystemCollection *) - systemCollection

Static Public Member Functions

(id) + trajectoryFromLocation:error:

Detailed Description

Descendant of AdTrajectory which adds the ability to modify the trajectory contents. The initialisation of this method depends on whether the trajectory exists at the time of creation or not. Note: Although not listed here AdMutableTrajectory instances respond to all AdTrajectory methods.

Recording Energy Data

When adding an energy checkpoint AdMutableTrajectory instances retrieve energy data for each system in their systemCollection() from a provided AdForceFieldCollection instance. This AdForceFieldCollection object must be provided on instantiation for new trajectories or after instantiation when appending (see Appending Energy Data to a Trajectory).

To obtain the energy data, AdMutableTrajectory instances use the method forceFieldsForSystem: (AdForceFieldCollection) passing the system objects in their systemCollection(). Therefore, recording energies requires that the AdForceFieldCollection must contain a force-field operating on the same AdSystem or AdInteractionSystem instances in the AdSystemCollection the trajectory uses. N.B. At the moment only one force-field per system is supported (the first returned by forceFieldsForSystem: (AdForceFieldCollection))

If the AdForceFieldCollection instance contains force-fields operating on other systems, these are ignored.

If the AdForceFieldCollection instance provided on initialisation does not contain a force-field for a given system no energy can ever be recorded for that system i.e. This cannot be undone by adding a force-field at a later time. If a force-field is removed from the force-field collection after initialisation then values of potential-energy terms in energy checkpoints for the corresponding system will be set to zero. If the force-field is later re-added, energy checkpoints will be resumed as normal.

Adding New Force-Field Terms

If a force-field in the force-field collection (which is operating on a system stored in the trajectory) is modified e.g. by adding terms, the potentials corresponding to the new-terms will be recorded. Previous frames where the potentials did not exist will be extended with entries for this terms filled with zeros.

Appending Energy Data to a Trajectory

If you want to append energy data to a trajectory the most crucial step is to create an appropriate AdForceFieldCollection instance. Stored trajectories do not record information about force-fields, so it is up to the user to ensure consistency.

In order to record new energy information for the systems stored in the trajectory the AdForceFieldCollection instance you create must contain force-fields operating on the AdSystem or AdInteractionSystem instances in the system collection returned by AdMutableTrajectory::systemCollection() (see Recording Energy Data for an explanation of why this is).

One consequence of this is that you cannot pass an AdForceFieldCollection on instantiating an AdMutableTrajectory for appending. This is simply because there is no way it can be operating on the correct AdSystem/AdInteractionSystem instances. The correct procedure is given by the following code snippet

//Access an existing trajectory and retreive the AdSystemCollection
//it stores information for.
trajectory = [AdMutableTrajectory trajectoryFromLocation: somePath];
systemCollection = [trajectory systemCollection];
//Create force-field using the systems in systemCollection
....
[trajectory setForceFields: forceFieldCollection];

If you want to add information for new systems or use additional systems in the force-field you should create a new AdMutableTrajectory instance.


Member Function Documentation

- (void) addEnergyCheckpoint

Adds a row detailing the current energies to each systems state matrix.

- (void) addTopologyCheckpoint

Adds a checkpoint of the topology of all the systems in the system collection.

- (void) addTopologyCheckpointForSystem: (id)  aSystem

Adds a checkpoint of the topology of system.

- (void) addTrajectoryCheckpoint

Adds a checkpoint of the state of all the systems in the system collection. What exactly is stored depends on the value of each systems capture mask (see captureMask (AdMemento-p))

- (void) closeFrame

Closes the current frame for writing.

Note:
If no frame is open then this method does nothing.
- (id) dataStorage

Returns the data storage instance used by the object to access the simulation data.

- (id) initWithLocation: (NSString*)  path
error: (NSError**)  error 

Returns an AdMutableTrajectory initialised to append data to location. If no trajectory exists at location an NSInvalidArgumentException is raised. If there is a problem accessing the data at location error is set with an NSError object explaining the problem.

- (id) initWithLocation: (id)  path
systems: (AdSystemCollection*)  aSystemCollection
forceFields: (AdForceFieldCollection*)  aForceFieldCollection
iterationHeader: (NSString*)  aString
error: (NSError**)  error 

Designated initialiser. Initialises an AdMutableTrajectory object which can write data to aDataStore. The parameters to pass depend on whether a trajectory exists at path.

Parameters:
pathA path to a directory. If the directory exists the receiver is initialied to append to its contents (append mode). If not a new trajectory directory is created at path which the receiver can be used to write to (write mode).
aSystemCollectionAn AdSystemCollection instance containing the systems whose data will be recorded by the returned AdMutableTrajectory instance. This is required for write mode trajectories and must be nil for append mode trajectories. Violation of either requirement leads to an NSInvalidArgumentException being raised.
aStringSets the header of the column used to identify frames. Only used in write mode. Passing a value for this in append mode raises an NSInvalidArgumentException.
aForceFieldCollectionThe force-fields used to record energies. This is required for write mode trajectories and must be nil for append mode trajectories. Violation of these conditions results in an NSInvalidArgumentException. In append mode set after instantiation using setForceFields: (see class documentation for more).
Note:
If you are appending to an existing trajectory it is simpler to use initWithLocation:error:.

< Used fo AdSimulationStorageAppendMode

- (BOOL) isOpenFrame

Returns YES if a frame is currently open for writing. NO otherwise.

- (unsigned int) lastEnergyCheckpoint

Returns the frame that contains the last energy checkpoint

- (int) lastFrame

Returns the number of the last opened frame. Returns -1 if no frame has been opened.

- (NSNumber *) lastIterationNumber

Returns the iteration number supplied for the last frame.

- (unsigned int) lastTopologyCheckpoint

Returns the frame that contains the last topology checkpoint

- (unsigned int) lastTrajectoryCheckpoint

Returns the frame that contains the last trajectory checkpoint

- (void) openFrame: (NSNumber*)  iterationNumber

Opens a new frame for writing. Increments the frame count. iterationNumber will be used as the value for the column defined by iterationHeader in the state matrices for any energy checkpoints. You must open a frame in order to write checkpoints.

- (void) rollBackToFrame: (unsigned int)  value

Deletes all information stored since frame value. Raises an NSRangeException if value is greater than the number of frames.

- (void) setForceFields: (AdForceFieldCollection*)  aForceFieldCollection

Sets the force-fields used to record energies in each frame. See Recording Energy Data for a detailed information on how this AdForceFieldCollection is used.

Note:
Although this method makes it possible to change the force-fields used to record energies this must be done with care. No information is recorded on the force-fields used in each frame. Therefore, unless this information is recorded externally, it would be very difficult to know when/if a different force-field was used to record energies.
- (void) synchToStore

Writes all data held in memory to the store.

+ (id) trajectoryFromLocation: (NSString*)  location
error: (NSError**)  error 

Returns an autoreleased AdMutableTrajectory initialised to append data to location. If no trajectory exists at location an NSInvalidArgumentException is raised. If there is a problem accessing the data at location error is set with an NSError object explaining the problem.