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 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)[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.
Return type:

Union[Tuple[ndarray, Dict[str, List[int]]], Tuple[ndarray, Dict[str, List[int]], ndarray]]
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)[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 (str) – The path+filename of an .xyz file.
  • bonds (\(k*3\) np.ndarray [np.int64]) – 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) – 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.
Returns:

A MultiMolecule instance 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.