XYZ file format: molecule geometry

Introduction

The chemistry XYZ file holds the positions of the atoms of a molecule, one atom per line, as an element and three Cartesian coordinates. Open Babel’s description says that it is “widely supported by many programs, although no formal specification has been published”, so every reader decides for itself how strict to be.

The same extension is used for a different format, the text point cloud. The two are unrelated; a first line holding one whole number, followed by a comment line, is the usual sign of the chemistry format.

Structure

This follows Open Babel’s xyzformat.cpp (its description text and its reader and writer), read as raw source.

Line	Content	Notes
1	The number of atoms, `N`	A whole number. Open Babel reads it with `%u`, so text after the number is ignored, and it rejects a count of 0, a count that is not a number, and a count of 100,000,000 or more.
2	A title, comment or file name	Free text and may be empty. If it is empty, Open Babel uses the title of the caller instead. When reading, Open Babel cuts the title at the word `Energy` and trims white space.
3 to `N` + 2	One atom per line	An element, then X, Y and Z, separated by white space. The coordinates are in ångström.

Atom lines

The line is split on white space. A line with fewer than four items is an error; extra items are “ignored … which some applications add”, in Open Babel’s words.
The first item is looked up as an element symbol. If that gives nothing, Open Babel reads it as a whole number and takes it as the atomic number. This is the UniChem XYZ form, which writes the atomic number where XYZ writes the symbol. If neither works, the text is kept as an atom type.
The next three items are numbers read with C’s strtod, so a decimal point, a sign and an exponent are all accepted. An item that does not start with a number is an error.
Charge column. Some programs add a fifth value, a charge, “accepted by Jmol”. Open Babel takes it as a partial charge only if the line has more than five items and the fifth contains a decimal point.

Several frames

Open Babel states that “multiple molecules / frames can be contained within one file”. Each frame is a complete block of its own: the count line, the comment line and its atom lines, one after the other. After the last atom of a frame, Open Babel skips any empty lines before the next frame. Trajectories from molecular dynamics and geometry optimisations use this.

3
water
O   0.00000   0.00000   0.11779
H   0.00000   0.75545  -0.47116
H   0.00000  -0.75545  -0.47116
3
water, second frame
O   0.00000   0.00000   0.11800
H   0.00000   0.75600  -0.47200
H   0.00000  -0.75600  -0.47200

Two frames of a water molecule (illustrative values).

How Open Babel writes it

Line 1 is the atom count, line 2 the title (or, if the molecule has an energy larger than 0.001 in size, the title, a tab and Energy: with the energy as %15.7f).
Each atom is written with the C format %-3s%15.5f%15.5f%15.5f: the element symbol left-aligned in three characters, then each coordinate in a field 15 characters wide with five decimals.
Open Babel warns that some programs limit the atom count to three digits (it names Maestro).

12
benzene example
C        0.00000        1.40272        0.00000
H        0.00000        2.49029        0.00000
C       -1.21479        0.70136        0.00000

The start of Open Babel’s own example, a benzene molecule of 12 atoms (the first three atom lines).

Related forms

UniChem XYZ. The first column of each atom line is the atomic number instead of the element symbol. Open Babel’s reader accepts both.
Tinker XYZ. Open Babel lists “Tinker XYZ” as a similar format that “differ[s] slightly in the format of the files”. The sources read for this page do not say how, so the Tinker layout is not described here.
Extended XYZ. A superset described below.

Extended XYZ

Extended XYZ (extxyz) gives the comment line a structure and lets each atom line carry any number of named columns. The specification is in the README of the libAtoms extxyz repository, which also holds readers and writers for C, Fortran, Python and Julia. Everything below is from that README, read as raw text.

Frames

A file is one or more frames, with optional blank lines at the end but not between frames.
Line 1: a single integer N, with optional white space before and after it.
Line 2: zero or more key=value pairs for the whole frame. Spaces around = are allowed and are not part of the key or the value.
Lines 3 to N + 2: one atom per line, with M columns each.
Characters are the printable ASCII subset, one byte each. Allowed white space is the space and the tab. A blank line is allowed only as the second line of a plain XYZ frame and at the end of the file.

