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

#import <AdunSimulationData.h>

Inheritance diagram for AdSimulationData:
Inheritance graph
Collaboration diagram for AdSimulationData:
Collaboration graph

List of all members.

Public Member Functions

(id) - initWithName:location:
(id) - initWithName:location:useIdentification:
(NSURL *) - location
(NSString *) - dataPath
(NSURL *) - dataURL
(void) - update
(BOOL) - archive
(BOOL) - archiveToDirectory:
(unsigned int) - count
(NSArray *) - trajectories
(id) - trajectoryWithName:
(id) - trajectoryAtIndex:
(id) - activeTrajectory
(id) - addTrajectoryForSystems:withForceFields:
(id) - addTrajectoryForSystems:withForceFields:name:
(void) - switchToTrajectory:
(void) - switchToFirst
(unsigned int) - indexOfTrajectory:
(BOOL) - moveToLocation:useIdentification:error:
- Public Member Functions inherited from AdModelObject
(BOOL) - archiveToFile:
(NSString *) - identification
(NSString *) - archivePathExtension
(id) - creator
(id) - created
(NSString *) - name
(NSString *) - type
(id) - keywords
(NSDictionary *) - reference
(NSString *) - database
(NSString *) - schema
(NSDictionary *) - properties
(NSDictionary *) - systemMetadata
(NSDictionary *) - userMetadata
(NSDictionary *) - metadata
(NSDictionary *) - combinedMetadata
(NSDictionary *) - allMetadata
(id) - valueForMetadataKey:
(void) - setValue:forMetadataKey:
(void) - setValue:forMetadataKey:inDomain:
(void) - removeMetadataKey:
(AdMetadataDomain- domainForMetadataKey:
(void) - setDomain:forMetadataKey:
(void) - updateMetadata:
(void) - updateMetadata:inDomains:
(id) - valueForVolatileMetadataKey:
(void) - setValue:forVolatileMetadataKey:
(void) - removeVolatileMetadataKey:
(NSArray *) - inputReferencesToObjectsOfClass:
(NSArray *) - inputReferences
(void) - addInputReference:
(void) - addInputReferenceToObject:
(void) - addInputReferenceToObjectWithID:ofType:
(void) - removeInputReferenceToObject:
(void) - removeInputReferenceToObjectWithID:ofType:
(NSArray *) - outputReferencesToObjectsOfClass:
(NSArray *) - outputReferences
(void) - addOutputReferenceToObject:
(void) - addOutputReferenceToObjectWithID:ofType:
(void) - removeOutputReferenceToObject:
(void) - removeOutputReferenceToObjectWithID:ofType:
(void) - removeOutputReferenceToObjectWithID:
(void) - removeAllOutputReferences
(void) - copyMetadataInDomains:fromObject:
(void) - copyInputReferencesFromObject:
(void) - copyOutputReferencesFromObject:
- Public Member Functions inherited from
(AdSystemCollection *) - systemCollection

Static Public Member Functions

(id) + unarchiveFromLocation:
(id) + simulationDataWithName:location:
(BOOL) + isSimulationDataArchive:
- Static Public Member Functions inherited from AdModelObject
(id) + unarchiveFromFile:

Detailed Description

AdSimulationData instances represent the output of an Adun simulation (more generally, a set of AdTrajectory objects). Each instance is associated with a specific directory (essentially the simulation output "file") where the simulation data is written and stored - The directory is specified on instantiation. The directory can exist on the local filesystem or on a remote ftp/http server. Each run of AdunCore has an associated AdSimulationData instance which is used to store the data generated during the program. However AdSimulationData instances can also be created programatically if desired.

Editing Simulation Contents

AdSimulationData provides methods for creating the output directory, accessing it, and adding to its contents. However these can only be used if the location of the underlygin data directory is on the local file-system.

Archiving and Unarchiving

Like any AdModelObject, AdSimulationData instances can be "unarchived" at a later time using the unarchiveFromFile: method of AdModelObject. Note in this case "File" will be a directory path (see below). Archived AdSimulationData instances residing on a remote http/ftp server can also be unarchived using unarchiveFromLocation: (AdSimulationData) and passing an URL specifing the location of the simulation data directory

Only AdSimulationData objects whose data directories are located on the local file-system can be archived. In addition to archive AdSimulationData objects do not directly use NSKeyedArchiver (e.g. via archiveRootObject:toFile:()). Doing so will only archive the simulations metadata as the simulation data is in other files in the data directory. Instead use the instances archive (AdSimulationData) method. This ensures that the object is written to the correct location (the path returned by dataPath (AdSimulationData)) with the correct name. The path returned by dataPath (AdSimulationData) is also what is passed to unarchiveFromFile: (AdModelObject) to recreate the object.


AdSimulationData objects contain at least one, and up to any number, of AdTrajectory (or AdMutableTrajectory) objects. These can be added as AdTrajectory or AdMutableTrajectory objects. The methods for accessing these object are very similar to those of NSArray except using 'trajectory' instead of 'object' e.g. trajectoryAtIndex: (AdSimulationData) instead of objectAtIndex:(). AdSimulationData instances consider AdMutableTrajectory and AdTrajectory objects that access the same location identical. (That is location (AdTrajectory) returns the same directory). Unlike NSArray, AdSimulationData cannot contain duplicates of AdTrajectory objects (as determined by the above criteria).

On unarchiving an AdSimulationData instance the trajectories are unarchived as AdMutableTrajectory objects if the simulation data is on local file-system otherwised they are unarchived as AdTrajectory objects.

Since AdSimulationData determines similarity of AdTrajectory object using the value location (AdTrajectory), methods like indexOfTrajectory: (AdSimulationData) will return the same value regardless of the mutablity of the passed trajectory.

Each trajectory in the receiver has an associated name providing dictionary like access to them.

Active Trajectory

AdSimulationData is polymorphic to many of the methods of AdTrajectory. The trajectory accessed via these methods is called the active trajectory and is the first by default. This can be changed using the switchToTrajectory: (AdSimulationData) method.

Distributed Objects

Since most of an AdSimulationData instances data resides on-disk it makes no sense to send a copy of the class to a remote machine. (In that case the remote copy will think its data is on the remote machine). Hence AdSimulationData instances are always sent byref. This overrides the default AdModelObject behaviour.

Parallel Runs

AdSimulationData can be used in parallel. In this case each trajectory created by a parallel processes is stored in the same simulation directory.

However there are a few things that must be kept in mind.

It is important to note that all nodes can see and manipulate all trajectories that are present when the data is first read. In this case care is requried since there is no protection against concurrent write attempts to such trajectories.

When AdunCore is run in parallel it can use the above method to store the mulitple trajectories. In the case of restarting a parallel run with such simulation data AdunCore does the following by default

This behaviour can be turned of. In this case a controller must take over assigning trajectories to nodes. Otherwise all nodes will attempt to write to the same trajectory.

Member Function Documentation

- (id) activeTrajectory

Returns the currently active trajecotry

- (id) addTrajectoryForSystems: (AdSystemCollection*)  systems
withForceFields: (AdForceFieldCollection*)  forceFields 

As addTrajectoryForSystems:withForceFields:name: passing 'Trajectoryd' for name where d is the index of the trajectory in the receiver.

- (id) addTrajectoryForSystems: (AdSystemCollection*)  systems
withForceFields: (AdForceFieldCollection*)  forceFields
name: (NSString*)  name 

Creates a new AdMutableTrajectory object for systems and forceFields. The name of the trajectory is given by name.

- (BOOL) archive

Saves the current state of the simulation data to the simulation directory. This method causes synchToStore (AdMutableTrajectory): to be called on any AdMutableTrajectory objects contained by the receiver.

You should always use this method to archive an AdSimulationData instance.
- (BOOL) archiveToDirectory: (NSString*)  directory

Overrides AdModelObject archiveToDirectory:. This method simple calls archive - the directory location is ignored

Implements AdModelObject.

- (unsigned int) count

Returns the number of trajectories contained in the receiver.

- (NSString*) dataPath

Returns the path component of the URL returned by dataURL. If dataURL returns a file-url then this path is a valid file-system path

- (NSURL*) dataURL

Returns an URL identifying where the simulation is located. This can be a file URL or a http/ftp URL.

- (unsigned int) indexOfTrajectory: (AdTrajectory*)  aTrajectory

Returns the index of aTrajectory in the receiver. This is determined by comparing the location of aTrajecotry to that accessed by each AdTrajectory object contained in the receiver (i.e. the return value of location (AdTrajectory)). Thus the object at the returned index may be of a different mutability than aTrajectory. Returns NSNotFound if no simulation accessing the same location is in the receiver.

- (id) initWithName: (NSString*)  name
location: (NSString*)  path 

As initWithName:location:useIdentification passing NO for identification.

- (id) initWithName: (NSString*)  name
location: (NSString*)  path
useIdentification: (BOOL)  value 

Creates a new AdSimulationData instance called name in the directory given by path. The name of the created directory depends on the useIdentification: flag. If this is NO it will be name.adsim, if YES it will be the objects unique ID appended by adsim.

If a directory already exists with this name this method deallocs the receiver and returns a new AdSimulationData instance initalised using unarchiveFromFile: (AdModelObject).
+ (BOOL) isSimulationDataArchive: (NSString*)  filename

Returns true if the location given by filename is a simulation data archive. (Either new or old).

- (NSURL *) location

Returns the URL of the directory containing the data directory the receiver represents.

- (BOOL) moveToLocation: (NSString*)  aDirectory
useIdentification: (BOOL)  useIdentification
error: (NSError**)  error 

Moves the receivers data directory to the directory location. If useIdentification is YES the data directory will be renamed to the result of identification:(), otherwise the current name is kept. Return YES if the move succeeded, NO otherwise. If the move fails and error points to an NSError object it contains information on the failure on return.

+ (id) simulationDataWithName: (NSString*)  name
location: (NSString*)  path 

Class method. As initWithName:location: returning an autoreleased object

- (void) switchToFirst

Makes the first object in the receiver the active trajectory.

- (void) switchToTrajectory: (unsigned int)  index

Makes the trajectory at index the active trajectory (see class documentation). Raises an NSRangeException if index is beyond the range of the receiver.

- (NSArray*) trajectories

Returns an NSArray object containing all the trajectories in the receiver.

- (id) trajectoryAtIndex: (unsigned int)  index

Returns the trajectory at index. Raises an NSRangeException if index is beyond the range of the receiver.

- (id) trajectoryWithName: (NSString*)  key

Returns the trajectory called name. If no trajectory called name exists in the receiver this method returns nil.

+ (id) unarchiveFromLocation: (id)  location

As AdModelObject:unarchiveFromFile() except location, which specifies a file or directory, can be an NSString or NSURL instance.

- (void) update

Forces all the trajectories the receiver to re-read their data