PySCF Support

PySCF Support#

Compatibility layer for supporting DFT-D3 and GCP in pyscf.

class dftd3.pyscf.DFTD3Dispersion(mol: Mole | Cell, xc: str = 'hf', version: str = 'd3bj', atm: bool = False, param: Dict[str, float] | None = None, ewald: Dict[str, float] | None = None)[source]#

Implementation of the interface for using DFT-D3 in pyscf. The xc functional can be provided in the constructor together with the version of the DFT-D3 damping function to use. Possible damping functions are

"d3bj": (default): For rational damping function
"d3zero": For zero damping function
"d3mbj": Modified damping parameters for the rational damping function
"d3mzero": Modified version of the zero damping function
"d3op": Optimized power damping function
"d3cso": CSO (C6-scaled only) damping function
"d3z": Z damping function

Custom parameters can be provided with the param dictionary. The param dict contains the damping parameters, at least s8, a1 and a2 must be provided for rational damping, while s8 and rs6 are required in case of zero damping. For CSO and Z damping, a1 must be provided.

Parameters for (modified) rational damping are:

Tweakable parameter	Default	Description
s6	1.0	Scaling of the dipole-dipole dispersion
s8	None	Scaling of the dipole-quadrupole dispersion
s9	1.0	Scaling of the three-body dispersion energy
a1	None	Scaling of the critical radii
a2	None	Offset of the critical radii
alp	14.0	Exponent of the zero damping (ATM only)

Parameters for (modified) zero damping are:

Tweakable parameter	Default	Description
s6	1.0	Scaling of the dipole-dipole dispersion
s8	None	Scaling of the dipole-quadrupole dispersion
s9	1.0	Scaling of the three-body dispersion energy
rs6	None	Scaling of the dipole-dipole damping
rs8	1.0	Scaling of the dipole-quadrupole damping
alp	14.0	Exponent of the zero damping
bet	None	Offset for damping radius (modified zero damping)

Parameters for optimized power damping are:

Tweakable parameter	Default	Description
s6	1.0	Scaling of the dipole-dipole dispersion
s8	None	Scaling of the dipole-quadrupole dispersion
s9	1.0	Scaling of the three-body dispersion energy
a1	None	Scaling of the critical radii
a2	None	Offset of the critical radii
alp	14.0	Exponent of the zero damping (ATM only)
bet	None	Power for the zero-damping component

Parameters for CSO (C6-scaled only) damping are:

Tweakable parameter	Default	Description
s6	1.0	Scaling of the dipole-dipole dispersion
s9	1.0	Scaling of the three-body dispersion energy
a1	None	Sigmoid amplitude parameter
a2	2.5	Sigmoid reference distance scale
a3	0.0	Denominator critical radii scale
a4	6.25	Denominator constant offset
alp	14.0	Exponent of the zero damping (ATM only)

The version of the damping can be changed after constructing the dispersion correction. With the atm boolean the three-body dispersion energy can be enabled, which is generally recommended.

For a periodic cell the ewald dict enables the reciprocal space summation of the two-body dispersion energy, which removes the truncation error of the real space summation. An empty dict selects the default settings, the entries rank, tolerance and kcut allow to control the accuracy. The mesh entry switches to the particle mesh evaluation, which is substantially faster for large cells. This requires a cell with three-dimensional periodic boundary conditions and either the rational or the zero damping function.

Examples

>>> from pyscf import gto
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          C   -0.189833176  -0.645396435   0.069807761
...          C    1.121636324  -0.354065576   0.439096514
...          C    1.486520953   0.962572632   0.712107225
...          C    0.549329390   1.989209324   0.617868956
...          C   -0.757627135   1.681862630   0.246856908
...          C   -1.138190460   0.370551816  -0.028582325
...          Br  -2.038462778   3.070459841   0.115165429
...          H    1.852935245  -1.146434699   0.514119204
...          H    0.825048723   3.012176989   0.829385472
...          H    2.502259769   1.196433556   1.000317333
...          H   -2.157140187   0.151608161  -0.313181471
...          H   -0.480820487  -1.664983631  -0.142918416
...          S   -4.157443472   5.729584377  -0.878761129
...          H   -4.823791426   4.796089466  -1.563433338
...          C   -2.828338520   5.970593053  -2.091189515
...          H   -2.167577293   6.722356639  -1.668621815
...          H   -2.264954814   5.054835899  -2.240198499
...          H   -3.218524904   6.337447714  -3.035087058
...          '''
... )
>>> d3 = disp.DFTD3Dispersion(mol, xc="PW6B95", version="d3bj")
>>> d3.kernel()[0]
array(-0.01009386)
>>> d3.version = "d3zero"  # Change to zero damping
>>> d3.kernel()[0]
array(-0.00574098)
>>> d3.atm = True  # Activate three-body dispersion
>>> d3.kernel()[0]
array(-0.00574289)

dump_flags(verbose: bool | None = None) → DFTD3Dispersion[source]#: Show options used for the DFT-D3 dispersion correction.

hessian() → ndarray[source]#

Compute the analytical second derivatives of the DFT-D3 dispersion correction with respect to the nuclear coordinates.

Returns:: The dispersion hessian in the pyscf layout (natm, natm, 3, 3) in Hartree per Bohr squared.
Return type:: ndarray

Examples

>>> from pyscf import gto
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          O  0.00000000  0.00000000 -0.73578586
...          H  1.44183152  0.00000000  0.36789293
...          H -1.44183152  0.00000000  0.36789293
...          '''
... )
>>> d3 = disp.DFTD3Dispersion(mol, xc="PBE0")
>>> d3.hessian().shape
(3, 3, 3, 3)

