Module MMTK.Trajectory


Functions


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:

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:

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:


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

Methods:

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


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:

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.