index | modules | gitlab | page source

# TURBOMOLE

TURBOMOLE is a program package for ab initio electronic structure calculations. This interface integrates the TURBOMOLE code as a calculator in ASE.

## Setting up the environment

The TURBOMOLE package must be installed to use it with ASE. All modules and scripts from the TURBOMOLE packages must be available in $PATH and the variable $TURBODIR must be set. More information on how to install TURBOMOLE and to set up the environment can be found in the manual or the tutorial at the web site.

## Using the calculator

### Python interface

The constructor method has only keyword arguments that can be specified in any order. The list of accepted parameters with their types and default values is provided in the section “Parameters” below.

The following example demonstrates how to construct a Turbomole calculator object for a single-point energy calculation of a neutral singlet system:

    from ase.calculators.turbomole import Turbomole
    calc = Turbomole(multiplicity=1)

The selection of the method will be according to the default parameter values (see below), i.e. in this case DFT with b-p functional and the def-SV(P) basis set. After this the calculator can be associated with an existing Atoms object

    atoms.set_calculator(calc)

The recommended methods to access parameters and properties are the getter methods, i.e. these ones starting with get. The calculations then are triggered according to the principle of lazy evaluation, i.g.:

    energy = atoms.get_potential_energy()
    print(energy)

Alternatively all calculations necessary to perform a task (see `task` parameter below) can be explicitly started with the `calculate()` method:

    calc.calculate(atoms)

The getter methods (see below) check for convergence and eventually return `None` or an exception if the calculation has not converged. If the properties are read using the Turbomole object attributes then the convergence must be checked with:

    assert calc.converged

If the user wishes to use the input files (such as the control file) generated by module `define` before (or without) an actual calculation starts, the `initialize()` method has to be called explicitly after constructing the calculator and associating it with an atoms object, e.g.:

    from ase.build import molecule
    from ase.calculators.turbomole import Turbomole
    mol = molecule('C60')
    params = {
        'use resolution of identity': True,
        'total charge': -1,
        'multiplicity': 2
    }
    calc = Turbomole(**params)
    mol.set_calculator(calc)
    calc.initialize()

Optionally the calculator will be associated with the atoms object in one step with constructing the calculator:

    calc = Turbomole(atoms=mol, **params)

### Command-line interface

The command-line interface has limited capability. For example the keyword `task` is not effective due to the specific way the methods are called by `ase-run`. This example shows how to run a single-point DFT calculation of water with the PBE functional and with geometry taken from the database:

    ase-build H2O | ase-run turbomole --parameters="multiplicity=1,density functional=pbe"

Using the calculation output a second geometry optimization calculation with the BFGS optimizer from ASE can be started using the `restart` keyword:

    ase-build H2O | ase-run turbomole --parameters="restart=True" -f 0.02

## Reading output

### Properties

The implemented properties are described in the following table.

Property | Type | Getter method | Storage | Task
--- | --- | --- | --- | ---
total energy | float | get_potential_energy(), get_property(‘energy’) | e_total | any task
forces | np.array | get_forces(), get_property(‘forces’) | forces | gradient
dipole moment | np.array | get_dipole_moment(), get_property(‘magmom’) | dipole | any task
charges | np.array | get_charges(), get_property(‘charges’) | charges | any task
<S2> | float | get_results | results | any task
normal modes | list | get_results | results | frequencies
mode frequencies | list | get_results | results | frequencies
gradient | list | get_results | results | gradient, optimize
hessian | list | get_results | results | frequencies
molecular orbitals | list | get_results | results | any task
occupancies | list | get_results | results | any task

### Metadata

Additionally, some useful information can be read with the calculator using the functions `read_version()`, `read_datetime()`, `read_runtime()`, `read_hostname()`. Then the respective data can be retrieved using the version, datetime, runtime and hostname attributes. Example:

    calc.read_runtime()
    print(calc.runtime)

### Restart mode

The restart mode can be used either to start a calculation from the data left from previous calculations or to analyze or post-process these data. The previous run may have been performed without ASE but the working directory of the job should contain the control file and all files referenced in it. In addition, the standard output will be searched in files beginning with job. and ending with .out but this is optional input, mainly to extract job datetime, runtimes, hostname and TURBOMOLE version. After constructing the calculator object (where params dictionary is optional):

    calc = Turbomole(restart=True, **params)

