7.3 How to Perform a Calculation

7.3.1 Basis Sets for Periodic Calculations

In periodic systems too diffuse basis functions result in near-singularity of the overlap matrix. Therefore, it is recommended that the exponents of the Gaussian basis sets used for periodic calculations are not smaller than 0.01. Optimally, the exponents should be larger than 0.1. The easiest way to achieve this is to remove the small exponent basis functions from the basis sets. Optionally, basis sets optimized for periodic calculations can be used, such as the ones in Ref. [100]. They are available in the TURBOMOLE basis sets library as pob-TZVP.

7.3.2 Prerequisites

Calculations using riper require the control file and starting orbitals generated using define. DFT method needs to be specified in the $dft data group. All LDA, GGA and meta-GGA exchange-correlation functionals including interface to the XCFun library (see Sec. 6.2) are supported. Moreover, auxiliary basis sets defined in the data group $jbas are required. For periodic calculations additional keywords specifying the system periodicity and number of k points (if used) have to be added manually to the control file. Optionally, the $riper group containing control options specific to riper (including the LMIDF keywords) can be added. The input preparation steps are summarized below. More detailed information about riper keywords are provided in Sec. 20.2.10.

7.3.3 Creating the Input File

The following examples illustrate the additions to the control file required for calculations using the riper module.

Example 1: In this example a 3D periodic system is defined ($periodic 3). The unit cell is specified using the $cell keyword, with lengths and angles given in atomic units and degrees, respectively. A uniform grid of 27 (3 3 3) k points for numerical integration over the BZ is specified using the keyword $kpoints. The section $riper (see Sec. 20.2.10) is added with the keyword lenonly set to on. It forces riper to skip the calculation of energy gradients (by default both energy and gradients are calculated in one run). In addition, Gaussian smearing is switched on by providing sigma 0.01 (see Sec. 7.2.4).

$periodic 3  
  18.5911 16.5747 16.5747 90. 90. 90.  
  nkpoints 3 3 3  
  lenonly on  
  sigma 0.01

Example 2: In this example a 2D periodic system is defined ($periodic 2). The unit cell is specified using the $cell keyword, with lengths and angles given in  and degrees, respectively. A uniform grid of 9 (3 3) k-points for numerical integration over the BZ is defined using the keyword $kpoints. The section $riper (see Sec. 20.2.10) is added with the keyword lmaxmom 30. This changes the maximum order of multipole expansions used in CFMM to 30 (default value is 20).

$periodic 2  
$cell angs  
  18.5911 16.5747 90.0  
  nkpoints 3 3  
  lmaxmom 30

Example 3: In this example a 1D periodic system is defined ($periodic 1). The dimension of the periodic direction in atomic units is specified using the $cell keyword. A one dimensional grid of 3 k-points for numerical integration over the BZ is defined using the keyword $kpoints.

$periodic 1  
  nkpoints 3

Example 4: In this example a molecular system is defined (default if no $periodic is specified). The section $riper (see Sec. 20.2.10) is added with the keyword lpcg on, which activates the low-memory modification of the RI approximation for calculations on very large molecular systems.

  lpcg on

7.3.4 Single Point Energy and Gradient

By default riper calculates single point energy and gradient in one run. For this, simply invoke riper as

nohup riper > riper.out &

For energy calculation only add lenonly on to the $riper section in the control file, i.e.,

  lenonly on

The parallel OpenMP version of riper can be invoked ad described in Sec. 3.2.2.

7.3.5 Structure Optimization

jobex will automatically use riper when the keyword $periodic is present in the control file. Alternatively, the use of riper can be forced by specifying -riper argument of jobex, i.e., invoking

nohup jobex -riper > jobex.out &

Note, that at present only structure optimization using Cartesian coordinates is possible when using periodic boundary conditions. Using internal coordinates for periodic systems will lead to convergence problems in structure optimizations.

7.3.6 Band Structure Plots

Band structure plots show the values of band (orbital) energies for values of k along lines connecting symmetry points of the Brillouin zone. In riper these lines can be specified by providing their start and end points as well as the number of k points along the line within the $kpoints section. They will be calculated at the end of the self-consistent procedure and written to the file bands.xyz.

Note: The calculation of band structure for periodic systems requires a self-consistent calculation that is reasonably well converged with respect to the k points sampling (using the keyword $kpoints).

In the following example band energies are calculated along four lines, as specified by the keyword kptlines 4. Each line definition starts in a new line with the keyword recipr, followed by three real numbers defining the start point of the line and three real numbers defining its end point. Finally, the number of k points along the line is given as an integer number. Thus, the first line starts at the point (0.500 0.500 0.500), ends at (0.000 0.000 0.000) and contains 40 k points.

 kptlines 4  
 recipr 0.500 0.500 0.500 0.000 0.000 0.000 40  
 recipr 0.000 0.000 0.000 0.500 0.500 0.000 40  
 recipr 0.500 0.500 0.000 0.746 0.373 0.373 40  
 recipr 0.746 0.373 0.373 0.000 0.000 0.000 40

Each line of the resulting bands.xyz file contains five real numbers: the coordinates k1, k2 and k3 of the k point, its length |k| and the corresponding band energy ϵnk.

7.3.7 Density Plots

Plots of electron density for molecular and periodic systems can be generated adding the keyword $pointvalper to the control file. The values of the total density and, in case of UHF calculations also the spin density are calculated on a 3D grid and written to appropriate output files. Density plot files can be generated either running a single point energy riper calculation or invoking

nohup riper -proper > riper.out &

provided that converged orbitals and occupation numbers from previous calculation are present in the files RIPER.BANDS and RIPER.BANDS.OCCUPATIONS, respectively.

The format of the density files can be specified using the keyword fmt= following $pointvalper in the same line. Supported formats are:


(default) Density data is written to binary files that can be read by gOpenMol and other external visualization programs. This format uses orthogonal grids. Therefore, for non-orthogonal unit cells grid data is generated for a rectangular box that contains the supercell (unit cell and its periodic images). By default, density values at grid points outside of the supercell are set to zero. For strongly non-orthogonal systems this may lead to large files. The option full switches off the zeroing of density vales on grid points outside the supercell.


Gaussian cube format. Can be imported by several external visualization programs.


Coordinates of grid points and density values are stored in a text file. Each line contains Cartesian grid point coordinates and the corresponding density or spin density value.


Density and grid data is output to binary files. First 8 (integer) records are: 1-2) rank value and descriptor, 3-8) number of grid points and number of periodic unit cell images in each periodic direction, 9...) Cartesian coordinates and the corresponding density or spin density value repeated for all grid points.

Output files in cub format contain information about atomic coordinates. For other formats additional coord.xyz file containing atomic coordinates is generated.

The following options can be used along with the keyword $pointvalper:

nimg n1 n2 n3

Number of unit cell images n1, n2 and n3 in the periodic directions a, b and c, respectively, for which plot data is generated.

npts n1 n2 n3

Number of grid points n1, n2 and n3 along each periodic direction. If not specified, value 100 is used for each n.

eps real

Specifies the distance real in bohr around the system for which plot grid is generated in aperiodic directions. Default value is 5 bohr.

ngrdpbx n

Number of grid points stored in one octree box during density calculations. Default value is 50. For very large systems or high resolution it may be necessary to increase this parameter to avoid memory allocation problems.


Only valid for plt output format. Switches off zeroing of density vales on grid points outside the supercell.