dxtb.integrals.types.DipoleIntegral

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

Bases: BaseIntegral

Dipole 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.
shift_r0_rj	Shift the centering of the dipole 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.
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

shift_r0_rj(overlap, pos)

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

\[\begin{split}\begin{align} D &= D^{r_j} \\ &= \langle i | r_j | j \rangle \\ &= \langle i | r | j \rangle - r_j \langle i | j \rangle \\ &= \langle i | r_0 | j \rangle - r_j S_{ij} \\ &= D^{r_0} - r_j S_{ij} \end{align}\end{split}\]

Parameters:

• r0 (Tensor) – Origin centered dipole integral.

• overlap (Tensor) – Overlap integral.

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

Raises:

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

Returns:

Second-index (ket) atom-centered dipole integral.

Return type:

Tensor

Parameters:

• overlap (Tensor)

• pos (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.

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)

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