The coord file

In TURBOMOLE the coord file mainly contains the coordinates and the types of the atoms of the molecule that should be simulated. These information can be stored in pymatgen Molecule object. However there are a set of data, stored in different data groups, that provide further information about the geometry of the molecule, more precisely on the dynamic during a geometry optimization. For this reason in turbomoleio the coord file is represented through a turbomoleio.core.molecule.MoleculeSystem object. This has methods to read and generate a coord file that can be read by TURBOMOLE. Other file formats can be written taking advantage of the conversion from Molecule, but the output will be limited to the geometry of the molecule.

Note

TURBOMOLE is also capable of performing periodic calculations (1, 2 or 3-dimensional). The turbomoleio.core.molecule.MoleculeSystem object is only used for isolated systems, i.e. molecules. For periodic systems, the turbomoleio.core.periodic.PeriodicSystem should be used. See Periodic systems below for more information.

Internally the MoleculeSystem stores the geometry of the molecule using a pymatgen Molecule. This allows to exploit all the functionalities available in the pymatgen package. Other attributes are used to determine the values of other data groups. The simplest one is frozen_indices that determines which atoms should have the cartesian coordinates frozen. Translated in the coord file format the atoms with an f at the end of the coordinate line. For example with frozen_indices={0,2} the coord file will look like:

$coord
   -0.00000000000000      0.00000000000000      0.00000000000000  n  f
   -1.17616323936717      2.03717448857876      0.00000000000000  o
   -1.17616323936717     -2.03717448857876      0.00000000000000  o  f
    2.35232647873438      0.00000000000000      0.00000000000000  o
$end

Warning

For all the properties set in MoleculeSystem that refers to the indices of the atoms in the Molecule the convention is to use 0-based indices. This is true for frozen_indices, int_def and user_defined_bonds. The values used then in the coord file are 1-based instead. The conversion is done internally and you should always use 0-based indices in the python code.

An important and more complicated attribute is int_def that, if present, is used to fill the $intdef data group in the coord file. The attribute should be a list of internal coordinates given as subclasses of turbomoleio.core.molecule.InternalDefinition. Each subclass define a type of internal variable as defined from TURBOMOLE. For example the turbomoleio.core.molecule.Distance represent an internal variable of type stre. For the internal definitions that are most commonly used (stre, bend and tors) helper methods are provided in MoleculeSystem to append additional internal definition to an existing instance. For example the following python code:

m = MoleculeSystem.from_file("coord")
m.add_distance(atom1=0, atom2=1, value=1.5)
m.add_bond_angle(atom1=1, atom2=2, vertex=3, status="k")

will result in a coord file with this structure:

$coord
    -0.00000000000000 0.00000000000000 0.00000000000000 n
    -1.17616323936717 2.03717448857876 0.00000000000000 o
    -1.17616323936717 -2.03717448857876 0.00000000000000 o
    2.35232647873438 0.00000000000000 0.00000000000000 o
$intdef
    1 f 1.0 stre 1 2 val=1.5
    2 k 1.0 bend 2 3 4
$user-defined bonds
    1-2, 2-4, 3-4
$end

We stress again that the indices provided by the are 0-based as opposed in the one produced in the file, that are 1-based.

Warning

Following pymatgen conventions the Molecule object contained in MoleculeSystem has coordinates in angstrom, while the coord file contains coordinates in Bohr. The values provided for the internal definitions in the helper methods and in the InternalDefinition subclasses are written in $intdef as they are provided. Their units are the same as those defined in TURBOMOLE for that specific type of internal coordinate.

Note that the helper methods have also automatically set the $user-defined bonds. This brings us to the last attribute that can be set in MoleculeSystem: user_defined_bonds. This can contain a set of tuples of the form (index1, symbol, index2), where the atom indices are 0-based and the symbol can be - or |.

These attributes could be used to set the complete list of internal coordinates required by TURBOMOLE, but in general this would be more useful to define a few of them and call define afterwards with the ired option to let it generate a complete list of redundant internal coordinates. Given its potentially complicated structure, the $redundant data group is never parsed nor stored when reading a coord file that contains it.

Periodic systems

Warning

This is an experimental feature in turbomoleio. As a work-in-progress, the API might still change without prior notice.

For periodic systems, the coord file and the periodicity is represented through a turbomoleio.core.periodic.PeriodicSystem object. This has methods to read and generate a coord file that can be read by TURBOMOLE, as well as the corresponding periodic attributes.