QpointFrequencies

The QpointFrequencies object contains precalculated phonon frequencies at certain q-points. This object does not contain eigenvectors, so allows some quantities such as a basic DOS or bandstructures to be calculated with lower memory requirements.

Reading From CASTEP

Phonon frequencies and eigenvectors can be read from a .phonon file using QpointFrequencies.from_castep.

from euphonic import QpointFrequencies

filename = 'quartz.phonon'
phonons = QpointFrequencies.from_castep(filename)

Reading From Phonopy

Using QpointFrequencies.from_phonopy Euphonic can read frequencies from Phonopy files with the following default names:

• mesh.yaml/mesh.hdf5

• qpoints.yaml/qpoints.hdf5

• bands.yaml/bands.hdf5

The file to be read can be specified with the phonon_name argument. Some of these files do not include the crystal information, so it must be read from a phonopy.yaml file, which can be specified with the summary_name argument. A path can also be specified.

from euphonic import QpointFrequencies

phonons = QpointFrequencies.from_phonopy(path='NaCl', phonon_name='mesh.hdf5')

From Force Constants

See Force Constants

Plotting Dispersion

See Plotting Dispersion

Calculating Density of States

See Calculating DOS

Docstring

class QpointFrequencies(crystal, qpts, frequencies, weights=None)

A class to read and store frequency data at q-points

Variables:

• crystal – Lattice and atom information

• n_qpts – Number of q-points in the object

• qpts – Shape (n_qpts, 3) float ndarray. Q-point coordinates, in fractional coordinates of the reciprocal lattice

• frequencies – Shape (n_qpts, n_branches) float Quantity in energy units. Frequencies per q-point and mode

• weights – Shape (n_qpts,) float ndarray. The weight for each q-point

Parameters:

• crystal (Crystal)

• qpts (ndarray)

• frequencies (Quantity)

• weights (ndarray | None)

__init__(crystal, qpts, frequencies, weights=None)

Parameters:

• crystal (Crystal) – Lattice and atom information

• qpts (ndarray) – Shape (n_qpts, 3) float ndarray. Q-point coordinates

• frequencies (Quantity) – Shape (n_qpts, n_branches) float Quantity in energy units. Frequencies per q-point and mode

• weights (ndarray | None) – Shape (n_qpts,) float ndarray. The weight for each q-point. If None, equal weights are assumed

Return type:

None

calculate_dos(dos_bins, *, mode_widths=None, mode_widths_min=<Quantity(0.01, 'millielectron_volt')>, adaptive_method='reference', adaptive_error=0.01)

Calculates a density of states, in units of modes per atom per energy unit, such that the integrated area is equal to 3.

Parameters:

• dos_bins (Quantity) – Shape (n_e_bins + 1,) float Quantity in energy units. The energy bin edges to use for calculating the DOS

• mode_widths (Quantity | None) – Shape (n_qpts, n_branches) float Quantity in energy units. The broadening width for each mode at each q-point, for adaptive broadening

• mode_widths_min (Quantity) – Scalar float Quantity in energy units. Sets a lower limit on the mode widths, as mode widths of zero will result in infinitely sharp peaks

• adaptive_method (Literal['reference', 'fast']) – String. Specifies whether to use slow, reference adaptive method or faster, approximate method.

• adaptive_error (float) – Scalar float. Acceptable error for gaussian approximations when using the fast adaptive method, defined as the absolute difference between the areas of the true and approximate gaussians

Returns:

dos – A spectrum containing the energy bins on the x-axis and DOS on the y-axis. The DOS is in units of modes per energy unit per atom, such that the integrated area is equal to 3.

Return type:

Spectrum1D

Notes

The fast adaptive broadening method reduces computation time by reducing the number of Gaussian functions that have to be evaluated. Broadening kernels are only evaulated for a subset of mode width values with intermediate values approximated using interpolation.

The adaptive_error keyword argument is used to determine how many broadening kernels are computed exactly. The more exact kernels are used, the more accurate the Gaussian approximations will be, but computation time will also be increased.

calculate_dos_map(dos_bins, *, mode_widths=None, mode_widths_min=<Quantity(0.01, 'millielectron_volt')>)

Produces a bandstructure-like plot, using the DOS at each q-point

Parameters:

• dos_bins (Quantity) – Shape (n_e_bins + 1,) float Quantity in energy units. The energy bin edges to use for calculating the DOS

• mode_widths (Quantity | None) – Shape (n_qpts, n_branches) float Quantity in energy units. The broadening width for each mode at each q-point, for adaptive broadening

• mode_widths_min (Quantity) – Scalar float Quantity in energy units. Sets a lower limit on the mode widths, as mode widths of zero will result in infinitely sharp peaks

Returns:

dos_map – A 2D spectrum containing the q-point bins on the x-axis, energy bins on the y-axis and DOS on the z-axis

Return type:

Spectrum2D

get_dispersion()

Creates a set of 1-D bands from mode data

Bands follow the same q-point order as in the qpts array, with x-axis spacing corresponding to the absolute distances between q-points. Discontinuities will appear as large jumps on the x-axis.

Returns:

dispersion – A sequence of mode bands with a common x-axis

Return type:

Spectrum1DCollection

to_dict()

Convert to a dictionary. See QpointFrequencies.from_dict for details on keys/values

Return type:

dict[str, Any]

to_json_file(filename)

Write to a JSON file. JSON fields are equivalent to from_dict keys

Parameters:

filename (Path | str) – Name of the JSON file to write to

Return type:

None

classmethod from_dict(d)

Convert a dictionary to a QpointFrequencies object

Parameters:

d (dict[str, Any]) –

A dictionary with the following keys/values:

• ’crystal’: dict, see Crystal.from_dict

• ’qpts’: (n_qpts, 3) float ndarray

• ’frequencies’: (n_qpts, n_branches) float ndarray

• ’frequencies_unit’: str

There are also the following optional keys:

• ’weights’: (n_qpts,) float ndarray

Return type:

Self

classmethod from_json_file(filename)

Read from a JSON file. See from_dict for required fields

Parameters:

filename (Path | str) – The file to read from

Return type:

Self

classmethod from_castep(filename, *, average_repeat_points=True, prefer_non_loto=False)

Reads precalculated phonon mode data from a CASTEP .phonon file

Parameters:

• filename (Path | str) – The path and name of the .phonon file to read

• average_repeat_points (bool) – If multiple frequency/eigenvectors blocks are included with the same q-point index (i.e. for Gamma-point with LO-TO splitting), scale the weights such that these sum to the given weight

• prefer_non_loto (bool) – If multiple frequency/eigenvector blocks are provided with the same q-point index and all-but-one include a direction vector, use the data from the point without a direction vector. (i.e. use the “exact” Gamma data without non-analytic correction.) This option takes priority over average_repeat_points.

Return type:

Self

classmethod from_phonopy(*, path='.', phonon_name='band.yaml', phonon_format=None, summary_name='phonopy.yaml')

Reads precalculated phonon mode data from a Phonopy mesh/band/qpoints.yaml/hdf5 file. May also read from phonopy.yaml for structure information.

Parameters:

• path (Path | str) – Path to directory containing the file(s)

• phonon_name (Path | str) – Name of Phonopy file including the frequencies

• phonon_format (str | None) – Format of the phonon_name file if it isn’t obvious from the phonon_name extension, one of {‘yaml’, ‘hdf5’}

• summary_name (Path | str) – Name of Phonopy summary file to read the crystal information from. Crystal information in the phonon_name file takes priority, but if it isn’t present, crystal information is read from summary_name instead

Return type:

Self