mstk.trajectory.Trajectory

class mstk.trajectory.Trajectory(file, mode='r', Handler=None)

A Trajectory is made of a series of Frames.

It is assumed that all frames have the same number of atoms. If it’s not the case (e.g. the LammpsDump can have variable number of atoms in each frame), then this class may not be able to work correctly.

The file(s) can be opened in ‘r’, ‘w’ or ‘a’ modes, which mean read, write and append. The frames are loaded on request for performance issue, therefore a file handler is kept open until close() is called. The handler class used for parsing the trajectory is determined by the extension of the file. It can also be specified explicitly if non-standard extension is used for the name of trajectory file.

Several files can be opened at the same time (even for files of different format), which is useful for processing truncated trajectories. In this case, the trajectory is read-only.

Parameters:

• file (str or list of str) – If it’s a str, then open the file with corresponding parser. if it’s a list of str, then call CombinedTrj to open all of the files.

• mode (['r', 'w', 'a']) –

• Handler (subclass of TrjHandler) – Specify the handler class for parsing the trajectory. If set to None, then the handler class will be determined from the extension of the file name.

n_atom

Number of atoms in the trajectory. -1 means unknown yet

Type:

int

n_frame

Number of frames in the trajectory. -1 means unknown yet

Type:

int

frame

The latest frame been read by read_frame(). None means no frame has been read.

Type:

Frame or None

Examples

>>> trj = Trajectory('input.dcd')
>>> frame = trj.read_frame(0)
>>> frames = trj.read_frames([1,2,5])
>>> trj.close()

>>> trj = Trajectory('output.dcd', mode='a')
>>> trj.write_frame(frame)
>>> trj.close()

>>> trj = Trajectory(['input1.dcd', 'input2.xtc'])

Methods

__init__(file[, mode, Handler])
close()	Close the opened trajectory file(s).
open(file[, mode])	Open (a) trajectory file(s).
read_frame(i_frame)	Read a single frame from the trajectory.
read_frame_from_file(file[, i_frame])	Read one single frame from a trajectory file.
read_frames(i_frames)	Read a bunch of frames from the trajectory.
write_frame(frame[, topology, subset])	Write one frame to the opened trajectory file.

close()

Close the opened trajectory file(s).

read_frame(i_frame: int)

Read a single frame from the trajectory.

For the best of performance, a cached frame is used. When this method is called, the position and cell etc in the cached frame are updated, and the reference of this frame will be returned. Therefore, if you want to handle several different frames at the same time, this method should not be used because all the frames actually point to the same frame. In this case, use read_frames() instead.

i_frame should be in the range of [-1, n_frame), otherwise and Exception will be raised. -1 means the last frame.

Parameters:

i_frame (int) – The index of the frame in trajectory.

Returns:

frame

Return type:

Frame

read_frames(i_frames: [<class 'int'>])

Read a bunch of frames from the trajectory.

Unlike read_frame(), the cached frame is not used. Instead, a new Frame object is constructed for each frame. This method should be called when you want to multiprocess several frames in parallel.

All the items in i_frames should be in the range of [-1, n_frame), otherwise and Exception will be raised. -1 means the last frame.

Parameters:

i_frames (list of int) –

Returns:

frames

Return type:

list of Frame

write_frame(frame, topology=None, subset=None, **kwargs)

Write one frame to the opened trajectory file.

It requires the trajectory opened in ‘w’ or ‘a’ mode. Some trajectory format (e.g. GRO, XYZ) record part of the topology information, therefore, a topology should be provided for these formats.

It is possible to write only a subset of atoms in the frame. In this case, a list of indexes of these atoms should be provided. Make sure the number of atoms in the subset is the same for every frame been written.

Parameters:

• frame (Frame) –

• topology (Topology, optional) –

• subset (list of int, optional) –

• kwargs (dict) –

static open(file, mode='r')

Open (a) trajectory file(s). Deprecated. Use the constructor instead.

Parameters:

• file (str or list of str) –

• mode (['r', 'w', 'a']) –

static read_frame_from_file(file, i_frame=0)

Read one single frame from a trajectory file.

This is simply a shortcut for

>>> trj = Trajectory('input.dcd')
>>> frame = trj.read_frame(i_frame)
>>> trj.close()

By default, the first frame is read. Otherwise, argument i_frame should be set. If i_frame set to -1, then the last frame is read.

Parameters:

• file (str) –

• i_frame (int) –

Returns:

frame

Return type:

Frame