5.17. Base classes — MDAnalysis.coordinates.base
¶
Derive other Timestep, Reader and Writer classes from the classes in this
module. The derived classes must follow the Trajectory API in
MDAnalysis.coordinates.__init__
.
-
class
MDAnalysis.coordinates.base.
Timestep
[source]¶ -
__init__
(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
-
classmethod
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.
-
classmethod
from_timestep
(other, **kwargs)[source]¶ Create a copy of another Timestep, in the format of this Timestep
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
-
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.
-
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.
-
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
-
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.
-
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) –
-
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.
-
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.
-
_pos
¶ numpy.ndarray
of dtypefloat32
of shape (n_atoms, 3) and internal FORTRAN order, holding the raw cartesian coordinates (in MDAnalysis units, i.e. Å).Note
Normally one does not directly access
_pos
but uses thecoordinates()
method of anAtomGroup
but sometimes it can be faster to directly use the raw coordinates. Any changes to this array are immediately reflected in atom positions. If the frame is written to a new trajectory then the coordinates are changed. If a new trajectory frame is loaded, then all contents of_pos
are overwritten.
-
_velocities
¶ numpy.ndarray
of dtypefloat32
. of shape (n_atoms, 3), holding the raw velocities (in MDAnalysis units, i.e. typically Å/ps).Note
Normally velocities are accessed through the
velocities
or thevelocities()
method of anAtomGroup
_velocities
only exists if thehas_velocities
flag is TrueNew in version 0.7.5.
-
_forces
¶ numpy.ndarray
of dtypefloat32
. of shape (n_atoms, 3), holding the forces_forces
only exists ifhas_forces
is TrueNew in version 0.11.0: Added as optional to
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.
Setting dimensions will populate the underlying native format description of box dimensions
-
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.
-
volume
¶ volume of the unitcell
-
__getitem__
(atoms)[source]¶ Get a selection of coordinates
ts[i]
return coordinates for the i’th atom (0-based)ts[start:stop:skip]
return an array of coordinates, where start, stop and skip correspond to atom indices,MDAnalysis.core.AtomGroup.Atom.index
(0-based)
-
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.
-
-
class
MDAnalysis.coordinates.base.
IObase
[source]¶ Base class bundling common functionality for trajectory I/O.
Changed in version 0.8: Added context manager protocol.
-
convert_forces_from_native
(force, inplace=True)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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.
-
units
= {'velocity': None, 'length': None, 'time': None}¶ dict with units of of time and length (and velocity, force, ... for formats that support it)
-
-
class
MDAnalysis.coordinates.base.
Reader
(filename, convert_units=None, **kwargs)[source]¶ Base class for trajectory readers that extends
ProtoReader
with a__del__()
method.New Readers should subclass
Reader
and properly implement aclose()
method, to ensure proper release of resources (mainly file handles). Readers that are inherently safe in this regard should subclassProtoReader
instead.See the Trajectory API definition in
MDAnalysis.coordinates.__init__
for the required attributes and methods.See also
ProtoReader
Changed in version 0.11.0: Most of the base Reader class definitions were offloaded to
ProtoReader
so as to allow the subclassing of Readers without a__del__()
method. Created init method to create common functionality, all Reader subclasses must nowsuper()
through this class. Added attribute_ts_kwargs
, which is created in init. Provides kwargs to be passed toTimestep
-
class
MDAnalysis.coordinates.base.
ChainReader
(filenames, **kwargs)[source]¶ Reader that concatenates multiple trajectories on the fly.
Known issues
- Trajectory API attributes exist but most of them only reflect
the first trajectory in the list;
ChainReader.n_frames
,ChainReader.n_atoms
, andChainReader.fixed
are properly set, though - slicing not implemented
Changed in version 0.11.0: Frames now 0-based instead of 1-based
Changed in version 0.13.0:
time
now reports the time summed over each trajectory’s frames and individualdt
.Set up the chain reader.
Parameters: - *filenames* –
file name or list of file names; the reader will open all file names and provide frames in the order of trajectories from the list. Each trajectory must contain the same number of atoms in the same order (i.e. they all must belong to the same topology). The trajectory format is deduced from the extension of filename.
Extension: filenames are either single filename or list of file names in either plain file names format or (filename,format) tuple combination
- *skip* – skip step (also passed on to the individual trajectory readers); must be same for all trajectories
- *dt* – Passed to individual trajectory readers to enforce a common time difference between frames, in MDAnalysis time units. If not set, each reader’s dt will be used (either inferred from the trajectory files, or set to the reader’s default) when reporting frame times; note that this might mean an inconstant time difference between frames.
- *kwargs* – all other keyword arguments are passed on to each trajectory reader unchanged
Changed in version 0.8: The delta keyword was added.
Changed in version 0.13: The delta keyword was deprecated in favor of using dt.
-
active_reader
¶ Reader instance from which frames are being read.
-
frame
¶ Cumulative frame number of the current time step.
-
time
¶ Cumulative time of the current frame in MDAnalysis time units (typically ps).
- Trajectory API attributes exist but most of them only reflect
the first trajectory in the list;
-
class
MDAnalysis.coordinates.base.
Writer
[source]¶ Base class for trajectory writers.
See Trajectory API definition in
MDAnalysis.coordinates.__init__
for the required attributes and methods.-
convert_dimensions_to_unitcell
(ts, inplace=True)[source]¶ Read dimensions from timestep ts and return appropriate unitcell.
The default is to return
[A,B,C,alpha,beta,gamma]
; if this is not appropriate then this method has to be overriden.
-
has_valid_coordinates
(criteria, x)[source]¶ 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
-