6.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

MDAnalysis.coordinates.LAMMPS
module provides a more flexible DCD reader/writer.

The classes in this module are the reference implementations for the Trajectory API.

6.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 (in ps)

Changed in version 0.11.0: Added keywords for positions, velocities and forces. Can add and remove position/velocity/force information by using the has_* attribute.

copy()[source]

Make an independent (“deep”) copy of the whole Timestep.

copy_slice(sel)[source]

Make a new Timestep containing a subset of the original Timestep.

Parameters:sel (array_like or slice) – The underlying position, velocity, and force arrays are sliced using a list, slice, or any array-like.
Returns:A Timestep object of the same type containing all header information and all atom information relevant to the selection.
Return type:Timestep

Note

The selection must be a 0 based slice or array of the atom indices in this Timestep

Example

Using a Python slice object:

new_ts = ts.copy_slice(slice(start, stop, step))

Using a list of indices:

new_ts = ts.copy_slice([0, 2, 10, 20, 23])

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:forces – force data of shape (n_atoms, 3) for all atoms
Return type:numpy.ndarray with dtype numpy.float32
Raises:MDAnalysis.exceptions.NoDataError – if the Timestep has no force data

New in version 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 or False 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 or False 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 or False 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:positions – position data of shape (n_atoms, 3) for all atoms
Return type:numpy.ndarray with dtype numpy.float32
Raises:MDAnalysis.exceptions.NoDataError – if the Timestep has no position data

