dxtb.components.dispersion.DispersionD3

class dxtb.components.dispersion.DispersionD3(numbers, param, charge=None, ref_charges='eeq', device=None, dtype=None)

Bases: Dispersion

Representation of the DFT-D3(BJ) dispersion correction (DispersionD3).

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	Obtain cache for storage of settings.
get_energy	Get D3 dispersion energy.
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

numbers	(..., nat)).
param	Dispersion parameters.
charge	Total charge of the system.
ref_charges	Reference charges for the dispersion model.
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:

• numbers (Tensor)

• param (Param)

• charge (Tensor | None)

• ref_charges (Literal['eeq', 'gfn2'])

• 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_cache(numbers, ihelp=None, **kwargs)

Obtain cache for storage of settings.

Settings can be passed as kwargs. The available optional parameters are the same as in tad_dftd3.dftd3(), i.e., “ref”, “rcov”, “rvdw”, and “r4r2”.

Return type:

DispersionD3Cache

Parameters:

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

Returns:

Cache for the D3 dispersion.

Return type:

DispersionD3Cache

Parameters:

• numbers (Tensor)

• ihelp (IndexHelper | None)

• kwargs (Any)

get_energy(positions, cache, **kwargs)

Get D3 dispersion energy.

Return type:

Tensor

Parameters:

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

• cache (ComponentCache) – Dispersion cache containing settings.

Returns:

Atom-resolved D3 dispersion energy.

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.

charge: Tensor | None

Total charge of the system.

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.

numbers: Tensor

(..., nat)).

Type:

Atomic numbers for all atoms in the system (shape

param: D4Param

Dispersion parameters.

ref_charges: Literal['eeq', 'gfn2']

Reference charges for the dispersion model. This is only required for charge-dependent models.

Default:

"eeq"