dxtb.integrals.types.QuadrupoleIntegral

class dxtb.integrals.types.QuadrupoleIntegral(device=None, dtype=None, uplo='l', cutoff=50.0)

Bases: BaseIntegral

Quadrupole integral from atomic orbitals.

Methods

build	Create the integral matrix.
checks	Check if the driver is setup.
clear	Clear the integral matrix and gradient.
cpu	Returns a copy of the TensorLike instance on the CPU.
get_gradient	Calculate the full nuclear gradient matrix of the integral.
normalize	Normalize the integral (changes self.matrix).
normalize_gradient	Normalize the gradient (changes self.gradient).
override_device	Override the device of the class object.
override_dtype	Override the dtype of the class object.
reduce_9_to_6	Remove symmetry-equivalent elements from the quadrupole integral, i.e., only the lower/upper triangular matrix is kept.
shift_r0r0_rjrj	Shift the centering of the quadrupole integral (moment operator) from the origin (\(r0 = r - (0, 0, 0)\)) to atoms (ket index, \(rj = r - r_j\)).
to	Returns a copy of the integral on the specified device "device".
to_pt	Save the integral matrix to a file.
traceless	Make a quadrupole (integral) tensor traceless.
type	Returns a copy of the TensorLike instance with specified floating point type.

Attributes

family	Family of the integral implementation (PyTorch or libcint).
cutoff	Real-space cutoff for integral calculation in Bohr.
uplo	Whether the matrix of unique shell pairs should be create as a triangular matrix (l: lower, u: upper) or full matrix (n).
allowed_dtypes	Specification of dtypes that the TensorLike object can take.
dd	Shortcut for device and dtype.
device	The device on which the class object resides.
dtype	Floating point dtype used by class object.
gradient
matrix	Matrix of the integral.
norm
requires_grad	Check if any field of the integral class is requires gradient.

Parameters:

• device (torch.device | None)

• dtype (torch.dtype | None)

• uplo (Literal['n', 'u', 'l'])

• cutoff (Tensor | float | int | None)

abstract build(driver, **kwargs)

Create the integral matrix.

Return type:

Tensor

Parameters:

driver (IntDriver) – Integral driver for the calculation.

Returns:

Integral matrix.

Return type:

Tensor

Parameters:

• driver (IntDriver)

• kwargs (Any)

checks(driver)

Check if the driver is setup.

Return type:

None

Parameters:

driver (IntDriver) – Integral driver for the calculation.

Parameters:

driver (IntDriver)

clear()

Clear the integral matrix and gradient.

Return type:

None

cpu()

Returns a copy of the TensorLike instance on the CPU.

This method creates and returns a new copy of the TensorLike instance on the CPU.

Return type:

Self

Returns:

A copy of the TensorLike instance placed on the CPU.

Return type:

TensorLike

abstract get_gradient(driver, **kwargs)

Calculate the full nuclear gradient matrix of the integral.

Return type:

Tensor

Parameters:

driver (IntDriver) – Integral driver for the calculation.

Returns:

Nuclear integral derivative matrix.

Return type:

Tensor

Parameters:

• driver (IntDriver)

• kwargs (Any)

normalize(norm=None, **_)

Normalize the integral (changes self.matrix).

Return type:

None

Parameters:

norm (Tensor | None, optional) – Overlap norm to normalize the integral.

Parameters:

• norm (Tensor | None)

• _ (Any)

normalize_gradient(norm=None)

Normalize the gradient (changes self.gradient).

Return type:

None

Parameters:

norm (Tensor) – Overlap norm to normalize the integral.

Parameters:

norm (Tensor | None)

override_device(device)

Override the device of the class object. :rtype: None

Warning

This does not change the device of the underlying tensors. It only changes the device of the class object. Use with caution.

Parameters:

device (torch.device) – Device to override the current device.

Parameters:

device (device)

Return type:

None

override_dtype(dtype)

Override the dtype of the class object. :rtype: None

Warning

This does not change the dtype of the underlying tensors. It only changes the dtype of the class object. Use with caution.

Parameters:

dtype (torch.dtype) – Floating point dtype to override the current dtype.

Parameters:

dtype (dtype)

Return type:

None

reduce_9_to_6(uplo='l')

Remove symmetry-equivalent elements from the quadrupole integral, i.e., only the lower/upper triangular matrix is kept.

Lower triangular matrix: xx xy xz 0 1 2 0 yx yy yz <=> 3 4 5 -> 3 4 zx zy zz 6 7 8 6 7 8

Upper triangular matrix: xx xy xz 0 1 2 0 1 2 yx yy yz <=> 3 4 5 -> 4 5 zx zy zz 6 7 8 8

Return type:

Tensor

Parameters:

uplo (Literal[“u”, “U”, “l”, “L”], optional) – Upper or lower triangular matrix, by default “l”.

Returns:

Reduced quadrupole integral of shape (..., 6, n, n).

Return type:

Tensor

Parameters:

uplo (Literal['u', 'U', 'l', 'L'])

shift_r0r0_rjrj(r0, overlap, pos, uplo='l')

Shift the centering of the quadrupole integral (moment operator) from the origin (\(r0 = r - (0, 0, 0)\)) to atoms (ket index, \(rj = r - r_j\)).

The output tensor will always be of shape (..., 6, n, n), i.e., the quadrupole integral is always reduced to the lower/upper triangular matrix if not already done.