Changed in version 0.11.0: Now can raise :exc`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:A (3, 3) numpy.ndarray of unit cell vectors
Return type:numpy.ndarray

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:velocities – velocity data of shape (n_atoms, 3) for all atoms
Return type:numpy.ndarray with dtype numpy.float32
Raises:MDAnalysis.exceptions.NoDataError – if the Timestep has no velocity data

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

Methods:
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()

Writer(filename, **kwargs)[source]

Returns a DCDWriter for filename with the same parameters as this DCD.

Defaults for all values are obtained from the DCDReader itself but all values can be changed through keyword arguments.

Parameters:
  • filename (str) – filename of the output DCD trajectory
  • n_atoms (int (optional)) – number of atoms
  • start (int (optional)) – number of the first recorded MD step
  • step (int (optional)) – indicate that step MD steps (!) make up one trajectory frame
  • delta (float (optional)) – MD integrator time step (!), in AKMA units
  • dt (float (optional)) – 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 is None, in which case step and delta are used.
  • remarks (str (optional)) – string that is stored in the DCD header
Returns:

Return type:

DCDWriter

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!

Here step is really the number of MD integrator time steps that occured after this frame, including the frame itself that is the coordinate snapshot and delta is the integrator stime step. The DCD file format contains this information so it needs to be provided here.

See also

DCDWriter

add_auxiliary(auxname, auxdata, format=None, **kwargs)

Add auxiliary data to be read alongside trajectory.

Auxiliary data may be any data timeseries from the trajectory additional to that read in by the trajectory reader. auxdata can be an AuxReader instance, or the data itself as e.g. a filename; in the latter case an appropriate AuxReader is guessed from the data/file format. An appropriate format may also be directly provided as a key word argument.

On adding, the AuxReader is initially matched to the current timestep of the trajectory, and will be updated when the trajectory timestep changes (through a call to next() or jumping timesteps with trajectory[i]).

The representative value(s) of the auxiliary data for each timestep (as calculated by the AuxReader) are stored in the current timestep in the ts.aux namespace under auxname; e.g. to add additional pull force data stored in pull-force.xvg:

u = MDAnalysis.Universe(PDB, XTC)
u.trajectory.add_auxiliary('pull', 'pull-force.xvg')

The representative value for the current timestep may then be accessed as u.trajectory.ts.aux.pull or u.trajectory.ts.aux['pull'].

Note

Auxiliary data is assumed to be time-ordered, with no duplicates. See the Auxiliary API.

aux_list

Lists the names of added auxiliary data.

check_slice_indices(start, stop, step)

Check frame indices are valid and clip to fit trajectory.

The usage follows standard Python conventions for range() but see the warning below.

Parameters:
  • start (int or None) – Starting frame index (inclusive). None corresponds to the default of 0, i.e., the initial frame.
  • stop (int or None) – Last frame index (exclusive). None corresponds to the default of n_frames, i.e., it includes the last frame of the trajectory.
  • step (int or None) – step size of the slice, None corresponds to the default of 1, i.e, include every frame in the range start, stop.
Returns:

start, stop, step – Integers representing the slice

Return type:

tuple (int, int, int)

Warning

The returned values start, stop and step give the expected result when passed in range() but gives unexpected behavior when passed in a slice when stop=None and step=-1

This can be a problem for downstream processing of the output from this method. For example, slicing of trajectories is implemented by passing the values returned by check_slice_indices() to range()

range(start, stop, step)

and using them as the indices to randomly seek to. On the other hand, in MDAnalysis.analysis.base.AnalysisBase the values returned by check_slice_indices() are used to splice the trajectory by creating a slice instance

slice(start, stop, step)

This creates a discrepancy because these two lines are not equivalent:

range(10, -1, -1)             # [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
range(10)[slice(10, -1, -1)]  # []
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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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.) In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

New in version 0.7.5.

correl(*args, **kwds)

correl is deprecated! This method will be removed in 0.17

Populate a TimeseriesCollection object with time series computed from the trajectory.

Calling this method will iterate through the whole trajectory and perform the calculations prescribed in timeseries.

Parameters:
  • timeseries (MDAnalysis.core.Timeseries.TimeseriesCollection) – The MDAnalysis.core.Timeseries.TimeseriesCollection that defines what kind of computations should be performed on the data in this trajectory.
  • start (int (optional)) – Begin reading the trajectory at frame index start (where 0 is the index of the first frame in the trajectory); the default None starts at the beginning.
  • stop (int (optional)) – End reading the trajectory at frame index stop-1, i.e, stop is excluded. The trajectory is read to the end with the default None.
  • step (int (optional)) – Step size for reading; the default None is equivalent to 1 and means to read every frame.

Note

The correl functionality is only implemented for DCD trajectories and the DCDReader.

Deprecated since version 0.16.0: skip has been deprecated in favor of the standard keyword step.

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.

get_aux_attribute(auxname, attrname)

Get the value of attrname from the auxiliary auxname

Parameters:
  • auxname (str) – Name of the auxiliary to get value for
  • attrname (str) – Name of gettable attribute in the auxiliary reader
get_aux_descriptions(auxnames=None)

Get descriptions to allow reloading the specified auxiliaries.

If no auxnames are provided, defaults to the full list of added auxiliaries.

Passing the resultant description to add_auxiliary() will allow recreation of the auxiliary. e.g., to duplicate all auxiliaries into a second trajectory:

descriptions = trajectory_1.get_aux_descriptions()
for aux in descriptions:
    trajectory_2.add_auxiliary(**aux)
Returns:List of dictionaries of the args/kwargs describing each auxiliary.
Return type:list
iter_as_aux(auxname)

Iterate through timesteps for which there is at least one assigned step from the auxiliary auxname within the cutoff specified in auxname.

iter_auxiliary(auxname, start=None, stop=None, step=None, selected=None)

Iterate through the auxiliary auxname independently of the trajectory.

Will iterate over the specified steps of the auxiliary (defaults to all steps). Allows to access all values in an auxiliary, including those out of the time range of the trajectory, without having to also iterate through the trajectory.

After interation, the auxiliary will be repositioned at the current step.

Parameters:
  • auxname (str) – Name of the auxiliary to iterate over.
  • stop, step) ((start,) – Options for iterating over a slice of the auxiliary.
  • selected (lst | ndarray, optional) – List of steps to iterate over.
Yields:

AuxStep object

See also

iter_as_aux()

next()

Forward one step to next frame.

next_as_aux(auxname)

Move to the next timestep for which there is at least one step from the auxiliary auxname within the cutoff specified in auxname.

This allows progression through the trajectory without encountering NaN representative values (unless these are specifically part of the auxiliary data).

If the auxiliary cutoff is not set, where auxiliary steps are less frequent (auxiliary.dt > trajectory.dt), this allows progression at the auxiliary pace (rounded to nearest timestep); while if the auxiliary steps are more frequent, this will work the same as calling next().

See the Auxiliary API.

See also

iter_as_aux()

remove_auxiliary(auxname)

Clear data and close the AuxReader for the auxiliary auxname.

See also

add_auxiliary()

rename_aux(auxname, new)

Change the name of the auxiliary auxname to new.

Provided there is not already an auxiliary named new, the auxiliary name will be changed in ts.aux namespace, the trajectory’s list of added auxiliaries, and in the auxiliary reader itself.

Parameters:
  • auxname (str) – Name of the auxiliary to rename
  • new (str) – New name to try set
Raises:

ValueError – If the name new is already in use by an existing auxiliary.

rewind()

Position at beginning of trajectory

set_aux_attribute(auxname, attrname, new)

Set the value of attrname in the auxiliary auxname.

Parameters:
  • auxname (str) – Name of the auxiliary to alter
  • attrname (str) – Name of settable attribute in the auxiliary reader
  • new – New value to try set attrname to
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=None, start=None, stop=None, step=None, skip=None, format=u’afc’)[source]

Return a subset of coordinate data for an AtomGroup

Parameters:
  • asel (AtomGroup) – The AtomGroup to read the coordinates from. Defaults to None, in which case the full set of coordinate data is returned.
  • start (int (optional)) – Begin reading the trajectory at frame index start (where 0 is the index of the first frame in the trajectory); the default None starts at the beginning.
  • stop (int (optional)) – End reading the trajectory at frame index stop-1, i.e, stop is excluded. The trajectory is read to the end with the default None.
  • step (int (optional)) – Step size for reading; the default None is equivalent to 1 and means to read every frame.
  • format (str (optional)) – 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)

Deprecated since version 0.16.0: skip has been deprecated in favor of the standard keyword step.

totaltime

Total length of the trajectory

The time is calculated as (n_frames - 1) * dt, i.e., we assume that the first frame no time as elapsed. Thus, a trajectory with two frames will be considered to have a length of a single time step dt and a “trajectory” with a single frame will be reported as length 0.

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]

Write to a CHARMM/NAMD DCD trajectory file.

Parameters:
  • filename (str) – name of output file
  • n_atoms (int (optional)) – number of atoms in dcd file
  • start (int (optional)) – starting frame number
  • step (int (optional)) – skip between subsequent timesteps (indicate that step MD integrator steps (!) make up one trajectory frame); default is 1.
  • delta (float (optional)) – timestep (MD integrator time step (!), in AKMA units); default is 20.45482949774598 (corresponding to 1 ps).
  • remarks (str (optional)) – comments to annotate dcd file
  • dt (float (optional)) – 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 is None, in which case step and delta are used.
  • convert_units (bool (optional)) – units are converted to the MDAnalysis base format; None selects the value of MDAnalysis.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”.

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 the DCDReader); 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.

Example

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.

close()[source]

Close trajectory and flush buffers.

convert_dimensions_to_unitcell(ts, _ts_order=[0, 2, 5, 4, 3, 1])[source]

Read dimensions from timestep ts and return appropriate native unitcell.

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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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.) In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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. In-place operations improve performance because allocating new arrays is avoided.

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 <= max
Parameters:
  • criteria (dict) – dictionary containing the max and min values in native units
  • x (numpy.ndarray) – (x, y, z) coordinates of atoms selected to be written out
Returns:

Return type:

bool

write(obj)

Write current timestep, using the supplied obj.

Parameters:obj (AtomGroup or Universe or a Timestep) – write coordinate information associate with obj

Note

The size of the obj must be the same as the number of atoms provided when setting up the trajectory.

write_next_timestep(ts=None)[source]

Write a new timestep to the DCD file.

Parameters:

ts (Timestep (optional)) – Timestep object containing coordinates to be written to DCD file; by default it uses the current Timestep associated with the Writer.

Raises:
  • ValueError – if wrong number of atoms supplied
  • NoDataError – if no coordinates to be written.

Changed in version 0.7.5: Raises ValueError instead of generic Exception if wrong number of atoms supplied and NoDataError if no coordinates to be written.