matador.orm.spectral package¶
This submodule implements some useful classes for manipulating DOS and dispersion data.
-
class
matador.orm.spectral.
VibrationalDOS
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dos.DensityOfStates
Specific class for phonon DOS data, including free energy integration.
Initialise the DOS and trim the DOS data arrays.
- Parameters
data (dict/Dispersion) – dictionary containing the phonon dos data, or a dispersion object to convert.
-
gaussian_width
= 0.0012398419840000002¶
-
property
debye_temperature
¶ Returns the Debye temperature in K.
-
property
debye_freq
¶ Returns the Debye frequency in eV.
-
property
zpe
¶ The zero-point energy per atom as computed from frequency data.
-
vibrational_free_energy
(temperatures=None)[source]¶ Computes and returns the vibrational contribution to the free energy, including zero-point energy, from the phonon frequencies.
- Parameters
temperatures (list) – list or array of temperatures to compute G(T) at.
- Returns
temperature and energy array.
- Return type
(np.ndarray, np.ndarray)
-
compute_free_energy
(temperature)[source]¶ Compute the vibrational free energy at the given temperature, using lru_cache to avoid doing much extra work. Uses minimum temperature cutoff of 1e-9, below which it returns just the ZPE (unless T < 0 K).
- Raises
RuntimeError – if temperature is < 0 K.
- Returns
vibrational free energy per atom, including ZP correction.
- Return type
-
vibrational_free_energy_from_dos
(temperatures=None)[source]¶ Computes the vibrational contribution to the free energy at a given set of temperatures.
- Keyword Arguments
temperature (list) – list, array or float of temperatures.
-
property
vdos_function
¶ From the data arrays
sample_energies
andsample_dos
, return an interpolated function to integrate.
-
plot_free_energy
(temperatures=None, ax=None, **kwargs)[source]¶ Plot G(T) on the array of given temperatures. Default T is [0, 800].
- Keyword Arguments
temperatures (list/np.ndarray) – list or array of temperatures to plot. If the array/list has length 2, use these as the start and endpoints with 21 plotting points.
ax (matplotlib.pyplot.Axis) – axis object to plot onto.
-
class
matador.orm.spectral.
ElectronicDOS
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dos.DensityOfStates
Specific class for electronic DOS data.
Initialise the DOS and trim the DOS data arrays.
- Parameters
data (dict/Dispersion) – dictionary containing the phonon dos data, or a dispersion object to convert.
-
gaussian_width
= 0.01¶
-
class
matador.orm.spectral.
DensityOfStates
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dispersion.Dispersion
,matador.orm.orm.DataContainer
Generic class for density of states.
Initialise the DOS and trim the DOS data arrays.
- Parameters
data (dict/Dispersion) – dictionary containing the phonon dos data, or a dispersion object to convert.
-
required_keys
= ['dos', 'energies']¶
-
property
sample_dos
¶ Return the calculated density of states, trimmed at each end to only include non-zero values.
-
property
sample_energies
¶ Return the energies corresponding to the trimmed DOS.
-
class
matador.orm.spectral.
VibrationalDispersion
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dispersion.Dispersion
Class that stores vibrational dispersion data. Attributes are all implemented as properties based on underlying raw data.
-
eigs
¶ eigenvalue array of shape (1, num_modes, num_kpoints), in frequency units below, with first index denoting the single “spin channel” for phonons.
- Type
-
kpoint_path
¶ array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.
- Type
-
kpoint_path_cartesian
¶ as above, in Cartesian coordinates.
- Type
Initalise copy of raw data.
-
required_keys
= ['num_kpoints', 'num_modes', 'eigs_q', 'kpoint_path']¶
-
property
num_atoms
¶ Number of atoms in cell.
-
property
num_modes
¶ Number of phonon modes.
-
property
num_bands
¶ Alias for number of modes.
-
property
eigs_q
¶ Eigenvalues in frequency units self.freq_unit, with shape (1, num_modes, num_kpoints).
-
property
softest_mode_freq
¶ The frequency of the softest mode in the calculation. Negative modes correspond to imaginary frequencies.
-
property
debye_temperature
¶ Returns the Debye temperature in K.
-
property
debye_freq
¶ Returns the Debye frequency in cm^-1.
-
-
class
matador.orm.spectral.
ElectronicDispersion
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dispersion.Dispersion
Class that stores electronic dispersion data. Attributes are all implemented as properties based on underlying raw data.
-
eigs_s_k
¶ eigenvalue array of shape (num_spins, num_bands, num_kpoints).
- Type
-
kpoint_path
¶ array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.
- Type
-
kpoint_path_cartesian
¶ as above, in Cartesian coordinates.
- Type
-
fermi_energy
¶ Fermi energy in eV (takes average of spin channels if more than one is present).
- Type
-
projector_weights
¶ array of projector_weights with shape (num_kpoints, num_bands, num_projectors)
- Type
Note
projector_weights will only work with one spin channel.
Initalise copy of raw data.
-
required_keys
= ['num_kpoints', 'num_spins', 'num_bands', 'num_electrons', 'eigs_s_k', 'kpoint_path', 'lattice_cart', 'fermi_energy']¶
-
property
num_spins
¶ Number of spin channels in spectrum.
-
property
num_electrons
¶ Number of electrons.
-
property
eigs_s_k
¶ Array of electronic eigenvalues with shape (num_spins, num_bands, num_kpoints).
-
property
eigs
¶ Alias for self.eigs_s_k.
-
property
fermi_energy
¶ Return the Fermi energy as described in the raw data.
-
property
spin_fermi_energy
¶ Return the Fermi energy as described in the raw data.
-
property
band_gap
¶ Return the band gap of the system.
-
property
band_gap_path_inds
¶ Return the indices of the k-points that comprise the smallest band gap.
-
property
spin_band_gap
¶ Return the band gap for each spin channel.
-
property
spin_band_gap_path_inds
¶ Return the indices of the k-points that comprise the smallest band gap for each spin channel.
-
-
class
matador.orm.spectral.
Dispersion
(data=None, **kwargs)[source]¶ Bases:
matador.orm.spectral.spectral.Spectral
Parent class for continuous spectra in reciprocal space, i.e. electronic and vibrational bandstructures.
Note
This class speaks of “k-points” as general reciprocal space points used to display the dispersion curves; these correspond to CASTEP’s phonon_kpoints or spectral_kpoints, and not the k-points used to generate the underlying wavefunction or dynamical matrix.
Initalise copy of raw data.
-
linearise_path
(preserve_kspace_distance=False)[source]¶ For a given k-point path, normalise the spacing between points, mapping it onto [0, 1].
- Keyword Arguments
preserve_kspace_distance (bool) – if True, point separation will be determined by their actual separation in reciprocal space, otherwise they will be evenly spaced.
- Returns
3xN array containing k-points mapped onto [0, 1].
- Return type
np.ndarray
-
static
get_band_reordering
(eigs, kpoint_branches)[source]¶ Recursively reorder eigenvalues such that bands join up correctly, based on local gradients.
- Parameters
dispersion (numpy.ndarray) – array containing eigenvalues as a function of q/k
branches (
list
ofint
) – list containing branches of k/q-point path
- Returns
reordered branches.
- Return type
-
-
class
matador.orm.spectral.
Spectral
(data=None, **kwargs)[source]¶ Bases:
matador.orm.orm.DataContainer
Note
This class speaks of “k-points” as general reciprocal space points used to display the dispersion curves; these correspond to CASTEP’s phonon_kpoints or spectral_kpoints, and not the k-points used to generate the underlying wavefunction or dynamical matrix.
Initalise copy of raw data.
-
property
eigs
¶ Alias for the correct eigenvalue array.
-
property
lattice_cart
¶ The Cartesian lattice vectors of the real space lattice.
-
property
num_kpoints
¶ Number of dispersion k-points sampled.
-
property
num_qpoints
¶ Alias for number of kpoints.
-
property
projectors
¶ Return list of projector labels in the format (element, l-channel).
-
property
num_modes
¶ Number of eigenvalues per q/k-point.
-
property
num_bands
¶ Number of eigenvalues per q/k-point.
-
property
projector_weights
¶ Return the array of projector weights per eigval, with shape (num_projectors, num_kpoints, num_bands).
-
property
num_projectors
¶ Return the number of projectors.
-
property
kpoint_branches
¶ Return the k-point branches in the older format, which contained a list of lists of continous indices.
-
property
kpoint_branch_start
¶ Return the indices of the start of branches.
-
property
kpoint_path_spacing
¶ An estimated kpoint spacing.
-
property
kpoint_path
¶ The fractional sampling path in reciprocal space.
-
property
kpoint_weights
¶
-
property
kpoint_path_cartesian
¶ The reicprocal space sampling path in Cartesian coordinates.
-
property
num_spins
¶ Dummy number of spins.
-
property
spin_fermi_energy
¶ Dummy Fermi energy per spin channel.
-
property
Submodules¶
matador.orm.spectral.dispersion module¶
This file implements classes to store and manipulate electronic and vibrational bandstructures, with or without projection data.
-
class
matador.orm.spectral.dispersion.
Dispersion
(data=None, **kwargs)[source]¶ Bases:
matador.orm.spectral.spectral.Spectral
Parent class for continuous spectra in reciprocal space, i.e. electronic and vibrational bandstructures.
Note
This class speaks of “k-points” as general reciprocal space points used to display the dispersion curves; these correspond to CASTEP’s phonon_kpoints or spectral_kpoints, and not the k-points used to generate the underlying wavefunction or dynamical matrix.
Initalise copy of raw data.
-
linearise_path
(preserve_kspace_distance=False)[source]¶ For a given k-point path, normalise the spacing between points, mapping it onto [0, 1].
- Keyword Arguments
preserve_kspace_distance (bool) – if True, point separation will be determined by their actual separation in reciprocal space, otherwise they will be evenly spaced.
- Returns
3xN array containing k-points mapped onto [0, 1].
- Return type
np.ndarray
-
static
get_band_reordering
(eigs, kpoint_branches)[source]¶ Recursively reorder eigenvalues such that bands join up correctly, based on local gradients.
- Parameters
dispersion (numpy.ndarray) – array containing eigenvalues as a function of q/k
branches (
list
ofint
) – list containing branches of k/q-point path
- Returns
reordered branches.
- Return type
-
-
class
matador.orm.spectral.dispersion.
ElectronicDispersion
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dispersion.Dispersion
Class that stores electronic dispersion data. Attributes are all implemented as properties based on underlying raw data.
-
eigs_s_k
¶ eigenvalue array of shape (num_spins, num_bands, num_kpoints).
- Type
-
kpoint_path
¶ array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.
- Type
-
kpoint_path_cartesian
¶ as above, in Cartesian coordinates.
- Type
-
fermi_energy
¶ Fermi energy in eV (takes average of spin channels if more than one is present).
- Type
-
projector_weights
¶ array of projector_weights with shape (num_kpoints, num_bands, num_projectors)
- Type
Note
projector_weights will only work with one spin channel.
Initalise copy of raw data.
-
required_keys
= ['num_kpoints', 'num_spins', 'num_bands', 'num_electrons', 'eigs_s_k', 'kpoint_path', 'lattice_cart', 'fermi_energy']¶
-
property
num_spins
¶ Number of spin channels in spectrum.
-
property
num_electrons
¶ Number of electrons.
-
property
eigs_s_k
¶ Array of electronic eigenvalues with shape (num_spins, num_bands, num_kpoints).
-
property
eigs
¶ Alias for self.eigs_s_k.
-
property
fermi_energy
¶ Return the Fermi energy as described in the raw data.
-
property
spin_fermi_energy
¶ Return the Fermi energy as described in the raw data.
-
property
band_gap
¶ Return the band gap of the system.
-
property
band_gap_path_inds
¶ Return the indices of the k-points that comprise the smallest band gap.
-
property
spin_band_gap
¶ Return the band gap for each spin channel.
-
property
spin_band_gap_path_inds
¶ Return the indices of the k-points that comprise the smallest band gap for each spin channel.
-
-
class
matador.orm.spectral.dispersion.
VibrationalDispersion
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dispersion.Dispersion
Class that stores vibrational dispersion data. Attributes are all implemented as properties based on underlying raw data.
-
eigs
¶ eigenvalue array of shape (1, num_modes, num_kpoints), in frequency units below, with first index denoting the single “spin channel” for phonons.
- Type
-
kpoint_path
¶ array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.
- Type
-
kpoint_path_cartesian
¶ as above, in Cartesian coordinates.
- Type
Initalise copy of raw data.
-
required_keys
= ['num_kpoints', 'num_modes', 'eigs_q', 'kpoint_path']¶
-
property
num_atoms
¶ Number of atoms in cell.
-
property
num_modes
¶ Number of phonon modes.
-
property
num_bands
¶ Alias for number of modes.
-
property
eigs_q
¶ Eigenvalues in frequency units self.freq_unit, with shape (1, num_modes, num_kpoints).
-
property
softest_mode_freq
¶ The frequency of the softest mode in the calculation. Negative modes correspond to imaginary frequencies.
-
property
debye_temperature
¶ Returns the Debye temperature in K.
-
property
debye_freq
¶ Returns the Debye frequency in cm^-1.
-
matador.orm.spectral.dos module¶
This file implements classes to store and manipulate electronic and vibrational DOS, with or without projection data.
-
class
matador.orm.spectral.dos.
DensityOfStates
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dispersion.Dispersion
,matador.orm.orm.DataContainer
Generic class for density of states.
Initialise the DOS and trim the DOS data arrays.
- Parameters
data (dict/Dispersion) – dictionary containing the phonon dos data, or a dispersion object to convert.
-
required_keys
= ['dos', 'energies']¶
-
property
sample_dos
¶ Return the calculated density of states, trimmed at each end to only include non-zero values.
-
property
sample_energies
¶ Return the energies corresponding to the trimmed DOS.
-
class
matador.orm.spectral.dos.
VibrationalDOS
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dos.DensityOfStates
Specific class for phonon DOS data, including free energy integration.
Initialise the DOS and trim the DOS data arrays.
- Parameters
data (dict/Dispersion) – dictionary containing the phonon dos data, or a dispersion object to convert.
-
gaussian_width
= 0.0012398419840000002¶
-
property
debye_temperature
¶ Returns the Debye temperature in K.
-
property
debye_freq
¶ Returns the Debye frequency in eV.
-
property
zpe
¶ The zero-point energy per atom as computed from frequency data.
-
vibrational_free_energy
(temperatures=None)[source]¶ Computes and returns the vibrational contribution to the free energy, including zero-point energy, from the phonon frequencies.
- Parameters
temperatures (list) – list or array of temperatures to compute G(T) at.
- Returns
temperature and energy array.
- Return type
(np.ndarray, np.ndarray)
-
compute_free_energy
(temperature)[source]¶ Compute the vibrational free energy at the given temperature, using lru_cache to avoid doing much extra work. Uses minimum temperature cutoff of 1e-9, below which it returns just the ZPE (unless T < 0 K).
- Raises
RuntimeError – if temperature is < 0 K.
- Returns
vibrational free energy per atom, including ZP correction.
- Return type
-
vibrational_free_energy_from_dos
(temperatures=None)[source]¶ Computes the vibrational contribution to the free energy at a given set of temperatures.
- Keyword Arguments
temperature (list) – list, array or float of temperatures.
-
property
vdos_function
¶ From the data arrays
sample_energies
andsample_dos
, return an interpolated function to integrate.
-
plot_free_energy
(temperatures=None, ax=None, **kwargs)[source]¶ Plot G(T) on the array of given temperatures. Default T is [0, 800].
- Keyword Arguments
temperatures (list/np.ndarray) – list or array of temperatures to plot. If the array/list has length 2, use these as the start and endpoints with 21 plotting points.
ax (matplotlib.pyplot.Axis) – axis object to plot onto.
-
class
matador.orm.spectral.dos.
ElectronicDOS
(*args, **kwargs)[source]¶ Bases:
matador.orm.spectral.dos.DensityOfStates
Specific class for electronic DOS data.
Initialise the DOS and trim the DOS data arrays.
- Parameters
data (dict/Dispersion) – dictionary containing the phonon dos data, or a dispersion object to convert.
-
gaussian_width
= 0.01¶
matador.orm.spectral.spectral module¶
-
class
matador.orm.spectral.spectral.
Spectral
(data=None, **kwargs)[source]¶ Bases:
matador.orm.orm.DataContainer
Note
This class speaks of “k-points” as general reciprocal space points used to display the dispersion curves; these correspond to CASTEP’s phonon_kpoints or spectral_kpoints, and not the k-points used to generate the underlying wavefunction or dynamical matrix.
Initalise copy of raw data.
-
property
eigs
¶ Alias for the correct eigenvalue array.
-
property
lattice_cart
¶ The Cartesian lattice vectors of the real space lattice.
-
property
num_kpoints
¶ Number of dispersion k-points sampled.
-
property
num_qpoints
¶ Alias for number of kpoints.
-
property
projectors
¶ Return list of projector labels in the format (element, l-channel).
-
property
num_modes
¶ Number of eigenvalues per q/k-point.
-
property
num_bands
¶ Number of eigenvalues per q/k-point.
-
property
projector_weights
¶ Return the array of projector weights per eigval, with shape (num_projectors, num_kpoints, num_bands).
-
property
num_projectors
¶ Return the number of projectors.
-
property
kpoint_branches
¶ Return the k-point branches in the older format, which contained a list of lists of continous indices.
-
property
kpoint_branch_start
¶ Return the indices of the start of branches.
-
property
kpoint_path_spacing
¶ An estimated kpoint spacing.
-
property
kpoint_path
¶ The fractional sampling path in reciprocal space.
-
property
kpoint_weights
¶
-
property
kpoint_path_cartesian
¶ The reicprocal space sampling path in Cartesian coordinates.
-
property
num_spins
¶ Dummy number of spins.
-
property
spin_fermi_energy
¶ Dummy Fermi energy per spin channel.
-
property