turbomoleio.core package<a class="headerlink" href="#turbomoleio-core-package" title="Link to this heading">

turbomoleio.core.base.get_mol_and_indices_frozen(string, cell_string=None, periodic_string=None, lattice_string=None, periodic_extension=5.0)[source]

Get the pymatgen Molecule and indices of the frozen atoms from a $coord datagroup.

Parameters:

string (str) – The string containing the list of coordinates.
cell_string (str) – The string containing the cell parameters. For 1D periodic systems, cell consists of a single number: “a” lattice parameter. For 2D periodic systems, cell consists of 3 numbers: “a” and “b” lattice parameters and Gamma angle between “a” and “b”. For 3D periodic systems, cell consists of 6 numbers: “a”, “b” and “c” lattice parameters and Alpha, Beta and Gamma angles between lattice parameters. Only cell_string or lattice_string should be set for periodic systems (not both).
periodic_string (str) – The string describing periodicity.
lattice_string (str) – The string containing the lattice parameters as a matrix. Only cell_string or lattice_string should be set for periodic systems (not both).
periodic_extension (float) – For 1D and 2D periodic systems, periodic_extension is the amount (in Angstroms) of artificially added vacuum in the Structure object in the non-periodic directions).

Returns:

molecule: a pymatgen molecule or structure (when cell and: periodic are provided).

frozen_indices: a set with the indices of the frozen atoms.

Return type:

namedtuple

turbomoleio.core.control module

Module with objects and functions to interact directly with a control file.

It also contains other objects related to the control file, e.g. gradient, energy, etc …

class turbomoleio.core.control.Control(string=None, dg_list=None)[source]

Bases: DataGroups

Represents the control string/file for TurboMole.

The Control class is used to store the parameters of a control file. Parameters in a control file are stored as “Data Groups”. A data group is a key-value pair storing data “value” for the specific “key”. Value may be a single number, a string or a series of strings, numbers or combinations thereof.

Initialize a Control class.

Parameters:

string – The control string (in the data group format). Usually read from file.
dg_list – List of the data groups in the control string/file.

add_cosmo(epsilon=None, nppa=None, nspa=None, disex=None, rsolv=None, routf=None, cavity=None, use_old_amat=None)[source]

Add the $cosmo datagroup to the control.

The keywords are used to set the cosmo options. If None all the options will not be written to the control file.

Parameters:

epsilon (float) – permittivity used for scaling of the screening charges.
nppa (int) – number of basis grid points per atom.
nspa (int) – number of segments per atom.
disex (float) – distance threshold for A matrix elements (Angstrom).
rsolv (float) – distance to outer solvent sphere for cavity construction (Angstrom).
routf (float) – factor for outer cavity construction in the outlying charge correction.
cavity (str) – acceptable values are “open” (leave untidy seams between atoms) and “closed” (pave intersection seams with segments).
use_old_amat (bool) – if True adds the use_old_amat to the $cosmo datagroup, i.e. uses A matrix setup of TURBOMOLE 5.7.

Returns:

None

cpc(dest_dir, force_overwrite=False)[source]

Copy the control file and all files referenced here.

This creates the destination folder if not already existing.

Parameters:

dest_dir (str) – path to the destination folder.
force_overwrite (bool) – if True files already present in the destination folder will be overwritten.

property energy

Get an Energy object with the data from the $energy data group.

This is None if the datagroup is absent/empty or if the file is missing.

classmethod from_file(filename='control')[source]

Create Control object reading from a given file.

Parameters:: filename (str) – Name of the file from which this Control object should be read, default is “control”.

classmethod from_metric(metric)[source]

Generate a new Control from a given metric.

The new Control object contains the metric in $redund_inp and an empty $coord.

Parameters:: metric (int) – the value of the metric.

get_charge()[source]

Extract the charge from the “$charge from xxx” datagroup.

Returns:: the charge in the control file. None if not present.
Return type:: float

get_shells(shells_type)[source]

Extract a Shell object for a specific type of shell.

Parameters:: shells_type – the type of shell. Can be “closed”, “alpha” or “beta”.
Returns:: An instance of Shells

get_subfiles_list()[source]

Extract the list of files referenced in the datagroups with “file directives”.

Files directives are of the form “file=xxx” or “file xxx”.

Returns:: list of files referenced in the datagroups.
Return type:: list

property gradient

Get a Gradient object with the data from the $grad data group.

This is None if the datagroup is absent/empty or if the file is missing.

property is_uhf: Determine if the $uhf datagroup is present in control.

remove_last_energy(filename='control', backup_suffix=None)[source]

Remove last energy step from the energy data group.

In addition to removing the last energy step, it writes the energy data group to the correct file, depending on the original location of the data group. N.B. if the energies are in control and not in an external file, this will call the to_file of the current instance of Control. If other modifications have been done to the dg_list will be written to the file as well.

Parameters:

filename (str) – name of the file to which the current instance of Control will be written in case the energies are control. If energies are in external file it will be ignored.
backup_suffix (str) – if not None a file named filename+backup_suffix will be created with the current content of Control.

Raises:

RuntimeError – if there is no energy step to be removed or if energy file is missing.

remove_last_gradient(filename='control', backup_suffix=None)[source]

Remove last gradient step from the grad data group.

In addition to removing the last gradient step, it writes the grad data group to the correct file, depending on the original location of the data group. N.B. if the gradients are in control and not in an external file, this will call the to_file of the current instance of Control. If other modifications have been done to the dg_list will be written to the file as well.

Parameters:

filename (str) – name of the file to which the current instance of Control will be written in case the gradients are control. If gradients are in external file it will be ignored.
backup_suffix (str) – if not None a file named filename+backup_suffix will be created with the current content of Control.

Raises:

RuntimeError – if there is no gradient step to be removed or if gradient file is missing.

set_disp(dispersion_correction)[source]

Set the dispersion correction.

