5.3. DCD trajectory I/O — MDAnalysis.coordinates.DCD
¶
Classes to read and write DCD binary trajectories, the format used by CHARMM, NAMD, and also LAMMPS. Trajectories can be read regardless of system-endianness as this is auto-detected.
Generally, DCD trajectories produced by any code can be read (with the
DCDReader
) although there can be issues with the unitcell
(simulation box) representation (see
Timestep.dimensions
). DCDs can also be written but the
DCDWriter
follows recent NAMD/VMD convention for the unitcell
but still writes AKMA time. Reading and writing these trajectories
within MDAnalysis will work seamlessly but if you process those
trajectories with other tools you might need to watch out that time
and unitcell dimensions are correctly interpreted.
Note
The DCD file format is not well defined. In particular, NAMD and
CHARMM use it differently. Currently, MDAnalysis tries to guess the
correct format for the unitcell representation but it can be
wrong. Check the unitcell dimensions, especially for triclinic
unitcells (see Issue 187 and Timestep.dimensions
). A
second potential issue are the units of time which are AKMA for the
DCDReader
(following CHARMM) but ps for NAMD. As a
workaround one can employ the configurable
MDAnalysis.coordinates.LAMMPS.DCDReader
for NAMD
trajectories.
See also
The MDAnalysis.coordinates.LAMMPS
module provides
a more flexible DCD reader/writer.
The classes in this module are the reference implementations for the Trajectory API.
5.3.1. Classes¶
-
class
MDAnalysis.coordinates.DCD.
Timestep
(n_atoms, **kwargs)[source]¶ Create a Timestep, representing a frame of a trajectory
Parameters: - n_atoms (int) – The total number of atoms this Timestep describes
- positions (bool, optional) – Whether this Timestep has position information [
True
] - velocities (bool, optional) – Whether this Timestep has velocity information [
False
] - forces (bool, optional) – Whether this Timestep has force information [
False
] - reader (Reader, optional) – A weak reference to the owning Reader. Used for when attributes require trajectory manipulation (e.g. dt)
- dt (float, optional) – The time difference between frames (ps). If
time
is set, then dt will be ignored. - time_offset (float, optional) – The starting time from which to calculate time (ps)
- versionchanged (.) – Added keywords for positions, velocities and forces Can add and remove position/velocity/force information by using the has_* attribute
-
__delattr__
¶ x.__delattr__(‘name’) <==> del x.name
-
__format__
()¶ default object formatter
-
__getattribute__
¶ x.__getattribute__(‘name’) <==> x.name
-
__hash__
¶
-
__reduce__
()¶ helper for pickle
-
__reduce_ex__
()¶ helper for pickle
-
__setattr__
¶ x.__setattr__(‘name’, value) <==> x.name = value
-
__sizeof__
() → int¶ size of object in memory, in bytes
-
__str__
¶
-
copy_slice
(sel)[source]¶ Make a new Timestep containing a subset of the original Timestep.
ts.copy_slice(slice(start, stop, skip))
ts.copy_slice([list of indices])
Returns: - A Timestep object of the same type containing all header
- information and all atom information relevant to the selection.
Note
The selection must be a 0 based slice or array of the atom indices in this Timestep
New in version 0.8.
Changed in version 0.11.0: Reworked to follow new Timestep API. Now will strictly only copy official attributes of the Timestep.
-
dimensions
¶ unitcell dimensions (A, B, C, alpha, beta, gamma)
lengths A, B, C are in the MDAnalysis length unit (Å), and angles are in degrees.
dimensions
is read-only because it transforms the actual format of the unitcell (which differs between different trajectory formats) to the representation described here, which is used everywhere in MDAnalysis.The ordering of the angles in the unitcell is the same as in recent versions of VMD’s DCDplugin (2013), namely the X-PLOR DCD format: The original unitcell is read as
[A, gamma, B, beta, alpha, C]
from the DCD file (actually, the direction cosines are stored instead of the angles but the underlying C code already does this conversion); if any of these values are < 0 or if any of the angles are > 180 degrees then it is assumed it is a new-style CHARMM unitcell (at least since c36b2) in which box vectors were recorded.Warning
The DCD format is not well defined. Check your unit cell dimensions carefully, especially when using triclinic boxes. Different software packages implement different conventions and MDAnalysis is currently implementing the newer NAMD/VMD convention and tries to guess the new CHARMM one. Old CHARMM trajectories might give wrong unitcell values. For more details see Issue 187.
Changed in version 0.9.0: Unitcell is now interpreted in the newer NAMD DCD format as
[A, gamma, B, beta, alpha, C]
instead of the old MDAnalysis/CHARMM ordering[A, alpha, B, beta, gamma, C]
. We attempt to detect the new CHARMM DCD unitcell format (see Issue 187 for a discussion).
-
dt
¶ The time difference in ps between timesteps
Note
This defaults to 1.0 ps in the absence of time data
New in version 0.11.0.
-
forces
¶ A record of the forces of all atoms in this Timestep
Setting this attribute will add forces to the Timestep if they weren’t originally present.
Returns: - A numpy.ndarray of shape (n_atoms, 3) of force data for each
- atom
Raises: - class:MDAnalysis.NoDataError
- When the Timestep does not contain force information –
- .. versionadded (: 0.11.0) –
-
from_coordinates
(positions=None, velocities=None, forces=None, **kwargs)[source]¶ Create an instance of this Timestep, from coordinate data
Can pass position, velocity and force data to form a Timestep.
New in version 0.11.0.
-
from_timestep
(other, **kwargs)[source]¶ Create a copy of another Timestep, in the format of this Timestep
New in version 0.11.0.
-
has_forces
¶ A boolean of whether this Timestep has force data
This can be changed to
True
orFalse
to allocate space for or remove the data.New in version 0.11.0.
-
has_positions
¶ A boolean of whether this Timestep has position data
This can be changed to
True
orFalse
to allocate space for or remove the data.New in version 0.11.0.
-
has_velocities
¶ A boolean of whether this Timestep has velocity data
This can be changed to
True
orFalse
to allocate space for or remove the data.New in version 0.11.0.
-
n_atoms
¶ A read only view of the number of atoms this Timestep has
Changed in version 0.11.0: Changed to read only property
-
positions
¶ A record of the positions of all atoms in this Timestep
Setting this attribute will add positions to the Timestep if they weren’t originally present.
Returns: - A numpy.ndarray of shape (n_atoms, 3) of position data for each
- atom
Raises: - class:MDAnalysis.exceptions.NoDataError
- If the Timestep has no position data –
Changed in version 0.11.0: Now can raise NoDataError when no position data present
-
time
¶ The time in ps of this timestep
This is calculated as:
time = ts.data['time_offset'] + ts.time
Or, if the trajectory doesn’t provide time information:
time = ts.data['time_offset'] + ts.frame * ts.dt
New in version 0.11.0.
-
triclinic_dimensions
¶ The unitcell dimensions represented as triclinic vectors
Returns: Return type: A (3, 3) numpy.ndarray of unit cell vectors Examples
The unitcell for a given system can be queried as either three vectors lengths followed by their respective angle, or as three triclinic vectors.
>>> ts.dimensions array([ 13., 14., 15., 90., 90., 90.], dtype=float32) >>> ts.triclinic_dimensions array([[ 13., 0., 0.], [ 0., 14., 0.], [ 0., 0., 15.]], dtype=float32)
Setting the attribute also works:
>>> ts.triclinic_dimensions = [[15, 0, 0], [5, 15, 0], [5, 5, 15]] >>> ts.dimensions array([ 15. , 15.81138802, 16.58312416, 67.58049774, 72.45159912, 71.56504822], dtype=float32)
New in version 0.11.0.
-
velocities
¶ A record of the velocities of all atoms in this Timestep
Setting this attribute will add velocities to the Timestep if they weren’t originally present.
Returns: - A numpy.ndarray of shape (n_atoms, 3) of velocity data for each
- atom
Raises: - class:MDAnalysis.exceptions.NoDataError
- When the Timestep does not contain velocity information –
New in version 0.11.0.
-
volume
¶ volume of the unitcell
-
class
MDAnalysis.coordinates.DCD.
DCDReader
(dcdfilename, **kwargs)[source]¶ Reads from a DCD file
Data: - ts
Timestep
object containing coordinates of current frame
-
``dcd = DCD(dcdfilename)``
open dcd file and read header
-
``len(dcd)``
return number of frames in dcd
-
``for ts in dcd
`` iterate through trajectory
-
``for ts in dcd[start
stop:skip]:`` iterate through a trajectory
-
``dcd[i]``
random access into the trajectory (i corresponds to frame number)
-
``data = dcd.timeseries(...)``
retrieve a subset of coordinate information for a group of atoms
-
``data = dcd.correl(...)``
populate a
MDAnalysis.core.Timeseries.Collection
object with computed timeseries
Note
The DCD file format is not well defined. In particular, NAMD and CHARMM use it differently. Currently, MDAnalysis tries to guess the correct format for the unitcell representation but it can be wrong. Check the unitcell dimensions, especially for triclinic unitcells (see Issue 187 and
Timestep.dimensions
). A second potential issue are the units of time (TODO).Changed in version 0.9.0: The underlying DCD reader (written in C and derived from the catdcd/molfile plugin code of VMD) is now reading the unitcell in NAMD ordering:
[A, B, C, sin(gamma), sin(beta), sin(alpha)]
. See Issue 187 for further details.Changed in version 0.11.0: Frames now 0-based instead of 1-based Native frame number read into ts._frame Removed skip keyword and functionality
-
OtherWriter
(filename, **kwargs)¶ Returns a writer appropriate for filename.
Sets the default keywords start, step and dt (if available). n_atoms is always set from
Reader.n_atoms
.See also
Reader.Writer()
andMDAnalysis.Writer()
-
Writer
(filename, **kwargs)[source]¶ Returns a DCDWriter for filename with the same parameters as this DCD.
All values can be changed through keyword arguments.
Parameters: *filename* – filename of the output DCD trajectory
Keywords: - n_atoms
number of atoms
- start
number of the first recorded MD step
- step
indicate that step MD steps (!) make up one trajectory frame
- delta
MD integrator time step (!), in AKMA units
- dt
Override step and delta so that the DCD records that dt ps lie between two frames. (It sets step = 1 and delta =
AKMA(dt)
.) The default isNone
, in which case step and delta are used.- remarks
string that is stored in the DCD header [XXX – max length?]
Returns: Note
The keyword arguments set the low-level attributes of the DCD according to the CHARMM format. The time between two frames would be delta * step !
See also
DCDWriter
has detailed argument description
-
__delattr__
¶ x.__delattr__(‘name’) <==> del x.name
-
__format__
()¶ default object formatter
-
__getattribute__
¶ x.__getattribute__(‘name’) <==> x.name
-
__hash__
¶
-
__reduce__
()¶ helper for pickle
-
__reduce_ex__
()¶ helper for pickle
-
__setattr__
¶ x.__setattr__(‘name’, value) <==> x.name = value
-
__sizeof__
() → int¶ size of object in memory, in bytes
-
__str__
¶
-
check_slice_indices
(start, stop, step)¶ Check frame indices are valid and clip to fit trajectory
Parameters: stop, step (start,) – Values representing the slice indices. Can use None to use defaults of (0, -1, and 1) respectively. Returns: start, stop, step – Integers representing the slice Return type: int
-
convert_forces_from_native
(force, inplace=True)¶ Conversion of forces array force from native to base units
Parameters: - force (array_like) – Forces to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input force is modified in place and also returned.
New in version 0.7.7.
-
convert_forces_to_native
(force, inplace=True)¶ Conversion of force array force from base to native units.
Parameters: - force (array_like) – Forces to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input force is modified in place and also returned.
New in version 0.7.7.
-
convert_pos_from_native
(x, inplace=True)¶ Conversion of coordinate array x from native units to base units.
Parameters: - x (array_like) – Positions to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input x is modified in place and also returned.
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_pos_to_native
(x, inplace=True)¶ Conversion of coordinate array x from base units to native units.
Parameters: - x (array_like) – Positions to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input x is modified in place and also returned.
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_time_from_native
(t, inplace=True)¶ Convert time t from native units to base units.
Parameters: - t (array_like) – Time values to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input t is modified in place and also returned (although note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_time_to_native
(t, inplace=True)¶ Convert time t from base units to native units.
Parameters: - t (array_like) – Time values to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input t is modified in place and also returned. (Also note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_velocities_from_native
(v, inplace=True)¶ Conversion of velocities array v from native to base units
Parameters: - v (array_like) – Velocities to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input v is modified in place and also returned.
New in version 0.7.5.
-
convert_velocities_to_native
(v, inplace=True)¶ Conversion of coordinate array v from base to native units
Parameters: - v (array_like) – Velocities to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input v is modified in place and also returned.
New in version 0.7.5.
-
correl
(timeseries, start=0, stop=-1, skip=1)[source]¶ Populate a TimeseriesCollection object with timeseries computed from the trajectory
Parameters: - *timeseries* –
MDAnalysis.core.Timeseries.TimeseriesCollection
- stop, skip* (*start,) – subset of trajectory to use, with start and stop being inclusive
- *timeseries* –
-
dt
¶ Time between two trajectory frames in picoseconds.
-
frame
¶ Frame number of the current time step.
This is a simple short cut to
Timestep.frame
.
-
next
()¶ Forward one step to next frame.
-
rewind
()¶ Position at beginning of trajectory
-
time
¶ Time of the current frame in MDAnalysis time units (typically ps).
This is either read straight from the Timestep, or calculated as time =
Timestep.frame
*Timestep.dt
-
timeseries
(asel, start=0, stop=-1, skip=1, format=u'afc')[source]¶ Return a subset of coordinate data for an AtomGroup
Parameters: - *asel* –
AtomGroup
object - stop, skip* (*start,) – range of trajectory to access, start and stop are inclusive
- *format* – the order/shape of the return data array, corresponding to (a)tom, (f)rame, (c)oordinates all six combinations of ‘a’, ‘f’, ‘c’ are allowed ie “fac” - return array where the shape is (frame, number of atoms, coordinates)
- *asel* –
-
totaltime
¶ Total length of the trajectory n_frames * dt.
-
class
MDAnalysis.coordinates.DCD.
DCDWriter
(filename, n_atoms, start=0, step=1, delta=20.45482949774598, dt=None, remarks=u'Created by DCDWriter', convert_units=None)[source]¶ Writes to a DCD file
Typical usage:
with DCDWriter("new.dcd", u.atoms.n_atoms) as w: for ts in u.trajectory w.write_next_timestep(ts)
Keywords are available to set some of the low-level attributes of the DCD.
-
``d = DCDWriter(dcdfilename, n_atoms, start, step, delta, remarks)``
Note
The Writer will write the unit cell information to the DCD in a format compatible with NAMD and older CHARMM versions, namely the unit cell lengths in Angstrom and the angle cosines (see
Timestep
). Newer versions of CHARMM (at least c36b2) store the matrix of the box vectors. Writing this matrix to a DCD is currently not supported (although reading is supported with theDCDReader
); instead the angle cosines are written, which might make the DCD file unusable in CHARMM itself. See Issue 187 for further information.The writing behavior of the
DCDWriter
is identical to that of the DCD molfile plugin of VMD with the exception that by default it will use AKMA time units.Create a new DCDWriter
Arguments: - filename
name of output file
- n_atoms
number of atoms in dcd file
- start
starting timestep
- step
skip between subsequent timesteps (indicate that step MD integrator steps (!) make up one trajectory frame); default is 1.
- delta
timestep (MD integrator time step (!), in AKMA units); default is 20.45482949774598 (corresponding to 1 ps).
- remarks
comments to annotate dcd file
- dt
Override step and delta so that the DCD records that dt ps lie between two frames. (It sets step = 1 and delta =
AKMA(dt)
.) The default isNone
, in which case step and delta are used.- convert_units
units are converted to the MDAnalysis base format;
None
selects the value ofMDAnalysis.core.flags
[‘convert_lengths’]. (see Flags)
Note
The keyword arguments set the low-level attributes of the DCD according to the CHARMM format. The time between two frames would be delta * step ! For convenience, one can alternatively supply the dt keyword (see above) to just tell the writer that it should record “There are dt ps between each frame”.
-
__delattr__
¶ x.__delattr__(‘name’) <==> del x.name
-
__format__
()¶ default object formatter
-
__getattribute__
¶ x.__getattribute__(‘name’) <==> x.name
-
__hash__
¶
-
__reduce__
()¶ helper for pickle
-
__reduce_ex__
()¶ helper for pickle
-
__setattr__
¶ x.__setattr__(‘name’, value) <==> x.name = value
-
__sizeof__
() → int¶ size of object in memory, in bytes
-
__str__
¶
-
convert_dimensions_to_unitcell
(ts, _ts_order=[0, 2, 5, 4, 3, 1])[source]¶ Read dimensions from timestep ts and return appropriate native unitcell.
See also
-
convert_forces_from_native
(force, inplace=True)¶ Conversion of forces array force from native to base units
Parameters: - force (array_like) – Forces to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input force is modified in place and also returned.
New in version 0.7.7.
-
convert_forces_to_native
(force, inplace=True)¶ Conversion of force array force from base to native units.
Parameters: - force (array_like) – Forces to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input force is modified in place and also returned.
New in version 0.7.7.
-
convert_pos_from_native
(x, inplace=True)¶ Conversion of coordinate array x from native units to base units.
Parameters: - x (array_like) – Positions to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input x is modified in place and also returned.
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_pos_to_native
(x, inplace=True)¶ Conversion of coordinate array x from base units to native units.
Parameters: - x (array_like) – Positions to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input x is modified in place and also returned.
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_time_from_native
(t, inplace=True)¶ Convert time t from native units to base units.
Parameters: - t (array_like) – Time values to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input t is modified in place and also returned (although note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_time_to_native
(t, inplace=True)¶ Convert time t from base units to native units.
Parameters: - t (array_like) – Time values to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input t is modified in place and also returned. (Also note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)
Changed in version 0.7.5: Keyword inplace can be set to
False
so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.
-
convert_velocities_from_native
(v, inplace=True)¶ Conversion of velocities array v from native to base units
Parameters: - v (array_like) – Velocities to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input v is modified in place and also returned.
New in version 0.7.5.
-
convert_velocities_to_native
(v, inplace=True)¶ Conversion of coordinate array v from base to native units
Parameters: - v (array_like) – Velocities to transform
- inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data
Note
By default, the input v is modified in place and also returned.
New in version 0.7.5.
-
has_valid_coordinates
(criteria, x)¶ Returns
True
if all values are within limit values of their formats.Due to rounding, the test is asymmetric (and min is supposed to be negative):
min < x <= maxParameters: - *criteria* – dictionary containing the max and min values in native units
- *x* –
np.ndarray
of(x, y, z)
coordinates of atoms selected to be written out.
Returns: boolean
-
write
(obj)¶ Write current timestep, using the supplied obj.
The argument should be a
AtomGroup
or aUniverse
or aTimestep
instance.Note
The size of the obj must be the same as the number of atom provided when setting up the trajectory.
-
write_next_timestep
(ts=None)[source]¶ write a new timestep to the dcd file
ts - timestep object containing coordinates to be written to dcd file
Changed in version 0.7.5: Raises
ValueError
instead of genericException
if wrong number of atoms supplied andNoDataError
if no coordinates to be written.
-