6.23. XYZ trajectory reader — MDAnalysis.coordinates.XYZ

The XYZ format is a loosely defined, simple coordinate trajectory format. The implemented format definition was taken from the VMD xyzplugin and is therefore compatible with VMD.

Note the following:

  • Comments are not allowed in the XYZ file (we neither read nor write them to remain compatible with VMD).

  • The atom name (first column) is ignored during reading.

  • The coordinates are assumed to be space-delimited rather than fixed width (this may cause issues - see below).

  • All fields to the right of the z-coordinate are ignored.

  • The unitcell information is all zeros since this is not recorded in the XYZ format.

Units

  • Coordinates are in Angstroms.

  • The length of a timestep can be set by passing the dt argument, it’s assumed to be in ps (default: 1 ps).

There appears to be no rigid format definition so it is likely users will need to tweak this class.

6.23.1. XYZ File format

Definition used by the XYZReader and XYZWriter (and the VMD xyzplugin from whence the definition was taken):

[ comment line            ] !! NOT IMPLEMENTED !! DO NOT INCLUDE
[ N                       ] # of atoms, required by this xyz reader plugin  line 1
[ molecule name           ] name of molecule (can be blank)                 line 2
atom1 x y z [optional data] atom name followed by xyz coords                line 3
atom2 x y z [ ...         ] and (optionally) other data.
...
atomN x y z [ ...         ]                                                 line N+2

Note

  • comment lines not implemented (do not include them)

  • molecule name: the line is required but the content is ignored at the moment

  • optional data (after the coordinates) are presently ignored

6.23.2. Classes

class MDAnalysis.coordinates.XYZ.XYZReader(filename, **kwargs)[source]

Reads from an XYZ file

Data
ts

Timestep object containing coordinates of current frame

Methods
len(xyz)

return number of frames in xyz

for ts in xyz:

iterate through trajectory

The XYZ file format follows VMD’s xyzplugin and is also described under XYZ format.

Changed in version 0.11.0: Frames now 0-based instead of 1-based. Added dt and time_offset keywords (passed to Timestep)

Writer(filename, n_atoms=None, **kwargs)[source]

Returns a XYZWriter for filename with the same parameters as this XYZ.

Parameters

  • filename (str) – filename of the output trajectory

  • n_atoms (int (optional)) – number of atoms. If none is given use the same number of atoms from the reader instance is used

  • **kwargs – See XYZWriter for additional kwargs

Return type

XYZWriter (see there for more details)

See also

XYZWriter

close()[source]

Close xyz trajectory file if it was open.

property n_atoms

number of atoms in a frame

units = {'length': 'Angstrom', 'time': 'ps'}

dict with units of of time and length (and velocity, force, … for formats that support it)

class MDAnalysis.coordinates.XYZ.XYZWriter(filename, n_atoms=None, convert_units=True, remark=None, **kwargs)[source]

Writes an XYZ file

The XYZ file format is not formally defined. This writer follows the VMD implementation for the molfile xyzplugin.

Notes

By default, the XYZ writer will attempt to use the input AtomGroup or Universe elements record to assign atom names in the XYZ file. If the elements record is missing, then the name record will be used. In the event that neither of these are available, the atoms will all be named X. Please see, the User Guide for more information on how to add topology attributes if you wish to add your own elements / atom names to a Universe.

Changed in version 1.0.0: Use elements attribute instead of names attribute, if present.

Changed in version 2.0.0: Support for passing timestep to the writer was deprecated in 1.0 and has now been removed. As a consequence, custom names can no longer be passed to the writer, these should be added to the Universe, or AtomGroup before invoking the writer.

Initialize the XYZ trajectory writer

Parameters

  • filename (str) – filename of trajectory file. If it ends with “gz” then the file will be gzip-compressed; if it ends with “bz2” it will be bzip2 compressed.

  • n_atoms (int (optional)) – Number of atoms in trajectory. By default assume that this is None and that this file is used to store several different models instead of a single trajectory. If a number is provided each written TimeStep has to contain the same number of atoms.

  • convert_units (bool (optional)) – convert quantities to default MDAnalysis units of Angstrom upon writing [True]

  • remark (str (optional)) – single line of text (“molecule name”). By default writes MDAnalysis version and frame

Changed in version 1.0.0: Removed default_remark variable (Issue #2692).

Changed in version 2.0.0: Due to the removal of timestep as an input for writing, the atoms parameter is no longer relevant and has been removed. If passing an empty universe, please use add_TopologyAttr to add in the required elements or names.

close()[source]

Close the trajectory file and finalize the writing

units = {'length': 'Angstrom', 'time': 'ps'}

dict with units of of time and length (and velocity, force, … for formats that support it)

write(obj)[source]

Write object obj at current trajectory frame to file.

Atom elements (or names) in the output are taken from the obj or default to the value of the atoms keyword supplied to the XYZWriter constructor.

Parameters

obj (Universe or AtomGroup) – The AtomGroup or Universe to write.

Changed in version 2.0.0: Deprecated support for Timestep argument has now been removed. Use AtomGroup or Universe as an input instead.