Parameters:: dispersion_correction (str) – the name of the method used for the dispersion correction. Supported values are “DFT-D1”, “DFT-D2”, “DFT-D3” and “DFT-D3 BJ”, case insensitive. If None all the “disp” datagroup will be eliminated.
Returns:: None

to_file(filename='control')[source]

Write this Control object to a file.

If the file exists it will be overwritten.

Parameters:: filename (str) – Name of the file to which this Control object should be written.

class turbomoleio.core.control.Defaults[source]

Bases: object

Class collecting default values used by TM executables.

When some values are not present in the control file, some defaults are used.

METRIC = 3

class turbomoleio.core.control.Energy(scf=None, scfkin=None, scfpot=None, mp2=None)[source]

Bases: MSONable

Represents the “energy” data group of TurboMole.

Usually stored in the “energy” file or directly in the control file.

Construct Energy object.

Parameters:

scf (list) – energies from scf calculations.
scfkin (list) – kinetic contribution to the scf energy.
scfpot (list) – potential contribution to the scf energy.
mp2 (list) – mp2 contribution to the total energy (not counted in scf).

property delta_e

Get the variation of the total energy in the last step.

This is None if less than 2 steps are present.

classmethod from_file(filename='energy')[source]

Create Energy object reading from a given file.

Parameters:: filename (str) – Name of the file from which this Energy object should be read, default is “energy”.
Raises:: RuntimeError – if the energy file comes from a subfile and is missing.

classmethod from_string(string)[source]

Create Energy object reading from a string.

Parameters:: string (str) – the string of the “energy” datagroup.

property n_steps: Get the number of steps present.

plot(ax=None, **kwargs)[source]

Plot the evolution of the energies.

Parameters:

ax (Axes) – a matplotlib Axes or None if a new figure should be created.
kwargs – arguments passed to matplotlib plot function.

Returns:

A matplotlib Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.

class turbomoleio.core.control.Gradient(gradients=None, energies=None, molecules=None, periodicity=0, lattice_vectors=None, lattice_gradients=None)[source]

Bases: MSONable

Represents the “grad” data group of TurboMole.

Usually stored in the “gradient” file or directly in the control file.

Construct Gradient object.

Parameters:

gradients (list) – gradients for all the steps and all the atoms with shape nsteps*natoms*3.
energies (list) – total energies for each step.
molecules (list) – list of MoleculeSystem with coordinates for each step.
periodicity (int) – periodicity of the system: 0 (default) or 1/2/3 for calculations performed with riper.
lattice_vectors (list) – list of lattice vectors for each step. The number and size of each lattice vector depends on the periodicity. For 1-dimensional systems, a single lattice vector of size one.
lattice_gradients (list) – lattice gradients for all the steps.

classmethod from_file(filename='gradient')[source]

Create Gradient object reading from a given file.

Note: For periodic systems, the lattice gradients are usually either: in the control file directly or in a different file. One option is thus to initialize the Gradients object from the control file, which will then get the atom gradients from the $grad datagroup and the lattice gradient from the $gradlatt datagroup.

Parameters:: filename (str) – Name of the file from which this Gradient object should be read, default is “gradient”.

classmethod from_string(string, lattice_string=None)[source]

Create Gradient object reading from a given file.

Parameters:

string (str) – the string of the “grad” datagroup.
lattice_string (str) – the string of the “gradlatt” datagroup.

property last_grad_max

Get the value of the maximum value of the gradient in the last step.

This is None if no step is present.

property last_grad_norm

Get the value of the last gradient norm.

This is None if no step is present.

property max_gradients: Get norms of the largest gradients for each step.

property n_steps: Get the number of steps present.

property norms: Get total norm of the gradients for each step.

plot(**kwargs)[source]

Plot the evolution of the maximum and the norm of the gradient.

Parameters:: kwargs – arguments passed to matplotlib plot function.
Returns:: A matplotlib Figure

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.

class turbomoleio.core.control.Shells(states, occupations)[source]

Bases: MSONable

Object describing the occupation of a type of shells.

It can map $closed shells, $alpha shells and $beta shells ($open shells not supported). Handles integer, fractional and floating point occupations. Occupations are stored as Fraction objects Supports presence of the same irrep in multiple lines.

Construct Shells object.

Parameters:

states (list) – list of tuples (irrep, irrep_index) with the occupied states for each.
occupations (list) – list of Fraction with the occupations for each state.

as_dict()[source]: Get a JSON serializable dict representation of Shells.

classmethod from_dict(d)[source]

Generate an instance of Shell from a JSON serialized representation.

Parameters:: d (dict) – the dictionary with the data to initialize Shells
Returns:: A Shells instance

classmethod from_file(shells_type, filename='control')[source]

Generate an instance of Shells from a file containing the datagroup.

Parameters:

shells_type (str) – the type of shell. The supported type are “closed”, “alpha” or “beta”.
filename (str) – the name of the file.

Returns:

Shells

Raises:

ValueError – if the shell of the specified type is not present

classmethod from_string(string)[source]

Generate an instance of Shells from a string.

Examples of a string:

a1      1-3                      ( 2 )
b1      1,3                       ( 2 )
b2      1                        ( 2 )

Parameters:: string (str) – the string of the datagroup.
Returns:: Shells

property irreps: Get the set of irreducible representations.

to_datagroup()[source]

Generate a string that can be used to set the datagroup in control.

Returns:: The string of the data group.

property total_electrons

Get the total number of electrons present in all the shells.

Returns:: the total number of electrons.
Return type:: Fraction

turbomoleio.core.control.adg(data_group, data_block, filepath='control', backup_file=None)[source]

Add data_group with data_block from the control file specified by the path.

Comments and empty lines will be removed. The file will be overwritten.

Parameters:

data_group (str) – Data group (key) to be added. The dollar (“$”) sign will be automatically added if not present.
data_block (str) – Data block corresponding to the data group.
filepath (str) – path to the control file
backup_file (str) – filename to which the original file will be backed up. If None no backup will be created.

Returns:

None

Raises:

RuntimeError – if data_group already exists.

turbomoleio.core.control.cdg(data_group, data_block, filepath='control', backup_file=None)[source]

Replace an existing data_group with data_block from the control file.

Comments and empty lines will be removed. The file will be overwritten.

If data_block is None it is equivalent to kdg. To set a data group with no explicit value use and empty string for data_block (e.g. to add $uhf the input should be data_group=”uhf” and data_block=””).

Parameters:

data_group (str) – Data group (key) to be added. The dollar (“$”) sign will be automatically added if not present.
data_block (str) – Data block corresponding to the data group. If None it will simply kill_data_group for the specified data_group value.
filepath (str) – path to the control file
backup_file (str) – filename to which the original file will be backed up. If None no backup will be created.

Returns:

None

turbomoleio.core.control.cpc(dest_dir, force_overwrite=False, control_dir=None)[source]

Copy a control file and its referenced files to another folder.

The destination folder is created if it does not already exists.

Parameters:

dest_dir (str) – path to the destination folder.
force_overwrite (bool) – if True files already present in the destination folder will be overwritten.
control_dir (str) – path to the directory containing the control file and the other files to be copied. If None the current dir will be used.

turbomoleio.core.control.kdg(data_group, filepath='control', strict=True, backup_file=None)[source]

Remove data_group from the control file specified by the path.

Comments and empty lines will be removed. The file will be overwritten.

Parameters:

data_group (str) – Data group to be removed.
filepath (str) – path to the control file
strict (bool) – If True data_group should be an exact match. If False, any Data group starting with data_group will be removed.
backup_file (str) – filename to which the original file will be backed up. If None no backup will be created.

Returns:

None

turbomoleio.core.control.mdgo(data_group, options, filepath='control', backup_file=None)[source]

Modify a data group option.

Given a data group that allows several options on separate lines (e.g. $dft), this function updates the values of the options according to the dictionary provided. The option dictionary should have the form:

{"option_name1": "option_name1 option_value",
 "option_name2": "option_name2=option_value"}

The key will be used to identify the line to be modified and that line would be entirely replaced by the value. Since different options may be defined in different ways, no attempt is made here to identify the suitable format for the option. It is responsibility of the caller to specify the line for the option in the correct format.

If the datagroup is not present will be created with the specified options.

If the entire data group should be modified it would be safer to use change_data_group.

Parameters:

data_group (str) – Data group (key) to be changed. The dollar (“$”) sign will be automatically added if not present.
options (dict) – The options that should be added or updated. If the value of one key is None the option will be removed if present.
filepath (str) – path to the control file
backup_file (str) – filename to which the original file will be backed up. If None no backup will be created.

Returns:

None

turbomoleio.core.control.sdg(data_group, filepath='control', default=None, show_from_subfile=True, raise_if_multiple_subfiles=False, raise_if_missing_subfile=False, raise_if_regular_and_subfile=False)[source]

Show the data_group from the control file specified by the path.

Comments and empty lines will be removed. If the filepath is a full path (i.e. not just a file name), it will change directory to the specified one, so that the subfiles are correctly read.

Parameters:

data_group (str) – Data group to be removed.
filepath (str) – path to the control file
default (str) – the default value that will be returned if the data_group is not present in the list. Default is None.
show_from_subfile (bool) – If True, will show data_group from within the “subfile” if the data block contains a “file=FILENAME”. If False the “file=FILENAME” block is simply returned. This supposes that file exists in the current directory.
raise_if_multiple_subfiles (bool) – Whether to raise an error if multiple “file=” directives are present in this data group. If False, just returns the standard control data block.
raise_if_missing_subfile (bool) – Whether to raise an error if the subfile does not exist in the current directory or exists but is empty. If False, just returns the standard control data block.
raise_if_regular_and_subfile (bool) – Whether to raise an error if data group contains both a reference to a file with a “file=FILENAME” and regular data block options. If False, just returns the standard control data block.

Returns:

the value of the selected datagroup. None if no data_group is found.

Return type:

turbomoleio.core.control.sdgo(data_group, option, filepath='control', default=None)[source]

Show the option of a given data group.

Given a data group that allows several options on separate line (e.g. $dft), returns the value of the option provided.

Since each value may be defined in a different way, the returned value will include anything after the option specified. It is up to the caller determine if there are symbols like “=” that should be removed, depending on the data group and option that is queried.

Parameters:

data_group (str) – Data group (key) to be changed. The dollar (“$”) sign will be automatically added if not present.
option (str) – The options that should be returned.
filepath (str) – path to the control file.
default (str) – the default value that will be returned if the data_group or the option are not present in the list.

Returns:

The value of the option.

Return type:

turbomoleio.core.datagroups module

Utility module for the “data group” model of TurboMole.

This module contains utility functions to parse, manipulate and write files formatted using the “data group” convention of TurboMole. Examples of files that are written in this fashion are the “control” file, the “coord” file, the “basis” file and many other files written by TurboMole.

Files using the “data group” model of TurboMole are human readable ASCII files in which data is formally split into consistent “groups”. Each “data group” consists of a keyword starting with a dollar (“$”) sign (e.g. “$symmetry”, “$open shell”, “$optimize” …) and its associated data. The associated data can be empty or just one value/word but it can also be very large (e.g. molecular orbitals : “$scfmo” data group contained in the “mos” file).

A complete description of the data group model of TurboMole can be found in the user’s manual, as well as a description of all the keywords available.

class turbomoleio.core.datagroups.DataGroups(string=None, dg_list=None)[source]

Bases: MSONable

Generic class for data group formatted files and strings.

DataGroups is a generic class for parsing, manipulating and generating strings/files using the data group format of TurboMole.

Initialize a DataGroups class.

