mlipops.DFTD3#

class mlipops.DFTD3(neighbor_list: NeighborList, s8: float, a1: float, a2: float, prefactor: float, bohr_radius: float)#

Compute the DFT-D3(BJ) dispersion potential.

This is a highly accurate model for dispersion that depends only on positions and atomic numbers. It supports all elements through Lawrencium (atomic number 103). It is described in https://doi.org/10.1063/1.3382344 and https://doi.org/10.1002/jcc.21759.

This class computes only the two body part of the potential. The original publication also described a three body part, but recommended omitting it by default.

The potential depends on three parameters called s8, a1, and a2. Normally they are chosen to give the best accuracy when combined with a particular DFT functional. The appropriate values will depend on how it is being used. For example, if a model is trained to reproduce DFT data without a dispersion correction, it would be appropriate to add a DFT-D3(BJ) potential using the parameters for the DFT functional used to generate the training data.

When performing backpropagation with Triton acceleration, this class can only compute first derivatives. If you need second derivatives, specify need_second_derivatives=True to disable Triton acceleration. This will make it slower, but allow for arbitrary derivatives.

When you create an instance of this class, you must specify the values of Coulomb’s constant 1/(4*pi*eps0) and the Bohr radius. The values you specify set the unit system. See the User Guide for the values in common unit systems.

__init__(neighbor_list: NeighborList, s8: float, a1: float, a2: float, prefactor: float, bohr_radius: float)#

Create on object for computing the DFT-D3(BJ) dispersion potential.

Parameters:

  • neighbor_list (NeighborList) – the NeighborList used to identify interactions. It determines the cutoff distance, the device to run on, and whether padding is used to enable caching of neighbors.

  • s8 (float) – the scale factor for the 1/r**8 term in the potential

  • a1 (float) – the first parameter of the Becke-Johnson damping function (dimensionless)

  • a2 (float) – the second parameter of the Becke-Johnson damping function (measured in Bohr)

  • prefactor (float) – Coulomb’s constant 1/(4*pi*eps0)

  • bohr_radius (float) – the Bohr radius

forward(positions: Tensor, atomic_numbers: Tensor, covalent_radii: Tensor, box_vectors: Tensor | None = None, batch: Tensor | None = None, need_second_derivatives: bool = False) → Tensor#

Compute the interaction.

Parameters:

  • positions (torch.Tensor) – a Tensor of shape (n_particles, 3) containing the Cartesian coordinates of each particle

  • atomic_numbers (torch.Tensor) – a Tensor of shape (n_particles,) containing the atomic number of each particle

  • covalent_radii (torch.Tensor | None) – a Tensor of shape (n_particles,) containing the covalent radius of each particle. These should be obtained by calling get_covalent_radii().

  • box_vectors (torch.Tensor | None) – if batch is None, a Tensor of shape (3, 3) containing box vectors defining the periodic box. If batch is not None, a Tensor of shape (n_systems, 3, 3) containing the box vectors for each system. If None, periodic boundary conditions are not used.

  • batch (torch.Tensor | None) – a Tensor of shape (n_particles,) containing the index of the system each particle belongs to. This must be sorted in ascending order, and every system must contain at least one particle. If None, the interaction is computed for a single system instead of a batch of systems.

  • need_second_derivatives (bool) – whether you intend to compute second derivatives of the returned value. This disables Triton acceleration.

Returns:

a torch.Tensor containing the energy of the interaction. If batch is None, this is a scalar containing the total energy. Otherwise, it has shape (n_systems,) containing the energy of each system in the batch.

Return type:

torch.Tensor