# Module MMTK.Trajectory

## Functions

- isTrajectory()

  Returns 1 if object is a trajectory.

- trajectoryInfo()

  Return a string with summarial information about the trajectory file identified by filename.

## Class Trajectory: Trajectory file

Constructor: Trajectory(object, filename, mode="r", comment=None, double_precision=0, cycle=0, block_size=1)

object

  the object whose data is stored in the trajectory file. This can be `None` when opening a file for reading; in that case, a universe object is constructed from the description stored in the trajectory file. This universe object can be accessed via the attribute `universe` of the trajectory object.

filename

  the name of the trajectory file

mode

  one of "r" (read-only), "w" (create new file for writing), or "a" (append to existing file or create if the file does not exist)

comment

  optional comment that is stored in the file; allowed only with mode="r"

double_precision

  if non-zero, data in the file is stored using double precision; default is single precision. Note that all I/O via trajectory objects is double precision; conversion from and to single precision file variables is handled automatically.

cycle

  if non-zero, a trajectory is created for a fixed number of steps equal to the value of cycle, and these steps are used cyclically. This is meant for restart trajectories.

block_size

  an optimization parameter that influences the file structure and the I/O performance for very large files. A block size of 1 is optimal for sequential access to configurations etc., whereas a block size equal to the number of steps is optimal for reading coordinates or scalar variables along the time axis. The default value is 1. Note that older MMTK releases always used a block size of 1 and cannot handle trajectories with different block sizes.

The data in a trajectory file can be accessed by step or by variable. If `t` is a Trajectory object, then:

- `len(t)` is the number of steps

- `t[i]` is the data for step i, in the form of a dictionary that maps variable names to data

- `t[i:j]` and `t[i:j:n]` return a SubTrajectory object that refers to a subset of the total number of steps (no data is copied)

- `t.variable` returns the value of the named variable at all time steps. If the variable is a simple scalar, it is read completely and returned as an array. If the variable contains data for each atom, a TrajectoryVariable object is returned from which data at specific steps can be obtained by further indexing operations.

The routines that generate trajectories decide what variables are used and what they contain. The most frequently used variable is "configuration", which stores the positions of all atoms. Other common variables are "time", "velocities", "temperature", "pressure", and various energy terms whose name end with "_energy".

Methods:

- close()

  Close the trajectory file. Must be called after writing to ensure that all buffered data is written to the file. No data access is possible after closing a file.

- readParticleTrajectory(atom, first=`0`, last=`None`, skip=`1`, variable=`'configuration'`)

  Read the values of the specified variable for the specified atom at all time steps from first to last with an increment of skip. The result is a ParticleTrajectory object. If the variable is "configuration", the resulting trajectory is made continuous by eliminating all jumps caused by periodic boundary conditions. The pseudo-variable "box_coordinates" can be read to obtain the values of the variable "configuration" scaled to box coordinates. For non-periodic universes there is no difference between box coordinates and real coordinates.

- readRigidBodyTrajectory(object, first=`0`, last=`None`, skip=`1`, reference=`None`)

  Read the positions for the specified object at all time steps from first to last with an increment of skip and extract the rigid-body motion (center-of-mass position plus orientation as a quaternion) by an optimal-transformation fit. The result is a RigidBodyTrajectory object.

- variables()

  Returns a list of the names of all variables that are stored in the trajectory.

- view(first=`0`, last=`None`, step=`1`, object=`None`)

  Show an animation of object using the positions in the trajectory at all time steps from first to last with an increment of skip. object defaults to the entire universe.

## Class SubTrajectory: Reference to a subset of a trajectory

A SubTrajectory object is created by slicing a Trajectory object or another SubTrajectory object. It provides all the operations defined on Trajectory objects.

## Class TrajectoryVariable: Variable in a trajectory

A TrajectoryVariable object is created by extracting a variable from a Trajectory object if that variable contains data for each atom and is thus potentially large. No data is read from the trajectory file when a TrajectoryVariable object is created; the read operation takes place when the TrajectoryVariable is indexed with a specific step number.

If `t` is a TrajectoryVariable object, then:

- `len(t)` is the number of steps

- `t[i]` is the data for step i, in the form of a ParticleScalar, a ParticleVector, or a Configuration object, depending on the variable

- `t[i:j]` and `t[i:j:n]` return a SubVariable object that refers to a subset of the total number of steps

## Class SubVariable: Reference to a subset of a TrajectoryVariable

A subclass of MMTK.Trajectory.TrajectoryVariable.

A SubVariable object is created by slicing a TrajectoryVariable object or another SubVariable object. It provides all the operations defined on TrajectoryVariable objects.

## Class TrajectorySet: Trajectory file set

A trajectory set permits to treat a sequence of trajectory files like a single trajectory for reading data. It behaves like an object of the class MMTK.Trajectory.Trajectory. The trajectory files must all contain data for the same system. The variables stored in the individual files need not be the same, but only variables common to all files can be accessed.

