Python API

Python API for the DFT-D3 dispersion model

• ASE Support
• QCSchema Support
• PySCF Support
• DFTD3Dispersion
  • DFTD3Dispersion.dump_flags()
  • DFTD3Dispersion.kernel()
  • DFTD3Dispersion.reset()
• energy()
• grad()

Library interface

Wrapper around the C-API of the s-dftd3 shared library. It provides the definition the basic interface to the library for most further integration in other Python frameworks.

The classes defined here allow a more Pythonic usage of the API object provided by the library in actual workflows than the low-level access provided in the CFFI generated wrappers.

Structure

class dftd3.interface.Structure(numbers: numpy.ndarray, positions: numpy.ndarray, lattice: numpy.ndarray | None = None, periodic: numpy.ndarray | None = None)

Represents a wrapped structure object in s-dftd3. The molecular structure data object has a fixed number of atoms and immutable atomic identifiers

Example

>>> from dftd3.interface import Structure
>>> import numpy as np
>>> mol = Structure(
...     positions=np.array([
...         [+0.00000000000000, +0.00000000000000, -0.73578586109551],
...         [+1.44183152868459, +0.00000000000000, +0.36789293054775],
...         [-1.44183152868459, +0.00000000000000, +0.36789293054775],
...     ]),
...     numbers = np.array([8, 1, 1]),
... )
...
>>> len(mol)
3

Raises:

ValueError – on invalid input, like incorrect shape / type of the passed arrays

update(positions: numpy.ndarray, lattice: numpy.ndarray | None = None) → None

Update coordinates and lattice parameters, both provided in atomic units (Bohr). The lattice update is optional also for periodic structures.

Generally, only the cartesian coordinates and the lattice parameters can be updated, every other modification, boundary condition, atomic types or number of atoms requires the complete reconstruction of the object.

Raises:

ValueError – on invalid input, like incorrect shape / type of the passed arrays

DispersionModel

class dftd3.interface.DispersionModel(numbers: numpy.ndarray, positions: numpy.ndarray, lattice: numpy.ndarray | None = None, periodic: numpy.ndarray | None = None)

Contains the required information to evaluate all dispersion related properties, like C6 coefficients. It also manages an instance of the geometry it was constructed for to ensure that the dispersion model is always used with the correct structure input.

get_dispersion(param: DampingParam, grad: bool) → dict

Perform actual evaluation of the dispersion correction

get_pairwise_dispersion(param: DampingParam) → dict

Evaluate pairwise representation of the dispersion energy

set_realspace_cutoff(disp2: float, disp3: float, cn: float)

Set realspace cutoff for evaluation of interactions

DampingParam

class dftd3.interface.DampingParam(**kwargs)

Abstract base class for damping parameters, representing a parametrization of a DFT-D3 method.

The damping parameters contained in the object are immutable. To change the parametrization, a new object must be created. Furthermore, the object is opaque to the user and the contained data cannot be accessed directly.

There are two main ways provided to generate a new damping parameter object:

1. a method name is passed to the constructor, the library will load the required data from the s-dftd3 shared library.

2. all required parameters are passed to the constructor and the library will generate an object from the given parameters.

Note

Mixing of the two methods is not allowed to avoid partial initialization of any created objects. Users who need full control over the creation of the object should use the second method.

RationalDampingParam

class dftd3.interface.RationalDampingParam(**kwargs)

Rational damping function for DFT-D3. The original scheme was proposed by Becke and Johnson[1][2][3] and implemented in a slightly adjusted form using only the C8/C6 ratio in the critical for DFT-D3.[4] The rational damping scheme has the advantage of damping the dispersion energy to finite value, rather than removing it at short distances.

Note

The zero damping function is retained for the three-body contributions from the ATM term.

ZeroDampingParam

class dftd3.interface.ZeroDampingParam(**kwargs)

Original DFT-D3 damping function,[5] based on a variant proposed by Chai and Head-Gordon.[6] Since it is damping the dispersion energy to zero at short distances it is usually called zero damping scheme for simplicity. However, due to this short-range limit of the dispersion energy a repulsive contribution to the gradient can arise, which is considered artificial.[4]