We start with the quadrupole integral generated by the r0 moment operator: :rtype: Tensor

\[Q_{xx}^{r0} = \langle i | (r_x - r0)^2 | j \rangle = \langle i | r_x^2 | j \rangle\]

Now, we shift the integral to r_j yielding the quadrupole integral center on the respective atoms:

\[\begin{split}\begin{align} Q_{xx} &= \langle i | (r_x - r_{xj})^2 | j \rangle \\ &= \langle i | r_x^2 | j \rangle - 2 \langle i | r_{xj} r_x | j \rangle + \langle i | r_{xj}^2 | j \rangle \\ &= Q_{xx}^{r0} - 2 r_{xj} \langle i | r_x | j \rangle + r_{xj}^2 \langle i | j \rangle \\ &= Q_{xx}^{r0} - 2 r_{xj} D_{x}^{r0} + r_{xj}^2 S_{ij} \end{align}\end{split}\]

Next, we create the shift contribution for all off-diagonal elements of the quadrupole integral.

\[\begin{split}\begin{align} Q_{ab} &= \langle i | (r_a - r_{aj})(r_b - r_{bj}) | j \rangle \\ &= \langle i | r_a r_b | j \rangle - \langle i | r_a r_{bj} | j \rangle - \langle i | r_{aj} r_b | j \rangle + \langle i | r_{aj} r_{bj} | j \rangle \\ &= Q_{ab}^{r0} - r_{bj} \langle i | r_a | j \rangle - r_{aj} \langle i | r_b | j \rangle + r_{aj} r_{bj} \langle i | j \rangle \\ &= Q_{ab}^{r0} - r_{bj} D_a^{r0} - r_{aj} D_b^{r0} + r_{aj} r_{bj} S_{ij} \end{align}\end{split}\]

Parameters:

• r0 (Tensor) – Origin-centered dipole integral.

• overlap (Tensor) – Monopole integral (overlap).

• pos (Tensor) – Orbital-resolved atomic positions.

• uplo (Literal[“u”, “U”, “l”, “L”], optional) – If the symmetry-equivalent elements have not been removed yet, this method will always do so by calling reduce_9_to_6(). With this parameter, you can specify whether the matrix is upper or lower triangular, by default “l”.

Returns:

Second-index (ket) atom-centered quadrupole integral of shape (..., 6, n, n).

Return type:

Tensor

Raises:

• RuntimeError – Shape mismatch between positions and overlap. The positions must be orbital-resolved.

• RuntimeError – Quadrupole integral is no 9xNxN or 6xNxN tensor.

Parameters:

• r0 (Tensor)

• overlap (Tensor)

• pos (Tensor)

• uplo (Literal['u', 'U', 'l', 'L'])

to(device=None, dtype=None)

Returns a copy of the integral on the specified device “device”. This is essentially a wrapper around the to() method of the TensorLike class, but explicitly also moves the integral matrix.

Return type:

Self

Parameters:

device (torch.device | None) – Device to which all associated tensors should be moved.

Returns:

A copy of the integral placed on the specified device.

Return type:

Self

Parameters:

• device (device | None)

• dtype (dtype | None)

to_pt(path=None)

Save the integral matrix to a file.

Return type:

None

Parameters:

path (PathLike | None) – Path to the file where the integral matrix should be saved. If None, the matrix is saved to the default location.

Parameters:

path (str | Path | None)

traceless()

Make a quadrupole (integral) tensor traceless.

Return type:

Tensor

Parameters:

qpint (Tensor) – Quadrupole moment tensor of shape (..., 6, n, n).

Returns:

Traceless Quadrupole moment tensor of shape (..., 6, n, n).

Return type:

Tensor

Raises:

RuntimeError – Supplied quadrupole integral is no 6xNxN tensor.

type(dtype)

Returns a copy of the TensorLike instance with specified floating point type. This method creates and returns a new copy of the TensorLike instance with the specified dtype.

Return type:

Self

Parameters:

dtype (torch.dtype) – Floating point type.

Returns:

A copy of the TensorLike instance with the specified dtype.

Return type:

TensorLike

Parameters:

dtype (dtype)

Notes

If the TensorLike instance has already the desired dtype Self will be returned.

property allowed_dtypes: tuple[dtype, ...]

Specification of dtypes that the TensorLike object can take. Defaults to float types and must be overridden by subclass if float are not allowed. The IndexHelper is an example that should only allow integers.

Returns:

Collection of allowed dtypes the TensorLike object can take.

Return type:

tuple[torch.dtype, …]

cutoff: Tensor | float | int | None

Real-space cutoff for integral calculation in Bohr. Defaults to constants.defaults.INTCUTOFF.

property dd: DD

Shortcut for device and dtype.

property device: device

The device on which the class object resides.

property dtype: dtype

Floating point dtype used by class object.

family: str | None

Family of the integral implementation (PyTorch or libcint).

property gradient: Tensor

property matrix: Tensor

Matrix of the integral.

property norm: Tensor | None

property requires_grad: bool

Check if any field of the integral class is requires gradient.

Returns:

Flag for gradient requirement.

Return type:

bool

uplo: Literal['n', 'u', 'l']

Whether the matrix of unique shell pairs should be create as a triangular matrix (l: lower, u: upper) or full matrix (n). Defaults to l (lower triangular matrix).