Multi-XYZ reader

A reader of multi-xyz files has been implemented in the module. The .xyz fileformat is designed for storing the atomic symbols and cartesian coordinates of one or more molecules. The herein implemented function allows for the fast, and memory-effiecient, retrieval of the various molecular geometries stored in an .xyz file.

An .xyz file, example_xyz_file, can also be directly converted into a FOX.MultiMolecule instance.

>>> from FOX import MultiMolecule, example_xyz

>>> mol = MultiMolecule.from_xyz(example_xyz)

>>> print(type(mol))
<class 'FOX.classes.multi_mol.MultiMolecule'>

API, return_comment=True, unit='angstrom')[source]

Read a (multi) .xyz file.

  • filename (str) – The path+filename of a (multi) .xyz file.

  • return_comment (bool) – Whether or not the comment line in each Cartesian coordinate block should be returned. Returned as a 1D array of strings.

  • unit (str) – The unit of the to-be returned array.


  • \(m*n*3\) np.ndarray [np.float64], dict [str, list [int]] and

  • (optional) \(m\) np.ndarray [str] –

    • A 3D array with Cartesian coordinates of \(m\) molecules with \(n\) atoms.

    • A dictionary with atomic symbols as keys and lists of matching atomic indices as values.

    • (Optional) a 1D array with \(m\) comments.


.XYZError – Raised when issues are encountered related to parsing .xyz files.

classmethod MultiMolecule.from_xyz(filename, bonds=None, properties=None, read_comment=False)[source]

Construct a MultiMolecule instance from a (multi) .xyz file.

Comment lines extracted from the .xyz file are stored, as array, under["comments"].

  • filename (path-like object) – The path+filename of an .xyz file.

  • bonds (np.ndarray[np.int64], shape \((k, 3)\)) – An optional 2D array with indices of the atoms defining all \(k\) bonds (columns 1 & 2) and their respective bond orders multiplied by 10 (column 3). Stored in the MultieMolecule.bonds attribute.

  • properties (dict, optional) – A Settings object (subclass of dictionary) intended for storing miscellaneous user-defined (meta-)data. Is devoid of keys by default. Stored in the attribute.

  • read_comments (bool) – If True, extract all comment lines from the passed .xyz file and store them under properties.comments.


A molecule constructed from filename.

Return type


FOX.example_xyz = '/home/docs/checkouts/'

The path+filename of the example multi-xyz file.