dxtb.integrals.types.QuadrupoleIntegral

dxtb.integrals.types.QuadrupoleIntegral#

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

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.

Parameters:

driver (IntDriver) – Integral driver for the calculation.
kwargs (Any)

Returns:

Integral matrix.

Return type:

Tensor

checks(driver)#

Check if the driver is setup.

Parameters:: driver (IntDriver) – Integral driver for the calculation.
Return type:: None

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.

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.

Parameters:

driver (IntDriver) – Integral driver for the calculation.
kwargs (Any)

Returns:

Nuclear integral derivative matrix.

Return type:

Tensor

normalize(norm=None, **_)#

Normalize the integral (changes self.matrix).

Parameters:

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

Return type:

None

normalize_gradient(norm=None)#

Normalize the gradient (changes self.gradient).

Parameters:: norm (Tensor) – Overlap norm to normalize the integral.
Return type:: None

override_device(device)#

Override the device of the class object.

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.
Return type:: None

override_dtype(dtype)#

Override the dtype of the class object.

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.
Return type:: None

reduce_9_to_6(uplo='l')[source]#

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

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

shift_r0r0_rjrj(r0, overlap, pos, uplo='l')[source]#

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:

\[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.

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.

Parameters:

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

Returns:

A copy of the integral placed on the specified device.

Return type:

Self

to_pt(path=None)#

Save the integral matrix to a file.

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.
Return type:: None

traceless()[source]#

Make a quadrupole (integral) tensor traceless.

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.

Parameters:: dtype (torch.dtype) – Floating point type.
Returns:: A copy of the TensorLike instance with the specified dtype.
Return type:: TensorLike

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).

dxtb.integrals.types.QuadrupoleIntegral

Contents

dxtb.integrals.types.QuadrupoleIntegral#