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
andTrjReader._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; ifFalse
, 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.
Arguments: - 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”
-
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 (seeopen()
).
-
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.
See also
-
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
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, 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
Arguments: - 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. Thetime
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 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()
.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