the data left from the previous calculations can be queried, for example:

    from ase.visualize import view
    view(calc.atoms)
    print(calc.converged)
    print(calc.get_potential_energy())

A previous calculation may have crashed or not converged. Also in these cases all data that is available will be retrieved but the `calc.converged` will be set to `False`. The calculation can be continued without any parameter modifications (for example if it has exceeded the job maximum run time and was interrupted) or with better convergence parameters specified in `params` dictionary. Finally, another calculation task can be started beginning from the data left from a converged previous one, specifying a new `task` parameter:

    calc = Turbomole(restart=True, task='gradient', **params)

### Policies for files in the working directory

- When the calculator is constructed in restart mode (i.e. `restart=True`) and with no other parameters, then no files will be created, deleted or modified in the working directory.
- When the calculator is created in normal (i.e. `restart=False`) mode then all TURBOMOLE related files found in the working directory will be deleted.
- When the calculator is created with `restart=True` and other parameters, the control file might be modified. In particular, if `define_str`, `control_input` or `control_kdg` are specified or `initialize()` is called then the control file will be modified.
- When `calculate()`, `get_potential_energy()`, `get_forces()` etc. are called in restart mode, the control file will be modified if the previous calculation has not converged.
- When an atoms object is associated with the calculator or any calculator method is called with an atoms object specified, then the calculator will be reset and all TURBOMOLE related files found in the working directory will be deleted if atoms is different (tol=1e-2) from the internal atoms object or if internal coordinates are used and the internal and the supplied atoms positions are different (tol=1e-13). The coord file will be changed only if the atoms positions are different (tol=1e-13).

## Parameters

The following table provides a summary of all parameters and their default values.

Name | Type | Default | Units | Updateable
--- | --- | --- | --- | ---
restart | bool | False | None | True
define_str | str | None | None | True
control_kdg | list | None | None | True
control_input | list | None | None | True
automatic orbital shift | float | 0.1 | eV | True
basis set name | str | def-SV(P) | None | False
closed-shell orbital shift | float | None | eV | True
damping adjustment step | float | None | None | True
density convergence | float | None | None | True
density functional | str | b-p | None | True
energy convergence | float | None | eV | True
esp fit | str | None | None | True
fermi annealing factor | float | 0.95 | None | True
fermi final temperature | float | 300 | Kelvin | True
fermi homo-lumo gap criterion | float | 0.1 | eV | True
fermi initial temperature | float | 300 | Kelvin | True
fermi stopping criterion | float | 0.001 | eV | True
force convergence | float | None | eV/Angstrom | True
geometry optimization iterations | int | None | None | True
grid size | str | m3 | None | True
ground state | bool | True | None | False
initial damping | float | None | None | True
initial guess | None | eht | None | False
minimal damping | float | None | None | True
multiplicity | int | None | None | False
non-automatic orbital shift | bool | False | None | True
numerical hessian | dict | None | None | True
point group | str | c1 | None | False
ri memory | int | 1000 | Megabyte | True
scf energy convergence | float | None | eV | True
scf iterations | int | 60 | None | True
task | str | energy | None | True
title | str | ‘’ | None | False
total charge | int | 0 | None | False
uhf | bool | None | None | False
use basis set library | bool | True | None | False
use dft | bool | True | None | False
use fermi smearing | bool | False | None | True
use redundant internals | bool | False | None | False
use resolution of identity | bool | False | None | False

The attribute `Updateable` specifies whether it is possible to change a parameter upon restart. The `restart` keyword tells the calculator whether to restart from a previous calculation. The optional `define_str` is a string of characters that would be entered in an interactive session with module `define`, i.e. this is the stdin for running module `define`. The `control_kdg` is an optional list of data groups in control file to be deleted after running module `define` and `control_input` is an optional list of data groups to be added to control file after running module `define`.

The parameter `initial guess` can be either the strings eht (extended Hückel theory) or hcore (one-electron core Hamiltonian) or a dictionary {‘use’: ‘<path/to/control>’} specifying a path to a control file with the molecular orbitals that should be used as initial guess.

