dxtb.calculators.EnergyCalculator

Contents

dxtb.calculators.EnergyCalculator#

class dxtb.calculators.EnergyCalculator(numbers, par, *, classical=None, interaction=None, opts=None, cache=None, device=None, dtype=None, **kwargs)[source]#

Bases: BaseCalculator

Parametrized calculator defining the extended tight-binding model.

This class provides the basic functionality for the extended tight-binding model. It provides methods for single point calculations, nuclear gradients, Hessians, molecular properties, and spectra.

Instantiate the Calculator object with the following parameters:

Parameters:

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

  • par (Param) – Representation of an extended tight-binding model (full xTB parametrization). Decides energy contributions.

  • classical (Sequence[Classical] | None, optional) – Additional classical contributions. Defaults to None.

  • interaction (Sequence[Interaction] | None, optional) – Additional self-consistent contributions (interactions). Defaults to None.

  • opts (dict[str, Any] | None, optional) – Calculator options. If None (default) is given, default options are used automatically.

  • device (torch.device | None, optional) – Device to store the tensor on. If None (default), the default device is used.

  • dtype (torch.dtype | None, optional) – Data type of the tensor. If None (default), the data type is inferred.

  • kwargs (Any) – Additional keyword arguments. - auto_int_level: Automatically set the integral level based on

    the parametrization. Defaults to True. This should only be turned off for testing purposes.

    • timer: Enable the timer. Defaults to False. The global timer can also be enabled by setting the environment variable DXTB_TIMER to 1.

Parameters:

Methods

bond_orders

Calculate the (Wiberg) bond order matrix.

calculate

Calculate the requested properties.

cpu

Returns a copy of the TensorLike instance on the CPU.

energy

Calculate the total energy \(E\) of the system.

get_bond_orders

get_charges

Get orbital-resolved Mulliken charges.

get_coefficients

get_density

get_dipole

get_dipole_deriv

get_dipole_derivatives

get_dipole_moment

get_energy

get_forces

Calculate the nuclear forces \(f\) via AD.

get_frequencies

get_hessian

get_hyperpolarizability

get_implemented_properties

get_ir

get_ir_intensities

get_iterations

get_mo_energies

get_mulliken_charges

get_normal_modes

get_occupation

get_pol_deriv

get_polarizability

get_polarizability_derivatives

get_potential

get_potential_energy

get_property

Get the named property.

get_raman

get_raman_depol

get_raman_intensities

get_vibration

override_device

Override the device of the class object.

override_dtype

Override the dtype of the class object.

reset

Reset the calculator to its initial state.

singlepoint

Entry point for performing single point calculations.

to

Returns a copy of the TensorLike instance on the specified device.

type

Returns a copy of the class instance with specified floating point type.

Attributes

numbers

(..., nat)).

cache

Cache for storing multiple calculation results.

opts

Calculator configuration.

classicals

Classical contributions.

interactions

Interactions to minimize in self-consistent iterations.

integrals

Integrals for the extended tight-binding model.

ihelp

Helper class for indexing.

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.

implemented_properties

Names of implemented methods of the Calculator.

results

Results container.
bond_orders(positions, chrg=0, spin=None, **kwargs)[source]#

Calculate the (Wiberg) bond order matrix.

Return type:

Tensor

Parameters:

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

  • chrg (Tensor | float | int, optional) – Total charge. Defaults to 0.

  • spin (Tensor | float | int, optional) – Number of unpaired electrons. Defaults to None.

Returns:

Bond order matrix.

Return type:

Tensor

Parameters:
calculate(properties, positions, chrg=0, spin=None, **kwargs)[source]#

Calculate the requested properties. This is more of a dispatcher method that calls the appropriate methods of the Calculator.

Parameters:

  • properties (list[str]) – List of properties to calculate.

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

  • chrg (Tensor | float | int, optional) – Total charge. Defaults to 0.

  • spin (Tensor | float | int, optional) – Number of unpaired electrons. Defaults to None.

Returns:

Dictionary of calculated properties.

Return type:

dict

Parameters:
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

energy(positions, chrg=0, spin=None, **kwargs)[source]#

Calculate the total energy \(E\) of the system.

Return type:

Tensor

Parameters:

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

  • chrg (Tensor | float | int, optional) – Total charge. Defaults to 0.

  • spin (Tensor | float | int, optional) – Number of unpaired electrons. Defaults to None.

Returns:

Total energy of the system (scalar value).

Return type:

Tensor

