13.3.2. Low level DCD trajectory reading -
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.coordinates.DCD. They behave similar to normal
For example, one can use a
DCDFile to directly calculate mean
coordinates (where the coordinates are stored in x attribute of the
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.
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.
- fname (str) – The filename to open.
- mode (('r', 'w')) – The mode in which to open the file, either ‘r’ read or ‘w’ write
>>> from MDAnalysis.lib.formats.libdcd import DCDFile >>> with DCDFile('foo.dcd') as f: >>> for frame in f: >>> print(frame.x)
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
DCDFilewill 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
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 the open DCD file
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 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 next dcd frame
Returns: DCDFrame – positions are in
xand unitcell in
unitcellattribute of DCDFrame
Return type: namedtuple
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
- start (int (optional)) – starting frame, default to 0
- stop (int (optional)) – stop frame, default to
- 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
DCDFrame – positions are in
xand unitcell in
unitcellattribute of DCDFrame. Here the attributes contain the positions for all frames in the given order
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.
Returns: Return type: current frame (0-based)
write one frame into DCD file.
- 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.
- 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