Integrals

Integrals#

Integrals: Overview#

This module stores the container, drivers and underlying implementations of the integrals.

For the GFNn-xTB family of methods, only two-center one-electron integrals are required.

  • GFN1-xTB: Overlap Integral

  • GFN2-xTB: Overlap, Dipole, and Quadrupole Integral

Fundametally, there are two drivers (backends) for the integral computation:

  • PyTorch: pure PyTorch implementation, only overlap integral

  • `libcint <https://github.com/sunqm/libcint>`_: Python interface with custom backward functions for derivatives; arbitrary integrals and derivatives

We generally recommend the libcint driver as it is much faster, especially for derivatives. The driver can be selected with the int_driver keyword in the calculator options:

import torch
from dxtb.calculators import GFN1Calculator as Calculator

numbers = torch.tensor([3, 1])
opts = {"int_driver": "libcint"}
calc = Calculator(numbers, opts=opts)

print(calc.opts.ints.driver)  # 0

For all available keywords and settings, see here.

Integrals: Wrappers/Shortcuts#

A simple collection of convenience functions to obtain all integral matrices. This is intended for testing and developing. In these functions, defaults will be applied. Although (some) settings can be accessed through keyword arguments, it is recommended to follow the interal integral builds as used in the Integrals class for more direct control.

Note that there are several peculiarities for the multipole integrals:

  • The multipole operators are centered on (0, 0, 0) (r0) and not on the ket (rj), the latter being the default in dxtb.

  • An overlap calculation is executed for the normalization of the multipole integral every time dipole() or quadrupole() are called.

  • The quadrupole integral is not in its traceless representation.

Example

from dxtb.integrals.wrappers import overlap, dipint, quadint
from dxtb import GFN1_XTB as par
import torch

numbers = torch.tensor([14, 1, 1, 1, 1])
positions = torch.tensor([
    [0.00000000000000, 0.00000000000000, 0.00000000000000],
    [1.61768389755830, 1.61768389755830, -1.61768389755830],
    [-1.61768389755830, -1.61768389755830, -1.61768389755830],
    [1.61768389755830, -1.61768389755830, 1.61768389755830],
    [-1.61768389755830, 1.61768389755830, 1.61768389755830],
])

# Calculate the overlap integrals using the GFN1_XTB parameters
s = overlap(numbers, positions, par)
print(s.shape)  # Output: torch.Size([17, 17])

# Calculate the dipole integrals
d = dipint(numbers, positions, par)
print(d.shape)  # Output: torch.Size([3, 17, 17])

# Calculate the quadrupole integrals
q = quadint(numbers, positions, par)
print(q.shape)  # Output: torch.Size([9, 17, 17])

Integrals: Drivers#

Integral drivers are the main interface to the integral implementations. They provide a unified interface to the integral implementations, and are responsible for the calculation of the integrals.

There are two main types of integral drivers: PyTorch and Libcint. Note that the Libcint drivers are only available if the tad-libcint library is installed. The PyTorch drivers are implemented in pure Python, but are currently only available for overlap integrals.

Integrals: Types#

Integral objects for the calculation of various molecular integrals.

Currently, the following integral types are supported:

  • Overlap

  • Dipole

  • Quadrupole

Note that the Hamiltonian is different as it does not require a driver.

Contents