Parameters:
get_bond_orders(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_charges(positions, chrg=0, spin=None, **kwargs)#

Get orbital-resolved Mulliken charges.

Return type:

Tensor

Parameters:

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

  • chrg (Tensor | float | int, optional) – Total charge. Defaults to 0.

  • spin (Tensor | float | int | None, optional) – Number of unpaired electrons. Defaults to 0.

  • **kwargs (Any) – Additional keyword arguments.

Returns:

Orbital-resolved Mulliken charges of shape (..., nao).

Return type:

Tensor

Parameters:

Example

import torch
import dxtb

dd = {"dtype": torch.double, "device": torch.device("cpu")}
numbers = torch.tensor([3, 1], device=dd["device"])
positions = torch.tensor([[0.0, 0.0, 0.0], [0.0, 0.0, 1.5]], **dd)

calc = dxtb.calculators.GFN1Calculator(numbers, **dd)

charges_nao = calc.get_charges(positions)
print(f"Expected shape: {torch.Size([6])}")
print(f"Actual shape  : {charges_nao.shape}")

charges_nat = calc.ihelp.reduce_orbital_to_atom(charges_nao)
print(f"Expected shape: {torch.Size([2])}")
print(f"Actual shape  : {charges_nat.shape}")
get_coefficients(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_density(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_dipole(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_dipole_deriv(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_dipole_derivatives(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_dipole_moment(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_energy(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_forces(positions, chrg=0, spin=None, grad_mode='autograd', **kwargs)#

Calculate the nuclear forces \(f\) via AD. :rtype: Tensor

\[f = -\dfrac{\partial E}{\partial R}\]

One can calculate the Jacobian either row-by-row using the standard torch.autograd.grad() with unit vectors in the VJP or using torch.func’s function transforms (e.g., torch.func.jacrev()).

Note

Using torch.func’s function transforms can apparently be only used once. Hence, for example, the Hessian and the dipole derivatives cannot be both calculated with functorch.

Parameters:

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

  • chrg (Tensor | float | int, optional) – Total charge. Defaults to 0.

  • spin (Tensor | float | int, optional) – Number of unpaired electrons. Defaults to None.

  • grad_mode (Literal, optional) – Specify the mode for gradient calculation. Possible options are:

    • “autograd” (default): Use PyTorch’s torch.autograd.grad().

    • “backward”: Use PyTorch’s backward function.

    • “functorch”: Use functorch’s jacrev.

    • “row”: Use PyTorch’s autograd row-by-row (unnecessary here).

Returns:

Atomic forces of shape (..., nat, 3).

Return type:

Tensor

Parameters:
get_frequencies(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_hessian(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_hyperpolarizability(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_implemented_properties()#
Return type:

list[str]

get_ir(positions, chrg=0, spin=None, **kwargs)#
Return type:

IRResult

Parameters:
get_ir_intensities(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_iterations(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_mo_energies(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_mulliken_charges(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_normal_modes(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_occupation(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_pol_deriv(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_polarizability(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_polarizability_derivatives(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_potential(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_potential_energy(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_property(name, positions, chrg=0, spin=None, allow_calculation=True, return_clone=False, **kwargs)#

Get the named property.

Return type:

Tensor | VibResult | IRResult | RamanResult | None

Parameters:

  • name (str) – Name of the property to get.

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

  • chrg (Tensor | float | int, optional) – Total charge. Defaults to 0.

  • spin (Tensor | float | int, optional) – Number of unpaired electrons. Defaults to None.

  • allow_calculation (bool, optional) – If the property is not present, allow its calculation. This does not check if we even allow caching or if the inputs are the same. Use with caution. Defaults to True.

  • return_clone (bool, optional) – If True, return a clone of the property. Defaults to False.

Parameters:
get_raman(positions, chrg=0, spin=None, **kwargs)#
Return type:

RamanResult

Parameters:
get_raman_depol(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_raman_intensities(positions, chrg=0, spin=None, **kwargs)#
Return type:

Tensor

Parameters:
get_vibration(positions, chrg=0, spin=None, **kwargs)#
Return type:

VibResult

Parameters:
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 calculator to its initial state.

Return type:

None

singlepoint(positions, chrg=0, spin=None, **kwargs)[source]#

Entry point for performing single point calculations.

Parameters:

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

  • chrg (Tensor | float | int, optional) – Total charge. Defaults to 0 (also for batched calculations).

  • spin (Tensor | float | int, optional) – Number of unpaired electrons. Defaults to 0.

Parameters:
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:

Notes

If the TensorLike instance is already on the desired device self will be returned.

type(dtype)#

Returns a copy of the class instance with specified floating point type.

This method overrides the usual approach because the dxtb.Calculator’s arguments and slots differ significantly. Hence, it is not practical to instantiate a new copy.

Return type:

Self

Parameters:

dtype (torch.dtype) – Floating point type.

Returns:

A copy of the class instance with the specified dtype.

Return type:

Self

Raises:

  • RuntimeError – If the __slots__ attribute is not set in the class.

  • DtypeError – If the specified dtype is not allowed.

Parameters:

dtype (dtype)

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

cache: CalculatorCache#

Cache for storing multiple calculation results.

classicals: ClassicalList#

Classical contributions.

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.

ihelp: IndexHelper#

Helper class for indexing.

implemented_properties: list[str] = ['bond_orders', 'energy', 'coefficients', 'charges', 'density', 'iterations', 'mo_energies', 'occupation', 'potential']#

Names of implemented methods of the Calculator.

integrals: Integrals#

Integrals for the extended tight-binding model.

interactions: InteractionList#

Interactions to minimize in self-consistent iterations.

numbers: Tensor#

(..., nat)).

Type:

Atomic numbers for all atoms in the system (shape

opts: Config#

Calculator configuration.

results: dict[str, Any]#

Results container.

Contents