dxtb.components.coulomb.ES3

dxtb.components.coulomb.ES3#

class dxtb.components.coulomb.ES3(hubbard_derivs, shell_scale=None, device=None, dtype=None)[source]#

Bases: Interaction

On-site third-order electrostatic energy (ES3).

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 third-order electrostatic energy.
`get_monopole_atom_potential`	Calculate the third-order electrostatic potential.
`get_monopole_shell_energy`	Calculate the third-order electrostatic energy.
`get_monopole_shell_potential`	Calculate the third-order electrostatic potential.
`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

`hubbard_derivs`	Hubbard derivatives of all atoms.
`shell_scale`	Scaling factors for shell-resolved third-order electrostatics.
`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:

hubbard_derivs (Tensor)
shell_scale (Tensor | None)
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)[source]#

Create restart data for individual interactions.

Return type:

ES3Cache

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:

ES3Cache

Parameters:

numbers (Tensor | None)
positions (Tensor | None)
ihelp (IndexHelper | None)

Note

If the ES3 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, **_)[source]#

Calculate the third-order electrostatic energy.

Implements Eq.30 of the following paper: :rtype: Tensor

C. Bannwarth, E. Caldeweyher, S. Ehlert, A. Hansen, P. Pracht, J. Seibert, S. Spicher and S. Grimme, WIREs Computational Molecular Science, 2020, 11, e1493. DOI: 10.1002/wcms.1493

Parameters:

cache (ES3Cache) – Restart data for the interaction.
charges (Tensor) – Atomic charges of all atoms.

Returns:

Atom-wise third-order Coulomb interaction energies.

Return type:

Tensor

Parameters:

cache (ES3Cache)
qat (Tensor)
_ (Any)

get_monopole_atom_potential(cache, qat, qdp=None, qqp=None)[source]#

Calculate the third-order electrostatic potential. Zero if this interaction is shell-resolved.

Return type:

Tensor

Parameters:

qat (ES3Cache) – Restart data for the interaction.
charges (Tensor) – Atomic charges of all atoms.

Returns:

Atom-wise third-order Coulomb interaction potential.

Return type:

Tensor

Parameters:

cache (ES3Cache)
qat (Tensor)
qdp (Tensor | None)
qqp (Tensor | None)

get_monopole_shell_energy(cache, qat, **_)[source]#

Calculate the third-order electrostatic energy.

Return type:

Tensor

Parameters:

cache (ES3Cache) – Restart data for the interaction.
qat (Tensor) – Shell charges of all atoms.

Returns:

Shell-wise third-order Coulomb interaction energy.

Return type:

Tensor

Parameters:

cache (ES3Cache)
qat (Tensor)
_ (Any)

get_monopole_shell_potential(cache, qsh, *_, **__)[source]#

Calculate the third-order electrostatic potential. Zero if this interaction is atom-resolved.

Return type:

Tensor

Parameters:

qsh (Tensor) – Shell charges of all atoms.
cache (ES3Cache) – Restart data for the interaction.

Returns:

Shell-wise third-order Coulomb interaction potential.

Return type:

Tensor

Parameters:

cache (ES3Cache)
qsh (Tensor)
_ (Any)
__ (Any)

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.

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.

hubbard_derivs: Tensor#: Hubbard derivatives of all atoms.

label: str#: Label for the interaction.

shell_scale: Tensor | None#

Scaling factors for shell-resolved third-order electrostatics.

In GFN2-xTB, this is a tensor of shape (3,) containing the scaling factors for the s, p, and d shells.

Default:: None

dxtb.components.coulomb.ES3

Contents

dxtb.components.coulomb.ES3#