Interface to DFTD3 by S. Grimme¶
Code author: Lori A. Burns
Section author: Lori A. Burns
Module: Samples
Installation¶
Binary
DFTD3 is available as a conda package for Linux and macOS (and Windows, through the Ubuntu shell).
If using the Psi4conda installer, DFTD3 has already been installed alongside.
If using the PSI4 conda package, the dftd3 conda package can be obtained through
conda install dftd3 c psi4
orconda install psi4rt c psi4
.If using PSI4 built from source, and anaconda or miniconda has already been installed (instructions at Quick Installation), the dftd3 executable can be obtained through
conda install dftd3 c psi4
.To remove a conda installation,
conda remove dftd3
.
Source
If using PSI4 built from source and you want to build DFTD3 from from source also, follow the instructions provided with the source (essentially, download the freely available tarball, unpack the source, edit the Makefile to select a Fortran compiler, and run make). From version 3.1.0 onwards, DFTD3 can be used asis; for earlier versions, patches are available: psi4/psi4/share/psi4/scripts/patch_grimme_dftd3.3.0.2.
To be used by PSI4, the program binary (dftd3
) must be
found in your PSIPATH
or PATH
(in that order). If
PSI4 is unable to execute the binary, an error will be reported.
To preferentially use a particular dftd3 compilation, simply adjust its
position in the path environment variables.
Theory¶
The local or semilocal character of conventional density functionals necessarily leads to neglect of the longrange correlation interactions which capture attractive van der Waals forces. Initially proposed by Yang [Wu:2002:515] and assiduously developed by Grimme, [Grimme:2004:1463] [Grimme:2006:1787] [Grimme:2010:154104] the DFT+Dispersion method appends to the base functional a scaled, damped, and fitted leading term to the wellknown dispersion energy series, \(E_{disp} = C_6/R^6 C_8/R^8 C_{10}/R^{10}\cdots\). The DFTD2 [Grimme:2006:1787] variant takes the explicit form below. Here, dispersion coefficients, \(C_6^{ij}\), obtained from the geometric mean of tabulated elemental values, are summed over interatomic distances, \(R_{ij}\), modulated by a damping function, \(f_{damp}(R_{ij})\), that gradually activates the dispersion correction (at a rate characterized by \(\alpha_6\)) over a distance characterized by the sum of the two atomic vdW radii, \(R_{vdW}\), while an overall scaling term, \(s_6\), is optimized to be unique to each \(E_{xc}\) functional. (\(\alpha_6\) is sometimes allowed to vary as well.)
Grimme recently presented a refined method, DFTD3, [Grimme:2010:154104] which incorporates an additional \(R^{8}\) term in the dispersion series and adjusts the \(C_{6}^{ij}\) combination formula and damping function. The individual atomic \(C_6^i\) are interpolated from several reference values based upon coordination numbers extracted from the molecular structure, rather than assigned solely by atomic identity as in DFTD2, and thereby incorporate some awareness of the chemical environment into an otherwise largely heuristic correction. The D3 dispersion has the following form, where \(s_{r,6}\) and \(s_8\) are the customary nonunity parameters fitted for individual functionals.
A modified damping scheme for DFTD3 using the rational damping form of Becke and Johnson was introduced in [Grimme:2011:1456]. The parameters fit for individual functionals are now \(s_6\), \(s_8\), \(a_1\), and \(a_2\).
All parameters characterizing the dispersion correction are taken from http://toc.unimuenster.de/DFTD3/ or else from the literature.
Running DFTD3¶
A number of a posteriori dispersion corrections are available in
PSI4. While most are computed within PSI4’s codebase (D1, D2,
CHG, DAS2009, DAS2010), the D3 correction and its variants are
available only through the DFTD3
program. Once installed, the
dftd3
/PSI4 interface is transparent, and all corrections are
interfaced exactly alike.
Dispersion corrections are built into DFT functionals, so appending an a
posteriori correction to a computation is as simple as
energy('b2plypd')
vs. energy('b2plyp')
. For example, the
following input file computes (with much redundant work) for water a
B3LYP, a B3LYPD2, and a B3LYPD3 (zerodamping) energy.
1 2 3 4 5 6 7 8 9 10 11  molecule h2o {
O
H 1 1.0
H 1 1.0 2 104.5
}
set {
basis ccpVDZ
}
energy('b3lyp')
energy('b3lypd')
energy('b3lypd3')

Consult the table D Functionals to see for each
functional what corrections are available and what default parameters
define them. The dispersion correction is available after a calculation in
the PSI variable DISPERSION CORRECTION ENERGY
.
By default, the output from the dftd3
program is suppressed; to see it in the output file, set print > 2.
Extension [1]  Variant and Computing Program  DFT_DISPERSION_PARAMETERS 

