3.3 A ‘Quick and Dirty’ Tutorial for the define input generator

For the generation of input files for more complex calculations TURBOMOLE offers the interactive input generator define, which guides the user through a series of menues to set up the required input without the need to know by hard the names of the keywords and options.

The define module (program) generates in a step by step manner and interactively the control file: coordinates, atomic attributes (e.g. basis sets), MO start vectors and keywords specific for the desired method of calculation. We recommend generating a set of Cartesian coordinates for the desired molecule using your favourite molecular builder (e.g. molden) and converting these coordinates into TURBOMOLE format (see Section 26.2) as input for define. Alternatively the graphical user interface TmoleX can be used to import and/or build molecules.

A straightforward way to perform even complex TURBOMOLE calculations from scratch is as follows:

• generate your atomic coordinates by any tool you are familiar with,

• save it as an .xyz file which is a standard output format of all programs, or use a conversion tool like babel,

• use the TURBOMOLE script x2t to convert your .xyz file to the TURBOMOLE coord file:
  x2t xyzinputfile > coord

• since input files for TURBOMOLE are always called control, each input has to be placed in a different directory. Create a new directory and copy the coord file there,

• call
  define
  after specifying the title, you get the coord menu — just enter
  a coord
  to read in the coordinates.
  Use desy to let define determine the point group automatically.
  If you want to do geometry optimizations, we recommend to use generalized internal coordinates; ired generates them automatically.

• you may then go through the menus without doing anything: just press <Enter>, * or q—whatever ends the menu, or by confirming the proposed decision of define again by just pressing <Enter>.
  This way you get the necessary specifications for a (SCF-based) run with def-SV(P) as the default basis set (which is qualitatively similar to 6-31G*).

• for more accurate SCF or DFT calculations choose larger basis sets, e.g. TZVP by entering b all def-TZVP or b all def2-TZVP in the basis set menu.

• ECPs which include (scalar) relativistic corrections are automatically used beyond Kr.

• an initial guess for MOs and occupation numbers is provided by eht

• for DFT you have to enter dft in the last menu and then enter on

• for efficient DFT calculations you best choose the RI approximation by entering ri and then on. For small molecules it can be beneficial to provide additional memory (with m number; number in MB), but make sure not to use more than 80% of the memory your computer has available (note that the setting is per core for parallel jobs!). Auxiliary basis sets are provided automatically. For medium-sized to larger molecules, additional memory for integral-storage is not helpful (can even slow down the calculation), but activating the multipole accelerated RI-J (marij) can speed up the calculation significantly (without introducing additional errors for RI-J).

• B-P86 is the default functional. It has a good and stable performance throughout the periodic system.

• for an HF or DFT run without RI, you simply enter:
  [nohup] dscf > dscf.out &
  or, for a RI-DFT run:
  [nohup] ridft > ridft.out &

• for a gradient run, you simply enter:
  [nohup] grad > grad.out &
  or
  [nohup] rdgrad > rdgrad.out &

• for a geometry optimization simply call jobex:
  for a standard SCF input:
  [nohup] jobex &
  for a standard RI-DFT input:
  [nohup] jobex -ri &

• many features, such as NMR chemical shifts or vibrational frequencies at SCF or DFT level, do not require further modifications of the input. Just call e.g. mpshift or aoforce after the appropriate energy calculation.

• other features, such as post–SCF methods need further action on the input, using either the last menu of define where one can activate all settings needed for DFT, TDDFT, MP2, CC2, etc. calculations (this is the recommended way), or tools like mp2prep.

If that was a too quick and dirty chapter, please read the TURBOMOLE Tutorial in the DOC directory of your local TURBOMOLE installation. It explains step by step the generation of input with define and how to run calculations on the command line.

3.3.1 Single Point Calculations: Running Turbomole Modules

All calculations are carried out in a similar way. First you have to run define to obtain the control file or to add/change the keywords you need for your purpose. This can also be done manually with an editor. Given a bash and a path to $TURBODIR/bin/[arch] (see installation, Chapter 2) you call the appropriate module in the following way (e.g. module dscf):

