abinslib.displacements

Functions for calculation of atomic displacement tensors.

The phonon mode displacements are described by 3x3 matrices related to the covariance matrices of atomic positions associated with each mode. In the CLIMAX/Abins notation this is ‘B’ and may include a Bose occupation factor.

The sum over modes (include Brillouin Zone integration for periodic systems) with appropriate Bose occupation gives a physical distribution known in various forms as ‘A’, ‘Atomic Displacement Parameters’, ‘U’, … and sometimes even ‘B’.

In abinslib these are referred to respectively as ‘mode displacements’ and ‘atomic displacements’ where space permits, or ‘B’ and ‘A’ in compact notation, downcased to ‘b’ and ‘a’ in python variable names.

The Quantity A is equal to the debye_waller attribute of the DebyeWaller class from Euphonic and may be read/stored from that class as convenient.

Classes

Displacements

Phonon mode displacement dataset.

Module Contents

class abinslib.displacements.Displacements

Phonon mode displacement dataset.

This represents atomic displacements as 3x3 tensors, often denoted U or B. The data is arranged by qpoint, phonon mode and atom.

Note that while the “displacements” attribute represents the underlying data of a Displacements object, the data should be accessed by the “one”, “n”, “n_plus_one” and “two_n_plus_one” properties which provide displacements at corresponding Bose occupation values.

displacements: euphonic.Quantity

Atomic displacement tensor with dimensions (qpts, modes, atoms, 3, 3) and units length^2, without Bose occupation factor. (i.e. with the same values as the “one” property on resulting object.)

weights: numpy.ndarray

Normalised q-point weights corresponding to axis 0 of mode_displacements.

bose_n: numpy.ndarray

Bose factors <n> corresponding to displacements at target temperature.

Other occupations <1>, <n+1> and <2n+1> will be derived from these values.

temperature: euphonic.Quantity

Temperature for Bose occupation.

classmethod from_modes(modes: euphonic.QpointPhononModes, temperature: euphonic.Quantity, frequency_min: euphonic.Quantity = Quantity(10, 'cm_1')) → Self

Instantiate new Displacements from a QpointPhononModes.

Bose occupation factors are calculated as <n> and stored along with unscaled displacements; the appropriate Bose scaling is applied later depending on the method used for retrieval.

Parameters:

• modes – phonon mode data

• temperature – determines Bose factors and displacement magnitude

• frequency_min – frequency threshold below which mode displacements are set to zero. This is intended to eliminate translational modes at the Gamma point; for precise calculations on a fine q-point mesh it may be appropriate to reduce this threshold.

property one: euphonic.Quantity

Displacements without Bose occupation scaling.

property n: euphonic.Quantity

Displacements with <n> Bose occupation scaling.

property n_plus_one: euphonic.Quantity

Displacements with <n+1> Bose occupation scaling.

property two_n_plus_one: euphonic.Quantity

Displacements with <2n+1> Bose occupation scaling.

to_atomic_displacements() → euphonic.Quantity

Calculate atomic displacement tensor (A) for each atom.

This is given in the same scaling convention as the “debye_waller” attribute of the DebyeWaller class in Euphonic, and may be used to initialize this class correctly. The value is half the “A” used in CLIMAX terminology, but for convenience the array is sometimes referred to as “a” or “A” in this codebase.

In Euphonic coherent scattering intensity calculations, the Debye—Waller intensity factor appears as exp(-W_k) inside a square of sums.

In incoherent intensity calculations the Debye—Waller factor typically appears as a pure factor exp(-2W_k).

In both cases W_k is related to the displacement tensor of a given atom summed over all phonon modes.

Returns:

Array with length^2 dimensions, indices (atom_index, direction, direction)

(i.e. a 3x3 quadratic displacement tensor per atom).