\(\newcommand{\AA}{\text{Å}}\)

CRYSTALpytools.phonons module

A post-processing module for visualizing and analyzing phonon-related properties.

class PhononBand(tick_pos, tick_label, bands, k_path, geometry=None, reciprocal_latt=None, tick_pos3d=None, k_path3d=None, unit='THz')

Bases: object

Phonon band object. Frequency unit: THz.

Note

Even though this class is not directly inherited from the electronics.ElectronBand class, its bands attribute still has the same, nBand*nKpoint*nSpin dimentionalities for using the shared plotting functions. nSpin is always 1 here.

Parameters:

  • tick_pos (array) – 1*nTick array of 1D tick coordinates. Unit: Angstrom

  • tick_label (list) – 1*nTick of default tick labels

  • bands (array) – nBand*nKpoint*1 array of frequency. Unit: THz

  • k_path (array) – 1D coordinates of k points. Unit: Angstrom

  • geometry (Structure) – Pymatgen structure

  • reciprocal_latt (array) – 3*3 array of reciprocal lattice matrix. Not valid if geometry is specified.

  • tick_pos3d (array) – 1*nTick 3D fractional tick coordinates

  • k_path3d (array) – nKpoints*3 3D fractional coordinates of k points

  • unit (str) – In principle, should always be ‘THz’: THz-Angstrom.

classmethod from_file(output, q_overlap_tol=0.0001)

Generate an PhononBand object from the output file of CRYSTAL.

Note

Currently only the screen output (‘.out’) file is supported.

Parameters:

  • output (str) – CRYSTAL output file

  • q_overlap_tol (float) – The threshold for overlapped k points. Only used for getting tick positions.

Returns:

cls (PhononBand)

plot(**kwargs)

A wrapper to plot band structure of a single system using matplotlib. For input arguments or plotting multiple systems, check plot.plot_phonon_bands().

Parameters:

**kwargs – Plot setting parameters (i.e., except the variable for PhononBand object). Check documents for plot.plot_electron_bands().

Returns:

fig (Figure) – Matplotlib figure object

_set_unit(unit)

Set units of data of PhononBand object. Internal method.

Parameters:

unit (str) – ‘THz’ or ‘cm-1’. Length unit is always in \(\AA\).

class PhononDOS(doss, frequency, unit='THz')

Bases: object

Phonon DOS object. Frequency unit: THz.

Note

Even though this class is not directly inherited from the electronics.ElectronDOS class, its doss attribute still has the same, nProj*nFrequency*nSpin dimentionalities for using the shared plotting functions. nSpin is always 1 here.

Parameters:

  • doss (array) – nProj*nFrequency*1 array of DOS.

  • frequency (array) – Positions of DOS peaks (x axis)

  • unit (str) – In principle, should always be ‘THz’: THz-Angstrom.

classmethod from_file(output, read_INS=False, atom_prj=[], element_prj=[])

Generate an PhononDOS object from the output file of CRYSTAL.

Note

Currently only the screen output (‘.out’) file is supported.

Parameters:

  • output (str) – CRYSTAL output file

  • read_INS (bool) – Read the inelastic neutron scattering spectra.

  • atom_prj (list) – Read the projections of atoms with specified labels.

  • element_prj (list) – Read projections of elements with specified conventional atomic numbers.

Returns:

cls (PhononDOS)

plot(**kwargs)

A wrapper to plot density of states of a single system with matplotlib. For input arguments or plotting multiple systems, check plot.plot_phonon_doss().

Parameters:

**kwargs – Plot setting parameters (i.e., except the variable for PhononDOS object). Check documents for plot.plot_phonon_doss().

Returns:

fig (Figure) – Matplotlib figure object

_set_unit(unit)

Set units of data of PhononDOS object.

Parameters:

unit (str) – ‘THz’ or ‘cm-1’. Length unit is always in \(\AA\).

class PhononBandDOS(band, dos)

Bases: object

Phonon band + dos object. Frequency unit: THz.

Parameters:
classmethod from_file(*output, q_overlap_tol=0.0001, read_INS=False, atom_prj=[], element_prj=[])

Get PhononBandDOS object from files

Parameters:

  • *output (str) – CRYSTAL screen output file. 2 files, the first one is for band the second one is for DOS. Or a single output file file with both band and DOS.

  • q_overlap_tol (float) – The threshold for overlapped k points. Only used for getting tick positions.

  • read_INS (bool) – Read the inelastic neutron scattering spectra.

  • atom_prj (list) – Read the projections of atoms with specified labels.

  • element_prj (list) – Read projections of elements with specified conventional atomic numbers.

Returns:

cls (PhononBandDOS)

plot(**kwargs)

A wrapper to plot phonon band structure + density of states of a single system with matplotlib. For input arguments, check plot.plot_phonon_banddos().

Parameters:

**kwargs – Plot setting parameters (i.e., except the variable for PhononBandDOS object). Check documents for plot.plot_phonon_banddos().

Returns:

fig (Figure) – Matplotlib figure object

_set_unit()

Set units of data of PhononBandDOS object.

Parameters:

unit (str) – ‘THz’ or ‘cm-1’. Length unit is always in \(\AA\).

class Phonon(structure, u_0, qpoint, frequency, mode_symm=[], eigenvector=[], fragment_idx=[])

Bases: object

The basic class to save, analyze and visualize phonon vibrations. Unit: THz, eV and \(\AA\). Other units are not allowed, except outputs.

Parameters:

  • structure (CStructure) – Extended Pymatgen structure class. The extended structure for phonon dispersion calculations by finite displacement method must be reduced accordingly.

  • u_0 (float) – Internal energy. Unit: eV.

  • qpoint (array) – nQpoint*4 array. The first 3 elements are fractional coordinates in reciprocal space and the fourth is its weight.

  • frequency (array) – nQpoint*nMode array. Phonon frequencies in THz.

  • mode_symm (array) – nQpoint*nMode array of irreducible representations. In Mulliken symbols.

  • eigenvector (array) – nQpoint*nMode*nAtom*3 complex array. Phased and mass-weighted eigenvectors normalized to 1. Unit: \(\AA\).

  • fragment_idx (array) – Indices of atoms (starting from 1) if a fragement calculation is performed.

Returns:

self (Phonon) – Attribute names same as inputs

classmethod from_file(filename, source='crystal', q_id=None, q_coord=None, **kwargs)

Instantiation from a file. Files generated by the following methods are supported (also the accepted entries for source):

  • 'crystal': CRYSTAL harmonic phonon outputs (Gamma, dispersion and band).

  • 'crystal-QHA': CRYSTAL QHA outputs.

  • 'phonopy': Phonopy band, qpoints and mesh files.

Note

In rare cases, the user might want to collect data of a few specific q points. q_id and q_coord can be set but not simultaneously. If set, q_id takes priority and q_coord is ignored.

Parameters:

  • filename (str) – Name of the output file.

  • source (str) – The program used for the output file.

  • q_id (array) – Index (from 0) of q points to be read. 1*nqpoint.

  • q_coord (array) – Fractional coordinates of q points to read. nqpoint*3 list.

  • **kwargs – Other keywords passed to corresponding I/O functions. See below.

  • qha_index (int) – crystal-QHA. The index of calculation to read (from 0).

  • struc_yaml (str) – phonopy. ‘qpoints.yaml’ only.

  • u_0 (float) – phonopy. Static internal energy in eV.

  • irreps_yaml (array[str]) – phonopy. Read ‘irreps.yaml’ for mode symmetry symbols. The fractional coordinates in the file are used for q_coord if not specified. Phonopy ‘irreps.yaml’ only contains symmetry info of a q point. Use a list of filenames for multiple q points.

clean_q_overlap(threshold=0.0001)

Remove the repeated q points and update the weight. Qpoint, frequency, symmetry and eigenvector are updated.

Parameters:

threshold (float) – The q point overlap threshold. Defined in fractional coordinates.

clean_imaginary(threshold=-0.0001)

Set negative frequenceies and related properteis to 0 and print warning message. Only frequency is modified.

Parameters:

threshold (float) – The threshold to identify a phonon mode as negative.

Returns:

self

scale_frequency(scale, scale_range=[])

Empirically scaling phonon frequencies by the scale factor. It does not update the attribute.

Parameters:

  • scale (float|array) – Scaling factors

  • scale_range (array) – nScale*2 array. The frequency range of the scaling factor. Including the minimum and excluding the maximum. Use empty list for a uniform scaling.

Returns:

freq (array) – nQpoint*nMode frequencies in THz.

classical_eigvec()

Return to phonon eigenvector with classical amplitude. The attribute is not changed.

Returns:

eigvec (array) – Eigenvector with classical amplitude, in \(\AA\) and same dimension as self.eigenvector.

unweight_eigvec()

Return to mass-unweighted phonon eigenvector normalized to 1. The attribute is not changed.

Returns:

eigvec (array) – Mass-unweighted eigenvector normalized to 1.

classmethod get_eigvec(struc, freq, eigvec, method, fragment_idx=[])

Get eigenvectors suitable for instantiation.

Parameters:

  • struc (CStructure) – Structure

  • freq (array) – nQpoint*nMode array of phonon frequencies in THz.

  • eigvec (array) – nQpoint*nMode*nAtom*3 complex array of phonon eigenvectors, must corresponding to the method specified.

  • method (str) – ‘remove classical’, ‘mass weight’.

  • fragment_idx (array) – 1*nAtom array of ints. Atomic indices from 1.

Returns:

eigvec (array) – Mass-weighted and phased eigenvector normalized to 1.