kernel() → Tuple[float, ndarray, ndarray][source]#

Compute the DFT-D3 dispersion correction.

The dispersion model as well as the parameters are created locally and not part of the state of the instance.

Returns:: The energy and gradient of the DFT-D3 dispersion correction.
Return type:: float, ndarray

Examples

>>> from pyscf import gto
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          Br    0.000000    0.000000    1.919978
...          Br    0.000000    0.000000   -0.367147
...          N     0.000000    0.000000   -3.235006
...          C     0.000000    0.000000   -4.376626
...          H     0.000000    0.000000   -5.444276
...          '''
... )
>>> d3 = disp.DFTD3Dispersion(mol, xc="PBE0")
>>> energy, gradient = d3.kernel()
>>> energy
array(-0.00303589)
>>> gradient
array([[ 0.00000000e+00,  0.00000000e+00,  9.66197638e-05],
       [ 0.00000000e+00,  0.00000000e+00,  2.36000434e-04],
       [ 0.00000000e+00,  0.00000000e+00, -1.16718302e-04],
       [ 0.00000000e+00,  0.00000000e+00, -1.84332770e-04],
       [ 0.00000000e+00,  0.00000000e+00, -3.15691249e-05]])

reset(mol: Mole | Cell) → DFTD3Dispersion[source]#: Reset mol and clean up relevant attributes for scanner mode

class dftd3.pyscf.GeometricCounterpoiseCorrection(mol: Mole | Cell, method: str, basis: str)[source]#

Implementation of the interface for using GCP in pyscf.

Parameters:

mol (gto.Mole or pbc.gto.Cell) – The molecule or periodic cell for which the GCP correction is computed.
method (str) – The exchange-correlation functional to use for the GCP correction.
basis (str) – The basis set to use for the GCP correction.

dump_flags(verbose: bool | None = None) → GeometricCounterpoiseCorrection[source]#: Show options used for the GCP correction.

hessian() → ndarray[source]#

Compute the analytical second derivatives of the GCP correction with respect to the nuclear coordinates.

Returns:: The counter-poise hessian in the pyscf layout (natm, natm, 3, 3) in Hartree per Bohr squared.
Return type:: ndarray

Examples

>>> from pyscf import gto
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          O  0.00000000  0.00000000 -0.73578586
...          H  1.44183152  0.00000000  0.36789293
...          H -1.44183152  0.00000000  0.36789293
...          '''
... )
>>> gcp = disp.GeometricCounterpoiseCorrection(mol, "hf3c", "minix")
>>> gcp.hessian().shape
(3, 3, 3, 3)

kernel() → Tuple[float, ndarray, ndarray][source]#: Kernel function is the main driver of a method. Every method should define the kernel function as the entry of the calculation. Note the return value of kernel function is not strictly defined. It can be anything related to the method (such as the energy, the wave-function, the DFT mesh grids etc.).

reset(mol: Mole | Cell) → GeometricCounterpoiseCorrection[source]#: Reset mol and clean up relevant attributes for scanner mode

dftd3.pyscf.d3_energy(mf: SCF, method: str | None = None, **kwargs) → SCF[source]#

Apply DFT-D3 corrections to SCF or MCSCF methods by returning an instance of a new class built from the original instances class. The dispersion correction is stored in the with_dftd3 attribute of the class.

Parameters:

mf (scf.hf.SCF) – The method to which DFT-D3 corrections will be applied.
method (str, optional) – The exchange-correlation functional to use for the DFT-D3 correction.
**kwargs – Keyword arguments passed to the DFTD3Dispersion class.

Return type:

The method with DFT-D3 corrections applied.

Examples