If `numerical hessian` is defined then the force constant matrix will be computed numerically using the script NumForce. The keys can be ‘central’ indicating use of central differences (type bool) and ‘delta’ specifying the coordinate displacements in Angstrom (type float).

Some parameter names contain spaces. This means that the preferred way to pass the parameters is to construct a dictionary, for example:

    params = {'task': 'optimize',
              'use resolution of identity': True,
              'ri memory': 2000,
              'scf iterations': 80,
              'force convergence': 0.05}
    calc = Turbomole(**params)

Using the `todict()` method, the parameters of an existing Turbomole calculator object can be stored in a flat dictionary and then re-used to create a new Turbomole calculator object:

    params = calc.todict()
    new_calc = Turbomole(**params)

This is especially useful if the calc object has been created in restart mode or retrieved from a database.

## Examples

### Single-point energy calculation

This script calculates the total energy of H2:

ase/test/turbomole/turbomole_H2.py.

### Nudged elastic band calculation

The example demonstrates a proton transfer barrier calculation in H3O2-:

ase/test/turbomole/turbomole_h3o2m.py.

### Single-point gradient calculation of Au13-

This script demonstrates the use of the restart option.

ase/test/turbomole/turbomole_au13.py.

### Geometry optimization and normal mode analysis for H2O

ase/test/turbomole/turbomole_h2o.py.

### QMMM simulation

The following example demonstrates how to use the Turbomole calculator in simple and explicit QMMM simulations on the examples of a water dimer partitioned into an MM and a QM region.

ase/test/turbomole/turbomole_qmmm.py.

The MM region is treated within a TIP3P model in the MM calculator and as an array of point charges in the QM calculation. The interaction between the QM and MM regions, used in the explicit QMMM calculator, is of Lennard-Jones type.

The point charge embedding functionality of the Turbomole calculator can also be used without QMMM calculators if the `embed()` method is called with a specification of the point charges and their positions in which to embed the QM system:

    from ase.collections import s22
    from ase.calculators.turbomole import Turbomole

    params = {'esp fit': 'kollman', 'multiplicity': 1}
    dimer = s22['Water_dimer']
    qm_mol = dimer[0:3]
    calc = Turbomole(atoms=qm_mol, **params)
    calc.embed(
        charges=[-0.76, 0.38,  0.38],
        positions=dimer.positions[3:6]
    )
    print(qm_mol.get_potential_energy())
    print(qm_mol.get_forces())
    print(qm_mol.get_charges())

A more elaborated version of the latter example is used in the test script:

ase/test/turbomole/turbomole_2h2o.py.

## Deprecated, non-implemented and unsupported features

### Deprecated but still accepted parameters

Name | Type | Default value | Description
--- | --- | --- | ---
`calculate_energy` | `str` | `dscf` | module name for energy calculation
`calculate_forces` | `str` | `grad` | module name for forces calculation
`post_HF` | `bool` | `False` | post Hartree-Fock format for energy reader

### Not implemented parameters

The following table includes parameters that are planned but not implemented yet.

Name | Type | Default | Units | Updateable
--- | --- | --- | --- | ---
basis set definition | dict | None | None | False
excited state | bool | False | None | False
label | str | None | None | False
number of excited states | int | None | None | False
optimized excited state | int | None | None | False
rohf | bool | None | None | False

### Unsupported methods and features

The following methods and features are supported in TURBOMOLE but currently not in the ASE Turbomole calculator:

- MP2 and coupled-cluster methods (modules mpgrad, rimp2, ricc2)
- Excited state calculations (modules escf, egrad)
- Molecular dynamics (modules mdprep, uff)
- Solvent effects (COSMO model)
- Global optimization (module haga)
- Property modules (modules freeh, moloch)
- Point groups other than C1 (see not implemented parameters)
- Restricted open-shell Hartree-Fock (see not implemented parameters)
- Per-element and per-atom basis set specifications (see not implemented parameters)
- Explicit basis set specification (see not implemented parameters)

Documentation v: 3.19.0

Versions
  3.20.0b1 (development)
  3.19.0 (latest stable)