6.17. AMBER trajectories —
AMBER trajectories are assumed to be in the following units:
- lengths in Angstrom (Å)
- time in ps (but see below)
AMBER trajectory coordinate frames are based on a custom
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
- n_atoms (int) – The total number of atoms this Timestep describes
- positions (bool, optional) – Whether this Timestep has position information [
- velocities (bool (optional)) – Whether this Timestep has velocity information [
- forces (bool (optional)) – Whether this Timestep has force information [
- reader (Reader (optional)) – A weak reference to the owning Reader. Used for when attributes require trajectory manipulation (e.g. dt)
- dt (float (optional)) – The time difference between frames (ps). If
timeis set, then dt will be ignored.
- time_offset (float (optional)) – The starting time from which to calculate time (in 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
velocities of the atoms as a
numpy.ndarrayof shape (n_atoms, 3); only available if the trajectory contains velocities or if the velocities =
Truekeyword has been supplied.
6.17.1. Binary NetCDF trajectories¶
Binary trajectories can also contain velocities and forces, and can record the
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.
NCDFReader(filename, n_atoms=None, mmap=None, **kwargs)¶
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
Forces are autodetected and read into the
Periodic unit cell information is detected and used to populate the
Timestep.dimensionsattribute. (If no unit cell is available in the trajectory, then
- only trajectories with time in ps and lengths in Angstroem are processed
- scale_factors are supported on read but are currently not kept/used when writing
The NCDF reader uses
scipymust be installed. It supports the mmap keyword argument (when reading):
mmap=Trueis memory efficient and directly maps the trajectory on disk to memory (using the
mmap=Falsemay consume large amounts of memory because it loads the whole trajectory into memory but it might be faster. The default is
mmap=Noneand then default behavior of
Truewhen filename is a file name,
Falsewhen filename is a file-like object.
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.
Changed in version 0.17.0: Uses
scipy.io.netcdfand supports the mmap kwarg.
Changed in version 0.20.0: Now reads scale_factors for all expected AMBER convention variables. Timestep variables now adhere standard MDAnalysis units, with lengths of angstrom, time of ps, velocity of angstrom/ps and force of kJ/(mol*Angstrom). It is noted that with 0.19.2 and earlier versions, velocities would have often been reported in values of angstrom/AKMA time units instead (Issue #2323).
Changed in version 1.0.0: Support for reading degrees units for cell_angles has now been removed (Issue #2327)
Returns a NCDFWriter for filename with the same parameters as this NCDF.
All values can be changed through keyword arguments.
Parameters: Returns: Return type:
Close trajectory; any further access will raise an
scipy.io.netcdfmodule may open netcdf files with
mmap=Truewas set. Hence any reference to an array must be removed before the file can be closed.
NCDFWriter(filename, n_atoms, start=0, step=1, dt=1.0, remarks=None, convert_units=True, **kwargs)¶
Writer for AMBER NETCDF format (version 1.0).
AMBER binary trajectories are automatically recognised by the file extension “.ncdf” or “.nc”.
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.
- filename (str) – name of output file
- n_atoms (int) – number of atoms in trajectory file
- start (int (optional)) – starting timestep
- step (int (optional)) – skip between subsequent timesteps
- dt (float (optional)) – timestep
- convert_units (bool (optional)) –
True: units are converted to the AMBER base format; [
- velocities (bool (optional)) – Write velocities into the trajectory [
- forces (bool (optional)) – Write forces into the trajectory [
scipy.io.netcdfto access AMBER files, which are in netcdf 3 format. Although
scipy.io.netcdfis very fast at reading these files, it is very slow when writing, and it becomes slower the longer the files are. On the other hand, the netCDF4 package (which requires the compiled netcdf library to be installed) is fast at writing but slow at reading. Therefore, we try to use
netCDF4for writing if available but otherwise fall back to the slower
AMBER users might have a hard time getting netCDF4 to work with a conda-based installation (as discussed in Issue #506) because of the way that AMBER itself handles netcdf: When the AMBER environment is loaded, the following can happen when trying to import netCDF4:
>>> import netCDF4 Traceback (most recent call last): File "<string>", line 1, in <module> File "/scratch2/miniconda/envs/py35/lib/python3.5/site-packages/netCDF4/__init__.py", line 3, in <module> from ._netCDF4 import * ImportError: /scratch2/miniconda/envs/py35/lib/python3.5/site-packages/netCDF4/_netCDF4.cpython-35m-x86_64-linux-gnu.so: undefined symbol: nc_inq_var_fletcher32
The reason for this (figured out via ldd) is that AMBER builds its own NetCDF library that it now inserts into
LD_LIBRARY_PATHwithout the NetCDF4 API and HDF5 bindings. Since the conda version of
netCDF4was built against the full NetCDF package, the one ld tries to link to at runtime (because AMBER requires
LD_LIBRARY_PATH) is missing some symbols. Removing AMBER from the environment fixes the import but is not really a convenient solution for users of AMBER.
At the moment there is no obvious solution if one wants to use
netCDF4and AMBER in the same shell session. If you need the fast writing capabilities of
netCDF4then you need to unload your AMBER environment before importing MDAnalysis.
FutureWarning– When writing. The
NCDFWritercurrently does not write any scale_factor values for the data variables. Whilst not in breach of the AMBER NetCDF standard, this behaviour differs from that of most AMBER writers, especially for velocities which usually have a scale_factor of 20.455. In MDAnalysis 2.0, the
NCDFWriterwill enforce scale_factor writing to either match user inputs (either manually defined or via the
NCDFReader) or those as written by AmberTools’s sander under default operation.
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
Changed in version 0.17.0: Use fast
netCDF4for writing but fall back to slow
netCDF4is not available.
Changed in version 0.20.1: Changes the cell_angles unit to the AMBER NetCDF convention standard of degree instead of the degrees written in previous version of MDAnalysis (Issue #2327).
Close the trajectory file.
6.17.2. ASCII TRAJ trajectories¶
AMBER ASCII trajectories are recognised by the suffix ‘.trj’, ‘.mdcrd’ or ‘.crdbox (possibly with an additional ‘.gz’ or ‘.bz2’).
In the AMBER community, these trajectories are often saved with the
suffix ‘.crd’ but this extension conflicts with the CHARMM CRD
format and MDAnalysis will not correctly autodetect AMBER “.crd”
trajectories. Instead, explicitly provide the
u = MDAnalysis.Universe("top.prmtop", "traj.crd", format="TRJ")
In this way, the AMBER
TRJReader is used.
- 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)
- 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).
- Velocities are currently not supported as ASCII trajectories.
TRJReader(filename, n_atoms=None, **kwargs)¶
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
ValueErrorif n_atoms is left at its default value of
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.
Changed in version 0.11.0: Frames now 0-based instead of 1-based. kwarg delta renamed to dt, for uniformity with other Readers
Close trj trajectory file if it was open.
Number of frames (obtained from reading the whole trajectory).
Open the trajectory for reading and load first frame.