>>> from pyscf import gto, scf
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          N  -1.57871857  -0.04661102   0.00000000
...          N   1.57871857   0.04661102   0.00000000
...          H  -2.15862174   0.13639605   0.80956529
...          H  -0.84947130   0.65819321   0.00000000
...          H  -2.15862174   0.13639605  -0.80956529
...          H   2.15862174  -0.13639605  -0.80956529
...          H   0.84947130  -0.65819321   0.00000000
...          H   2.15862174  -0.13639605   0.80956529
...          '''
... )
>>> mf = disp.d3_energy(scf.RHF(mol)).run()
converged SCF energy = -110.932603617026
>>> mf.kernel()
-110.93260361702605

dftd3.pyscf.d3_grad(scf_grad: GradientsBase, **kwargs) → GradientsBase[source]#

Apply DFT-D3 corrections to SCF or MCSCF nuclear gradients methods by returning an instance of a new class built from the original class. The dispersion correction is stored in the with_dftd3 attribute of the class.

Parameters:

scf_grad (rhf_grad.Gradients) – The method to which DFT-D3 corrections will be applied.
**kwargs – Keyword arguments passed to the DFTD3Dispersion class.

Return type:

The method with DFT-D3 corrections applied.

Examples

>>> from pyscf import gto, scf
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          O  -1.65542061  -0.12330038   0.00000000
...          O   1.24621244   0.10268870   0.00000000
...          H  -0.70409026   0.03193167   0.00000000
...          H  -2.03867273   0.75372294   0.00000000
...          H   1.57598558  -0.38252146  -0.75856129
...          H   1.57598558  -0.38252146   0.75856129
...          '''
... )
>>> grad = disp.d3_energy(scf.RHF(mol)).run().nuc_grad_method()
converged SCF energy = -149.947191000075
>>> g = grad.kernel()
--------------- DFTD3 gradients ---------------
         x                y                z
0 O     0.0171886976     0.0506606246     0.0000000000
1 O     0.0383596853    -0.0459057549     0.0000000000
2 H    -0.0313133974    -0.0125865676    -0.0000000000
3 H     0.0066705789    -0.0380501872     0.0000000000
4 H    -0.0154527822     0.0229409425     0.0215141991
5 H    -0.0154527822     0.0229409425    -0.0215141991
----------------------------------------------

dftd3.pyscf.d3_hess(scf_hess, **kwargs)[source]#

Apply DFT-D3 corrections to SCF nuclear hessian methods by returning an instance of a new class built from the original class. The dispersion correction is stored in the with_dftd3 attribute of the class.

Parameters:

scf_hess (hessian.rhf.Hessian) – The method to which DFT-D3 corrections will be applied.
**kwargs – Keyword arguments passed to the DFTD3Dispersion class.

Return type:

The hessian method with DFT-D3 corrections applied.

Examples

>>> from pyscf import gto, scf
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          O  0.00000000  0.00000000 -0.73578586
...          H  1.44183152  0.00000000  0.36789293
...          H -1.44183152  0.00000000  0.36789293
...          '''
... )
>>> mf = disp.d3_energy(scf.RHF(mol)).run()
>>> hess = mf.Hessian().kernel()

dftd3.pyscf.energy(mf: SCF, method: str | None = None, **kwargs) → SCF#: Alias for the d3_energy function, which applies DFT-D3 corrections to SCF or MCSCF methods.

dftd3.pyscf.gcp_energy(mf: SCF, method: str | None = None, basis: str | None = None) → SCF[source]#

Apply GCP corrections to SCF or MCSCF methods by returning an instance of a new class built from the original instances class. The GCP correction is stored in the with_gcp attribute of the class.

Parameters:

mf (scf.hf.SCF) – The method to which GCP corrections will be applied.
method (str, optional) – The exchange-correlation functional to use for the GCP correction.
basis (str, optional) – The basis set to use for the GCP correction.

Return type:

The method with GCP corrections applied.

dftd3.pyscf.gcp_grad(scf_grad: GradientsBase, **kwargs) → GradientsBase[source]#

Apply GCP corrections to SCF or MCSCF nuclear gradients methods by returning an instance of a new class built from the original class. The GCP correction is stored in the with_gcp attribute of the class.

Parameters:

scf_grad (rhf_grad.Gradients) – The method to which GCP corrections will be applied.
**kwargs – Keyword arguments passed to the GeometricCounterpoiseCorrection class.

Return type:

The method with GCP corrections applied.

dftd3.pyscf.gcp_hess(scf_hess, **kwargs)[source]#

Apply GCP corrections to SCF nuclear hessian methods by returning an instance of a new class built from the original class. The GCP correction is stored in the with_gcp attribute of the class.

Parameters:

scf_hess (hessian.rhf.Hessian) – The method to which GCP corrections will be applied.
**kwargs – Keyword arguments passed to the GeometricCounterpoiseCorrection class.

Return type:

The hessian method with GCP corrections applied.

Examples

>>> from pyscf import gto, scf
>>> import dftd3.pyscf as disp
>>> mol = gto.M(
...     atom='''
...          O  0.00000000  0.00000000 -0.73578586
...          H  1.44183152  0.00000000  0.36789293
...          H -1.44183152  0.00000000  0.36789293
...          '''
... )
>>> mf = disp.gcp_energy(scf.RHF(mol)).run()
>>> hess = mf.Hessian().kernel()

dftd3.pyscf.grad(scf_grad: GradientsBase, **kwargs) → GradientsBase#: Alias for the d3_grad function, which applies DFT-D3 corrections to SCF or MCSCF nuclear gradients methods.

dftd3.pyscf.hess(scf_hess, **kwargs)#: Alias for the d3_hess function, which applies DFT-D3 corrections to SCF nuclear hessian methods.

PySCF Support

Contents

PySCF Support#