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 Grimme’s website or else from the literature.
Running DFTD3 or DFTD4¶
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 or D4 corrections and their variants are
available only through the DFTD3
or DFTD4
programs. Once installed, the
dftd3
/PSI4 and dftd4
/PSI4 interfaces are 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, a B3LYPD3 (zerodamping), and a B3LYPD4 (BeckeJohnson damping) energy.
molecule h2o {
O
H 1 1.0
H 1 1.0 2 104.5
}
set {
basis ccpVDZ
}
energy('b3lyp')
energy('b3lypd')
energy('b3lypd3')
energy('b3lypd4')
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.
No text output is available from the dftd4
program.
Extension [1] 
Variant 
Computing Program (engine) 


D 
alias to D2 

D1 
D1 [2] 
PSI4‘s libdisp 
[\(s_6\)] 
D2 
D2 [3] 
PSI4‘s libdisp OR 
[\(s_6\), \(\alpha_6\), \(s_{r,6}\)] 
D3 
alias to D3ZERO 

D3ZERO 
D3 [4] w/ original zerodamping 

[\(s_6\), \(s_8\), \(s_{r,6}\), \(\alpha_6\), \(s_{r,8}\)] 
D3BJ 
D3 [5] w/ newer BeckeJohnson rational damping 

[\(s_6\), \(s_8\), \(a_1\), \(a_2\)] 
D3(BJ) 
alias to D3BJ 

D3M 
alias to D3MZERO 

D3MZERO 
D3 [6] w/ reparameterized and more flexible original zerodamping 

[\(s_6\), \(s_8\), \(s_{r,6}\), \(\beta\)] 
D3MBJ 
D3 [6] w/ reparameterized newer BeckeJohnson rational damping 

[\(s_6\), \(s_8\), \(a_1\), \(a_2\)] 
D3M(BJ) 
alias to D3MBJ 

NL 
Grimme’s NL (DFT plus VV10 correlation) [7] 
PSI4‘s nl 
[\(b\), \(c\)] via NL_DISPERSION_PARAMETERS 
CHG 
Chai & HeadGordon dispersion formula [8] 
PSI4‘s libdisp 
[\(s_6\)] 
DAS2009 
Podeszwa & Szalewicz dispersion formula [9] 
PSI4‘s libdisp 
[\(s_6\)] 
DAS2010 
Podeszwa & Szalewicz dispersion formula [10] 
PSI4‘s libdisp 
[\(s_6\)] 
D4 
alias to D4BJEEQATM 

D4BJ 
alias to D4BJEEQATM 

D4BJEEQATM 
D4 [12] 

[\(a_1\), \(a_2\), \(alp\), \(s_6\), \(s_8\), \(s_9\)] 
ThreeBody Dispersion Corrections¶
In addition to the previously discussed twobody dispersion corrections,
the dftd3
/PSI4 interface enables computations of threebody dispersion
corrections. In DFTD3
, threebody dispersion is approximated with the
AxilrodTellerMuto model:
where \(\theta_a\) is the angle at atom A corresponding to the triangle formed by atoms A, B, and C, and \(\bar{r}_{ABC}\) is the geometric mean of the corresponding atomicpair distances. The dispersion coefficients are defined as
See the DFTD3 documentation for more details.
For now, the threebody correction can be called by using the run_dftd3()
function with d3atmgr as the passed functional string.
For example, the threebody ATM dispersion correction for a neon trimer could
be computed with:
molecule ne3 {
Ne 0.0 0.0 0.0
Ne 0.0 0.0 1.0
Ne 0.0 1.0 1.0
}
ne.update_geometry()
energy = m.run_dftd3('d3atmgr', dertype=0)
print(energy)
Footnotes
A few practical examples:
DFTD2 single point with default parameters (
dftd3
not called)energy('bp86d')
DFTD3BJ optimization with default parameters
optimize('pbed3bj')
DFTD2 optimization with custom s6 parameter
set dft_dispersion_parameters [1.20] optimize('b3lypd2')
DFTD3ZERO single point (b3lyp) with custom s8 parameter (reset all four values)
set dft_dispersion_parameters [1.0, 2.0, 1.261, 14.0] energy('b3lypd3')
DFTD2 single point with
dftd3
instead of PSI4‘s libdispenergy('pbed2', engine='dftd3')
If only dispersion corrections (rather than total energies) are of
interest, the dispersion programs can be run independently of the scf
through the python function run_dftd3()
or run_dftd4()
. (These functions
call QCEngine, which is the same PSI4 + dftd3
/dftd4
interface that is called during an scf job.)
This “Donly” route is much faster than running a DFTD energy.
Note that in a DFT+D energy or gradient calculation, userspecified
dispersion parameters override any information provided about the
functional. The same holds true for a dftd3
“Donly” calculation. But
in a dftd4
“Donly” calculation, functional information overrides
any userspecified dispersion parameters.
Some setup:
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.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.Molecule.run_dftd3(self, func=None, dashlvl=None, dashparam=None, dertype=None, verbose=1)¶
Compute dispersion correction via Grimme’s DFTD3 program.
 Parameters:
func (
Optional
[str
]) – Name of functional (func only, func & disp, or disp only) for which to compute dispersion (e.g., blyp, BLYPD2, blypd3bj, blypd3(bj), hf+d). Any or all parameters initialized from dashcoeff[dashlvl][func] can be overwritten via dashparam.dashlvl (
Optional
[str
]) – Name of dispersion correction to be applied (e.g., d, D2, d3(bj), das2010). Must be key in dashcoeff or “alias” or “formal” to run.dashparam (
Optional
[Dict
]) – Values for the same keys as dashcoeff[dashlvl][‘default’] used to override any or all values initialized by func. Extra parameters will error.dertype (
Union
[int
,str
,None
]) – Maximum derivative level at which to run DFTD3. For large molecules, energyonly calculations can be significantly more efficient. Influences return values, see below.verbose (
int
) – Amount of printing.
 Returns:
energy (float) – When dertype=0, energy [Eh].
gradient (~numpy.ndarray) – When dertype=1, (nat, 3) gradient [Eh/a0].
(energy, gradient) (tuple of float and ~numpy.ndarray) – When dertype=None, both energy [Eh] and (nat, 3) gradient [Eh/a0].
 qcdb.Molecule.run_dftd4(self, func=None, dashlvl=None, dashparam=None, dertype=None, verbose=1)¶
Compute dispersion correction via Grimme’s DFTD4 program.
 Parameters:
func (
Optional
[str
]) – Name of functional (func only, func & disp, or disp only) for which to compute dispersion (e.g., blyp, BLYPD2, blypd3bj, blypd3(bj), hf+d). Unlike run_dftd3,func
overwrites any parameter initialized via dashparam.dashlvl (
Optional
[str
]) – Name of dispersion correction to be applied (e.g., d, D2, d3(bj), das2010). Must be key in dashcoeff or “alias” or “formal” to run.dashparam (
Optional
[Dict
]) – Values for the same keys as dashcoeff[dashlvl][‘default’] used to provide custom values. Unlike run_dftd3, will not have effect if func given. Must provide all parameters. Extra parameters will error.dertype (
Union
[int
,str
,None
]) – Maximum derivative level at which to run DFTD3. For large molecules, energyonly calculations can be significantly more efficient. Influences return values, see below.verbose (
int
) – 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].
Notes
This function wraps the QCEngine dftd4 harness which wraps the internal DFTD4 Python API. As such, the upstream convention of func trumping dashparam holds, rather than the
run_dftd3()
behavior of dashparam extending or overriding func.
 class psi4.driver.procrouting.empirical_dispersion.EmpiricalDispersion(*, name_hint=None, level_hint=None, param_tweaks=None, engine=None, save_pairwise_disp=False)[source]¶
Lightweight unification of empirical dispersion calculation modes.
 dashlevel¶
{‘d1’, ‘d2’, ‘d3zero’, ‘d3bj’, ‘d3mzero’, ‘d3mbj’, ‘chg’, ‘das2009’, ‘das2010’, ‘nl’, ‘dmp2’, “d4bjeeqatm”} Name of dispersion correction to be applied. Resolved from name_hint and/or level_hint into a key of empirical_dispersion_resources.dashcoeff.
 Type:
 dashparams¶
Complete set of parameter values defining the flexible parts of
dashlevel
. Number and parameter names vary bydashlevel
. Resolved into a complete set (keys of dashcoeff[dashlevel][‘default’]) from name_hint and/or dashcoeff_supplement and/or user param_tweaks. Type:
 fctldash¶
If
dashparams
fordashlevel
corresponds to a defined, named, untweaked “functionaldashlevel” set, then that functional. Otherwise, empty string. Type:
 dashlevel_citation¶
Literature reference for dispersion
dashlevel
in general, not necessarily fordashparams
. Type:
 dashparams_citation¶
Literature reference for dispersion parameters, if
dashparams
corresponds to a defined, named, untweaked “functionaldashlevel” set with a citation. Otherwise, empty string. Type:
 dashcoeff_supplement¶
See description in qcengine.programs.empirical_dispersion_resources.from_arrays. Used here to “bless” the dispersion definitions attached to the procedures/dft/<rung>_functionalsdefined dictionaries as legit, noncustom, and of equal validity to qcengine.programs.empirical_dispersion_resources.dashcoeff itself for purposes of validating
fctldash
. Type:
 engine¶
{‘libdisp’, ‘dftd3’, ‘nl’, ‘mp2d’, “dftd4”} Compute engine for dispersion. One of Psi4’s internal libdisp library, external Grimme or Beran projects, or nl.
 Type:
 ordered_params¶
Fixedorder list of relevant parameters for
dashlevel
. MatchesDISPERSION CORRECTION ENERGY
ordering. Used for printing. Type:
 Parameters:
name_hint (
Optional
[str
]) – Name of functional (func only, func & disp, or disp only) for which to compute dispersion (e.g., blyp, BLYPD2, blypd3bj, blypd3(bj), hf+d). Any or all parameters initialized fromdashcoeff[dashlevel][functionalwithoutdashlevel]
ordashcoeff_supplement[dashlevel][functionalwithdashlevel]
can be overwritten via param_tweaks.level_hint (
Optional
[str
]) – 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.param_tweaks (
Union
[Dict
,List
,None
]) – Values for the same keys as dashcoeff[dashlevel][‘default’] (and same order if list) used to override any or all values initialized by name_hint. Extra parameters will error.engine (
Optional
[str
]) – Override which code computes dispersion. See above for allowed values. Really only relevant for D2, which can be computed by libdisp or dftd3.