iodata.formats.xyz module

XYZ file format.

Usually, the different frames in a trajectory describe different geometries of the same molecule, with atoms in the same order. The load_many and dump_many functions below can also handle an XYZ with different molecules, e.g. a molecular database.

The load_* and dump_* functions all accept the optional argument atom_columns. This argument fixes the meaning of the columns to be loaded from or dumped to an XYZ file. The following example defines, in addition to the conventional columns, also a column with atomic charges and three columns with atomic forces.

atom_columns = iodata.formats.xyz.DEFAULT_ATOM_COLUMNS + [
    # Atomic charges are stored in a dictionary atcharges and they key
    # refers to the name of the partitioning method.
    ("atcharges", "mulliken", (), float, float, "{:10.5f}".format),
    # Note that in IOData, the energy gradient is stored, which contains the
    # negative forces.
    ("atgradient", None, (3,), float,
     (lambda word: -float(word)),
     (lambda value: "{:15.10f}".format(-value)))
]

mol = load_one("test.xyz", atom_columns=atom_columns)
# The following attributes are present:
print(mol.atnums)
print(mol.atcoords)
print(mol.atcharges["mulliken"])
print(mol.atgradient)

When defining atom_columns, no columns can be skipped, such that all information loaded from a file can also be written back out when dumping it.

dump_many(f, datas, atom_columns=None)

Dump multiple frames into a XYZ file.

Parameters:

• f (TextIO) – A writeable file object.

• datas (Iterator[IOData]) – An iterator over IOData instances which must have the following attributes initialized: atcoords, atnums. If the following attributes are present, they are also dumped into the file: title.

• atom_columns – A list of atomic fields to be loaded. Each field as a tuple with the following items: attribute (str), key (None or str, when str the IOData attribute is a dict), shape for one atom (tuple), dtype, load_word (function taking string and returning a value with the correct type), dump_word (function taking a value and returning a formatted string).

Notes

dump_one(f, data, atom_columns=None)

Dump a single frame into a XYZ file.

Parameters:

• f (TextIO) – A writeable file object.

• data (IOData) – An IOData instance which must have the following attributes initialized: atcoords, atnums. If the following attributes are present, they are also dumped into the file: title.

• atom_columns – A list of atomic fields to be loaded. Each field as a tuple with the following items: attribute (str), key (None or str, when str the IOData attribute is a dict), shape for one atom (tuple), dtype, load_word (function taking string and returning a value with the correct type), dump_word (function taking a value and returning a formatted string).

Notes

load_many(lit, atom_columns=None)

Load multiple frames from a XYZ file.

Parameters:

• lit (LineIterator) – The line iterator to read the data from.

• atom_columns – A list of atomic fields to be loaded. Each field as a tuple with the following items: attribute (str), key (None or str, when str the IOData attribute is a dict), shape for one atom (tuple), dtype, load_word (function taking string and returning a value with the correct type), dump_word (function taking a value and returning a formatted string).

Yields:

result (dict) – A dictionary with IOData attributes. The following attribtues are guaranteed to be loaded: atcoords, atnums, title.

Return type:

Iterator[dict]

load_one(lit, atom_columns=None)

Load a single frame from a XYZ file.

Parameters:

• lit (LineIterator) – The line iterator to read the data from.

• atom_columns – A list of atomic fields to be loaded. Each field as a tuple with the following items: attribute (str), key (None or str, when str the IOData attribute is a dict), shape for one atom (tuple), dtype, load_word (function taking string and returning a value with the correct type), dump_word (function taking a value and returning a formatted string).

Return type:

dict

Returns:

result (dict) – A dictionary with IOData attributes. The following attributes are guaranteed to be loaded: atcoords, atnums, title.