The DataGroups object defines a set of key-value-like pairs. A data group is a key starting with a dollar (“$”) sign. The value corresponding to the data group is called the data block. When initializing DataGroups from a string (e.g. reading a file), comments and/or unnecessary lines/spaces/… may be present in that string. In that case, the initial string is kept as a reference. Note that if changes are applied to the DataGroups object, the initial string is not updated as comments may interfere with the modifications. The actual string corresponding to the data group list (dg_list) is always in line with the data group list.

Parameters:

string (str) – A string in the data group format.
dg_list (list of str) – A list of the data groups.

add_data_group(data_group, data_block)[source]

Add data_group->`data_block` to this DataGroups object.

Parameters:

data_group (str) – Data group (key) to be added. The dollar (“$”) sign will be automatically added if not present.
data_block (str) – Data block corresponding to the data group.

Raises:

RuntimeError – if data_group already exists.

adg(data_group, data_block)

Add data_group->`data_block` to this DataGroups object.

Parameters:

data_group (str) – Data group (key) to be added. The dollar (“$”) sign will be automatically added if not present.
data_block (str) – Data block corresponding to the data group.

Raises:

RuntimeError – if data_group already exists.

as_dict()[source]: Return a dictionary representing the DataGroups object.

cdg(data_group, data_block)

Change the value of the data_group to the new data_block.

If the key is not present will be added.

It will first apply the kill_data_group and then add_data_group. Note that in the current implementation, the data group will be moved to the end of the data groups object (just before $end).

If data_block is None it is equivalent to kill_data_group. To set a data group with no explicit value use an empty string for data_block (e.g. to add $uhf the input should be data_group=”uhf” and data_block=””).

Parameters:

data_group (str) – Data group (key) to be changed. The dollar (“$”) sign will be automatically added if not present.
data_block (str) – Data block corresponding to the data group. If None it will simply kill_data_group for the specified data_group value.

change_data_group(data_group, data_block)[source]

Change the value of the data_group to the new data_block.

If the key is not present will be added.

It will first apply the kill_data_group and then add_data_group. Note that in the current implementation, the data group will be moved to the end of the data groups object (just before $end).

If data_block is None it is equivalent to kill_data_group. To set a data group with no explicit value use an empty string for data_block (e.g. to add $uhf the input should be data_group=”uhf” and data_block=””).

Parameters:

data_group (str) – Data group (key) to be changed. The dollar (“$”) sign will be automatically added if not present.
data_block (str) – Data block corresponding to the data group. If None it will simply kill_data_group for the specified data_group value.

compare(datagroups, tol=None, ignored_dg=None, return_all_diffs=False)[source]

Compare the current object with another DataGroups.

Aside from the datagroups that should be ignored, (define in the ignored_dg argument), the two should contain the same amount of elements in dg_list and each one from the current object should have a matching elements in the one that is passed as argument. To match two strings should have the same number of lines. Each line should have the same number of chunks. Each chunk should match exactly as a string, except if they are numbers. In that, if a tol is specified they will be converted to float and their difference should be lower than the tolerance.

If the two objects match None will be returned, otherwise a message describing the property that caused the match to fail.

Note that, given the variety of notations supported by Turbomole, this function is to be intended more for testing purposes rather than as a complete tool to guarantee the equivalence of two control file.

Parameters:

datagroups (DataGroups) – a Datagroups that should match with the current instance.
tol (float) – the tolerance allowed when comparing numbers. If None even the number should match as strings.
ignored_dg (list) – a list of datagroups that should be ignored for the comparison. It is expected to be the name of the datagroup, thus starting with a “$”. If the “$” symbol is not present will be added before trying to match the datagroup to skip.
return_all_diffs (bool) – If True, a list of all differences is returned. If False (default), a string describing the first source of difference found is returned.

Returns:

None if the results match or a string describing a source of difference: otherwise (if return_all_diffs is False) or a list of all differences (if return_all_diffs is True).

classmethod empty()[source]

Create an empty DataGroups object.

An empty DataGroups object only contains the “$end” data group.

classmethod from_dict(d)[source]: Create DataGroups object from a dictionary.

classmethod from_file(filename)[source]

Create DataGroups object reading from a given file.

Parameters:: filename (str) – Name of the file from which this DataGroups object should be read.

kdg(data_group, strict=True)

Remove data_group from this DataGroups object.

Parameters:

data_group (str) – Data group to be removed.
strict (bool) – If True data_group should be an exact match. If False, any Data group starting with data_group will be removed.

kill_data_group(data_group, strict=True)[source]

Remove data_group from this DataGroups object.

Parameters:

data_group (str) – Data group to be removed.
strict (bool) – If True data_group should be an exact match. If False, any Data group starting with data_group will be removed.

mdgo(data_group, options)

Modify a data group option.

Given a data group that allows several options on separate line (e.g. $dft), updates the values of the options according to the dictionary provided. The option dictionary should have the form:

{"option_name1": "option_name1 option_value",
 "option_name2": "option_name2=option_value"}

The key will be used to identify the line to be modified and that line would be entirely replaced by the value. Since different options may be defined in different ways, no attempt is made here to identify the suitable format for the option. It is responsibility of the caller to specify the line for the option in the correct format.

If the datagroup is not present will be created with the specified options.

If the entire data group should be modified it would be safer to use change_data_group.

Parameters:

data_group (str) – Data group (key) to be changed. The dollar (“$”) sign will be automatically added if not present.
options (dict) – The options that should be added or updated. If the value of one key is None the option will be removed if present.

modify_data_group_options(data_group, options)[source]

Modify a data group option.

Given a data group that allows several options on separate line (e.g. $dft), updates the values of the options according to the dictionary provided. The option dictionary should have the form:

{"option_name1": "option_name1 option_value",
 "option_name2": "option_name2=option_value"}

The key will be used to identify the line to be modified and that line would be entirely replaced by the value. Since different options may be defined in different ways, no attempt is made here to identify the suitable format for the option. It is responsibility of the caller to specify the line for the option in the correct format.

If the datagroup is not present will be created with the specified options.

If the entire data group should be modified it would be safer to use change_data_group.

Parameters:

data_group (str) – Data group (key) to be changed. The dollar (“$”) sign will be automatically added if not present.
options (dict) – The options that should be added or updated. If the value of one key is None the option will be removed if present.

property ndg: Get the number of datagroups in this DataGroups object.

property number_of_data_groups: Get the number of datagroups in this DataGroups object.

sdg(data_group, strict=True, default=None, show_from_subfile=True, raise_if_multiple_subfiles=False, raise_if_missing_subfile=False, raise_if_regular_and_subfile=False)

Show data_group from this DataGroups object.

Parameters:

data_group (str) – Data group (key) to be added. The dollar (“$”) sign will be automatically added if not present.
strict (bool) – Whether data_group should be an exact match or if data groups starting with data_group are allowed.
default (str) – the default value that will be returned if the data_group is not present in the list. Default is None.
show_from_subfile (bool) – If True, will show data_group from within the “subfile” if the data block contains a “file=FILENAME”. If False the “file=FILENAME” block is simply returned. This supposes that file exists in the current directory.
raise_if_multiple_subfiles (bool) – Whether to raise an error if multiple “file=” directives are present in this data group. If False, just returns the standard control data block.
raise_if_missing_subfile (bool) – Whether to raise an error if the subfile does not exist in the current directory or exists but is empty. If False, just returns the standard data block.
raise_if_regular_and_subfile (bool) – Whether to raise an error if data group contains both a reference to a file with a “file=FILENAME” and regular data block options. If False, just returns the standard data block.

Returns:

the value of the selected datagroup. None if no data_group: is found.

Return type:

Raises:

RuntimeError – if multiple occurrences of data_group are found (and raise_if_multiple_subfiles is True), if the subfile is missing or empty (and raise_if_missing_subfile is True) or if regular data block options coexist with a reference to a subfile (and raise_if_regular_and_subfile is True).

sdgo(data_group, option, default=None)

Show a data group option.

Given a data group that allows several options on separate line (e.g. $dft), returns the value of the option provided.

Since each value may be defined in a different way, the returned value will include anything after the option specified. It is up to the caller determine if there are symbols like “=” that should be removed, depending on the data group and option that is queried.

Parameters:

data_group (str) – Data group (key) to be shown. The dollar (“$”) sign will be automatically added if not present.
option (str) – The options that should be returned.
default (str) – the default value that will be returned if the data_group or the option are not present in the list.

Returns:

The value of the option.

Return type:

show_data_group(data_group, strict=True, default=None, show_from_subfile=True, raise_if_multiple_subfiles=False, raise_if_missing_subfile=False, raise_if_regular_and_subfile=False)[source]

Show data_group from this DataGroups object.

Parameters:

data_group (str) – Data group (key) to be added. The dollar (“$”) sign will be automatically added if not present.
strict (bool) – Whether data_group should be an exact match or if data groups starting with data_group are allowed.
default (str) – the default value that will be returned if the data_group is not present in the list. Default is None.
show_from_subfile (bool) – If True, will show data_group from within the “subfile” if the data block contains a “file=FILENAME”. If False the “file=FILENAME” block is simply returned. This supposes that file exists in the current directory.
raise_if_multiple_subfiles (bool) – Whether to raise an error if multiple “file=” directives are present in this data group. If False, just returns the standard control data block.
raise_if_missing_subfile (bool) – Whether to raise an error if the subfile does not exist in the current directory or exists but is empty. If False, just returns the standard data block.
raise_if_regular_and_subfile (bool) – Whether to raise an error if data group contains both a reference to a file with a “file=FILENAME” and regular data block options. If False, just returns the standard data block.

Returns:

the value of the selected datagroup. None if no data_group: is found.

Return type:

Raises:

RuntimeError – if multiple occurrences of data_group are found (and raise_if_multiple_subfiles is True), if the subfile is missing or empty (and raise_if_missing_subfile is True) or if regular data block options coexist with a reference to a subfile (and raise_if_regular_and_subfile is True).

show_data_group_option(data_group, option, default=None)[source]

Show a data group option.

Given a data group that allows several options on separate line (e.g. $dft), returns the value of the option provided.

Since each value may be defined in a different way, the returned value will include anything after the option specified. It is up to the caller determine if there are symbols like “=” that should be removed, depending on the data group and option that is queried.

Parameters:

data_group (str) – Data group (key) to be shown. The dollar (“$”) sign will be automatically added if not present.
option (str) – The options that should be returned.
default (str) – the default value that will be returned if the data_group or the option are not present in the list.

Returns:

The value of the option.

Return type:

show_subfile_fname(data_group, raise_if_regular_and_subfile=False)[source]

Extract the name of the file from a datagroup.

Parameters:

data_group (str) – the string with the content of the data group.
raise_if_regular_and_subfile (bool) – if True will raise an error if the string contains both a file=FILENAME and other data. If False will return the filename anyway.

Returns:

the name of the file, None if no match for “file=filename” is found.

Return type:

(str)

Raises:

RuntimeError – if raise_if_regular_and_subfile is True and file=FILENAME is not the only content of the string.

to_file(filename)[source]

Write this DataGroups object to a file.

If the file exists it will be overwritten.

Parameters:: filename (str) – Name of the file to which this DataGroups object should be written.

turbomoleio.core.datagroups.cleanup_string(string, cleanup_types=None)[source]

Return a cleaned data groups string.

This function allows to clean up a data groups string. It allows to : - remove everything before the first dollar (“$”) sign, - remove blank lines, - remove spaces and tabs before “#” comments, - remove spaces and tabs before “$” signs.

Parameters:

string (str) – A string that should be in the “data group” format of TurboMole. Typically, this string is read from file (e.g. control, coord, basis, …).
cleanup_types (list of str, optional) – List of the cleanup types that should be performed. Valid types are “BEFORE_FIRST_DOLLAR”, “BLANK_LINES”, “LEADING_SPACES_DOLLAR” and “LEADING_SPACES_HASH”. Defaults to None in which case all four types of cleanup will be performed.