nohup means that the command is immune to hangups, logouts, and quits. & runs a background command. The output will be written to the file dscf.out. Several modules write some additional output to the control file. For the required keywords see Section 25. The features of TURBOMOLE will be described in the following section.

3.3.2 Energy and Gradient Calculations

Energy calculations may be carried out at different levels of theory.

Hartree–Fock–SCF

use modules dscf and grad or ridft and rdgrad to obtain the energy and gradient. The energy can be calculated after a define run without any previous runs. dscf and grad need no further keywords ridft and rdgrad only need the keyword $rij. The gradient calculation however requires a converged dscf or ridft run.

Density functional theory

DFT calculations are carried out in exactly the same way as Hartree–Fock calculations except for the additional keyword $dft. For DFT calculations with the fast Coulomb approximation you have to use the modules ridft and rdgrad instead of dscf and grad. Be careful: dscf and grad ignore RI–\(K\) flags and will try to do a normal calculation, but they will not ignore RI–\(J\) flags ($rij) and stop with an error message. To obtain correct derivatives of the DFT energy expression in grad or rdgrad  the program also has to consider derivatives of the quadrature weights—this option can be enabled by adding the keyword weight derivatives to the data group $dft.

For a semi-direct dscf calculation (Hartree–Fock or DFT) you first have to perform a statistics run. If you type

stati dscf
nohup dscf > dscf.stat &

the disk space requirement (MB) of your current $thime and $thize combination will be computed and written to the data group $scfintunit size=integer (see Section 25.2.10). The requirement of other combinations will be computed as well and be written to the output file dscf.stat. The size of the integral file can be set by the user to an arbitrary (but reasonable) number. The file will be written until it reaches the given size and dscf  will continue in direct mode for the remaining integrals. Note that TURBOMOLE  has no 2GB file size limit.

MP2 and MP2-F12

MP2 calculations need well converged SCF runs (the SCF run has to be done with at least the density convergence $denconv 1.d-6, and $scfconv 7 as described in Section 25). This applies also to the spin-component scaled (SCS and SOS) and explicitly-correlated (F12) variants of MP2. For MP2 and MP2-F12 calculations in the RI approximation use the ricc2 or pnoccsd modules. The module mpgrad calculates the conventional (non-RI and non-F12) MP2 energy its gradient (only recommended for test calculations). The input can be prepared with the mp2, cc, or pnocc menu in define.

Excited states with CIS, TDHF and TDDFT (escf)

Single point excited state energies for CIS, TDHF, and TDDFT methods can be calculated using escf. Excited state energies, gradients, and other first order properties are provided by egrad. Both modules require well converged ground state orbitals.

Excited states with second-order wavefunction methods (ricc2)

The module ricc2 calculates beside MP2 and CC2 ground state energies also CIS (identical to CCS), CIS(D), CIS(D\(_\infty\)), ADC(2) or CC2 excitation energies using the resolution-of-the-identity (RI) approximation. Also available are spin-component scaled (SCS and SOS) variants of the second-order methods CIS(D), CIS(D\(_\infty\)), ADC(2) or CC2. Excited state gradients are available at the CCS, CIS(D\(_\infty\)), ADC(2), and CC2 levels and the spin-component scaled variants of the latter three methods. In addition, transition moments and first-order properties are available for some of the methods. For more details see Section 10. The input can be prepared using the cc menu of define.

Coupled-Cluster methods beyond CC2: CCSD(F12*)(T) (ccsdf12)

Coupled-Cluster methods beyond CC2 as CCSD and CCSD(T) and Møller-Plesset perturbation theory beyond MP2 and explicitly-correlated F12 variants thereof are since Release V7.0 implemented in the ccsdf12 program. The F12 variants of these methods have a much faster basis set convergence and are therefore more efficient. We recommend in particular CCSD(F12*) and CCSD(F12*)(T). Excitation energies are only available for (conventional) CCSD.

3.3.3 Calculation of Molecular Properties

See Section 1.6 for the functionality and Section 25 for the required keywords of the modules dscf, ridft, mpshift, escf, and ricc2.

3.3.4 Modules and Data Flow

See Figure 3.3.