5.14. AMBER trajectories — MDAnalysis.coordinates.TRJ
¶
AMBER can write ASCII trajectories (“traj”) and binary trajectories (“netcdf”). MDAnalysis supports reading of both formats and writing for the binary trajectories.
Note
Support for AMBER is experimental and feedback and contributions are highly appreciated. Use the Issue Tracker or get in touch on the MDAnalysis mailinglist.
Units
- lengths in Angstrom (Å)
- time in ps (but see below)
AMBER trajectory coordinate frames are based on a Timestep
object.
-
class
MDAnalysis.coordinates.TRJ.
Timestep
(n_atoms, **kwargs)[source]¶ AMBER trajectory Timestep.
The Timestep can be initialized with arg being an integer (the number of atoms) and an optional keyword argument velocities to allocate space for both coordinates and velocities;
Changed in version 0.10.0: Added ability to contain Forces
Create a Timestep, representing a frame of a trajectory
Parameters: *n_atoms* – The total number of atoms this Timestep describes
Keywords: - positions
Whether this Timestep has position information [
True
]- velocities
Whether this Timestep has velocity information [
False
]- forces
Whether this Timestep has force information [
False
]- dt
The time difference between frames (ps). If
time
is set, then dt will be ignored.- time_offset
The starting time from which to calculate time (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
-
_pos
¶ coordinates of the atoms as a
numpy.ndarray
of shape (n_atoms, 3)
-
_velocities
¶ velocities of the atoms as a
numpy.ndarray
of shape (n_atoms, 3); only available if the trajectory contains velocities or if the velocities =True
keyword has been supplied.
-
_forces
¶ forces of the atoms as a
numpy.ndarray
of shape (n_atoms, 3); only available if the trajectory contains forces or if the forces =True
keyword has been supplied.
5.14.1. ASCII TRAJ trajectories¶
ASCII AMBER TRJ coordinate files (as defined in AMBER TRJ format)
are handled by the TRJReader
. It is also possible to directly
read bzip2 or gzip compressed files.
AMBER ASCII trajectories are recognised by the suffix ‘.trj’ or ‘.mdcrd’ (possibly with an additional ‘.gz’ or ‘.bz2’).
Limitations
- Periodic boxes are only stored as box lengths A, B, C in an AMBER trajectory; the reader always assumes that these are orthorhombic boxes.
- The trajectory does not contain time information so we simply set the time step to 1 ps (or the user could provide it as kwarg dt)
- No direct access of frames is implemented, only iteration through the trajectory.
- Trajectories with fewer than 4 atoms probably fail to be read (BUG).
- If the trajectory contains exactly one atom then it is always assumed to be non-periodic (for technical reasons).
-
class
MDAnalysis.coordinates.TRJ.
TRJReader
(filename, n_atoms=None, **kwargs)[source]¶ AMBER trajectory reader.
Reads the ASCII formatted AMBER TRJ format. Periodic box information is auto-detected.
The number of atoms in a timestep must be provided in the n_atoms keyword because it is not stored in the trajectory header and cannot be reliably autodetected. The constructor raises a
ValueError
if n_atoms is left at its default value ofNone
.The length of a timestep is not stored in the trajectory itself but can be set by passing the dt keyword argument to the constructor; it is assumed to be in ps. The default value is 1 ps.
Functionality is currently limited to simple iteration over the trajectory.
Changed in version 0.11.0: Frames now 0-based instead of 1-based kwarg ‘delta’ renamed to ‘dt’, for uniformity with other Readers
-
n_frames
¶ Number of frames (obtained from reading the whole trajectory).
-
5.14.2. Binary NetCDF trajectories¶
The AMBER netcdf format make use of NetCDF (Network Common Data
Form) format. Such binary trajectories are recognized in MDAnalysis by
the ‘.ncdf’ suffix and read by the NCDFReader
.
Binary trajectories can also contain velocities and forces, and can record the
exact time
step. In principle, the trajectories can be in different units than the AMBER
defaults of ångström and picoseconds but at the moment MDAnalysis only supports
those and will raise a NotImplementedError
if anything else is detected.
-
class
MDAnalysis.coordinates.TRJ.
NCDFReader
(filename, n_atoms=None, **kwargs)[source]¶ Reader for AMBER NETCDF format (version 1.0).
AMBER binary trajectories are automatically recognised by the file extension ”.ncdf”.
The number of atoms (n_atoms) does not have to be provided as it can be read from the trajectory. The trajectory reader can randomly access frames and therefore supports direct indexing (with 0-based frame indices) and full-feature trajectory iteration, including slicing.
Velocities are autodetected and read into the
Timestep._velocities
attribute.Forces are autodetected and read into the
Timestep._forces
attribute.Periodic unit cell information is detected and used to populate the
Timestep.dimensions
attribute. (If no unit cell is available in the trajectory, thenTimestep.dimensions
will return[0,0,0,0,0,0]
.)Current limitations:
- only trajectories with time in ps and lengths in Angstroem are processed
- scale_factors are not supported (and not checked)
See also
Changed in version 0.10.0: Added ability to read Forces
Changed in version 0.11.0: Frame labels now 0-based instead of 1-based kwarg ‘delta’ renamed to ‘dt’, for uniformity with other Readers
-
Writer
(filename, **kwargs)[source]¶ Returns a NCDFWriter for filename with the same parameters as this NCDF.
All values can be changed through keyword arguments.
Parameters: *filename* – filename of the output NCDF trajectory
Keywords: - n_atoms
number of atoms
- dt
length of one timestep in picoseconds
- remarks
string that is stored in the title field
Returns:
-
class
MDAnalysis.coordinates.TRJ.
NCDFWriter
(filename, n_atoms, start=0, step=1, dt=1.0, remarks=None, convert_units=None, zlib=False, cmplevel=1, **kwargs)[source]¶ Writer for AMBER NETCDF format (version 1.0).
AMBER binary trajectories are automatically recognised by the file extension ”.ncdf”.
Velocities are written out if they are detected in the input
Timestep
. The trajectories are always written with ångström for the lengths and picoseconds for the time (and hence Å/ps for velocities).Unit cell information is written if available.
See also
Changed in version 0.10.0: Added ability to write velocities and forces
Changed in version 0.11.0: kwarg ‘delta’ renamed to ‘dt’, for uniformity with other Readers
Create a new NCDFWriter
Parameters: - *filename* – name of output file
- *n_atoms* – number of atoms in trajectory file
Keywords: - start
starting timestep
- step
skip between subsequent timesteps
- dt
timestep
- convert_units
True
: units are converted to the AMBER base format;None
selects the value ofMDAnalysis.core.flags
[‘convert_lengths’]. (see Flags)- zlib
compress data [
False
]- cmplevel
compression level (1-9) [1]
- velocities
Write velocities into the trajectory [
False
]- forces
Write forces into the trajectory [
False
]