Interface to DFTD3 by S. Grimme

Code author: Lori A. Burns

Section author: Lori A. Burns

Module: Samples

https://img.shields.io/badge/home-DFTD3-5077AB.svg
https://img.shields.io/badge/docs-latest-5077AB.svg

Installation

Binary

  • https://anaconda.org/psi4/dftd3/badges/version.svg
  • 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 or conda install psi4-rt -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

  • https://img.shields.io/badge/home-DFTD3-5077AB.svg
  • 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 as-is; 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 long-range 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 well-known dispersion energy series, \(E_{disp} = -C_6/R^6 -C_8/R^8 -C_{10}/R^{10}-\cdots\). The DFT-D2 [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.)

(1)\[E_{disp}^{\text{D2}}=-s_6 \sum_{i,j>i}^{N_{at}} \frac{C_6^{ij}}{(R_{ij})^6} f_{damp}(R_{ij})\]
\[f_{damp}(R_{ij}) = \frac{1}{1 + e^{- \alpha_6 (R_{ij}/R_{vdW} - 1)}}\]

Grimme recently presented a refined method, DFT-D3, [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 DFT-D2, 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.

(2)\[E_{disp}^{\text{D3ZERO}}=-\sum_{n=6,8} s_n \sum_{i,j>i}^{N_{at}} \frac{C_n^{ij}}{(R_{ij})^n} f_{damp}(R_{ij})\]
\[f_{damp}(R_{ij}) = \frac{1}{1 + 6 (R_{ij}/(s_{r,n} R_0^{ij}))^{- \alpha_n}}\]

A modified damping scheme for DFT-D3 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\).

\[E_{disp}^{\text{D3BJ}}=-\sum_{n=6,8} s_n \sum_{i,j>i}^{N_{at}} \frac{C_n^{ij}}{(R_{ij})^n + (f_{damp})^n}\]
\[f_{damp} = a_1 \sqrt{\frac{C_8^{ij}}{C_6^{ij}}} + a_2\]

All parameters characterizing the dispersion correction are taken from Grimme’s website or else from the literature.

Running DFTD3

A number of a posteriori dispersion corrections are available in PSI4. While some 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('b2plyp-d') vs. energy('b2plyp'). For example, the following input file computes (with much redundant work) for water a B3LYP, a B3LYP-D2, and a B3LYP-D3 (zero-damping) energy.

molecule h2o {
     O
     H 1 1.0
     H 1 1.0 2 104.5
 }
 set {
     basis cc-pVDZ
 }
 energy('b3lyp')
 energy('b3lyp-d')
 energy('b3lyp-d3')

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.

Variants of dispersion corrections

Extension 1

Variant

Computing Program (engine)

DFT_DISPERSION_PARAMETERS 11

-D -D1 -D2 -D3 -D3ZERO -D3BJ -D3(BJ) -D3M -D3MZERO -D3MBJ -D3M(BJ) -NL -CHG -DAS2009 -DAS2010

alias to -D2 -D1 2 -D2 3 alias to -D3ZERO -D3 4 w/ original zero-damping -D3 5 w/ newer Becke-Johnson rational damping alias to -D3BJ alias to -D3MZERO -D3 6 w/ reparameterized and more flexible original zero-damping -D3 6 w/ reparameterized newer Becke-Johnson rational damping alias to -D3MBJ Grimme’s -NL (DFT plus VV10 correlation) 7 Chai & Head-Gordon dispersion formula 8 Podeszwa & Szalewicz dispersion formula 9 Podeszwa & Szalewicz dispersion formula 10

PSI4‘s libdisp PSI4‘s libdisp OR dftd3

dftd3 dftd3

dftd3 dftd3

PSI4‘s nl PSI4‘s libdisp PSI4‘s libdisp PSI4‘s libdisp

[\(s_6\)] [\(s_6\), \(\alpha_6\), \(s_{r,6}\)]

