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.

Parameters:

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

Return type:

Self

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.

Return type:

InteractionListCache

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

Parameters:

• numbers (Tensor)

• positions (Tensor)

• ihelp (IndexHelper)

get_energy(charges, cache, ihelp)

Compute the energy for a list of interactions.

Return type:

Tensor

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

Parameters:

• charges (Charges | Tensor)

• cache (InteractionListCache)

• ihelp (IndexHelper)

get_energy_as_dict(charges, cache, ihelp)

Compute the energy for a list of interactions.

Return type:

dict[str, Tensor]

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

Parameters:

• charges (Charges)

• cache (InteractionListCache)

• ihelp (IndexHelper)

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

Calculate gradient for a list of interactions.

Return type:

Tensor

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.

Returns:

Nuclear gradient of all interactions.

Return type:

Tensor

Parameters:

• charges (Charges)

• positions (Tensor)

• cache (InteractionListCache)

• ihelp (IndexHelper)

• grad_outputs (list[Tensor] | tuple[Tensor, ...] | Tensor | None)

• retain_graph (bool | None)

• create_graph (bool | None)

get_interaction(name)

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

Return type:

Interaction

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.

Parameters:

name (str)

get_potential(cache, charges, ihelp)

Compute the potential for a list of interactions.

Return type:

Potential

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

Parameters:

• cache (InteractionListCache)

• charges (Charges)

• ihelp (IndexHelper)

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

Return type:

TypeVar(C, bound= Component)

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.

Parameters:

name (str)

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.

Return type:

Interaction

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.

Return type:

Interaction

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.

Return type:

Interaction

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.

Return type:

Interaction

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.

Return type:

Interaction

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

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

Return type:

TypeVar(C, bound= Component)

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.

Parameters:

• name (str)

• kwargs (Any)

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.

Return type:

Interaction

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.

Parameters:

kwargs (Any)

Examples

See ComponentList.update.

update_efield(*, field=None)

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

Return type:

Interaction

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.

Parameters:

field (Tensor | None)

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.

Return type:

Interaction

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.

Parameters:

field_grad (Tensor | None)

Examples

See ComponentList.update.

update_es2(**kwargs)

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

Return type:

Interaction

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.

Parameters:

kwargs (Any)

Examples

See ComponentList.update.

update_es3(**kwargs)

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

Return type:

Interaction

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.

Parameters:

kwargs (Any)

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.