Types of Calculators

Contents

Types of Calculators#

Calculators: Types#

All calculator types for the extended tight-binding models (xTB).

Besides the basic energy calculator, different calculator types utilize different methods for differentiation, i.e., analytical, numerical, or automatic differentiation (autograd). The central Calculator class inherits from all types, i.e., it provides the energy and properties via automatic, analytical, and numerical differentiation.

The available methods of the specific types can be checked with:

from dxtb.calculators import AutogradCalculator

print(AutogradCalculator.implemented_properties)

Since automatic differentiation is the main mode for derivative calculations, all methods are available. The same is true for numerical differentiation, which can be used for testing and debugging purposes. Only a few properties are implemented with analytical differentiation. The syntax for calling the methods is as follows:

  • Automatic differentiation: calc.forces(positions)

  • Analytical differentiation: calc.forces_analytical(positions)

  • Numerical differentiation: calc.forces_numerical(positions)

Calculators: AD#

Using the get_ methods will automatically select automatic differentiation when multiple methods are available.

Note that most properties require Jacobians instead of vector-Jacobian products (VJP), which can be calculated row-by-row using the standard torch.autograd.grad() function with unit vectors in the VJP (see here) or using torch.func’s function transforms (e.g., torch.func.jacrev()). The selection can be made with the use_functorch keyword argument.

While using functorch is faster, it is sometimes less stable and does not work if we need to differentiate for multiple properties at once (e.g., Hessian and dipole moment for IR spectra). Hence, the default is use_functorch=False.

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

Bases: EnergyCalculator

Parametrized calculator defining the extended tight-binding model.

This class provides analytical formulas and/or gradients for certain properties.

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

Return type:

None

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.

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

Analytically calculate the electric dipole moment \(\mu\). :rtype: Tensor

\[\mu = \dfrac{\partial E}{\partial F}\]
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:

Electric dipole moment of shape (…, 3).

Return type:

Tensor

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

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.

Returns:

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

Return type:

Tensor

Parameters:
cache: CalculatorCache#

Cache for storing multiple calculation results.

classicals: ClassicalList#

Classical contributions.

ihelp: IndexHelper#

Helper class for indexing.

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

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.

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

Bases: EnergyCalculator

Parametrized calculator defining the extended tight-binding model.

This class provides properties via automatic differentiation.

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

Return type:

None

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.

Parameters:
dipole(positions, chrg=0, spin=None, use_functorch=False)[source]#

Calculate the electric dipole moment \(\mu\) via AD. :rtype: Tensor

\[\mu = \dfrac{\partial E}{\partial F}\]

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.

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd.

Returns:

Electric dipole moment of shape (..., 3).

Return type:

Tensor

Parameters:
dipole_deriv(positions, chrg=0, spin=None, use_analytical_dipmom=True, use_functorch=False, **kwargs)[source]#