D  alias to D2P4  
D1  D1 [2] within PSI4  
D2  alias to D2P4  
D2P4  D2 [3] within PSI4  [\(s_6\)] 
D2GR  D2 [3] through dftd3 
[\(s_6\), \(\alpha_6\)] 
D3  alias to D3ZERO  
D3ZERO  D3 [4] w/ original zerodamping through dftd3 
[\(s_6\), \(s_8\), \(s_{r,6}\), \(\alpha_6\)] 
D3BJ  D3 [5] w/ newer BeckeJohnson rational damping through dftd3 
[\(s_6\), \(s_8\), \(a_1\), \(a_2\)] 
D3M  alias to D3MZERO  
D3MZERO  D3 [6] w/ reparameterized and more flexible original zerodamping through dftd3 
[\(s_6\), \(s_8\), \(s_{r,6}\), \(\beta\)] 
D3MBJ  D3 [6] w/ reparameterized newer BeckeJohnson rational damping through dftd3 
[\(s_6\), \(s_8\), \(a_1\), \(a_2\)] 
Footnotes
[1]  Note that there are functionals with these extensions (e.g., wB97XD) that, not being Grimme corrections, have nothing to do with this table. 
[2]  [Grimme:2004:1463] 
[3]  (1, 2) [Grimme:2006:1787] 
[4]  [Grimme:2010:154104] 
[5]  [Grimme:2011:1456] 
[6]  (1, 2) [Smith:2016:2197] 
A few practical examples:
DFTD2 single point with default parameters (
dftd3
not called)1
energy('bp86d')
DFTD3BJ optimization with default parameters
1
optimize('pbed3bj')
DFTD2 optimization with custom s6 parameter
1 2
set dft_dispersion_parameters [1.20] optimize('b3lypd2')
DFTD3ZERO single point (b3lyp) with custom s8 parameter (reset all four values)
1 2
set dft_dispersion_parameters [1.0, 2.0, 1.261, 14.0] energy('b3lypd3')
If only dispersion corrections (rather than total energies) are of
interest, the dftd3
program can be run independently of the scf
through the python function run_dftd3()
. (This function
is the same PSI4/dftd3
interface that is called during an scf job.)
This route is much faster than running a DFTD energy.
Some setup:
1 2 3 4 5 6
molecule nene { Ne Ne 1 2.0 } nene.update_geometry()
The same four dispersion corrections/gradients as the section above:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
>>> print nene.run_dftd3('bp86', 'd', dertype=0) 7.735e05 >>> E, G = nene.run_dftd3('pbe', 'd3bj') >>> print G [[0.0, 0.0, 1.1809087569358e05], [0.0, 0.0, 1.1809087569358e05]] >>> E, G = nene.run_dftd3('b3lyp', 'd2', {'s6': 1.20}) >>> print E 8.84e05 >>> E, G = nene.run_dftd3(dashlvl='d3', dashparam={'s8': 2.0, 'alpha6': 14.0, 'sr6': 1.261, 's6': 1.0}) >>> print E 0.00024762

qcdb.interface_dftd3.
run_dftd3
(mol, func=None, dashlvl=None, dashparam=None, dertype=None, verbose=False)[source]¶ Compute dispersion correction using Grimme’s DFTD3 executable.
Function to call Grimme’s dftd3 program to compute the D correction of level dashlvl using parameters for the functional func. dashparam can supply a full set of dispersion parameters in the absence of func or individual overrides in the presence of func.
The DFTD3 executable must be independently compiled and found in
PATH
orPSIPATH
.Parameters:  mol (qcdb.Molecule or psi4.core.Molecule or str) – Molecule on which to run dispersion calculation. Both qcdb and psi4.core Molecule classes have been extended by this method, so either allowed. Alternately, a string that can be instantiated into a qcdb.Molecule.
 func (str or None) – Density functional (Psi4, not Turbomole, names) for which to load parameters from dashcoeff[dashlvl][func]. This is not passed to DFTD3 and thus may be a dummy or None. Any or all parameters initialized can be overwritten via dashparam.
 dashlvl ({'d2p4', 'd2gr', 'd3zero', 'd3bj', 'd3mzero', d3mbj', 'd', 'd2', 'd3', 'd3m'}) – Flavor of a posteriori dispersion correction for which to load parameters and call procedure in DFTD3. Must be a keys in dashcoeff dict (or a key in dashalias that resolves to one).
 dashparam (dict, optional) – Dictionary of the same keys as dashcoeff[dashlvl] used to override any or all values initialized by dashcoeff[dashlvl][func].
 dertype ({None, 0, 'none', 'energy', 1, 'first', 'gradient'}, optional) – Maximum derivative level at which to run DFTD3. For large mol, energyonly calculations can be significantly more efficient. Also controls return values, see below.
 verbose (bool, optional) – When True, additionally include DFTD3 output in output.
Returns:  energy (float, optional) – When dertype is 0, energy [Eh].
 gradient (list of lists of floats or psi4.core.Matrix, optional) – When dertype is 1, (nat, 3) gradient [Eh/a0].
 (energy, gradient) (float and list of lists of floats or psi4.core.Matrix, optional) – When dertype is unspecified, both energy [Eh] and (nat, 3) gradient [Eh/a0].
Notes
research site: https://www.chemie.unibonn.de/pctc/mullikencenter/software/dftd3 Psi4 mode: When psi4 the python module is importable at import qcdb
time, Psi4 mode is activated, with the following alterations: * output goes to output file * gradient returned as psi4.core.Matrix, not list o’lists * scratch is written to randomly named subdirectory of psi scratch * psivar “DISPERSION CORRECTION ENERGY” is set * verbose triggered when PRINT keywork of SCF module >=3