Ctrl+K

moleculekit.dcd module#

class moleculekit.dcd.DCDTrajectoryFile(filename, mode='r', force_overwrite=True)#

Bases: object

Interface for reading and writing to a CHARMM/NAMD DCD file. This is a file-like object, that both reading or writing depending on the mode flag. It implements the context manager protocol, so you can also use it with the python ‘with’ statement.

The conventional units in the DCD file are angstroms and degrees. The format supports saving coordinates and unit cell parameters (lengths and angles)

Parameters:

  • filename (string) – Path to the file to open

  • mode ({'r', 'w'}) – Mode in which to open the file. ‘r’ is for reading, and ‘w’ is for writing.

  • force_overwrite (bool) – In mode=’w’, how do you want to behave if a file by the name of filename already exists? if force_overwrite=True, it will be overwritten.

Examples

>>> # read a single frame, and then read the remaining frames
>>> f = DCDTrajectoryFile('mytrajectory.dcd', 'r')
>>> f.read(n_frames=1)  # read a single frame from the file
>>> xyz.read()            # read all of the remaining frames
>>> f.close()

>>> # read all of the data with automatic closing of the file
>>> with DCDTrajectoryFile('mytrajectory.dcd', 'r') as f:
>>>    xyz, cell_lengths, cell_angles = f.read()

>>> # write some xyz coordinates to a new file
>>> with DCDTrajectoryFile('mytrajectory2.dcd', 'w') as f:
>>>     f.write(np.random.randn(10,3,3))

>>> # write frames one at a time
>>> with DCDTrajectoryFile('mytrajectory2.dcd', 'w') as f:
>>>     n_frames, n_atoms = 5, 10
>>>     for i in range(n_frames):
>>>         f.write(np.random.randn(n_atoms, 3))
__enter__()#

Support the context manager protocol

__exit__(*exc_info)#

Support the context manager protocol

close()#

Close the DCD file handle

distance_unit#
read(n_frames=None, stride=None, atom_indices=None)#

Read the data from a DCD file

Parameters:

  • n_frames (int, optional) – If positive, then read only the next n_frames frames. Otherwise read all of the frames in the file.

  • stride (np.ndarray, optional) – Read only every stride-th frame.

  • atom_indices (array_like, optional) – If not none, then read only a subset of the atoms coordinates from the file. This may be slightly slower than the standard read because it required an extra copy, but will save memory.

Returns:

  • xyz (np.ndarray, shape=(n_frames, n_atoms, 3), dtype=float32) – The xyz coordinates of each atom in each frame. By convention, the coordinates in the dcd file are stored in units of angstroms.

  • cell_lengths (np.ndarray, shape=(n_frames, 3), dtype=float32) – The length of the box in each frame. cell_lengths[i,0] is the length of the A axis (in frame i), and cell_lengths[i,1] and cell_lengths[i,2] are the B and C axis respectively. By convention, the cell lengths in the dcd file are stored in units of angstroms.

  • cell_angles (np.ndarray, shape=(n_frames, 3), dtype=float32) – Organized analogously to cell_lengths. Gives the alpha, beta and gamma angles respectively in entries cell_angles[i,0], cell_angles[i,1], cell_angles[i,2]. By convention, the cell angles in the dcd file are stored in units of degrees.

read_header()#
Returns:

  • istart (int) – The starting step

  • nsavc (int) – The number of steps between each saved frame

  • delta (float) – The timestep of the simulation

seek(offset, whence=0)#

Move to a new file position

Parameters:

  • offset (int) – A number of frames.

  • whence ({0, 1, 2}) – 0: offset from start of file, offset should be >=0. 1: move relative to the current position, positive or negative 2: move relative to the end of file, offset should be <= 0. Seeking beyond the end of a file is not supported

tell()#

Current file position

Returns:

offset – The current frame in the file.

Return type:

int

write(xyz, cell_lengths=None, cell_angles=None)#

Write one or more frames of data to the DCD file

Parameters:

  • xyz (np.ndarray, shape=(n_frames, n_atoms, 3)) – The cartesian coordinates of the atoms to write. By convention for this trajectory format, the lengths should be in units of angstroms.

  • cell_lengths (np.ndarray, shape=(n_frames, 3), dtype=float32, optional) – The length of the periodic box in each frame, in each direction, a, b, c. By convention for this trajectory format, the lengths should be in units of angstroms.

  • cell_angles (np.ndarray, shape=(n_frames, 3), dtype=float32, optional) – Organized analogously to cell_lengths. Gives the alpha, beta and gamma angles respectively. By convention for this trajectory format, the angles should be in units of degrees.

  • istart (int, optional) – The starting step

  • nsavc (int, optional) – The number of steps between written frames

  • delta (float, optional) – The time-step of the simulation.

moleculekit.dcd.load_dcd(filename, top=None, stride=None, atom_indices=None, frame=None)#

Load an DCD file from disk.

The .dcd format is a cross-platform compressed binary trajectory format produced by many software packages, including CHARMM, NAMD, and OpenMM. It stores atomic coordinates, box vectors, and time information.

Parameters:

  • filename (path-like) – Path of DCD file.

  • stride (int, default=None) – Only read every stride-th frame

  • atom_indices (array_like, optional) – If not none, then read only a subset of the atoms coordinates from the file. This may be slightly slower than the standard read because it requires an extra copy, but will save memory.

  • frame (int, optional) – Use this option to load only a single frame from a trajectory on disk. If frame is None, the default, the entire trajectory will be loaded. If supplied, stride will be ignored.

On this page