dxtb.components.base.Classical

class dxtb.components.base.Classical(device=None, dtype=None)

Bases: ClassicalABC, Component

Base class for calculation of classical contributions.

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_cache	Store variables for energy calculation.
get_energy	Obtain energy of the contribution.
get_gradient	Calculates nuclear gradient of a classical 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

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 classical contribution.

Parameters:

• 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

abstract get_cache(numbers, ihelp=None, **kwargs)

Store variables for energy calculation.

Return type:

ComponentCache

Parameters:

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

• ihelp (IndexHelper) – Helper class for indexing.

Returns:

Cache class for storage of variables.

Return type:

Cache

Parameters:

• numbers (Tensor)

• ihelp (IndexHelper | None)

• kwargs (Any)

Note

The cache of a classical contribution does not require positions as it only becomes useful if numbers remain unchanged and positions vary, i.e., during geometry optimization.

abstract get_energy(positions, cache, **kwargs)

Obtain energy of the contribution.

Return type:

Tensor

Parameters:

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

• cache (Cache) – Cache for the parameters.

Returns:

Atomwise energy contributions.

Return type:

Tensor

Parameters:

• positions (Tensor)

• cache (ComponentCache)

• kwargs (Any)

get_gradient(energy, positions, grad_outputs=None)

Calculates nuclear gradient of a classical energy contribution via PyTorch’s autograd engine.

Return type:

Tensor

Parameters:

• energy (Tensor) – Energy that will be differentiated.

• positions (Tensor) – Nuclear positions. Needs requires_grad=True.

• grad_outputs (Tensor | None, optional) – Vector in the vector-Jacobian product. If None, the vector is initialized to ones.

Returns:

Nuclear gradient of energy.

Return type:

Tensor

Raises:

RuntimeError – positions tensor does not have requires_grad=True.

Parameters:

• energy (Tensor)

• positions (Tensor)

• grad_outputs (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

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.

label: str

Label for the classical contribution.