5.17. 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.

5.17.1. XYZ File format

Definiton 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
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, **kwargs)[source]

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

All values can be changed through keyword arguments.

Arguments:
filename

filename of the output DCD trajectory

Keywords:
atoms

names of the atoms (if not taken from atom groups)

Returns:

XYZWriter (see there for more details)

close()[source]

Close xyz trajectory file if it was open.

n_atoms

number of atoms in a frame

rewind()[source]

reposition on first frame

class MDAnalysis.coordinates.XYZ.XYZWriter(*args, **kwargs)[source]

Writes an XYZ file

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

Initialize the XYZ trajectory writer

Arguments:
filename

file name 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.

Keywords:
atoms

Provide atom names: This can be a list of names or an AtomGroup. If none is provided, atoms will be called ‘X’ in the output. These atom names will be used when a trajectory is written from raw Timestep objects which do not contain atom information.

If you write a AtomGroup with XYZWriter.write() then atom information is taken at each step and atoms is ignored.

remark

single line of text (“molecule name”)

close()[source]

Close the trajectory file and finalize the writing

write(obj)[source]

Write object obj at current trajectory frame to file.

obj can be a AtomGroup) or a whole Universe.

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

Arguments:
obj

AtomGroup or Universe

write_next_timestep(ts=None)[source]

Write coordinate information in ts to the trajectory