Constructor: TrajectorySet(object, filename_list)

object

  the object whose data is stored in the trajectory files. This can be (and usually is) `None`; in that case, a universe object is constructed from the description stored in the first trajectory file. This universe object can be accessed via the attribute `universe` of the trajectory set object.

filename_list

  a list of trajectory file names or (filename, first_step, last_step, increment) tuples.

Note: depending on how the sequence of trajectories was constructed, the first configuration of each trajectory might be the same as the last one in the preceding trajectory. To avoid counting it twice, specify (filename, 1, None, 1) for all but the first trajectory in the set.

## Class TrajectorySetVariable: Variable in a trajectory set

A TrajectorySetVariable object is created by extracting a variable from a TrajectorySet object if that variable contains data for each atom and is thus potentially large. It behaves exactly like a TrajectoryVariable object.

## Class ParticleTrajectory: Trajectory data for a single particle

A ParticleTrajectory object is created by calling the method `readParticleTrajectory` on a Trajectory object. If `pt` is a ParticleTrajectory object, then

- `len(pt)` is the number of steps stored in it

- `pt[i]` is the value at step `i` (a vector)

Methods:

- translateBy(vector)

  Adds vector to the values at all steps. This does not change the data in the trajectory file.

## Class RigidBodyTrajectory: Rigid-body trajectory data

A RigidBodyTrajectory object is created by calling the method `readRigidBodyTrajectory` on a Trajectory object. If `rbt` is a RigidBodyTrajectory object, then

- `len(rbt)` is the number of steps stored in it

- `rbt[i]` is the value at step `i` (a vector for the center of mass and a quaternion for the orientation)

## Class TrajectoryOutput: Trajectory output action

A TrajectoryOutput object is used in the action list of any trajectory-generating operation. It writes any of the available data to a trajectory file. It is possible to use several TrajectoryOutput objects at the same time in order to produce multiple trajectories from a single run.

Constructor: TrajectoryOutput(trajectory, data=None, first=0, last=None, skip=1)

trajectory

  a trajectory object or a string, which is interpreted as the name of a file that is opened as a trajectory in append mode

data

  a list of data categories. All variables provided by the trajectory generator that fall in any of the listed categories are written to the trajectory file. See the descriptions of the trajectory generators for a list of variables and categories. By default (data = `None`) the categories "configuration", "energy", "thermodynamic", and "time" are written.

first

  the number of the first step at which the action is executed

last

  the number of the last step at which the action is executed. A value of `None` indicates that the action should be executed indefinitely.

skip

  the number of steps to skip between two applications of the action

## Class RestartTrajectoryOutput: Restart trajectory output action

A RestartTrajectoryOutput object is used in the action list of any trajectory-generating operation. It writes those variables to a trajectory that the trajectory generator declares as necessary for restarting.

Constructor: RestartTrajectoryOutput(trajectory, skip=100, length=3)

trajectory

  a trajectory object or a string, which is interpreted as the name of a file that is opened as a trajectory in append mode with a cycle length of length and double-precision variables

skip

  the number of steps between two write operations to the restart trajectory

length

  the number of steps stored in the restart trajectory; used only if trajectory is a string

## Class LogOutput: Protocol file output action

A LogOutput object is used in the action list of any trajectory-generating operation. It writes any of the available data to a text file.

Constructor: LogOutput(file, data, first=0, last=None, skip=1)

file

  a file object or a string, which is interpreted as the name of a file that is opened in write mode

data

  a list of data categories. All variables provided by the trajectory generator that fall in any of the listed categories are written to the trajectory file. See the descriptions of the trajectory generators for a list of variables and categories. By default (data = `None`) the categories "energy" and "time" are written.

first

  the number of the first step at which the action is executed

last

  the number of the last step at which the action is executed. A value of `None` indicates that the action should be executed indefinitely.

skip

  the number of steps to skip between two applications of the action

## Class StandardLogOutput: Standard protocol output action

A StandardLogOutput object is used in the action list of any trajectory-generating operation. It is a specialization of LogOutput to the most common case and writes data in the categories "time" and "energy" to the standard output stream.

Constructor: StandardLogOutput(skip=50)

skip

  the number of steps to skip between two applications of the action

## Class SnapshotGenerator: Trajectory generator for single steps

A SnapshotGenerator is used for manual assembly of trajectory files. At each call it writes one step to the trajectory, using the current state of the universe (configuration, velocities, etc.) and data provided explicitly with the call.

Constructor: SnapshotGenerator(universe, **options)

universe

  the universe on which the integrator acts

options

  keyword options:

  - data: a dictionary that supplies values for variables that are not part of the universe state (e.g. potential energy)

  - actions: a list of actions to be executed periodically (default is none)

Each call to the SnapshotGenerator object produces one step. All the keyword options listed above can be specified either when creating the generator or when calling it.