14.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()

14.3.2. Low level DCD trajectory reading - MDAnalysis.lib.formats.libdcd

14.3.2. Low level DCD trajectory reading - `MDAnalysis.lib.formats.libdcd`