dxtb.components.coulomb.AES2

dxtb.components.coulomb.AES2#

class dxtb.components.coulomb.AES2(dmp3, dmp5, dkernel, qkernel, shift, kexp, rmax, rad, vcn, 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 interaction matrices.
`get_atom_gradient`	Return zero gradient.
`get_cache`	Obtain the cache object.
`get_dipole_atom_energy`	Calculate atom-resolved dipolar energy.
`get_dipole_atom_potential`	Calculate atom-resolved dipolar 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`	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`	Calculate atom-resolved dipolar energy.
`get_quadrupole_atom_potential`	Calculate atom-resolved quadrupolar 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

`dmp3`	Damping function for inverse quadratic contributions.
`dmp5`	Damping function for inverse cubic contributions.
`dkernel`	Kernel for on-site dipole exchange-correlation.
`qkernel`	Kernel for on-site quadrupole exchange-correlation.
`shift`	Shift for the generation of the multipolar damping radii.
`kexp`	Exponent for the generation of the multipolar damping radii.
`rmax`	Maximum radius for the multipolar damping radii.
`rad`	Base radii for the multipolar damping radii.
`vcn`	Valence coordination number.
`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:

dmp3 (Tensor)
dmp5 (Tensor)
dkernel (Tensor)
qkernel (Tensor)
shift (Tensor)
kexp (Tensor)
rmax (Tensor)
rad (Tensor)
vcn (Tensor)
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.

Parameters:

positions (Tensor) – Cartesian coordinates of all atoms (shape: (..., nat, 3)).
cvars (tuple[Tensor, ...])
tol (float | None)

Returns:

Flag for set up status.

Return type:

bool

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

get_atom_coulomb_matrix(numbers, positions, rad)[source]#

Calculate the atom-resolved interaction matrices.

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.
rad (Tensor)

Returns:

Interaction matrices for: - charges and dipoles (shape: (..., nat, nat, 3)), - dipoles and dipoles (shape: (..., nat, nat, 3, 3)), - charges and quadrupoles (shape: (..., nat, nat, 6)).

Return type:

tuple[Tensor, Tensor, Tensor]

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:

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).
charges (Tensor)
cache (InteractionCache)
grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)
retain_graph (bool | None)
create_graph (bool | None)

Returns:

Nuclear gradient for each atom.

Return type:

Tensor

get_cache(*, numbers=None, positions=None, ihelp=None)[source]#

Obtain the cache object.

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 anisotropic second order electrostatics.

Return type:

AES2Cache

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)[source]#

Calculate atom-resolved dipolar energy.

Parameters:

cache (ComponentCache) – Restart data for the interaction.
qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).
qdp (Tensor) – Atom-resolved shadow charges (shape: (..., nat, 3)).
qqp (Tensor) – Atom-resolved quadrupole moments (shape: (..., nat, 6)).

Returns:

Atom-resolved dipolar energy.

Return type:

Tensor

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

Calculate atom-resolved dipolar potential.

Parameters:

cache (ComponentCache) – 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 monopolar potential.

Return type:

Tensor

get_energy(cache, charges, ihelp)#

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

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

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.

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.
grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)
retain_graph (bool | None)
create_graph (bool | None)

Returns:

Nuclear gradient for each atom.

Return type:

Tensor

get_monopole_atom_energy(cache, qat, **_)#

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.

Parameters:

qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).
cache (InteractionCache)
_ (Any)

Returns:

Energy vector for each atom partial charge.

Return type:

Tensor

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

Calculate atom-resolved potential.

Parameters:

cache (ComponentCache) – 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 monopolar potential.

Return type:

Tensor

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.

Parameters:

qat (Tensor) – Shell-resolved partial charges.
cache (InteractionCache)
_ (Any)

Returns:

Energy vector for each shell partial charge.

Return type:

Tensor

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.

Parameters:

cache (InteractionCache) – Restart data for the interaction.
qsh (Tensor) – Shell-resolved partial charges.
qdp (Tensor | None)
qqp (Tensor | None)

Returns:

Potential vector for each atom partial charge.

Return type:

Tensor

get_potential(cache, charges, ihelp)#

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

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

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

Calculate atom-resolved dipolar energy.

Parameters:

cache (ComponentCache) – Restart data for the interaction.
qat (Tensor) – Atom-resolved partial charges (shape: (..., nat)).
qdp (Tensor) – Atom-resolved shadow charges (shape: (..., nat, 3)).
qqp (Tensor) – Atom-resolved quadrupole moments (shape: (..., nat, 6)).

Returns:

Atom-resolved dipolar energy.

Return type:

Tensor

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

Calculate atom-resolved quadrupolar potential.

Parameters:

cache (ComponentCache) – 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 monopolar potential.

Return type:

Tensor

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:

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).
charges (Tensor)
cache (InteractionCache)
grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)
retain_graph (bool | None)
create_graph (bool | None)

Returns:

Nuclear gradient for each atom.

Return type:

Tensor

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

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.

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.

Return type:: None

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

Parameters:

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

Returns:

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

Return type:

TensorLike

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.

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.

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.

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

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.

dkernel: Tensor#: Kernel for on-site dipole exchange-correlation.

dmp3: Tensor#: Damping function for inverse quadratic contributions.

dmp5: Tensor#: Damping function for inverse cubic contributions.

property dtype: dtype#: Floating point dtype used by class object.

kexp: Tensor#: Exponent for the generation of the multipolar damping radii.

label: str#: Label for the interaction.

qkernel: Tensor#: Kernel for on-site quadrupole exchange-correlation.

rad: Tensor#: Base radii for the multipolar damping radii.

rmax: Tensor#: Maximum radius for the multipolar damping radii.

shift: Tensor#: Shift for the generation of the multipolar damping radii.

vcn: Tensor#: Valence coordination number.

dxtb.components.coulomb.AES2

Contents

dxtb.components.coulomb.AES2#