Background

Background#

Properties#

Subpackage for calculation of molecular properties and related spectra.

Supported are the following:

  • analytical electrical dipole moment

  • analytical traceless quadrupole moment

  • vibrational frequencies and normal modes

  • IR intensities

  • static Raman intensities

Multipole Moments#

Properties: Multipole Moments#

Analytical calculation of multipole moments. Currently, dipole moment and traceless quadrupole moment are implemented. However, this module serves more as a short-cut for the calculation in Calculator as it should hide some implementation details.

Properties: Dipole Moment#

Analytical calculation of dipole moment.

This module serves more as a short-cut for the calculation in Calculator, hiding some implementation details.

dxtb._src.calculators.properties.moments.dip.dipole(charge, positions, density, integral)[source]#

Analytical calculation of electric dipole moment with electric dipole contribution from nuclei (\(\sum_i(r_{ik} q_i)\)) and electrons.

Return type:

Tensor

Parameters:

  • charge (Tensor) – Atom-resolved charges.

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

  • density (Tensor) – Density matrix.

  • integral (Tensor) – Dipole integral.

Returns:

Electric dipole moment.

Return type:

Tensor

Parameters:

Note

This version follows the tblite implementation, which employs r-rj as moment operator and requires the SCC charges for the nuclear dipole contribution.

dxtb._src.calculators.properties.moments.dip.dipole_xtb(numbers, positions, density, integral)[source]#

Analytical calculation of electric dipole moment with electric dipole contribution from nuclei (\(\sum_i(r_{ik} q_i)\)) and electrons.

Return type:

Tensor

Parameters:

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

  • charge (Tensor) – Atom-resolved charges.

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

  • density (Tensor) – Density matrix.

  • integral (Tensor) – Dipole integral.

Returns:

Electric dipole moment.

Return type:

Tensor

Parameters:

Note

This version follows the xtb implementation, where the r0 moment operator is used and the nuclear contribution uses the valence charges.

Properties: Quadrupole Moment#

Analytical calculation of the traceless quadrupole moment.

This module serves more as a short-cut for the calculation in Calculator, hiding some implementation details.

dxtb._src.calculators.properties.moments.quad.quadrupole(qat, dpat, qpat, positions)[source]#

Analytical calculation of traceless electric quadrupole moment.

Return type:

Tensor

Parameters:

  • qat (Tensor) – Atom-resolved monopolar charges.

  • dpat (Tensor) – Atom-resolved dipolar charges.

  • qpat (Tensor) – Atom-resolved quadrupolar charges.

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

Returns:

Traceless electric quadrupole moment.

Return type:

Tensor

Parameters:

Vibrational Analysis#

Vibrational Analysis#

This module contains all functions for the calculation of vibrational properties, such as frequencies, normal modes, and spectrosocpic data.

Vibrational Analysis: Frequencies#

This module contains the calculation of vibrational frequencies and the corresponding normal modes from the mass-weighted Hessian.

class dxtb._src.calculators.properties.vibration.analysis.VibResult(freqs, modes, device=None, dtype=None)[source]#

Bases: BaseResult

Data from the vibrational analysis.

  • Vibrational frequencies.

  • Normal modes.

Initialize the vibrational analysis result.

Parameters:

  • freqs (Tensor) – Vibrational frequencies in atomic units.

  • modes (Tensor) – Normal modes (unitless).

  • device (torch.device | None, optional) – Device of the tensors. If None, the device of freqs is used. Defaults to None.

  • dtype (torch.dtype | None, optional) – Data type of the tensors. If None, the data type of freqs is used. Defaults to None.

Parameters:
to_unit(value, unit)[source]#

Convert a value from one unit to another based on the converter dictionary.

Return type:

Tensor

Parameters:
use_common_units()[source]#

Convert the frequencies and intensities to common units, that is, cm^-1 for frequencies.

Return type:

None

dxtb._src.calculators.properties.vibration.analysis.vib_analysis(numbers, positions, hessian, project_translational=True, project_rotational=True)[source]#

Vibrational analysis yielding frequencies and normal modes from mass-weighted Hessian. :rtype: VibResult

Parameters:

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

  • positions (Tensor) – Cartesian coordinates of all atoms in the system (..., nat, 3).

  • hessian (Tensor) – Hessian matrix of shape (..., nat, 3, nat, 3).

  • project_rotational (bool, optional) – Whether to project out rotational degrees of freedom.

  • project_translational (bool, optional) – Whether to project out translational degrees of freedom.

Returns:

Frequencies of shape (..., nfreqs) and normal modes of shape (..., 3*nat, nfreqs).

Return type:

tuple[Tensor, Tensor]

Parameters:

Vibrational Analysis: IR Spectra#

