dxtb.components.base.InteractionList

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

Bases: ComponentList[Interaction]

List of interactions.

Instantiate a collection of tight-binding components.

Parameters:

• compontents (tuple[Component | None, ...] | list[Component | None]) – List or tuple of compontent classes.

• components (list[C])

• device (torch.device | None)

• dtype (torch.dtype | None)

Note

Duplicate components will be removed automatically.

Methods

cpu	Returns a copy of the TensorLike instance on the CPU.
get_cache	Create restart data for individual interactions.
get_energy	Compute the energy for a list of interactions.
get_energy_as_dict	Compute the energy for a list of interactions.
get_gradient	Calculate gradient for a list of interactions.
get_interaction	Obtain an component from the list of components by its class name.
get_potential	Compute the potential for a list of interactions.
override_device	Override the device of the class object.
override_dtype	Override the dtype of the class object.
reset	Reset the attributes of an component object within the list.
reset_all	Reset tensor attributes to a detached clone of the current state.
reset_d4sc	Reset the attributes of the 'reset_d4sc' object within the list.
reset_efield	Reset the attributes of the 'reset_efield' object within the list.
reset_efield_grad	Reset the attributes of the 'reset_efield_grad' object within the list.
reset_es2	Reset the attributes of the 'reset_es2' object within the list.
reset_es3	Reset the attributes of the 'reset_es3' object within the list.
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 an interaction object within the list.
update_d4sc	Update the attribute of the 'd4sc' object based on the provided arguments in the keyword arguments.
update_efield	Update the attribute of the 'efield' object based on the provided arguments in the keyword arguments.
update_efield_grad	Update the attribute of the 'efield_grad' object based on the provided arguments in the keyword arguments.
update_es2	Update the attribute of the 'es2' object based on the provided arguments in the keyword arguments.
update_es3	Update the attribute of the 'es3' object based on the provided arguments in the keyword arguments.

Attributes

components	List of tight-binding component instances.
allowed_dtypes	Specification of dtypes that the TensorLike object can take.
dd	Shortcut for device and dtype.
device	The device on which the class object resides.
dtype	Floating point dtype used by class object.
labels	Alphabetically sorted list of all components labels.

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_cache(numbers, positions, ihelp)

Create restart data for individual interactions.

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:

Restart data for the interactions.

Return type:

InteractionListCache

get_energy(charges, cache, ihelp)

Compute the energy for a list of interactions.

Parameters:

• charges (Charges | Tensor) – Collection of charges. Monopolar partial charges are orbital-resolved.

• ihelp (IndexHelper) – Index mapping for the basis set.

• cache (InteractionListCache) – Restart data for the interaction.

Returns:

Atom-resolved energy vector for orbital partial charges.

Return type:

Tensor

get_energy_as_dict(charges, cache, ihelp)

Compute the energy for a list of interactions.

Parameters:

• charges (Charges) – Collection of charges. Monopolar partial charges are orbital-resolved.

• ihelp (IndexHelper) – Index mapping for the basis set.

• cache (InteractionListCache) – Restart data for the interaction.

Returns:

Energy vector for each orbital partial charge.

Return type:

Tensor

get_gradient(charges, positions, cache, ihelp, grad_outputs=None, retain_graph=True, create_graph=None)

Calculate gradient for a list of interactions.

Parameters:

• charges (Charges) – Collection of charges. Monopolar partial charges are orbital-resolved.

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

• cache (InteractionListCache) – 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 of all interactions.

Return type:

Tensor

get_interaction(name)

Obtain an component from the list of components by its class name.

Parameters:

name (str) – Name of the component.

Returns:

Instance of the component as present in the InteractionList.

Return type:

Interaction

Raises:

ValueError – Unknown component name given or component is not in the list.

get_potential(cache, charges, ihelp)

Compute the potential for a list of interactions.

Parameters:

• cache (InteractionListCache) – Restart data for the interactions.

• charges (Charges) – Collection of charges. Monopolar partial charges are orbital-resolved.

• ihelp (IndexHelper) – Index mapping for the basis set.

Returns:

Potential vector for each orbital partial charge.

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(name)

Reset the attributes of an component object within the list.

This method iterates through the components in the list, finds the one with the matching label, and resets any tensor attributes to a detached clone of their original state. The requires_grad status of each tensor is preserved.

