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 inunitcell
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 inunitcell
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.
- tell()
- Return type:
current frame (0-based)
- write(xyz, box=None)
write one frame into DCD file.
- Parameters:
xyz (array_like, shape=(natoms, 3)) – cartesian 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