Calculate IR intensities from the geometric dipole derivative.

class dxtb._src.calculators.properties.vibration.ir.IRResult(freqs, ints, device=None, dtype=None)[source]#

Bases: BaseResult

Data from the calculation of an IR spectrum.

  • Vibrational frequencies

  • IR intensities

Initialize the IR result.

Parameters:

  • freqs (Tensor) – Vibrational frequencies in atomic units.

  • ints (Tensor) – IR intensities in atomic units.

  • device (torch.device | None, optional) – Device of the tensors. If None, the device of freqs is used. Defaults to None.

  • dtype (torch.dtype | None, optional) – Data type of the tensors. If None, the data type of freqs is used. Defaults to None.

Parameters:
to_unit(value, unit)[source]#

Convert a value from one unit to another based on the converter dictionary.

Return type:

Tensor

Parameters:
use_common_units()[source]#

Convert the frequencies and intensities to common units, that is, cm^-1 for frequencies and km/mol for intensities.

Return type:

None

dxtb._src.calculators.properties.vibration.ir.ir_ints(dmu_dr, modes)[source]#

Calculate IR intensities from the geometric dipole derivative.

Return type:

Tensor

Parameters:

  • dmu_dr (Tensor) – Dipole derivative tensor of shape (…, 3, nat, 3).

  • modes (Tensor) – Normal modes of shape (…, nat*3, nmodes).

Returns:

IR intensities of shape (…, nfreqs).

Return type:

Tensor

Parameters:

Vibrational Analysis: Raman Spectra#

Calculate Raman intensities and the depolarization ratio from the geometric polarizability derivative.

class dxtb._src.calculators.properties.vibration.raman.RamanResult(freqs, ints, depol, device=None, dtype=None)[source]#

Bases: BaseResult

Data from the calculation of a Raman spectrum.

  • Vibrational frequencies

  • Raman activities (intensities)

  • Depolarization ratios

Initialize the Raman result.

Parameters:

  • freqs (Tensor) – Vibrational frequencies in atomic units.

  • ints (Tensor) – IR intensities (activities) in atomic units.

  • depol (Tensor) – Depolarization ratio (unitless).

  • device (torch.device | None, optional) – Device of the tensors. If None, the device of freqs is used. Defaults to None.

  • dtype (torch.dtype | None, optional) – Data type of the tensors. If None, the data type of freqs is used. Defaults to None.

Parameters:
to_unit(value, unit)[source]#

Convert a value from one unit to another based on the converter dictionary.

Return type:

Tensor

Parameters:

  • value (Literal[‘freqs’, ‘ints’, ‘depol’]) – The value (stored property) to convert.

  • unit (str) – The unit to convert to.

Returns:

The converted value.

Return type:

Tensor

Raises:

  • NotImplementedError – If the value is “depol”, because the depolarization ratio is unitless.

  • ValueError – If the value (name of the stored property) does not exist.

Parameters:

  • value (Literal['freqs', 'ints', 'depol'])

  • unit (str)

use_common_units()[source]#

Convert the frequencies and intensities to common units, that is, cm^-1 for frequencies and A^4/amu for intensities.

Return type:

None

dxtb._src.calculators.properties.vibration.raman.raman_ints_depol(da_dr, modes)[source]#

Calculate static Raman activities (intensities) and the depolarization ratios from the geometric polarizability derivative (Raman susceptibility tensor \(\chi\)).

Formula taken from here.

Return type:

tuple[Tensor, Tensor]

Parameters:

  • da_dr (Tensor) – Geometric polarizability derivative tensor of shape (…, 3, 3, nat, 3).

  • modes (Tensor) – Normal modes of shape (…, nat*3, nmodes).

Returns:

Static Raman activities (intensities) of shape (…, nfreqs) and depolarization ratios of shape (…, nfreqs).

Return type:

tuple[Tensor, Tensor]

Parameters:

Vibrational Analysis: Result Container#

Base class for vibrational analysis results.

class dxtb._src.calculators.properties.vibration.result.BaseResult(freqs, device=None, dtype=None)[source]#

Bases: TensorLike

Base class for vibrational analysis results. Vibrational results always stored the frequencies (in atomic units).

Parameters:
save_all_to_pt(filepaths=None)[source]#

Save all results to a PyTorch file (“.pt”).

Return type:

None

Parameters:

filepath (PathLike) – Path to save the results to.

Parameters:

filepaths (list[str | Path] | None)

save_prop_to_pt(prop, filepath=None)[source]#

Save the results to a PyTorch file.

Return type:

None

Parameters:

  • prop (str) – The property to save.

  • filepath (PathLike) – Path to save the results to.

Parameters:
Contents