6.20. TRZ trajectory I/O — MDAnalysis.coordinates.TRZ
Classes to read IBIsCO / YASP TRZ binary trajectories, including
coordinates, velocities and more (see attributes of the Timestep
).
Data are read and written in binary representation but because this depends on the machine hardware architecture, MDAnalysis always reads and writes TRZ trajectories in little-endian byte order.
6.20.1. Classes
- class MDAnalysis.coordinates.TRZ.Timestep(n_atoms, **kwargs)[source]
Timestep data for one frame
- Methods
ts = Timestep(n_atoms)
create a timestep object with space for n_atoms
Changed in version 0.11.0: Added
from_timestep()
andfrom_coordinates()
constructor methods.Timestep
init now only accepts integer creation.n_atoms
now a read only property.frame
now 0-based instead of 1-based. Attributes status and step removed.Changed in version 2.0.0: Timestep now can be (un)pickled. Weakref for Reader will be dropped. Timestep now stores in to numpy array memory in ‘C’ order rather than ‘F’ (Fortran).
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.- frame
Index of current frame number (0 based)
- time
Current system time in ps
- n_atoms
Number of atoms in the frame (will be constant throughout trajectory)
- pressure
System pressure in pascals
- pressure_tensor
Array containing pressure tensors in order: xx, xy, yy, xz, yz, zz
- total_energy
Hamiltonian for the system in kJ/mol
- potential_energy
Potential energy of the system in kJ/mol
- kinetic_energy
Kinetic energy of the system in kJ/mol
- temperature
Temperature of the system in Kelvin
- 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
Note
The selection must be a 0 based
slice
or array of the atom indices in thisTimestep
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.
- property dimensions
View of unitcell dimensions (A, B, C, alpha, beta, gamma)
lengths a, b, c are in the MDAnalysis length unit (Å), and angles are in degrees.
- property 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.
- property 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.
- 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.
- property 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.
- property 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.
- property 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.
- property 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
- 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
NoDataError
when no position data present
- 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.
- property 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.
- property 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.
- property volume
volume of the unitcell
- class MDAnalysis.coordinates.TRZ.TRZReader(trzfilename, n_atoms=None, **kwargs)[source]
Reads an IBIsCO or YASP trajectory file
Note
Binary TRZ trajectories are always assumed to be written in little-endian byte order and are read as such.
Changed in version 0.11.0: Frames now 0-based instead of 1-based. Extra data (Temperature, Energies, Pressures, etc) now read into ts.data dictionary. Now passes a weakref of self to ts (ts._reader).
Changed in version 1.0.1: Now checks for the correct n_atoms on reading and can raise
ValueError
.Creates a TRZ Reader
- Parameters
trzfilename (str) – name of input file
n_atoms (int) – number of atoms in trajectory, must be taken from topology file!
convert_units (bool (optional)) – converts units to MDAnalysis defaults
- Raises
ValueError – If n_atoms or the number of atoms in the topology file do not match the number of atoms in the trajectory.
- Writer(filename, n_atoms=None)[source]
A trajectory writer with the same properties as this trajectory.
- property delta
MD integration timestep
- property n_atoms
Number of atoms in a frame
- property n_frames
Total number of frames in a trajectory
- property skip_timestep
Timesteps between trajectory frames
- class MDAnalysis.coordinates.TRZ.TRZWriter(filename, n_atoms, title='TRZ', convert_units=True)[source]
Writes a TRZ format trajectory.
Note
Binary TRZ trajectories are always written in little-endian byte order.
Create a TRZWriter
- Parameters
filename (str) – name of output file
n_atoms (int) – number of atoms in trajectory
title (str (optional)) – title of the trajectory; the title must be 80 characters or shorter, a longer title raises a ValueError exception.
convert_units (bool (optional)) – units are converted to the MDAnalysis base format; [
True
]
- class MDAnalysis.coordinates.TRZ.TRZReader(trzfilename, n_atoms=None, **kwargs)[source]
Reads an IBIsCO or YASP trajectory file
Note
Binary TRZ trajectories are always assumed to be written in little-endian byte order and are read as such.
Changed in version 0.11.0: Frames now 0-based instead of 1-based. Extra data (Temperature, Energies, Pressures, etc) now read into ts.data dictionary. Now passes a weakref of self to ts (ts._reader).
Changed in version 1.0.1: Now checks for the correct n_atoms on reading and can raise
ValueError
.Creates a TRZ Reader
- Parameters
trzfilename (str) – name of input file
n_atoms (int) – number of atoms in trajectory, must be taken from topology file!
convert_units (bool (optional)) – converts units to MDAnalysis defaults
- Raises
ValueError – If n_atoms or the number of atoms in the topology file do not match the number of atoms in the trajectory.
- Writer(filename, n_atoms=None)[source]
A trajectory writer with the same properties as this trajectory.
- property delta
MD integration timestep
- property n_atoms
Number of atoms in a frame
- property n_frames
Total number of frames in a trajectory
- property skip_timestep
Timesteps between trajectory frames
- class MDAnalysis.coordinates.TRZ.TRZWriter(filename, n_atoms, title='TRZ', convert_units=True)[source]
Writes a TRZ format trajectory.
Note
Binary TRZ trajectories are always written in little-endian byte order.
Create a TRZWriter
- Parameters
filename (str) – name of output file
n_atoms (int) – number of atoms in trajectory
title (str (optional)) – title of the trajectory; the title must be 80 characters or shorter, a longer title raises a ValueError exception.
convert_units (bool (optional)) – units are converted to the MDAnalysis base format; [
True
]