dxtb.components.dispersion.DispersionD4SC

class dxtb.components.dispersion.DispersionD4SC(param, model, rcov, r4r2, cutoff, counting_function=<function erf_count>, damping_function=<tad_dftd4.damping.functions.RationalDamping object>, device=None, dtype=None)

Bases: Interaction

Self-consistent D4 dispersion correction (DispersionD4SC).

Initialize the interaction.

Methods

cache_disable	Disable the cache.
cache_enable	Enable the cache.
cache_invalidate	Invalidate the cache to require renewed setup.
cache_is_latest	Check if the driver is set up and updated.
cpu	Returns a copy of the TensorLike instance on the CPU.
get_atom_gradient	Return zero gradient.
get_cache	Create restart data for individual interactions.
get_dipole_atom_energy	Compute the energy from the atomic dipole moments, all quantities are atom-resolved.
get_dipole_atom_potential	Compute the dipole potential.
get_energy	Compute the energy from the charges, all quantities are orbital-resolved.
get_gradient	Compute the nuclear gradient using orbital-resolved charges.
get_monopole_atom_energy	Calculate the D4 dispersion correction energy.
get_monopole_atom_potential	Calculate the D4 dispersion correction potential.
get_monopole_shell_energy	Compute the energy from the charges, all quantities are shell-resolved.
get_monopole_shell_potential	Compute the potential from the charges, all quantities are shell-resolved.
get_potential	Compute the potential from the charges, all quantities are orbital-resolved.
get_quadrupole_atom_energy	Compute the energy from the atomic quadrupole moments, all quantities are atom-resolved.
get_quadrupole_atom_potential	Compute the quadrupole potential.
get_shell_gradient	Return zero gradient.
override_device	Override the device of the class object.
override_dtype	Override the dtype of the class object.
reset	Reset the tensor attributes of the dxtb.components.base.Component instance to their original states or to specified values.
to	Returns a copy of the TensorLike instance on the specified device.
type	Returns a copy of the TensorLike instance with specified floating point type.
update	Update the attributes of the Component instance.

Attributes

param	Dispersion parameters.
model	Model for the D4 dispersion correction.
rcov	Covalent radii of all atoms.
r4r2	R4/R2 ratio of all atoms.
cutoff	Real-space cutoff for the D4 dispersion correction.
counting_function	Counting function for the coordination number.
damping_function	Damping function for the dispersion correction.
allowed_dtypes	Specification of dtypes that the TensorLike object can take.
cache	Cache for the interaction.
cache_is_setup	Whether the cache has been set up.
dd	Shortcut for device and dtype.
device	The device on which the class object resides.
dtype	Floating point dtype used by class object.
label	Label for the interaction.

Parameters:

• param (Param)

• model (D4Model)

• rcov (Tensor)

• r4r2 (Tensor)

• cutoff (Cutoff)

• counting_function (Callable[[Tensor, Tensor], Tensor])

• damping_function (Damping)

• device (torch.device | None)

• dtype (torch.dtype | None)

cache_disable()

Disable the cache.

Return type:

None

cache_enable()

Enable the cache.

Return type:

None

cache_invalidate()

Invalidate the cache to require renewed setup.

Return type:

None

cache_is_latest(cvars, tol=None)

Check if the driver is set up and updated.

Return type:

bool

Parameters:

positions (Tensor) – Cartesian coordinates of all atoms (shape: (..., nat, 3)).

Returns:

Flag for set up status.

Return type:

bool

Parameters:

• cvars (tuple[Tensor, ...])

• tol (float | 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

get_atom_gradient(charges, positions, cache, grad_outputs=None, retain_graph=True, create_graph=None)

Return zero gradient.

This method should be implemented by the subclass. However, returning zeros here serves three purposes: :rtype: Tensor

• the interaction can (theoretically) be empty

• the gradient of the interaction is indeed zero and thus requires no gradient implementation (one can, however, implement a method that returns zeros to make this more obvious)

• the interaction always uses shell-resolved charges and atom-resolved charges are never required

Parameters:

positions (Tensor) – Cartesian coordinates (for shape of gradient).

Returns:

Nuclear gradient for each atom.

Return type:

Tensor

Parameters:

• charges (Tensor)

• positions (Tensor)

• cache (InteractionCache)

• grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)

• retain_graph (bool | None)

• create_graph (bool | None)

get_cache(*, numbers=None, positions=None, ihelp=None, **_)

Create restart data for individual interactions.

Return type:

DispersionD4SCCache

Parameters:

• numbers (Tensor) – Atomic numbers for all atoms in the system (shape: (..., nat)).

• ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Restart data for the interaction.

Return type:

DispersionD4SCCache

Parameters:

• numbers (Tensor | None)

• positions (Tensor | None)

• ihelp (IndexHelper | None)

Note

If the DispersionD4SC interaction is evaluated within the dxtb.components.InteractionList, positions will be passed as an argument, too. Hence, it is necessary to absorb the positions in the signature of the function (also see dxtb.components.Interaction.get_cache()).