Returns:

A cleaned up string.

Return type:

Raises:

ValueError – If one of the cleanup_types is not valid, if there is no dollar (“$”) sign, if one of the dollar (“$”) or hash (“#”) signs is preceded by characters other than a space or a tab in a line or if there is no “$end” at the end of the file.

turbomoleio.core.datagroups.compare_datagroup_string(dg1, dg2, tol=None)[source]

Compare two datagroup strings as split from the DataGroups object.

Return True if the two match. The two strings should have the same number of lines. Each line should have the same number of chunks. Chunks will be separated using spaces and “=”. Each chunk should match exactly as a string, except if they are numbers. In that, if a tol is specified they will be converted to float and their difference should be lower than the tolerance.

Parameters:

dg1 (str) – the first datagroup string to be compared.
dg2 (str) – the second datagroup string to be compared.
tol (float) – the tolerance allowed when comparing numbers. If None even the number should match as strings.

Returns:

True if the string match.

Return type:

bool

turbomoleio.core.datagroups.remove_comments(string, comment_types=None)[source]

Return a data group string with comment lines removed.

Comments or additional information in TurboMole is typically specified in three different ways : a line starting with a hash (“#”) symbol, a data group with the keyword “$dummy” (can span multiple lines), anything after the “$end” keyword or anything after a hash (“#”) symbol (so-called “inline” comments). This function removes all types of comments in a data group formatted string. Note also that if a newline is added after the “$end” keyword if not present.

Parameters:

string (str) – A string that should be in the “data group” format of TurboMole. Typically, this string is read from file (e.g. control, coord, basis, …).
comment_types (list, optional) – List of the types of comments that should be removed. Valid types are “HASH_START”, “DUMMY”, “AFTER_END” and “HASH_INLINE”. Defaults to None in which case all four types of comments will be removed.

Returns:

A string without the comment lines.

Return type:

Raises:

ValueError – If one of the comment_types is not valid.

turbomoleio.core.datagroups.remove_dg_from_list(dg_to_remove, dg_list, strict=True)[source]

Return new list with a data group removed from the initial list.

This function will remove dg_to_remove from a list of data groups. If the data group is duplicated, all occurrences are removed. The standard usage is to remove the data group if it is an exact match (i.e. if the data group to be removed is followed by a space, a tab, a new line or a return). One can also remove all data groups starting with dg_to_remove by using strict=False.

Parameters:

dg_to_remove (str) – Data group to be removed from the list. Can be given with or without the dollar (“$”) sign.
dg_list (list) – List of strings. Each string should be a data group, i.e. should start with a dollar (“$”) sign and should not contain any other dollar sign.
strict (bool) – If False, all the data groups starting with dg_to_remove will be removed from the list. Otherwise, the data group is removed only if it is an exact match of dg_to_remove.

Returns:

The list of data groups with dg_to_remove removed.

Return type:

turbomoleio.core.datagroups.split_string_to_dg_list(string, cleanup_types=None, remove_comment_types=None)[source]

Split a string into a list of data groups.

Parameters:

string (str) – A string that should be in the “data group” format of TurboMole. Typically, this string is read from file (e.g. control, coord, basis, …).
cleanup_types (list of str, optional) – List of the cleanup types that should be performed before splitting the string into a list of data groups. Valid types are “BEFORE_FIRST_DOLLAR”, “HASH_START”, “DUMMY”, “AFTER_END” and “BLANK_LINES”. Defaults to None in which case all five types of comments will be removed.
remove_comment_types (list of str, optional) – List of the types of comments that should be removed before splitting the string into a list of data groups. Valid types are “BEFORE_FIRST_DOLLAR”, “HASH_START”, “DUMMY”, “AFTER_END” and “BLANK_LINES”. Defaults to None in which case all five types of comments will be removed.

Returns:

The list of data groups in the string.

Return type:

Raises:

ValueError – If there is no dollar (“$”) sign in the string, i.e. the string is not or incorrectly formatted with respect to the data group format of TurboMole.

Examples

>>> split_string_to_dg_list("$title\n$end\n")
['$title\n', '$end\n']
>>> split_string_to_dg_list("no dollar sign")
[]
>>> split_string_to_dg_list("\n\n$title\n"
...                         "$optimize\n"
...                         " internal   on\n"
...                         " redundant  on\n"
...                         " cartesian  off\n"
...                         " global     off\n"
...                         " basis      off\n")
['$title\n', '$optimize\n internal   on\n redundant  on\n cartesian  off\n global     off\n basis      off\n']

turbomoleio.core.molecule module

Module defining molecules in turbomoleio.

class turbomoleio.core.molecule.BondAngle(status, indices, weights=None, value=None)[source]

Class defining a bond angle internal coordinate (bend in TM).

Initialize InternalDefinition object.

Parameters:

status (str) – the status of the coordinate. Could be “k”, “f”, “d” or “i”
indices (list) – a lists of 0-based indices for the atoms involved in the internal coordinate. A list of lists if a linear combination should be considered. Stored internally as a list of lists.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as indices. If None will be set to a list of 1.0 with the same length as indices.
value (float) – value of the internal coordinate. Can be None.

compute_value(molecule)[source]

Calculate the value of the internal coordinate based on the given molecule.

Parameters:: molecule (Molecule) – a pymatgen Molecule.
Returns:: the calculated value of the internal coordinate.
Return type:: float

coord_str = 'bend'

coord_type = 'angle'

n_atoms = 3

class turbomoleio.core.molecule.CollinearBendingAngle(status, indices, weights=None, value=None)[source]

Class defining an collinear bending angle internal coordinate (linc in TM).

Initialize InternalDefinition object.

Parameters:

status (str) – the status of the coordinate. Could be “k”, “f”, “d” or “i”
indices (list) – a lists of 0-based indices for the atoms involved in the internal coordinate. A list of lists if a linear combination should be considered. Stored internally as a list of lists.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as indices. If None will be set to a list of 1.0 with the same length as indices.
value (float) – value of the internal coordinate. Can be None.

compute_value(molecule)[source]

Calculate the value of the internal coordinate based on the given molecule.

Parameters:: molecule (Molecule) – a pymatgen Molecule.
Returns:: the calculated value of the internal coordinate.
Return type:: float

coord_str = 'linc'

coord_type = 'angle'

n_atoms = 4

class turbomoleio.core.molecule.DihedralAngle(status, indices, weights=None, value=None)[source]

Class defining a dihedral angle internal coordinate (tors in TM).

Initialize InternalDefinition object.

Parameters:

status (str) – the status of the coordinate. Could be “k”, “f”, “d” or “i”
indices (list) – a lists of 0-based indices for the atoms involved in the internal coordinate. A list of lists if a linear combination should be considered. Stored internally as a list of lists.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as indices. If None will be set to a list of 1.0 with the same length as indices.
value (float) – value of the internal coordinate. Can be None.

compute_value(molecule)[source]

Calculate the value of the internal coordinate based on the given molecule.

Parameters:: molecule (Molecule) – a pymatgen Molecule.
Returns:: the calculated value of the internal coordinate.
Return type:: float

coord_str = 'tors'

coord_type = 'angle'

n_atoms = 4

class turbomoleio.core.molecule.Distance(status, indices, weights=None, value=None)[source]

Class defining a distance internal coordinate (stre in TM).

Initialize InternalDefinition object.

Parameters:

status (str) – the status of the coordinate. Could be “k”, “f”, “d” or “i”
indices (list) – a lists of 0-based indices for the atoms involved in the internal coordinate. A list of lists if a linear combination should be considered. Stored internally as a list of lists.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as indices. If None will be set to a list of 1.0 with the same length as indices.
value (float) – value of the internal coordinate. Can be None.

compute_value(molecule)[source]

Calculate the value of the internal coordinate based on the given molecule.

Parameters:: molecule (Molecule) – a pymatgen Molecule.
Returns:: the calculated value of the internal coordinate.
Return type:: float

coord_str = 'stre'

coord_type = 'length'

n_atoms = 2

class turbomoleio.core.molecule.InternalDefinition(status, indices, weights=None, value=None)[source]

Bases: ABC, MSONable

Abstract class for the definition of an internal coordinate.

This class follows the conventions established in turbomole.

Initialize InternalDefinition object.

Parameters:

status (str) – the status of the coordinate. Could be “k”, “f”, “d” or “i”
indices (list) – a lists of 0-based indices for the atoms involved in the internal coordinate. A list of lists if a linear combination should be considered. Stored internally as a list of lists.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as indices. If None will be set to a list of 1.0 with the same length as indices.
value (float) – value of the internal coordinate. Can be None.

abstract compute_value(molecule)[source]

Calculate the value of the internal coordinate based on the given molecule.

Parameters:: molecule (Molecule) – a pymatgen Molecule.
Returns:: the calculated value of the internal coordinate.
Return type:: float

coord_str = NotImplemented

coord_type = NotImplemented

classmethod from_string(string)[source]

Generate a concrete subclass of InternalDefinition from a tm string.

Parameters:: string (str) – a turbomole string used in the $intdef datagroup.
Returns:: An instance of a subclass of InternalDefinition.

static get_subclass_from_str(coord_str)[source]

Get the correct subclass based on the string description.

Parameters:: coord_str (str) – the string to determine the subclass.
Returns:: The appropriate subclass of InternalDefinition.

is_valid(molecule, tol=0.0001)[source]

Check if this internal definition is consistent with the molecule.

If the value of this internal coordinate is not None, it checks if it is consistent with the positions of the atoms in the given molecule.

Parameters:

molecule (Molecule) – a pymatgen Molecule.
tol (float) – the tolerance of the allowed difference between the internal and the calculated value.

Returns:

True if the values are consistent.

Return type:

bool

n_atoms = NotImplemented

to_string(index=1)[source]

Generate the turbomole string used in $intdef.

Parameters:: index (int) – the index that should be prepended to the generated string.
Returns:: A string that describes the coordinate and to be used inside $intdef.

class turbomoleio.core.molecule.InverseDistance(status, indices, weights=None, value=None)[source]

Class defining a inverse distance internal coordinate (invr in TM).

Initialize InternalDefinition object.

Parameters:

status (str) – the status of the coordinate. Could be “k”, “f”, “d” or “i”
indices (list) – a lists of 0-based indices for the atoms involved in the internal coordinate. A list of lists if a linear combination should be considered. Stored internally as a list of lists.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as indices. If None will be set to a list of 1.0 with the same length as indices.
value (float) – value of the internal coordinate. Can be None.

compute_value(molecule)[source]

Calculate the value of the internal coordinate based on the given molecule.

Parameters:: molecule (Molecule) – a pymatgen Molecule.
Returns:: the calculated value of the internal coordinate.
Return type:: float

coord_str = 'invr'

coord_type = 'length'

n_atoms = 2

class turbomoleio.core.molecule.MoleculeSystem(molecule, int_def=None, frozen_indices=None, user_defined_bonds=None)[source]

Bases: BaseSystem

Object providing information about the geometry of a molecule and its dynamics.

The geometry is described using a pymatgen Molecule, while internal definitions, constraints and frozen coordinates are provided as additional attributes.

Notably, since this can be used as an input for define to update the atomic coordinates, the constraints may be inconsistent with the actual cartesian coordinates. When parsed from a coord file obtained from define the information should be consistent. Methods are implemented to check such consistency.

Construct MoleculeSystem object.

Parameters:

molecule (Molecule) – a pymatgen Molecule object with the geometry of the system. Only supports ordered molecules.
int_def (list) – a list of InternalDefinition.
frozen_indices (set) – a set of indices (0-based) indicating atoms that should have fixed cartesian coordinates.
user_defined_bonds (set) – set of tuples with (index1, symbol, index2), where the atoms index are 0-based and the symbol can be “-” or “|”.

add_bond_angle(atom1, atom2, vertex, value=None, weights=None, status='f', add_user_def_bonds=True)[source]

Add a bond angle coordinate to the list of internal coordinates.

Typically used to add frozen coordinates.

Allows to set linear combinations of the coordinate. If a single value is given to the arguments it will be a simple internal coordinate. If a list of atoms and values are given this will produce a linear combination of those coordinates.

Parameters:

atom1 (int or list) – index (0-based) or list on indices of the first atom(s).
atom2 (int or list) – index (0-based) or list on indices of the second atom(s).
vertex (int or list) – index (0-based) or list on indices of the vertex.
value (float) – value of the distance.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as the atoms. If None will be set to a list of 1.0 with the same length as atoms.
status (str) – the status of the coordinate, can be “k”, “f”, “d” and “i”.
add_user_def_bonds (bool) – if True the pair of atoms will be added to the used defined bonds

add_dihedral(atom1, atom2, atom3, atom4, value=None, weights=None, status='f', add_user_def_bonds=True)[source]

Add a dihedral angle coordinate to the list of internal coordinates.

Typically used to add frozen coordinates.

Allows to set linear combinations of the coordinate. If a single value is given to the arguments it will be a simple internal coordinate. If a list of atoms and values are given this will produce a linear combination of those coordinates.

Parameters:

atom1 (int or list) – index (0-based) or list on indices of the first atom(s).
atom2 (int or list) – index (0-based) or list on indices of the second atom(s).
atom3 (int or list) – index (0-based) or list on indices of the third atom(s).
atom4 (int or list) – index (0-based) or list on indices of the fourth atom(s).
value (float) – value of the distance.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as the atoms. If None will be set to a list of 1.0 with the same length as atoms.
frozen (bool) – True if the coordinate should be frozen.
status (str) – the status of the coordinate, can be “k”, “f”, “d” and “i”.
add_user_def_bonds (bool) – if True the pair of atoms will be added to the used defined bonds.

add_distance(atom1, atom2, value=None, weights=None, status='f', add_user_def_bonds=True)[source]

Add a distance coordinate to the list of internal coordinates.

Typically used to add frozen coordinates.

Allows to set linear combinations of the coordinate. If a single value is given to the arguments it will be a simple internal coordinate. If a list of atoms and values are given this will produce a linear combination of those coordinates.

Parameters:

atom1 (int or list) – index (0-based) or list on indices of the first atom(s).
atom2 (int or list) – index (0-based) or list on indices of the second atom(s).
value (float) – value of the distance.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as the atoms. If None will be set to a list of 1.0 with the same length as atoms.
status (str) – the status of the coordinate, can be “k”, “f”, “d” and “i”.
add_user_def_bonds (bool) – if True the pair of atoms will be added to the user defined bonds.

as_dict()[source]

Return a JSON serializable dict representation of an object.

This overwrites base method to handle sets.

Returns:: json representation of the object.
Return type:: dict

classmethod from_dict(d)[source]

Generate object from JSON representation.

This overwrites base method to handle sets.

Parameters:: d (dict) – json representation of the object.
Returns:: An instance of MoleculeSystem.

classmethod from_file(filepath, fmt='')[source]

Create an instance from a file.

Could be a coord file or any other format supported by pymatgen Molecule.

Parameters:

filepath (str) – path to the file.
fmt (str) – the format of the data. could be “coord” for Turbomole coord file or any format supported in pymatgen Molecule. If None the code would try to infer it from the file name.

Returns:

An instance of MoleculeSystem.

classmethod from_string(string, fmt='coord')[source]

Create an instance from a string.

Could be the string of a coord file or any format supported by pymatgen Molecule.

Parameters:

string (str) – the string with the data.
fmt (str) – the format of the data. could be “coord” for Turbomole coord file or any format supported in pymatgen Molecule.

Returns:

An instance of MoleculeSystem.

get_int_def_inconsistencies(atol=0.0001, ltol=0.0001)[source]

Get inconsistent internal coordinates.

This returns a list of the internal coordinates whose values are not consistent with the values obtained from the molecule object.

Parameters:

atol (float) – tolerance allowed on distances (in bohr).
ltol (float) – tolerance allowed on angles (in degrees).

Returns:

list of inconsistent internal coordinates.

Return type:

has_inconsistencies(atol=0.0001, ltol=0.0001)[source]

Check if any inconsistency in internal coordinates is present.

Parameters:

atol (float) – tolerance allowed on distances (in bohr).
ltol (float) – tolerance allowed on angles (in degrees).

Returns:

True if inconsistencies are present.

Return type:

bool

property molecule: Return the pymatgen Molecule.

to_coord_string()[source]

Create the string of a coord file for this system.

Returns:: the string representing the system.
Return type:: str

class turbomoleio.core.molecule.OutOfPlaneAngle(status, indices, weights=None, value=None)[source]

Class defining an out-of-plane angle internal coordinate (outp in TM).

Initialize InternalDefinition object.

Parameters:

status (str) – the status of the coordinate. Could be “k”, “f”, “d” or “i”
indices (list) – a lists of 0-based indices for the atoms involved in the internal coordinate. A list of lists if a linear combination should be considered. Stored internally as a list of lists.
weights (float or list) – weight or list of weights in case of linear combinations of coordinates. Should have the same length as indices. If None will be set to a list of 1.0 with the same length as indices.
value (float) – value of the internal coordinate. Can be None.

compute_value(molecule)[source]

Calculate the value of the internal coordinate based on the given molecule.

Parameters:: molecule (Molecule) – a pymatgen Molecule.
Returns:: the calculated value of the internal coordinate.
Return type:: float

coord_str = 'outp'

coord_type = 'angle'

n_atoms = 4

class turbomoleio.core.molecule.PerpendicularBendingAngle(status, indices, weights=None, value=None)[source]