dxtb.components.coulomb.ES2

dxtb.components.coulomb.ES2#

class dxtb.components.coulomb.ES2(hubbard, lhubbard=None, average=<function harmonic_average>, gexp=tensor(2.), shell_resolved=True, device=None, dtype=None)[source]#

Bases: Interaction

Isotropic second-order electrostatic energy (ES2).

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_coulomb_matrix`	Calculate the atom-resolved Coulomb matrix.
`get_atom_gradient`	Calculates nuclear gradient of an second order electrostatic energy contribution via PyTorch's autograd engine.
`get_cache`	Obtain the cache object containing the Coulomb matrix.
`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`	Compute the energy from the charges, all quantities are atom-resolved.
`get_monopole_atom_potential`	Calculate atom-resolved potential.
`get_monopole_shell_energy`	Compute the energy from the charges, all quantities are shell-resolved.
`get_monopole_shell_potential`	Calculate shell-resolved 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_coulomb_matrix`	Calculate the Coulomb matrix.
`get_shell_gradient`	Calculates nuclear gradient of an second order electrostatic energy contribution via PyTorch's autograd engine.
`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`	Hubbard parameters of all elements.
`lhubbard`	Shell-resolved scaling factors for Hubbard parameters.
`average`	Function to use for averaging the Hubbard parameters.
`gexp`	Exponent of the second-order Coulomb interaction.
`shell_resolved`	Whether electrostatics is shell-resolved.
`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 (Tensor)
lhubbard (Tensor | None)
average (Callable[[Tensor], Tensor])
gexp (Tensor)
shell_resolved (bool)
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_coulomb_matrix(numbers, positions, ihelp)[source]#

Calculate the atom-resolved Coulomb matrix.

Return type:

Tensor

Parameters:

numbers (Tensor) – Atomic numbers for all atoms in the system (shape: (..., nat)).
positions (Tensor) – Cartesian coordinates of all atoms (shape: (..., nat, 3)).
ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Coulomb matrix.

Return type:

Tensor

Parameters:

numbers (Tensor)
positions (Tensor)
ihelp (IndexHelper)

get_atom_gradient(charges, positions, cache, grad_outputs=None, retain_graph=True, create_graph=None)[source]#

Calculates nuclear gradient of an second order electrostatic energy contribution via PyTorch’s autograd engine.

Return type:

Tensor

Parameters:

charges (Tensor) – Atom-resolved partial charges (shape: (..., nat)).
positions (Tensor) – Nuclear positions. Needs requires_grad=True.
cache (ES2Cache) – Cache object for second order electrostatics.
grad_out (Tensor | None) – Gradient of previous computation, i.e., “vector” in VJP of this gradient computation. Defaults to None.

Returns:

Nuclear gradient of energy.

Return type:

Tensor

Raises:

RuntimeError – positions tensor does not have requires_grad=True.

Parameters:

charges (Tensor)
positions (Tensor)
cache (ES2Cache)
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]#

Obtain the cache object containing the Coulomb matrix.

Return type:

ES2Cache

Parameters:

numbers (Tensor) – Atomic numbers for all atoms in the system (shape: (..., nat)).
positions (Tensor) – Cartesian coordinates of all atoms (shape: (..., nat, 3)).
ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Cache object for second order electrostatics.

Return type:

ES2Cache

Parameters:

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

Note

The cache of an interaction requires positions as they do not change during the self-consistent charge iterations.

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]#

Compute the energy from the charges, 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:

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

Returns:

Energy vector for each atom partial charge.

Return type:

Tensor

Parameters:

cache (ES2Cache)
qat (Tensor)
_ (Any)

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

Calculate atom-resolved potential. Zero if this interaction is shell-resolved.

Return type:

Tensor

Parameters:

cache (ES2Cache) – Cache object for second order electrostatics.
qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).

Returns:

Atom-resolved potential.

Return type:

Tensor

Parameters:

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

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

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 (ES2Cache)
qat (Tensor)
_ (Any)

get_monopole_shell_potential(cache, qsh, qdp=None, qqp=None)[source]#

Calculate shell-resolved potential. Zero if this interaction is only atom-resolved.

Return type:

Tensor

Parameters:

cache (ES2Cache) – Cache object for second order electrostatics.
qsh (Tensor) – Shell-resolved partial charges.

Returns:

Shell-resolved potential.

Return type:

Tensor

Parameters:

cache (ES2Cache)
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_coulomb_matrix(numbers, positions, ihelp)[source]#

Calculate the Coulomb matrix.

Return type:

Tensor

Parameters:

numbers (Tensor) – Atomic numbers for all atoms in the system (shape: (..., nat)).
positions (Tensor) – Cartesian coordinates of all atoms (shape: (..., nat, 3)).
ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Coulomb matrix.

Return type:

Tensor

Parameters:

numbers (Tensor)
positions (Tensor)
ihelp (IndexHelper)

get_shell_gradient(charges, positions, cache, grad_outputs=None, retain_graph=True, create_graph=None)[source]#

Calculates nuclear gradient of an second order electrostatic energy contribution via PyTorch’s autograd engine.

Return type:

Tensor

Parameters:

charges (Tensor) – Shell-resolved partial charges.
positions (Tensor) – Nuclear positions. Needs requires_grad=True.
cache (ES2Cache) – Cache object for second order electrostatics.
grad_out (Tensor | None) – Gradient of previous computation, i.e., “vector” in VJP of this gradient computation.

Returns:

Nuclear gradient of energy.

Return type:

Tensor

Raises:

RuntimeError – positions tensor does not have requires_grad=True.

Parameters:

charges (Tensor)
positions (Tensor)
cache (ES2Cache)
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, …]

average: AveragingFunction#

Function to use for averaging the Hubbard parameters.

Default:: dxtb._src.components.interactions.average.harmonic_average()

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.

gexp: Tensor#

Exponent of the second-order Coulomb interaction.

Default:: 2.0

hubbard: Tensor#: Hubbard parameters of all elements.

label: str#: Label for the interaction.

lhubbard: Tensor | None#

Shell-resolved scaling factors for Hubbard parameters.

Default:: None (i.e., no shell resolution).

shell_resolved: bool#

Whether electrostatics is shell-resolved.

Default:: True

dxtb.components.coulomb.ES2

Contents

dxtb.components.coulomb.ES2#