dxtb.calculators.GFN1Calculator

Contents

dxtb.calculators.GFN1Calculator#

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

Bases: Calculator

Calculator for the GFN1-xTB method.

This is a simple wrapper around the Calculator class with the GFN1-xTB parameters passed in as defaults.

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.

dipole

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

dipole_analytical

Analytically calculate the electric dipole moment \(\mu\).

dipole_deriv

Calculate cartesian dipole derivative \(\mu'\).

dipole_deriv_numerical

Numerically calculate cartesian dipole derivative \(\mu'\).

dipole_numerical

Numerically calculate the electric dipole moment \(\mu\).

energy

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

forces

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

forces_analytical

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

forces_numerical

Numerically calculate the atomic forces \(f\).

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

hessian

Calculation of the nuclear Hessian with AD.

hessian_numerical

Numerically calculate the Hessian.

hyperpolarizability

Calculate the hyper polarizability tensor \(\beta\).

hyperpolarizability_numerical

Numerically calculate the hyper polarizability tensor \(\beta\).

ir

Calculate the frequencies and intensities of IR spectra.

ir_numerical

Numerically calculate the frequencies and intensities of IR spectra.

override_device

Override the device of the class object.

override_dtype

Override the dtype of the class object.

pol_deriv

Calculate the cartesian polarizability derivative \(\chi\).

pol_deriv_numerical

Numerically calculate the cartesian polarizability derivative \(\chi\).

polarizability

Calculate the polarizability tensor \(\alpha\).

polarizability_numerical

Numerically calculate the polarizability tensor \(\alpha\).

raman

Calculate the frequencies, static intensities and depolarization ratio of Raman spectra.

raman_numerical

Numerically calculate the frequencies, static intensities and depolarization ratio of Raman spectra.

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.

vibration

Perform vibrational analysis.

vibration_numerical

Perform vibrational analysis via numerical Hessian.

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)#

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)#

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.

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

dipole(positions, chrg=0, spin=None, use_functorch=False)#

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_analytical(positions, chrg=0, spin=None, *_, **kwargs)#

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:
dipole_deriv(positions, chrg=0, spin=None, use_analytical_dipmom=True, use_functorch=False, **kwargs)#

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:
dipole_deriv_numerical(positions, chrg=0, spin=None, step_size=1e-05, **kwargs)#

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)#

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:
energy(positions, chrg=0, spin=None, **kwargs)#

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:
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:
forces_analytical(positions, chrg=0, spin=None, **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.

Returns:

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

Return type:

Tensor

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

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

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:
hessian_numerical(positions, chrg=0, spin=None, step_size=1e-05, matrix=False)#

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(positions, chrg=0, spin=None, use_functorch=False, derived_quantity='pol')#

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:
hyperpolarizability_numerical(positions, chrg=0, spin=None, step_size=1e-05)#

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(positions, chrg=0, spin=None, use_functorch=False, **kwargs)#

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:
ir_numerical(positions, chrg=0, spin=None, step_size=1e-05)#

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

pol_deriv(positions, chrg=0, spin=None, use_functorch=False, derived_quantity='dipole', **kwargs)#

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:
pol_deriv_numerical(positions, chrg=0, spin=None, step_size=1e-05)#

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(positions, chrg=0, spin=None, use_functorch=False, use_analytical=False, derived_quantity='dipole')#

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:
polarizability_numerical(positions, chrg=0, spin=None, step_size=1e-05, **kwargs)#

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(positions, chrg=0, spin=None, use_functorch=False, **kwargs)#

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:
raman_numerical(positions, chrg=0, spin=None, step_size=1e-05)#

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:
reset()#

Reset the calculator to its initial state.

Return type:

None

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

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)

vibration(positions, chrg=0, spin=None, use_functorch=False, project_translational=True, project_rotational=True, **kwargs)#

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:
vibration_numerical(positions, chrg=0, spin=None, step_size=1e-05, project_translational=True, project_rotational=True)#

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:
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] = ['raman', 'hyperpolarizability', 'energy', 'occupation', 'polarizability', 'hessian', 'dipole_deriv', 'iterations', 'bond_orders', 'density', 'ir_intensity', 'charges', 'coefficients', 'frequencies', 'raman_intensity', 'forces', 'ir', 'rama_depol', 'vibration', 'pol_deriv', 'normal_modes', 'mo_energies', 'potential', '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.

results: dict[str, Any]#

Results container.

Contents