13.3.2. Low level DCD trajectory reading - MDAnalysis.lib.formats.libdcd

libdcd contains the class DCDFile to read and write frames of a DCD file. The class tries to behave similar to a normal file object.

libdcd contains the classes DCDFile, which can be used to read and write frames from and to DCD files. These classes are used internally by MDAnalysis in MDAnalysis.coordinates.DCD. They behave similar to normal file objects.

For example, one can use a DCDFile to directly calculate mean coordinates (where the coordinates are stored in x attribute of the namedtuple frame):

with DCDFile("trajectory.dcd") as dcd:
    header = dcd.header
    mean = np.zeros((header['natoms'], 3))
    # iterate over trajectory
    for frame in dcd:
        mean += frame.x
mean /= header['natoms']

Besides iteration one can also seek to arbitrary frames using the seek() method. Note that instead of seeking to a byte-offset as for normal Python streams, the seek and tell method of DCDFile operate on complete trajectory frames.

Acknowledgements

libdcd contains and is originally based on DCD reading and writing code from VMD’s molfile plugin and catdcd.

class MDAnalysis.lib.formats.libdcd.DCDFile(fname, mode='r')

File like wrapper for DCD files

This class can be similar to the normal file objects in python. The read() function will return a frame and all information in it instead of a single line. Additionally the context-manager protocol is supported as well.

DCDFile can read typical DCD files created by e.g., CHARMM, NAMD, or LAMMPS. It reads raw data from the trajectory and hence interpretation of, for instance, different unitcell conventions or time and length units, has to be handled in higher level code. Reading and writing does not support fixed atoms or 4D coordinates.

Parameters:
  • fname (str) – The filename to open.
  • mode (('r', 'w')) – The mode in which to open the file, either ‘r’ read or ‘w’ write

Examples

>>> from MDAnalysis.lib.formats.libdcd import DCDFile
>>> with DCDFile('foo.dcd') as f:
>>>     for frame in f:
>>>         print(frame.x)

Notes

DCD is not a well defined format. One consequence of this is that different programs like CHARMM and NAMD are using different convention to store the unitcell information. The DCDFile will read the unitcell information as is when available. Post processing depending on the program this DCD file was written with is necessary. Have a look at the MDAnalysis DCD reader for possible post processing into a common unitcell data structure. You can also find more information how different programs store unitcell information in DCD on the mdawiki . This class can be pickled. The pickle will store filename, mode, current frame

charmm_bitfield

This DCDFile reader can process files written by different MD simulation programs. For files produced by CHARMM or other programs that follow the same convention we are reading a special CHARMM bitfield that stores different flags about additional information that is stored in the dcd. The bit flags are:

DCD_IS_CHARMM       = 0x01
DCD_HAS_4DIMS       = 0x02
DCD_HAS_EXTRA_BLOCK = 0x04

Here DCD_HAS_EXTRA_BLOCK means that unitcell information is stored.

close()

Close the open DCD file

header

returns: * dict of header values needed to write new dcd. * natoms (number of atoms) * istart (starting frame number) * nsavc (number of frames between saves) * delta (integrator time step.) * charm (bitfield integer if file contains special CHARMM information) * remarks (remark string, max 240 bytes.)

open(mode='r')

Open a DCD file

If another DCD file is currently opened it will be closed

Parameters:mode (('r', 'w')) – The mode in which to open the file, either ‘r’ read or ‘w’ write
read()

Read next dcd frame

Returns:DCDFrame – positions are in x and unitcell in unitcell attribute of DCDFrame
Return type:namedtuple

Notes

unitcell is read as is from DCD. Post processing depending on the program this DCD file was written with is necessary. Have a look at the MDAnalysis DCD reader for possible post processing into a common unitcell data structure.

readframes(start=None, stop=None, step=None, order='fac', indices=None)

read multiple frames at once

Parameters:
  • start (int (optional)) – starting frame, default to 0
  • stop (int (optional)) – stop frame, default to n_frames
  • step (int (optional)) – step between frames read, defaults to 1
  • order (str (optional)) – give order of returned array with f:frames, a:atoms, c:coordinates
  • indices (array_like (optional)) – only read selected atoms. In None read all.
Returns:

DCDFrame – positions are in x and unitcell in unitcell attribute of DCDFrame. Here the attributes contain the positions for all frames in the given order
Return type:

namedtuple

Notes

unitcell is read as it from DCD. Post processing depending the program this DCD file was written with is necessary. Have a look at the MDAnalysis DCD reader for possible post processing into a common unitcell data structure.

seek(frame)

Seek to Frame.

Parameters:frame (int) – seek the file to given frame (0-based)
tell()
Returns:
Return type:current frame (0-based)
write(xyz, box=None)

write one frame into DCD file.

Parameters:
  • xyz (array_like, shape=(natoms, 3)) – cartesion coordinates
  • box (array_like, shape=(6) (optional)) – Box vectors for this frame. Can be left to skip writing a unitcell
write_header(remarks, natoms, istart, nsavc, delta, is_periodic)

Write DCD header

This function needs to be called before the first frame can be written.

Parameters:
  • remarks (str) – remarks of DCD file. Writes up to 239 characters (ASCII). The character 240 will be the null terminator
  • natoms (int) – number of atoms to write
  • istart (int) – starting frame number
  • nsavc (int) – number of frames between saves
  • delta (float) – integrator time step. The time for 1 frame is nsavc * delta
  • is_periodic (bool) – write unitcell information. Also pretends that file was written by CHARMM 24