get_dipole_atom_energy(cache, qat, qdp=None, qqp=None)

Compute the energy from the atomic dipole moments, all quantities are atom-resolved.

This method should be implemented by the subclass. Here, it serves only to create an empty Interaction by returning zeros.

Return type:

Tensor

Parameters:

• cache (InteractionCache) – Restart data for the interaction.

• qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).

• qdp (Tensor) – Atom-resolved dipole moments (shape: (..., nat, 3)).

• qqp (Tensor) – Atom-resolved quadrupole moments (shape: (..., nat, 6)).

Returns:

Energy vector for each atomic dipole moment.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• qat (Tensor)

• qdp (Tensor | None)

• qqp (Tensor | None)

get_dipole_atom_potential(cache, qat, qdp=None, qqp=None)

Compute the dipole potential. All quantities are atom-resolved.

This method should be implemented by the subclass. Here, it serves only to create an empty Interaction by returning None.

Return type:

Tensor | None

Parameters:

• cache (InteractionCache) – Restart data for the interaction.

• qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).

• qdp (Tensor) – Atom-resolved dipole moments (shape: (..., nat, 3)).

• qqp (Tensor) – Atom-resolved quadrupole moments (shape: (..., nat, 6)).

Returns:

Atom-resolved potential vector for each atom or None if not needed.

Return type:

Tensor | None

Parameters:

• cache (InteractionCache)

• qat (Tensor)

• qdp (Tensor | None)

• qqp (Tensor | None)

get_energy(cache, charges, ihelp)

Compute the energy from the charges, all quantities are orbital-resolved.

Return type:

Tensor

Parameters:

• cache (InteractionCache) – Restart data for the interaction.

• charges (Charges) – Collection of charges. Monopolar partial charges are orbital-resolved.

• ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Atom-resolved energy vector.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• charges (Charges)

• ihelp (IndexHelper)

Note

The subclasses of dxtb.components.base.Interaction should implement the get_<type>_energy methods. If they are not implemented in the subclass, they will evaluate to zero.

get_gradient(charges, positions, cache, ihelp, grad_outputs=None, retain_graph=True, create_graph=None)

Compute the nuclear gradient using orbital-resolved charges.

Return type:

Tensor

Parameters:

• charges (Charges)

• positions (Tensor)

• cache (InteractionCache)

• ihelp (IndexHelper)

• grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)

• retain_graph (bool | None)

• create_graph (bool | None)

Note

This method calls both get_atom_gradient() and get_shell_gradient() and adds up both gradients. Hence, one of the contributions must be zero.

Parameters:

• charges (Tensor) – Orbital-resolved partial charges.

• positions (Tensor) – Cartesian coordinates of all atoms (shape: (..., nat, 3)).

• cache (InteractionCache) – Restart data for the interaction.

• ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Nuclear gradient for each atom.

Return type:

Tensor

Parameters:

• charges (Charges)

• positions (Tensor)

• cache (InteractionCache)

• ihelp (IndexHelper)

• grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)

• retain_graph (bool | None)

• create_graph (bool | None)

get_monopole_atom_energy(cache, qat, **_)

Calculate the D4 dispersion correction energy.

Return type:

Tensor

Parameters:

• cache (DispersionD4SCCache) – Restart data for the interaction.

• qat (Tensor) – Atomic charges of all atoms.

Returns:

Atomwise D4 dispersion correction energies.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• qat (Tensor)

• _ (Any)

get_monopole_atom_potential(cache, qat, *_, **__)

Calculate the D4 dispersion correction potential.

Return type:

Tensor

Parameters:

• cache (DispersionD4SCCache) – Restart data for the interaction.

• qat (Tensor) – Atomic charges of all atoms.

Returns:

Atomwise dispersion correction potential.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• qat (Tensor)

• _ (Any)

• __ (Any)

get_monopole_shell_energy(cache, qat, **_)

Compute the energy from the charges, all quantities are shell-resolved.

This method should be implemented by the subclass. Here, it serves only to create an empty Interaction by returning zeros.

Return type:

Tensor

Parameters:

qat (Tensor) – Shell-resolved partial charges.

Returns:

Energy vector for each shell partial charge.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• qat (Tensor)

• _ (Any)

get_monopole_shell_potential(cache, qsh, qdp=None, qqp=None)

Compute the potential from the charges, all quantities are shell-resolved.

This method should be implemented by the subclass. Here, it serves only to create an empty Interaction by returning zeros.

Return type:

Tensor

Parameters:

• cache (InteractionCache) – Restart data for the interaction.

• qsh (Tensor) – Shell-resolved partial charges.

Returns:

Potential vector for each atom partial charge.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• qsh (Tensor)

• qdp (Tensor | None)

• qqp (Tensor | None)

get_potential(cache, charges, ihelp)

Compute the potential from the charges, all quantities are orbital-resolved.

Return type:

Potential

Parameters:

• cache (InteractionCache) – Restart data for the interaction.

• charges (Charges) – Orbital-resolved partial charges.

• ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Potential vector for each orbital partial charge.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• charges (Charges)

