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() and from_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()[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

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.

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.

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.

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 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)

See also

MDAnalysis.lib.mdamath.triclinic_vectors()

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.TRZ.TRZReader(trzfilename, n_atoms=None, **kwargs)[source]

Reads an IBIsCO or YASP trajectory file

ts

Timestep object containing coordinates of current frame

Type:TRZ.Timestep

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.

close()[source]

Close trz file if it was open

delta

MD integration timestep

n_atoms

Number of atoms in a frame

n_frames

Total number of frames in a trajectory

open_trajectory()[source]

Open the trajectory file

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]
close()[source]

Close if it was open

class MDAnalysis.coordinates.TRZ.TRZReader(trzfilename, n_atoms=None, **kwargs)[source]

Reads an IBIsCO or YASP trajectory file

ts

Timestep object containing coordinates of current frame

Type:TRZ.Timestep

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.

close()[source]

Close trz file if it was open

delta

MD integration timestep

n_atoms

Number of atoms in a frame

n_frames

Total number of frames in a trajectory

open_trajectory()[source]

Open the trajectory file

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]
close()[source]

Close if it was open