matador.orm.spectral package

This submodule implements some useful classes for manipulating DOS and dispersion data.

class matador.orm.spectral.VibrationalDOS(*args, **kwargs)

Bases: 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)

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)

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:

float

vibrational_free_energy_from_dos(temperatures=None)

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 and sample_dos, return an interpolated function to integrate.

plot_free_energy(temperatures=None, ax=None, **kwargs)

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)

Bases: 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)

Bases: Dispersion, 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.

plot_dos(**kwargs)

Plot the density of states.

static bands_as_dos(bands, gaussian_width=0.1)

Convert bands data to DOS data.

class matador.orm.spectral.VibrationalDispersion(*args, **kwargs)

Bases: Dispersion

Class that stores vibrational dispersion data. Attributes are all implemented as properties based on underlying raw data.

source

list of source files.

Type:

list

num_kpoints

number of kpoints.

Type:

int

num_atoms

number of atoms.

Type:

int

num_modes

number of phonon modes.

Type:

int

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:

numpy.ndarray

freq_unit

human-readable frequency unit used for eig array.

Type:

str

kpoint_path

array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.

Type:

numpy.ndarray

kpoint_path_cartesian

as above, in Cartesian coordinates.

Type:

numpy.ndarray

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)

Bases: Dispersion

Class that stores electronic dispersion data. Attributes are all implemented as properties based on underlying raw data.

source

list of source files.

Type:

list

num_kpoints

number of kpoints.

Type:

int

num_spins

number of spin channels.

Type:

int

num_bands

number of bands.

Type:

int

num_electrons

number of bands.

Type:

int

eigs_s_k

eigenvalue array of shape (num_spins, num_bands, num_kpoints).

Type:

numpy.ndarray

kpoint_path

array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.

Type:

numpy.ndarray

kpoint_path_cartesian

as above, in Cartesian coordinates.

Type:

numpy.ndarray

fermi_energy

Fermi energy in eV (takes average of spin channels if more than one is present).

Type:

float

spin_fermi_energy

Fermi energy for each spin channel in eV.

Type:

list[float]

band_gap

smallest band gap across spin channels/momenta.

Type:

float

spin_band_gap

band gap per spin channel.

Type:

list[float]

projectors

list of projector labels in format (element, l-channel).

Type:

list[tuple]

projector_weights

array of projector_weights with shape (num_kpoints, num_bands, num_projectors)

Type:

numpy.ndarray

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.

set_gap_data()

Loop over bands to set the band gap, VBM, CBM, their positions and the smallest direct gap inside self._data, for each spin channel. Sets self.band_gap to be the smallest of the band gaps across all spin channels.

new_from_trimmed_path(k_start_ind=0, k_end_ind=None)

Returns a new ElectronicDispersion object with the kpoint path trimmed by the provided indices.

class matador.orm.spectral.Dispersion(data=None, mutable=False, **kwargs)

Bases: 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.

find_full_kpt_branch()

Find all branch indices from branch start indices.

set_branches_and_spacing()

Set the relevant kpoint spacing and branch attributes.

find_kpoint_branches()

Separate a kpoint path into discontinuous branches,

Returns:

list of lists containing the indices of

the discontinuous kpoint branches.

float: estimated k-point spacing from median of their

separations.

Return type:

list[list[int]]

linearise_path(preserve_kspace_distance=False)

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

reorder_bands()

Reorder the bands of this Dispersion object directly.

static get_band_reordering(eigs, kpoint_branches)

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 of int) – list containing branches of k/q-point path

Returns:

reordered branches.

Return type:

numpy.ndarray

plot_dispersion(**kwargs)

Make a plot of the band structure, with projections, if found.

class matador.orm.spectral.Spectral(data=None, mutable=False, **kwargs)

Bases: 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.

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, mutable=False, **kwargs)

Bases: 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.

find_full_kpt_branch()

Find all branch indices from branch start indices.

set_branches_and_spacing()

Set the relevant kpoint spacing and branch attributes.

find_kpoint_branches()

Separate a kpoint path into discontinuous branches,

Returns:

list of lists containing the indices of

the discontinuous kpoint branches.

float: estimated k-point spacing from median of their

separations.

Return type:

list[list[int]]

linearise_path(preserve_kspace_distance=False)

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

reorder_bands()

Reorder the bands of this Dispersion object directly.

static get_band_reordering(eigs, kpoint_branches)

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 of int) – list containing branches of k/q-point path

Returns:

reordered branches.

Return type:

numpy.ndarray

plot_dispersion(**kwargs)

Make a plot of the band structure, with projections, if found.

class matador.orm.spectral.dispersion.ElectronicDispersion(*args, **kwargs)

Bases: Dispersion

Class that stores electronic dispersion data. Attributes are all implemented as properties based on underlying raw data.

source

list of source files.

Type:

list

num_kpoints

number of kpoints.

Type:

int

num_spins

number of spin channels.

Type:

int

num_bands

number of bands.

Type:

int

num_electrons

number of bands.

Type:

int

eigs_s_k

eigenvalue array of shape (num_spins, num_bands, num_kpoints).

Type:

numpy.ndarray

kpoint_path

array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.

Type:

numpy.ndarray

kpoint_path_cartesian

as above, in Cartesian coordinates.

Type:

numpy.ndarray

fermi_energy

Fermi energy in eV (takes average of spin channels if more than one is present).

Type:

float

spin_fermi_energy

Fermi energy for each spin channel in eV.

Type:

list[float]

band_gap

smallest band gap across spin channels/momenta.

Type:

float

spin_band_gap

band gap per spin channel.

Type:

list[float]

projectors

list of projector labels in format (element, l-channel).

Type:

list[tuple]

projector_weights

array of projector_weights with shape (num_kpoints, num_bands, num_projectors)

Type:

numpy.ndarray

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.

set_gap_data()

Loop over bands to set the band gap, VBM, CBM, their positions and the smallest direct gap inside self._data, for each spin channel. Sets self.band_gap to be the smallest of the band gaps across all spin channels.

new_from_trimmed_path(k_start_ind=0, k_end_ind=None)

Returns a new ElectronicDispersion object with the kpoint path trimmed by the provided indices.

class matador.orm.spectral.dispersion.VibrationalDispersion(*args, **kwargs)

Bases: Dispersion

Class that stores vibrational dispersion data. Attributes are all implemented as properties based on underlying raw data.

source

list of source files.

Type:

list

num_kpoints

number of kpoints.

Type:

int

num_atoms

number of atoms.

Type:

int

num_modes

number of phonon modes.

Type:

int

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:

numpy.ndarray

freq_unit

human-readable frequency unit used for eig array.

Type:

str

kpoint_path

array of shape (num_kpoints, 3) containing the k-point path in fractional coordinates.

Type:

numpy.ndarray

kpoint_path_cartesian

as above, in Cartesian coordinates.

Type:

numpy.ndarray

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)

Bases: Dispersion, 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.

plot_dos(**kwargs)

Plot the density of states.

static bands_as_dos(bands, gaussian_width=0.1)

Convert bands data to DOS data.

class matador.orm.spectral.dos.VibrationalDOS(*args, **kwargs)

Bases: 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)

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)

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:

float

vibrational_free_energy_from_dos(temperatures=None)

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 and sample_dos, return an interpolated function to integrate.

plot_free_energy(temperatures=None, ax=None, **kwargs)

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)

Bases: 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, mutable=False, **kwargs)

Bases: 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.