[\(s_6\), \(s_8\), \(s_{r,6}\), \(\alpha_6\), \(s_{r,8}\)] [\(s_6\), \(s_8\), \(a_1\), \(a_2\)]

[\(s_6\), \(s_8\), \(s_{r,6}\), \(\beta\)] [\(s_6\), \(s_8\), \(a_1\), \(a_2\)]

[\(b\), \(c\)] via NL_DISPERSION_PARAMETERS [\(s_6\)] [\(s_6\)] [\(s_6\)]

Footnotes

1

Note that there are functionals with these extensions (e.g., wB97X-D) that, not being Grimme corrections, won’t follow this table exactly.

2

[Grimme:2004:1463]

3

[Grimme:2006:1787]

4

[Grimme:2010:154104]

5

[Grimme:2011:1456]

6(1,2)

[Smith:2016:2197]

7

[Hujo:2011:3866]

8

[Chai:2010:6615]

9

[Pernal:2009:263201]

10

[Podeszwa:2010:550]

11

Keyword not used for user-defined functionals where the dft_dict["dispersion"]["params"] is easily editable for this purpose. See Advanced Functional Use and Manipulation

A few practical examples:

  • DFT-D2 single point with default parameters (dftd3 not called)

    energy('bp86-d')
    
  • DFT-D3BJ optimization with default parameters

    optimize('pbe-d3bj')
    
  • DFT-D2 optimization with custom s6 parameter

    set dft_dispersion_parameters [1.20]
    optimize('b3lyp-d2')
    
  • DFT-D3ZERO single point (b3lyp) with custom s8 parameter (reset all four values)

    set dft_dispersion_parameters [1.0, 2.0, 1.261, 14.0]
    energy('b3lyp-d3')
    
  • DFT-D2 single point with dftd3 instead of PSI4‘s libdisp

    energy('pbe-d2', engine='dftd3')
    

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 DFT-D energy.

  • Some set-up:

    molecule nene {
    Ne
    Ne 1 2.0
    }
    
    nene.update_geometry()
    
  • The same four dispersion corrections/gradients as the section above:

    >>> print nene.run_dftd3('bp86', 'd', dertype=0)
    -7.735e-05
    
    >>> E, G = nene.run_dftd3('pbe', 'd3bj')
    >>> print G
    [[0.0, 0.0, -1.1809087569358e-05], [0.0, 0.0, 1.1809087569358e-05]]
    
    >>> E, G = nene.run_dftd3('b3lyp', 'd2', {'s6': 1.20})
    >>> print E
    -8.84e-05
    
    >>> 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.Molecule.run_dftd3(self, func=None, dashlvl=None, dashparam=None, dertype=None, verbose=1)

Compute dispersion correction via Grimme’s DFTD3 program.

Parameters
  • func (str, optional) – Name of functional (func only, func & disp, or disp only) for which to compute dispersion (e.g., blyp, BLYP-D2, blyp-d3bj, blyp-d3(bj), hf+d). Any or all parameters initialized from dashcoeff[dashlvl][func] can be overwritten via dashparam.

  • dashlvl (str, optional) – Name of dispersion correction to be applied (e.g., d, D2, d3(bj), das2010). Must be key in dashcoeff or “alias” or “formal” to one.

  • dashparam (dict, optional) – Values for the same keys as dashcoeff[dashlvl][‘default’] used to override any or all values initialized by func. Extra parameters will error.

  • dertype (int or str, optional) – Maximum derivative level at which to run DFTD3. For large molecules, energy-only calculations can be significantly more efficient. Influences return values, see below.

  • verbose (int, optional) – Amount of printing.

Returns

  • energy (float) – When dertype=0, energy [Eh].

  • gradient (ndarray) – When dertype=1, (nat, 3) gradient [Eh/a0].

  • (energy, gradient) (tuple of float and ndarray) – When dertype=None, both energy [Eh] and (nat, 3) gradient [Eh/a0].