5.21.3. Common high-level Gromacs XDR functionality — MDAnalysis.coordinates.xdrfile.core

The MDAnalysis.coordinates.xdrfile.core module contains generic classes to access Gromacs XDR-encoded trajectory formats such as TRR and XTC.

A generic Gromacs trajectory is simply called “trj” within this module.

See also

MDAnalysis.coordinates.base for the generic MDAnalysis base classes and MDAnalysis.coordinates.xdrfile.libxdrfile2 for the low-level bindings to the XDR trajectories.

5.21.3.1. Generic xdr trj classes

The generic classes are subclassed to generate the specific classes for the XTC and TRR format.

Changed in version 0.8.0: The XTC/TRR I/O interface now uses libxdrfile2, which has seeking and indexing capabilities. Note that unlike libxdrfile before it, libxdrfile2 is distributed under the GNU GENERAL PUBLIC LICENSE, version 2 (or higher).

Changed in version 0.9.0: TrjReader now stores the offsets used for frame seeking automatically as a hidden file in the same directory as the source trajectory. These offsets are automatically retrieved upon TrjReader instantiation, resulting in substantially quicker initialization times for long trajectories. The ctime and filesize of the trajectory are stored with the offsets, and these are checked against the trajectory on load to ensure the offsets aren’t stale. The offsets are automatically regenerated if they are stale or missing.

Changed in version 0.11.0: Frames now 0-based instead of 1-based

class MDAnalysis.coordinates.xdrfile.core.Timestep(n_atoms, **kwargs)[source]

Timestep for a Gromacs trajectory.

Changed in version 0.11.0: Attributes status, lmbda, prec all stored in the data dictionary Native frame number now stored as _frame, was step

dimensions

unitcell dimensions (A, B, C, alpha, beta, gamma)

  • A, B, C are the lengths of the primitive cell vectors e1, e2, e3
  • alpha = angle(e1, e2)
  • beta = angle(e1, e3)
  • gamma = angle(e2, e3)
class MDAnalysis.coordinates.xdrfile.core.TrjReader(filename, sub=None, **kwargs)[source]

Generic base class for reading Gromacs trajectories inside MDAnalysis.

Derive classes and set TrjReader.format, TrjReader._read_trj and TrjReader._read_trj_atoms.

Example

reader = TrjReader(“file.trj”) for ts in reader:

print ts
Parameters:

*filename* – the name of the trr file.

Keywords:
sub

an numpy integer array of what subset of trajectory atoms to load into the timestep. Intended to work similarly to the ‘sub’ argument to Gromacs‘ trjconv.

This is usefull when one has a Universe loaded with only an unsolvated protein, and wants to read a solvated trajectory.

The length of this array must be <= to the actual number of atoms in the trajectory, and equal to number of atoms in the Universe.

refresh_offsets

if True, do not retrieve stored offsets, but instead generate new ones; if False, use retrieved offsets if available [False]

Changed in version 0.9.0: New keyword refresh_offsets

Changed in version 0.11.0: Renamed “delta” attribute to “dt” Now passes weakref of self to ts (as “_reader”)

Writer(filename, **kwargs)[source]

Returns a Gromacs TrjWriter for filename with the same parameters as this trajectory.

All values can be changed through keyword arguments.

Parameters:

*filename* – filename of the output trajectory

Keywords:
n_atoms

number of atoms

dt

Time interval between frames.

precision

accuracy for lossy XTC format as a power of 10 (ignored for TRR) [1000.0]

Returns:

appropriate TrjWriter

Changed in version 0.11.0: Changed “delta” keyword to “dt”

close()[source]

Close xdr trajectory file if it was open.

format = None

override to define trajectory format of the reader (XTC or TRR)

load_offsets(filename, check=False)[source]

Loads current trajectory offsets from pickled filename.

Checks if ctime and size of trajectory file matches that stored in pickled filename. If either one does not match (and check == True) then the offsets are not loaded. This is intended to conservatively avoid loading out-of-date offsets.

The offset file is expected to be a pickled dictionary with keys/values::
ctime
the ctime of the trajectory file
size
the size of the trajectory file
offsets
a numpy array of the offsets themselves
Parameters:

*filename* – filename of pickle file saved with save_offsets() with the frame offsets for the loaded trajectory

Keywords:
check

if False, ignore ctime and size check of trajectory file

Raises:

IOError if the file cannot be read (see open()).

n_atoms

The number of publically available atoms that this reader will store in the timestep.

If ‘sub’ was not given in the ctor, then this value will just be the actual number of atoms in the underlying trajectory file. If however ‘sub’ was given, then this value is the number specified by the ‘sub’ sub-selection.

If for any reason the trajectory cannot be read then a negative value is returned.

n_frames

Read the number of frames from the trajectory.

The result is cached. If for any reason the trajectory cannot be read then 0 is returned.

This takes a long time because the frames are counted by iterating through the whole trajectory. If the trajectory was previously loaded and saved offsets exist, then loading will be significantly faster.

open_trajectory()[source]

Open xdr trajectory file.

Returns:pointer to XDRFILE (and sets self.xdrfile)
Raises:IOError with code EALREADY if file was already opened or ENOENT if the file cannot be found
save_offsets(filename)[source]

Saves current trajectory offsets into filename, as a pickled object.

Along with the offsets themselves, the ctime and file size of the trajectory file are also saved. These are used upon load as a check to ensure the offsets still match the trajectory they are being applied to.

The offset file is a pickled dictionary with keys/values::
ctime
the ctime of the trajectory file
size
the size of the trajectory file
offsets
a numpy array of the offsets themselves
Parameters:*filename* – filename in which to save the frame offsets
units = {'length': 'nm', 'time': 'ps'}

units of time (ps) and length (nm) in Gromacs

class MDAnalysis.coordinates.xdrfile.core.TrjWriter(filename, n_atoms, start=0, step=1, dt=None, precision=1000.0, remarks=None, convert_units=None)[source]

Writes to a Gromacs trajectory file

(Base class)

Create a new TrjWriter

Parameters:
  • *filename* – name of output file
  • *n_atoms* – number of atoms in trajectory file
Keywords:
start

starting timestep frame; only used when dt is set.

step

skip in frames between subsequent timesteps; only used when dt is set.

dt

time between frames to use. If set will override any time information contained in the passed Timestep objects, which will otherwise be used. The time attribute defaults to a timestep of to setting the trajectory time at 1 ps per step if there is no time information.

precision

accuracy for lossy XTC format as a power of 10 (ignored for TRR) [1000.0]

convert_units

True: units are converted to the MDAnalysis base format; None selects the value of MDAnalysis.core.flags [‘convert_lengths’]. (see Flags)

Changed in version 0.8.0: The TRR writer is now able to write TRRs without coordinates/velocities/forces, depending on the properties available in the Timestep objects passed to write().

Changed in version 0.11.0: Keyword “delta” renamed to “dt”

convert_dimensions_to_unitcell(ts)[source]

Read dimensions from timestep ts and return Gromacs box vectors

format = None

override to define trajectory format of the reader (XTC or TRR)

units = {'length': 'nm', 'time': 'ps'}

units of time (ps) and length (nm) in Gromacs

write_next_timestep(ts=None)[source]

write a new timestep to the trj file

ts is a Timestep instance containing coordinates to be written to trajectory file