ModifiedRationalDampingParam

class dftd3.interface.ModifiedRationalDampingParam(**kwargs)

Modified version of the rational damping parameters. The functional form of the damping function is unmodified with respect to the original rational damping scheme. However, for a number of functionals new parameters were introduced.:footcite:smith2016

This constructor allows to automatically load the reparameterized damping function from the library rather than the original one. Providing a full parameter set is functionally equivalent to using the RationalDampingParam constructor.

ModifiedZeroDampingParam

class dftd3.interface.ModifiedZeroDampingParam(**kwargs)

Modified zero damping function for DFT-D3.[7] This scheme adds an additional offset parameter to the zero damping scheme of the original DFT-D3.

Note

This damping function is identical to zero damping for bet=0.0.

OptimizedPowerDampingParam

class dftd3.interface.OptimizedPowerDampingParam(**kwargs)

Optimized power version of the rational damping parameters.[8] The functional form of the damping function is modified by adding an additional zero-damping like power function.

This constructor allows to automatically load the reparameterized damping function from the library rather than the original one. Providing the parameter bet=0 is equivalent to using rational the RationalDampingParam constructor.

QCSchema support

Note

For more information on using the DFT-D3 with QCSchema input see dftd3.qcschema.

ASE support

Note

For more information on using the DFT-D3 as ASE calculator see dftd3.ase.

PySCF support

Note

For more information on integrating DFT-D3 with PySCF see dftd3.pyscf.

Literature

[1]

Axel D Becke and Erin R Johnson. A density-functional model of the dispersion interaction. J. Chem. Phys., 123(15):154101, 2005. URL: https://aip.scitation.org/doi/10.1063/1.2065267, doi:10.1063/1.2065267.

[2]

Erin R Johnson and Axel D Becke. A post-hartree–fock model of intermolecular interactions. J. Chem. Phys., 123(2):024101, 2005. URL: https://aip.scitation.org/doi/10.1063/1.1949201, doi:10.1063/1.1949201.

[3]

Erin R Johnson and Axel D Becke. A post-hartree-fock model of intermolecular interactions: inclusion of higher-order corrections. J. Chem. Phys., 124(17):174104, 2006. URL: https://aip.scitation.org/doi/10.1063/1.2190220, doi:10.1063/1.2190220.

[4] (1,2)

S. Grimme, S. Ehrlich, and L. Goerigk. Effect of the damping function in dispersion corrected density functional theory. J. Comput. Chem., 32:1456–1465, 2011. URL: https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.21759, doi:10.1002/jcc.21759.

[5]

S. Grimme, J. Antony, S. Ehrlich, and H. Krieg. A consistent and accurate ab initio parametrization of density functional dispersion correction (DFT-D) for the 94 elements H-Pu. J. Chem. Phys., 132:154104, 2010. URL: https://aip.scitation.org/doi/full/10.1063/1.3382344, doi:10.1063/1.3382344.

[6]

Jeng-Da Chai and Martin Head-Gordon. Long-range corrected hybrid density functionals with damped atom–atom dispersion corrections. Phys. Chem. Chem. Phys., 10(44):6615–6620, 2008. URL: https://pubs.rsc.org/en/content/articlelanding/2008/CP/b810189b, doi:10.1039/B810189B.

[7]

Daniel GA Smith, Lori A Burns, Konrad Patkowski, and C David Sherrill. Revised damping parameters for the d3 dispersion correction to density functional theory. J. Phys. Chem. Lett., 7(12):2197–2203, 2016. URL: https://doi.org/10.1021/acs.jpclett.6b00780, doi:10.1021/acs.jpclett.6b00780.

[8]

Jonathon Witte, Narbe Mardirossian, Jeffrey B Neaton, and Martin Head-Gordon. Assessing DFT-D3 damping functions across widely used density functionals: can we do better? J. Chem. Theory Comput., 13(5):2043–2052, 2017. URL: https://pubs.acs.org/doi/10.1021/acs.jctc.7b00176, doi:10.1021/acs.jctc.7b00176.