Calculate cartesian dipole derivative \(\mu'\). :rtype: Tensor

\[\mu' = \dfrac{\partial \mu}{\partial R} = \dfrac{\partial^2 E}{\partial F \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.

  • use_analytical_dipmom (bool, optional) – Whether to use the analytically calculated dipole moment for AD or the automatically differentiated dipole moment.

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd.

Returns:

Cartesian dipole derivative of shape (..., 3, nat, 3).

Return type:

Tensor

Parameters:
forces(positions, chrg=0, spin=None, grad_mode='autograd', **kwargs)[source]#

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:
hessian(positions, chrg=0, spin=None, use_functorch=False, derived_quantity='forces', matrix=False, **kwargs)[source]#

Calculation of the nuclear Hessian with AD.

Return type:

Tensor

Parameters:

Note

The torch.func.jacrev() function of functorch requires scalars for the expected behavior, i.e., the nuclear Hessian only acquires the expected shape of (..., nat, 3, nat, 3) if the energy is provided as a scalar value.

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.

  • use_functorch (bool, optional) – Whether to use functorch for autodiff. Defaults to False.

  • derived_quantity (Literal[‘energy’, ‘forces’], optional) – Which derivative to calculate for the Hessian, i.e., derivative of forces or energy w.r.t. positions. Defaults to 'forces'.

  • matrix (bool, optional) – Whether to reshape the Hessian to a matrix, i.e., (nat*3, nat*3). Defaults to False.

Returns:

Hessian of shape (..., nat, 3, nat, 3) or (..., nat*3, nat*3).

Return type:

Tensor

Raises:

RuntimeError – Positions tensor does not have requires_grad=True.

Parameters:
hyperpolarizability(positions, chrg=0, spin=None, use_functorch=False, derived_quantity='pol')[source]#

Calculate the hyper polarizability tensor \(\beta\). :rtype: Tensor

\[\beta = \dfrac{\partial \alpha}{\partial F} = \dfrac{\partial^2 \mu}{\partial F^2} = \dfrac{\partial^3 E}{\partial^2 3}\]

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.

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd.

  • derived_quantity (Literal[‘energy’, ‘dipole’], optional) – Which derivative to calculate for the polarizability, i.e., derivative of dipole moment or energy w.r.t field.

Returns:

Hyper polarizability tensor of shape (..., 3, 3, 3).

Return type:

Tensor

Parameters:
ir(positions, chrg=0, spin=None, use_functorch=False, **kwargs)[source]#

Calculate the frequencies and intensities of IR spectra.

Return type:

IRResult

Parameters:

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

  • chrg (Tensor | float | int | str | None) – Total charge. Defaults to None.

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

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd. Defaults to False.

Returns:

Result container with frequencies (shape: (..., nfreqs)) and intensities (shape: (..., nfreqs)) of IR spectra.

Return type:

IRResult

Parameters:
pol_deriv(positions, chrg=0, spin=None, use_functorch=False, derived_quantity='dipole', **kwargs)[source]#

Calculate the cartesian polarizability derivative \(\chi\). :rtype: Tensor

\[\chi = \alpha' = \dfrac{\partial \alpha}{\partial R} = \dfrac{\partial^3 E}{\partial^2 F \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.

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd.

  • derived_quantity (Literal[‘energy’, ‘dipole’], optional) – Which derivative to calculate for the polarizability, i.e., derivative of dipole moment or energy w.r.t field.

Returns:

Polarizability derivative shape (..., 3, 3, nat, 3).

Return type:

Tensor

Parameters:
polarizability(positions, chrg=0, spin=None, use_functorch=False, use_analytical=False, derived_quantity='dipole')[source]#

Calculate the polarizability tensor \(\alpha\). :rtype: Tensor

\[\alpha = \dfrac{\partial \mu}{\partial F} = \dfrac{\partial^2 E}{\partial^2 F}\]

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.

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd.

  • use_analytical (bool, optional) – Whether to use the analytically calculated dipole moment for AD or the automatically differentiated dipole moment. Defaults to False.

  • derived_quantity (Literal[‘energy’, ‘dipole’], optional) – Which derivative to calculate for the polarizability, i.e., derivative of dipole moment or energy w.r.t field.

Returns:

Polarizability tensor of shape (..., 3, 3).

Return type:

Tensor

Parameters:
raman(positions, chrg=0, spin=None, use_functorch=False, **kwargs)[source]#

Calculate the frequencies, static intensities and depolarization ratio of Raman spectra. Formula taken from here.

Return type:

RamanResult

Parameters:

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

  • chrg (Tensor | float | int | str | None) – Total charge. Defaults to None.

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

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd. Defaults to False.

Returns:

Result container with frequencies (shape: (..., nfreqs)), intensities (shape: (..., nfreqs)) and the depolarization ratio (shape: (..., nfreqs)) of Raman spectra.

Return type:

RamanResult

Parameters:
vibration(positions, chrg=0, spin=None, use_functorch=False, project_translational=True, project_rotational=True, **kwargs)[source]#

Perform vibrational analysis. This calculates the Hessian matrix and diagonalizes it to obtain the vibrational frequencies and normal modes.

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

Return type:

VibResult

Parameters:

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.

  • use_functorch (bool, optional) – Whether to use functorch or the standard (slower) autograd.

  • project_translational (bool, optional) – Project out translational modes. Defaults to True.

  • project_rotational (bool, optional) – Project out rotational modes. Defaults to True.

Returns:

Result container with vibrational frequencies (shape: (..., nfreqs)) and normal modes (shape: (..., nat*3, nfreqs)).

Return type:

VibResult

Parameters:
cache: CalculatorCache#

Cache for storing multiple calculation results.

classicals: ClassicalList#

Classical contributions.

ihelp: IndexHelper#

Helper class for indexing.

implemented_properties: list[str] = ['bond_orders', 'energy', 'coefficients', 'charges', 'density', 'iterations', 'mo_energies', 'occupation', 'potential', 'forces', 'hessian', 'vibration', 'normal_modes', 'frequencies', 'dipole', 'dipole_deriv', 'polarizability', 'pol_deriv', 'hyperpolarizability', 'ir', 'ir_intensity', 'raman', 'raman_intensity', 'rama_depol']#

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.

class dxtb._src.calculators.types.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:
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:
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:
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:
cache: CalculatorCache#

Cache for storing multiple calculation results.

classicals: ClassicalList#

Classical contributions.

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.

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

Bases: EnergyCalculator

Parametrized calculator defining the extended tight-binding model.

This class provides various molecular properties through numerical differentiation.

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

Return type:

None

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.

Parameters:
dipole_deriv_numerical(positions, chrg=0, spin=None, step_size=1e-05, **kwargs)[source]#

Numerically calculate cartesian dipole derivative \(\mu'\). :rtype: Tensor

\[\mu' = \dfrac{\partial \mu}{\partial R} = \dfrac{\partial^2 E}{\partial F \partial R}\]

Here, the analytical dipole moment is used for the numerical differentiation (if it is available in the calculator).

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.

  • step_size (int | float, optional) – Step size for numerical differentiation.

Returns:

Cartesian dipole derivative of shape (..., 3, nat, 3).

Return type:

Tensor

Parameters:
dipole_numerical(positions, chrg=0, spin=None, step_size=1e-05, **kwargs)[source]#

Numerically calculate the electric dipole moment \(\mu\). :rtype: Tensor

\[\mu = \dfrac{\partial E}{\partial F}\]
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.

  • step_size (int | float, optional) – Step size for numerical differentiation.

Returns:

Electric dipole moment of shape (..., 3).

Return type:

Tensor

Parameters:
forces_numerical(positions, chrg=0, spin=None, step_size=1e-05, **kwargs)[source]#

Numerically calculate the atomic forces \(f\). :rtype: Tensor

\[f = -\dfrac{\partial E}{\partial R}\]
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.

  • step_size (int | float, optional) – Step size for numerical differentiation.

Returns:

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

Return type:

Tensor

Parameters:
hessian_numerical(positions, chrg=0, spin=None, step_size=1e-05, matrix=False)[source]#

Numerically calculate the Hessian.

Return type:

Tensor

Parameters:

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

  • chrg (Tensor | float | int | str | None) – Total charge. Defaults to None.

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

  • step_size (int | float, optional) – Step size for numerical differentiation.

  • matrix (bool, optional) – Whether to reshape the Hessian to a matrix, i.e., (nat*3, nat*3). Defaults to False.

Returns:

Hessian of shape (..., nat, 3, nat, 3) or (..., nat*3, nat*3).

Return type:

Tensor

Parameters:
hyperpolarizability_numerical(positions, chrg=0, spin=None, step_size=1e-05)[source]#

Numerically calculate the hyper polarizability tensor \(\beta\). :rtype: Tensor

\[\beta = \dfrac{\partial \alpha}{\partial F} = \dfrac{\partial^2 \mu}{\partial F^2} = \dfrac{\partial^3 E}{\partial^2 3}\]
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.

  • step_size (float | int, optional) – Step size for the numerical derivative.

Returns:

Hyper polarizability tensor of shape (..., 3, 3, 3).

Return type:

Tensor

Parameters:
ir_numerical(positions, chrg=0, spin=None, step_size=1e-05)[source]#

Numerically calculate the frequencies and intensities of IR spectra.

Return type:

IRResult

Parameters:

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

  • chrg (Tensor | float | int | str | None) – Total charge. Defaults to None.

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

  • step_size (float | int, optional) – Step size for the numerical derivative.

Returns:

Result container with frequencies (shape: (..., nfreqs)) and intensities (shape: (..., nfreqs)) of IR spectra.

Return type:

vib.IRResult

Parameters:
pol_deriv_numerical(positions, chrg=0, spin=None, step_size=1e-05)[source]#

Numerically calculate the cartesian polarizability derivative \(\chi\). :rtype: Tensor

\[\chi = \alpha' = \dfrac{\partial \alpha}{\partial R} = \dfrac{\partial^2 \mu}{\partial F \partial R} = \dfrac{\partial^3 E}{\partial^2 F \partial R}\]
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.

  • step_size (float | int, optional) – Step size for the numerical derivative.

Returns:

Polarizability derivative shape (..., 3, 3, nat, 3).

Return type:

Tensor

Parameters:
polarizability_numerical(positions, chrg=0, spin=None, step_size=1e-05, **kwargs)[source]#

Numerically calculate the polarizability tensor \(\alpha\). :rtype: Tensor

\[\alpha = \dfrac{\partial \mu}{\partial F} = \dfrac{\partial^2 E}{\partial^2 F}\]

Here, the analytical dipole moment is used for the numerical derivative.

Parameters:

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

  • chrg (Tensor | float | int | str | None) – Total charge. Defaults to None.

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

  • step_size (float | int, optional) – Step size for the numerical derivative.

Returns:

Polarizability tensor of shape (..., 3, 3).

Return type:

Tensor

Parameters:
raman_numerical(positions, chrg=0, spin=None, step_size=1e-05)[source]#

Numerically calculate the frequencies, static intensities and depolarization ratio of Raman spectra. Formula taken from here.

Return type:

RamanResult

Parameters:

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

  • chrg (Tensor | float | int | str | None) – Total charge. Defaults to None.

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

  • step_size (float | int, optional) – Step size for the numerical derivative.

Returns:

Result container with frequencies (shape: (..., nfreqs)), intensities (shape: (..., nfreqs)) and the depolarization ratio (shape: (..., nfreqs)) of Raman spectra.

Return type:

vib.RamanResult

Parameters:
vibration_numerical(positions, chrg=0, spin=None, step_size=1e-05, project_translational=True, project_rotational=True)[source]#

Perform vibrational analysis via numerical Hessian. The Hessian matrix is diagonalized to obtain the vibrational frequencies and normal modes.

Return type:

VibResult

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.

  • step_size (int | float, optional) – Step size for numerical differentiation.

  • project_translational (bool, optional) – Project out translational modes. Defaults to True.

  • project_rotational (bool, optional) – Project out rotational modes. Defaults to True.

Returns:

Result container with vibrational frequencies (shape: (..., nfreqs)) and normal modes (shape: (..., nat*3, nfreqs)).

Return type:

vib.VibResult

Parameters:
cache: CalculatorCache#

Cache for storing multiple calculation results.

classicals: ClassicalList#

Classical contributions.

ihelp: IndexHelper#

Helper class for indexing.

implemented_properties: list[str] = ['bond_orders', 'energy', 'coefficients', 'charges', 'density', 'iterations', 'mo_energies', 'occupation', 'potential', 'forces', 'hessian', 'normal_modes', 'frequencies', 'dipole', 'dipole_deriv', 'polarizability', 'pol_deriv', 'hyperpolarizability', 'ir', 'raman']#

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.

Contents