Multi-XYZ reader

A reader of multi-xyz files has been implemented in the FOX.io.read_xyz module. The .xyz fileformat is designed for storing the atomic symbols and cartesian coordinates of one or more molecules. The herein implemented FOX.io.read_xyz.read_multi_xyz() 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

FOX.io.read_xyz.read_multi_xyz(filename, return_comment=True, unit='angstrom')[source]

Read a (multi) .xyz file.

Parameters:
  • 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.
Returns:

  • \(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.
Raises:

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 MultiMolecule.properties["comments"].

Parameters:
  • 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 MultiMolecule.properties attribute.
  • read_comments (bool) – If True, extract all comment lines from the passed .xyz file and store them under properties.comments.
Returns:

A molecule constructed from filename.
Return type:

FOX.MultiMolecule
FOX.example_xyz: str = '/home/docs/checkouts/readthedocs.org/user_builds/auto-fox/checkouts/latest/FOX/data/Cd68Se55_26COO_MD_trajec.xyz'

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