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)