• ihelp (IndexHelper)

get_quadrupole_atom_energy(cache, qat, qdp=None, qqp=None)

Compute the energy from the atomic quadrupole moments, all quantities are atom-resolved.

This method should be implemented by the subclass. Here, it serves only to create an empty Interaction by returning zeros.

Return type:

Tensor

Parameters:

• cache (InteractionCache) – Restart data for the interaction.

• qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).

• qdp (Tensor) – Atom-resolved dipole moments (shape: (..., nat, 3)).

• qqp (Tensor) – Atom-resolved quadrupole moments (shape: (..., nat, 6)).

Returns:

Energy vector for each atomic quadrupole moment.

Return type:

Tensor

Parameters:

• cache (InteractionCache)

• qat (Tensor)

• qdp (Tensor | None)

• qqp (Tensor | None)

get_quadrupole_atom_potential(cache, qat, qdp=None, qqp=None)

Compute the quadrupole potential. All quantities are atom-resolved.

This method should be implemented by the subclass. Here, it serves only to create an empty Interaction by returning None.

Return type:

Tensor | None

Parameters:

• cache (InteractionCache) – Restart data for the interaction.

• qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).

• qdp (Tensor) – Atom-resolved dipole moments (shape: (..., nat, 3)).

• qqp (Tensor) – Atom-resolved quadrupole moments (shape: (..., nat, 6)).

Returns:

Atom-resolved potential vector for each atom or None if not needed.

Return type:

Tensor | Nene

Parameters:

• cache (InteractionCache)

• qat (Tensor)

• qdp (Tensor | None)

• qqp (Tensor | None)

get_shell_gradient(charges, positions, cache, grad_outputs=None, retain_graph=True, create_graph=None)

Return zero gradient.

This method should be implemented by the subclass. However, returning zeros here serves three purposes: :rtype: Tensor

• the interaction can (theoretically) be empty

• the gradient of the interaction is indeed zero and thus requires no gradient implementation (one can, however, implement a method that returns zeros to make this more obvious)

• the interaction always uses atom-resolved charges and shell-resolved charges are never required

Parameters:

positions (Tensor) – Cartesian coordinates (for shape of gradient).

Returns:

Nuclear gradient for each atom.

Return type:

Tensor

Parameters:

• charges (Tensor)

• positions (Tensor)

• cache (InteractionCache)

• grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)

• retain_graph (bool | None)

• create_graph (bool | 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

reset()

Reset the tensor attributes of the dxtb.components.base.Component instance to their original states or to specified values.

This method iterates through the attributes defined in __slots__ and resets any tensor attributes to a detached clone of their original state. The requires_grad status of each tensor is preserved.

Return type:

None

Examples

import torch
from dxtb.components.base.field import ElectricField

ef = ElectricField(field=torch.tensor([0.0, 0.0, 0.0]))
ef.reset()

Notes

Only tensor attributes defined in __slots__ are reset. Non-tensor attributes are ignored. Attempting to reset an attribute not defined in __slots__ or providing a non-tensor value in kwargs will not raise an error; the method will simply ignore these cases and proceed with the reset operation for valid tensor attributes.

to(device=None, dtype=None)

Returns a copy of the TensorLike instance on the specified device.

This method creates and returns a new copy of the TensorLike instance on the specified device “device”.

Return type:

Self

Parameters:

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

Returns:

A copy of the TensorLike instance placed on the specified device.

Return type:

TensorLike

Parameters:

• device (device | None)

• dtype (dtype | None)

Notes

If the TensorLike instance is already on the desired device self will be returned.

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.

update(**kwargs)

Update the attributes of the Component instance.

This method updates the attributes of the Component instance based on the provided keyword arguments. Only the attributes defined in __slots__ can be updated.

Return type:

None

Parameters:

kwargs (dict[str, Any]) – Keyword arguments where keys are attribute names and values are the new values for those attributes. Valid keys are those defined in __slots__ of this class.

Raises:

AttributeError – If any key in kwargs is not an attribute defined in __slots__.

Parameters:

kwargs (Any)

Examples

import torch
from dxtb.components.field import ElectricField

ef = ElectricField(field=torch.tensor([0.0, 0.0, 0.0]))
ef.update(field=torch.tensor([1.0, 0.0, 0.0]))

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, …]

property cache: ComponentCache | None

Cache for the interaction.

property cache_is_setup: bool

Whether the cache has been set up.

counting_function: CountingFunction

Counting function for the coordination number.

Default:

tad_mctc.ncoord.erf_count()

cutoff: d4.cutoff.Cutoff

Real-space cutoff for the D4 dispersion correction.

damping_function: d4.damping.Damping

Damping function for the dispersion correction.

Default:

d4.damping.RationalDamping()

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.

label: str

Label for the interaction.

model: d4.model.D4Model

Model for the D4 dispersion correction.

param: d4.Param

Dispersion parameters.

r4r2: Tensor

R4/R2 ratio of all atoms.

rcov: Tensor

Covalent radii of all atoms.