5.14. Gromacs TRR file IO — MDAnalysis.coordinates.TRR
¶
The Gromacs TRR trajectory format is a lossless format like
e.g. the DCD format (see DCD
) and
unlike the XTC
format, which stores
reduced precision coordinates. Therefore, if one wants to convert
to Gromacs trajectories without loss of precision then one should
use the TRR format.
The TRR format can store velocities and forces in addition to coordinates. It is also used by other Gromacs tools to store and process other data such as modes from a principal component analysis.
The TRR I/O interface uses libxdrfile2
to implement random access to frames. This works by initially building an
internal index of all frames and then using this index for direct
seeks. Building the index is triggered by
read_trr_numframes()
, which
typically happens when one accesses the TRRReader.numframes
attribute
for the first time. Building the index may take many minutes for large
trajectories but afterwards access is faster than with native Gromacs tools.
Changed in version 0.8.0: The 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).
Timestep
now correctly deals
with presence/absence of coordinate/velocity/force information on a
per-frame basis.
5.14.1. Tips and Tricks¶
5.14.1.1. Filling a TRR with PCA modes¶
The following recipe by Ramon Crehuet shows how to convert modes
stored in a NumPy-like array (e.g. from a PCA analysis with MMTK) to
a TRR usable by Gromacs. The idea is to manually fill a
Timestep
with the desired
values and then write it to a file with the appropriate
TRRWriter
. In order to
respect the Gromacs format for modes in a TRR file, one must write the
average coordinates in the first frame of the TRR and the modes into
subsequent ones. The mode number is stored in the
step
attribute
and the mode coordinates are filling the
_pos
attribute of
Timestep
:
# 'modes' is a mode object with M PCs, similar to a MxNx3 array
# 'xav' the average coordinates, a Nx3 array for N atoms
N = len(xav) # number of atoms, i.e. number of coordinates
W = Writer('pca.trr', numatoms=N) # TRR writer
ts = MDAnalysis.coordinates.TRR.Timestep(N) # TRR time step
# TRR handling requires 'has_x' to be set
# before low-level assignment to ts._pos.
# (likewise for 'has_v' and 'has_f' for assignment
# to ts._velocites and ts._forces). The default of
# the Timestep constructor is to set 'has_x' to True
# (but not 'has_v' or 'has_f') when only the number
# of atoms is passed.
for frame,mode in enumerate(modes[4:16]):
ts.lmbda = -1
if frame<=1:
ts._pos[:] = xav
else:
ts._pos[:] = mode.scaledToNorm(1.).array*10 # nm to angstroms
ts.frame = frame # manually change the frame number
ts.step = frame - 1
if frame <= 1:
ts.time = frame-1
else:
ts.time = mode.frequency
W.write(ts) # converts angstrom to nm for gmx
W.close()
5.14.2. Module reference¶
-
class
MDAnalysis.coordinates.TRR.
Timestep
(arg, **kwargs)[source]¶ Timestep for a Gromacs TRR trajectory.
The Timestep can be initialized with arg being
- an integer (the number of atoms)
- another
Timestep
instance, in which case a copy is made; attention: loss of attributes that do not exist within the TRRTimestep
may occur; - a
numpy.ndarray
of shape(numatoms, 3)
(for positions only) or(numatoms, 9)
(for positions, velocities, and forces):positions = arg[:,:3]
,velocities = arg[:,3:6]
, andforces = arg[:,6:]
.
The constructor also takes the named arguments has_x, has_v, and has_f, which are used to set the
Timestep
flagshas_x
,has_v
, andhas_f
, described below. Depending on the arg use-case above, the defaults set for these flags will vary:- when arg is an integer
has_x
defaults toTrue
andhas_v
andhas_f
toFalse
. - when arg is another
Timestep
instance the flags will default to being copied from the passedTimestep
. If that instance has no ‘has_*’ flags the behavior is to assign them toTrue
depending on the existence of_velocities
and_forces
(_pos
is assumed to always be there, so in this casehas_x
defaults toTrue
). - when arg is a numpy array, the default flags will reflect what information is passed in the array.
TRR
Timestep
objects are now fully aware of the existence or not of coordinate/velocity/force information in frames, reflected in thehas_x
,has_v
, andhas_f
flags. Accessing either kind of information while the corresponding flag is set toFalse
wil raise aNoDataError
. Internally, however, the arrays are always populated, even when the flags areFalse
; upon creation of aTimestep
they are zero-filled, but this might not always be the case later on for properties flagged asFalse
if the sameTimestep
instance is used to read from a TRR frame.When doing low-level writing to
_pos
,_velocities
, orThe TRR :class:`Timestep
constructor allows for the named boolean arguments has_x, has_v, and has_f to be passed for automatic setting of the corresponding flag. An exception to this is assignment to the full property array thus:ts = MDAnalysis.coordinates.TRR.Timestep(N) # N being the number of atoms ts._velocities = vel_array # Where vel_array is an existing array of shape (N, DIM) # This will also automatically set 'has_v' to True.
Attempting to populate the array instead will, however, raise a NoDataError exception:
ts = MDAnalysis.coordinates.TRR.Timestep(N) # N being the number of atoms ts._velocities[:] = vel_array # This will fail if 'has_v' hasn't been set to True.
Changed in version 0.8.0: TRR
Timestep
objects are now fully aware of the existence or not of coordinate/velocity/force information in frames.-
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 relevent 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.
-
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)
-
volume
¶ volume of the unitcell
-
class
MDAnalysis.coordinates.TRR.
TRRReader
(filename, convert_units=None, sub=None, **kwargs)[source]¶ Read a Gromacs TRR trajectory.
Changed in version 0.8.0:
Timestep
objects returned from TRR files now havehas_x
,has_v
, andhas_f
flags reflecting whether coordinates/velocities/forces were read. Attempting to access such data when the corresponding flag is set toFalse
will raise aNoDataError
.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; ifFalse
, use retrieved offsets if available [False
]
Changed in version 0.9.0: New keyword refresh_offsets
-
OtherWriter
(filename, **kwargs)¶ Returns a writer appropriate for filename.
Sets the default keywords start, step and delta (if available). numatoms is always set from
Reader.numatoms
.See also
Reader.Writer()
andMDAnalysis.Writer()
-
Writer
(filename, **kwargs)¶ 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
()¶ Close xdr trajectory file if it was open.
-
close_trajectory
()¶ Specific implementation of trajectory closing.
-
convert_forces_from_native
(force, inplace=True)¶ In-place conversion of forces array force from native units to base units.
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)¶ In-place conversion of force array force from base units to native units.
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)¶ In-place conversion of coordinate array x from native units to base units.
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)¶ Conversion of coordinate array x from base units to native units.
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)¶ Convert time t from native units to base units.
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)¶ Convert time t from base units to native units.
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)¶ In-place conversion of velocities array v from native units to base units.
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)¶ In-place conversion of coordinate array v from base units to native units.
By default, the input v is modified in place and also returned.
New in version 0.7.5.
-
delta
¶ 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.
-
dt
¶ Time between two trajectory frames in picoseconds.
-
frame
¶ Frame number of the current time step.
This is a simple short cut to
Timestep.frame
.
-
load_offsets
(filename, check=False)¶ 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 (seeopen()
).
-
next
()¶ Forward one step to next frame.
-
numatoms
¶ 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
¶ 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.
See also
TrjReader.load_offsets()
andTrjReader.save_offsets()
-
open_trajectory
()¶ 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
()¶ Position at beginning of trajectory
-
save_offsets
(filename)¶ 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
-
time
¶ Time of the current frame in MDAnalysis time units (typically ps).
time =
Timestep.frame
*Reader.dt
-
totaltime
¶ Total length of the trajectory numframes * dt.
-
class
MDAnalysis.coordinates.TRR.
TRRWriter
(filename, numatoms, start=0, step=1, delta=None, precision=1000.0, remarks=None, convert_units=None)[source]¶ Write a Gromacs TRR trajectory.
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 casetime
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 ofMDAnalysis.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 towrite()
.-
close_trajectory
()¶ Specific implementation of trajectory closing.
-
convert_dimensions_to_unitcell
(ts)¶ Read dimensions from timestep ts and return Gromacs box vectors
-
convert_forces_from_native
(force, inplace=True)¶ In-place conversion of forces array force from native units to base units.
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)¶ In-place conversion of force array force from base units to native units.
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)¶ In-place conversion of coordinate array x from native units to base units.
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)¶ Conversion of coordinate array x from base units to native units.
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)¶ Convert time t from native units to base units.
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)¶ Convert time t from base units to native units.
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)¶ In-place conversion of velocities array v from native units to base units.
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)¶ In-place conversion of coordinate array v from base units to native units.
By default, the input v is modified in place and also returned.
New in version 0.7.5.
-
has_valid_coordinates
(criteria, x)¶ 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 <= maxArguments: - criteria
dictionary containing the max and min values in native units
- x
numpy.ndarray
of(x, y, z)
coordinates of atoms selected to be written out.
Returns: boolean