Python API

Python API for the DFT-D3 dispersion model

• ASE Support
• QCSchema Support
• PySCF Support
• DFTD3Dispersion
  • DFTD3Dispersion.dump_flags()
  • DFTD3Dispersion.hessian()
  • DFTD3Dispersion.kernel()
  • DFTD3Dispersion.reset()
• GeometricCounterpoiseCorrection
  • GeometricCounterpoiseCorrection.dump_flags()
  • GeometricCounterpoiseCorrection.hessian()
  • GeometricCounterpoiseCorrection.kernel()
  • GeometricCounterpoiseCorrection.reset()
• d3_energy()
• d3_grad()
• d3_hess()
• energy()
• gcp_energy()
• gcp_grad()
• gcp_hess()
• grad()
• hess()

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: ndarray, positions: ndarray, lattice: ndarray | None = None, periodic: 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: ndarray, lattice: 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: ndarray, positions: ndarray, lattice: ndarray | None = None, periodic: 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_hessian(param: DampingParam) → dict

Evaluate the analytical second derivatives of the dispersion energy with respect to the nuclear coordinates.

The hessian is returned as a symmetric 3*n by 3*n matrix in Hartree per Bohr squared, using the index convention 3*i + c for the Cartesian component c of atom i.

get_pairwise_dispersion(param: DampingParam) → dict

Evaluate pairwise representation of the dispersion energy

set_ewald_summation(rank: int = 0, tolerance: float = 0.0, kcut: float = 0.0, mesh: int = 0) → None

Evaluate the two-body dispersion energy by summation over the reciprocal lattice, which removes the truncation error of the real space summation.

Requires three-dimensional periodic boundary conditions and a damping function with a known reciprocal space representation, currently the rational and the zero damping function. The two-body realspace cutoff is ignored once this is enabled.

Non-positive arguments select the respective default, a vanishing rank derives the rank of the expansion from the tolerance and a vanishing reciprocal cutoff derives it from the damping radii.

The mesh selects how the reciprocal space sum is evaluated. Zero derives a particle mesh from the reciprocal cutoff, which scales as O(N log N) and is the default. A positive value interpolates the structure factors on a mesh of that many points per direction, rounded up to a power of two, and a negative value sums over the reciprocal lattice directly, which is exact but scales quadratically with the number of atoms.

set_ghost_atoms(ghost_atoms) → None

Disable dispersion contributions from selected atoms.

set_realspace_cutoff(disp2: float, disp3: float, cn: float, width2: float = 0.0, width3: float = 0.0)

Set realspace cutoff for evaluation of interactions

set_work_partition(part: int, nparts: int) → None

Assign an externally managed part of the interaction loops to this model.

Parts are zero based, summing the results of all parts reproduces the complete calculation. Structure dependent quantities are evaluated for the full system on every part, only the pairwise, three-body and reciprocal space loops are partitioned.

The MPI aware entry points of the C API are not bound here, binding a communicator would make mpi4py a dependency. Distribute the parts yourself and reduce the results.

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.

CSODampingParam

class dftd3.interface.CSODampingParam(**kwargs)

CSO (C6-scaled only) damping function.[9] Reformulation of the D3(Becke-Johnson) dispersion correction using only C6 dispersion coefficients with a sigmoidal interpolation function.

This constructor allows to automatically load the parameterized damping function from the library. Only eight functionals are parametrized with this scheme.

ZDampingParam

class dftd3.interface.ZDampingParam(**kwargs)

Z damping function for DFT-D3, based on the atomic-number damping form proposed for XDM(Z).

No dedicated D3(Z) parameters are available; the internal parameter loader uses XDM(Z) values for the supported functionals.

GeometricCounterpoise

class dftd3.interface.GeometricCounterpoise(numbers: ndarray, positions: ndarray, lattice: ndarray | None = None, periodic: ndarray | None = None, method: str | None = None, basis: str | None = None)

Contains the required information to evaluate the counterpoise correction for a given geometry. The counterpoise correction is a method to correct the interaction energy in a supermolecular calculation for the basis set superposition error (BSSE).

get_counterpoise(grad: bool) → dict

Evaluate the counterpoise corrected interaction energy

get_hessian() → dict

Evaluate the analytical second derivatives of the counterpoise energy with respect to the nuclear coordinates.

The hessian is returned as a symmetric 3*n by 3*n matrix in Hartree per Bohr squared, using the index convention 3*i + c for the Cartesian component c of atom i.

set_realspace_cutoff(bas: float, srb: float)

Set realspace cutoff for evaluation of interactions

set_work_partition(part: int, nparts: int) → None

Assign an externally managed part of the interaction loops to these parameters.

Parts are zero based, summing the results of all parts reproduces the complete calculation.

The MPI aware entry points of the C API are not bound here, binding a communicator would make mpi4py a dependency. Distribute the parts yourself and reduce the results.

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.

[9]

Heiner Schröder, Anne Creon, and Tobias Schwabe. Reformulation of the D3 (Becke–Johnson) dispersion correction without resorting to higher than C6 dispersion coefficients. J. Chem. Theory Comput., 11(7):3163–3170, 2015. URL: https://pubs.acs.org/doi/10.1021/acs.jctc.5b00400, doi:10.1021/acs.jctc.5b00400.