Table Of Contents

Previous topic

5.18.2. Gromacs TRR trajectory I/O — MDAnalysis.coordinates.xdrfile.TRR

Next topic

5.18.4. The Gromacs XTC/TRR library libxdrfile2

This Page

5.18.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.18.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.

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

Timestep for a Gromacs trajectory.

dimensions[source]

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, convert_units=None, 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
Arguments:
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

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.

Arguments:
filename

filename of the output trajectory

Keywords:
numatoms

number of atoms

delta

Time interval between frames.

precision

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

Returns:

appropriate TrjWriter

close()[source]

Close xdr trajectory file if it was open.

delta[source]

Time step length in ps.

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

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
Arguments:
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()).

numatoms[source]

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.

numframes[source]

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

Position at beginning of trajectory

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
Arguments:
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, numatoms, start=0, step=1, delta=None, precision=1000.0, remarks=None, convert_units=None)[source]

Writes to a Gromacs trajectory file

(Base class)

Create a new TrjWriter

Arguments:
filename

name of output file

numatoms

number of atoms in trajectory file

Keywords:
start

starting timestep; only used when delta is set.

step

skip between subsequent timesteps; only used when delta is set.

delta

timestep to use. If set will override any time information contained in the passed Timestep objects; otherwise that will be used. If in the latter case time is unavailable the TrjWriter will default to setting the trajectory time at 1 MDAnalysis unit (typically 1ps) per step.

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

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