Values

A type is chosen from the text, in this order: integer, float, boolean, bare string, quoted string.

Type	Written as
Integer	Optional sign and decimal digits, with no leading zeros except a lone `0`
Float	Optional sign, digits with an optional decimal point, optional exponent starting with `d`, `D`, `e` or `E`
Boolean	`T`, `F`, `true`, `false`, `True`, `False`, `TRUE` or `FALSE`
String	Bare (no white space or special characters) or in double quotes. A string must be quoted if it contains white space, `=`, `"`, a comma, a square or curly bracket, a backslash or a newline. Inside quotes, a backslash escapes the next character, and `\n` stands for a newline
1-D array	`[` then values of one type separated by commas, then `]`. The older form, kept for compatibility, is values separated by white space inside `"…"`, `'…'` or `{…}`
2-D array	`[` then new-style 1-D arrays of the same length and type, separated by commas, then `]`

The Properties key

The special key Properties defines the columns of the atom lines. Its value is a list of triplets separated by colons, each name:type:count:

Part	Meaning
`name`	The name of the column or columns
`type`	`S` string, `I` integer, `R` real, `L` logical
`count`	How many consecutive columns, a whole number above 0

The counts must add up to M, the number of columns on each atom line. In atom lines, strings are “simple strings”: any run of characters other than white space. If no Properties key is found after full parsing, the file is treated as plain XYZ with four columns (species, then x, y, z), the whole second line is stored as a comment, and any columns after the fourth are not read.

An illustrative two-atom frame with a cell, written with the keys above:

2
Lattice="4.0 0.0 0.0 0.0 4.0 0.0 0.0 0.0 4.0" Properties=species:S:1:pos:R:3 pbc="T T T"
Cu   0.0   0.0   0.0
Cu   2.0   2.0   2.0

Key	Meaning
`Lattice`	The cell. A 3 × 3 matrix whose rows are the cell vectors (preferred), a 9-vector of the three vectors one after another (old files), or a 3-vector of the diagonal
`pbc`	Periodic boundaries: a vector of three booleans. The default is false in each direction if there is no `Lattice`, and true in each direction if there is one
`stress`, `virial`	A 6-vector in Voigt form, or a 3 × 3 matrix, which must be symmetric. A virial is converted to a stress by multiplying by −1 over the cell volume
Other per-frame results	Any other property of ASE’s calculator, stored under the same name

Property column	Meaning
`Z`	Atomic numbers
`species`	Element symbols (an error if not a valid chemical symbol)
`pos`	Positions
`mass`	Masses
`velo`	Momenta (the mass is taken from the atomic number if it is missing)
`initial_charges`, `initial_magmoms`	Stored under the same names
`local_energy`	Per-atom energies
`forces`	Forces
`magmoms`, `charges`	Stored under the same names

Not described

The page follows Open Babel’s reader and writer and the extxyz README. Nothing else was read.

Known, not yet covered

Reference: the Tinker XYZ layout, which Open Babel says differs slightly, and how other programs (Jmol, VMD, ASE’s plain xyz reader) treat counts that do not match the number of lines, extra columns and element names. Not yet read from their sources.
Reference: the extxyz README’s detailed regular expressions for numbers and strings, and the JSON-string convention for values that have no primitive form, are summarised, not listed in full.
Viewer: there is no XYZ viewer plugin yet; the explorer shows the file as text or bytes. When it exists it should tell this format from the point cloud by a first line holding one whole number followed by a comment line.

Unknown

Reference: any rule beyond what these two sources give. Plain XYZ has no published specification, so programs differ on blank lines, extra columns and title text.

Other formats that use .xyz

Text point cloud – The plainest point cloud: one line of X, Y and Z per point, often with extra columns.

.XYZ File Format