Parameters:

name (str) – The label of the component object to be updated.

Returns:

The component object with the resetted attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

Examples

import torch
from dxtb._src.components.interactions import InteractionList
from dxtb._src.components.interactions.external import field as efield

ef = efield.new_efield(torch.tensor([0.0, 0.0, 0.0]))
ilist = InteractionList(ef)
ilist.reset(efield.LABEL_EFIELD)

reset_all()

Reset tensor attributes to a detached clone of the current state.

Return type:

None

reset_d4sc()

Reset the attributes of the ‘reset_d4sc’ object within the list.

This method resets any tensor attributes to a detached clone of their original state. The requires_grad status of each tensor is preserved.

Returns:

The component object with the resetted attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

reset_efield()

Reset the attributes of the ‘reset_efield’ object within the list.

This method resets any tensor attributes to a detached clone of their original state. The requires_grad status of each tensor is preserved.

Returns:

The component object with the resetted attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

reset_efield_grad()

Reset the attributes of the ‘reset_efield_grad’ object within the list.

This method resets any tensor attributes to a detached clone of their original state. The requires_grad status of each tensor is preserved.

Returns:

The component object with the resetted attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

reset_es2()

Reset the attributes of the ‘reset_es2’ object within the list.

This method resets any tensor attributes to a detached clone of their original state. The requires_grad status of each tensor is preserved.

Returns:

The component object with the resetted attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

reset_es3()

Reset the attributes of the ‘reset_es3’ object within the list.

This method resets any tensor attributes to a detached clone of their original state. The requires_grad status of each tensor is preserved.

Returns:

The component object with the resetted attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

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(name, **kwargs)

Update the attributes of an interaction object within the list.

This method iterates through the interactions in the list, finds the one with the matching label, and updates its attributes based on the provided arguments.

Parameters:

• name (str) – The label of the interaction object to be updated.

• kwargs (dict) – Keyword arguments containing the attributes and their new values to be updated in the interaction object.

Raises:

ValueError – If no interaction with the given label is found in the list.

Return type:

C

Examples

import torch
from dxtb._src.components.interactions import InteractionList
from dxtb._src.components.interactions.field import efield

field_vector = torch.tensor([0.0, 0.0, 0.0])
ef = efield.new_efield(field_vector)
ilist = InteractionList(ef)

new_field_vector = torch.tensor([1.0, 0.0, 0.0])
ilist.update(efield.LABEL_EFIELD, field=new_field_vector)

update_d4sc(**kwargs)

Update the attribute of the ‘d4sc’ object based on the provided arguments in the keyword arguments.

Parameters:

kwargs (dict) – Keyword arguments containing the attributes and their new values to be updated in the component object.

Returns:

The component object with the updated attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

Examples

See ComponentList.update.

update_efield(*, field=None)

Update the attribute of the ‘efield’ object based on the provided arguments in the keyword arguments.

Parameters:

• kwargs (dict) – Keyword arguments containing the attributes and their new values to be updated in the component object.

• field (Tensor | None)

Returns:

The component object with the updated attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

Examples

See ComponentList.update.

update_efield_grad(*, field_grad=None)

Update the attribute of the ‘efield_grad’ object based on the provided arguments in the keyword arguments.

Parameters:

• kwargs (dict) – Keyword arguments containing the attributes and their new values to be updated in the component object.

• field_grad (Tensor | None)

Returns:

The component object with the updated attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

Examples

See ComponentList.update.

update_es2(**kwargs)

Update the attribute of the ‘es2’ object based on the provided arguments in the keyword arguments.

Parameters:

kwargs (dict) – Keyword arguments containing the attributes and their new values to be updated in the component object.

Returns:

The component object with the updated attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

Examples

See ComponentList.update.

update_es3(**kwargs)

Update the attribute of the ‘es3’ object based on the provided arguments in the keyword arguments.

Parameters:

kwargs (dict) – Keyword arguments containing the attributes and their new values to be updated in the component object.

Returns:

The component object with the updated attributes.

Return type:

Component

Raises:

ValueError – If no component with the given label is found in the list.

Examples

See ComponentList.update.

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, …]

components: list[C]

List of tight-binding component instances.

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.

property labels: list[str]

Alphabetically sorted list of all components labels.