phonon_lifetime.phonon package

A collection of code for manipulating normal modes.

class phonon_lifetime.phonon.BodyCenteredCubicPoint(*values)

Bases: Enum

High-symmetry points for a BCC lattice.

GAMMA = ('Γ', (0.0, 0.0, 0.0))

H = ('H', (0.5, -0.5, 0.5))

N = ('N', (0.0, 0.0, 0.5))

P = ('P', (0.25, 0.25, 0.25))

class phonon_lifetime.phonon.CubicPoint(*values)

Bases: Enum

High-symmetry points for a Cubic lattice.

GAMMA = ('Γ', (0.0, 0.0, 0.0))

M = ('M', (0.5, 0.5, 0.0))

MINUS_M = ('-M', (-0.5, -0.5, 0.0))

MINUS_R = ('-R', (-0.5, -0.5, -0.5))

MINUS_X = ('-X', (-0.5, 0.0, 0.0))

MINUS_Y = ('-Y', (0.0, -0.5, 0.0))

MINUS_Z = ('-Z', (0.0, 0.0, -0.5))

R = ('R', (0.5, 0.5, 0.5))

X = ('X', (0.5, 0.0, 0.0))

Y = ('Y', (0.0, 0.5, 0.0))

Z = ('Z', (0.0, 0.0, 0.5))

class phonon_lifetime.phonon.DispersionPath(*, points: tuple[DispersionPoint, Unpack[tuple[DispersionPathPoint, ...]]])

Bases: object

A path through the Brillouin zone for plotting the dispersion relation.

property labels: tuple[str, ...]

The labels for the high-symmetry points in the path.

points: tuple[DispersionPoint, Unpack[tuple[DispersionPathPoint, ...]]]

property q_values: ndarray[tuple[int, Literal[3]], dtype[floating]]

The q values for the dispersion path.

class phonon_lifetime.phonon.DispersionPathPhonons(system: S, omega: ndarray[tuple[int], dtype[floating]], vectors: ndarray[tuple[int, int, Literal[3]], dtype[complex128]], path: DispersionPath)

Bases: Phonons, Generic

A collection of phonon modes that form a dispersion relation.

property path: DispersionPath

The path through the Brillouin zone that these phonons correspond to.

property q_values: ndarray[tuple[int, Literal[3]], dtype[floating]]

The q values for each phonon.

type phonon_lifetime.phonon.DispersionPathPoint = tuple[int, DispersionPoint]

class phonon_lifetime.phonon.DispersionSegment(*, start: DispersionPoint, end: DispersionPoint, n_points: int)

Bases: object

A segment of the dispersion path.

end: DispersionPoint

n_points: int

property q_values: ndarray[tuple[int, Literal[3]], dtype[floating]]

The n q values for this segment.

start: DispersionPoint

class phonon_lifetime.phonon.DispersionSegmentPhonons(system: S, omega: ndarray[tuple[int], dtype[floating]], vectors: ndarray[tuple[int, int, Literal[3]], dtype[complex128]], path: DispersionSegment)

Bases: Phonons, Generic

A collection of phonon modes that form a dispersion relation.

property q_values: ndarray[tuple[int, Literal[3]], dtype[floating]]

The q values for each phonon.

property segment: DispersionSegment

The segment of the dispersion path that these phonons correspond to.

class phonon_lifetime.phonon.FaceCenteredCubicPoint(*values)

Bases: Enum

High-symmetry points for an FCC lattice (Standard Setyawan-Curtarolo convention).

GAMMA = ('Γ', (0.0, 0.0, 0.0))

K = ('K', (0.375, 0.375, 0.75))

L = ('L', (0.5, 0.5, 0.5))

U = ('U', (0.625, 0.25, 0.625))

W = ('W', (0.5, 0.25, 0.75))

X = ('X', (0.5, 0.0, 0.5))

class phonon_lifetime.phonon.GammaPhonon(*, system: S, omega: float, vector: ndarray[tuple[int, Literal[3]], dtype[complex128]])

Bases: MeshPhonon, Generic

Represents a normal mode of a system at the Gamma point.

class phonon_lifetime.phonon.GammaPhonons(*, system: S, omega: ndarray[tuple[int], dtype[floating]], vectors: ndarray[tuple[int, int, Literal[3]], dtype[complex128]])

Bases: MeshPhonons, Generic

Represents all normal modes of a system at the Gamma point.

class phonon_lifetime.phonon.HexagonalPoint(*values)

Bases: Enum

High-symmetry points for 2D and 3D hexagonal lattices (e.g., Graphene, HCP).

A = ('A', (0.0, 0.0, 0.5))

GAMMA = ('Γ', (0.0, 0.0, 0.0))

H = ('H', (0.3333333333333333, 0.3333333333333333, 0.5))

K = ('K', (0.3333333333333333, 0.3333333333333333, 0.0))

L = ('L', (0.5, 0.0, 0.5))

M = ('M', (0.5, 0.0, 0.0))

MINUS_A = ('-A', (0.0, 0.0, -0.5))

MINUS_H = ('-H', (-0.3333333333333333, -0.3333333333333333, -0.5))

MINUS_K = ('-K', (-0.3333333333333333, -0.3333333333333333, 0.0))

MINUS_L = ('-L', (-0.5, 0.0, -0.5))

MINUS_M = ('-M', (-0.5, 0.0, 0.0))

class phonon_lifetime.phonon.MeshPhonon(*, system: S, omega: float, vector: ndarray[tuple[int, Literal[3]], dtype[complex128]], iq: int | tuple[int, int, int], n_repeats: tuple[int, int, int] = (1, 1, 1))

Bases: Phonon, Generic

Represents a normal mode of a system.

property iq: int

property n_repeats: tuple[int, int, int]

class phonon_lifetime.phonon.MeshPhonons(*, system: S, omega: ndarray[tuple[int], dtype[floating]], vectors: ndarray[tuple[int, int, Literal[3]], dtype[complex128]], n_repeats: tuple[int, int, int] = (1, 1, 1))

Bases: Phonons, Generic

Represents all normal modes of a system.

at_branch(branch: int) → MeshPhonons

Get all phonons at a given branch.

get_mode_idx(branch: int, iq: int | tuple[int, int, int]) → int

get_mode_idx(branch: int, iq: None = None) → ndarray[tuple[int], dtype[int64]]

Get the index of a mode by branch and q point.

property n_repeats: tuple[int, int, int]

property q_values: ndarray[tuple[int, int], dtype[floating]]

The q values for each mode. Computed to match phonopy’s q points.

select_phonon(branch: int, iq: int | tuple[int, int, int]) → MeshPhonon[S]

select_phonon(branch: int, iq: None = None) → MeshPhonons[S]

Select a single phonon.

property vectors: ndarray[tuple[int, int, Literal[3]], dtype[complex128]]

The vector of the mode, an (n_modes, n_atoms, 3) array.

class phonon_lifetime.phonon.Phonon(*, system: S, omega: float, vector: ndarray[tuple[int, Literal[3]], dtype[complex128]], q: tuple[float, float, float])

Bases: Generic

Represents a normal mode of a system.

property omega: float

The frequency of the mode.

property q: tuple[float, float, float]

The q point of the mode.

property system: S

Get the system of the mode.

property vector: ndarray[tuple[int, Literal[3]], dtype[complex128]]

Get the vector of the mode, an (n_atoms, 3) array.

class phonon_lifetime.phonon.Phonons(*, system: S, omega: ndarray[tuple[int], dtype[floating]], q_values: ndarray[tuple[int, Literal[3]], dtype[floating]], vectors: ndarray[tuple[int, int, Literal[3]], dtype[complex128]])

Bases: Generic

Represents a collection of phonon modes.

get_mode_idx(branch: int, iq: int) → int

get_mode_idx(branch: int, iq: None = None) → ndarray[tuple[int], dtype[int64]]

Get the index of a mode by branch and q point.

Modes are indexed by (i_q, i_branch), where i_q is the index of the q point and i_branch is the index of the branch.

property n_branch: int

The number of bands in the calculation.

property n_modes: int

The number of modes in the calculation.

property n_q: int

The number of q points in the calculation.

property omega: ndarray[tuple[int], dtype[floating]]

A np.array of frequencies for each mode.

property q_values: ndarray[tuple[int, Literal[3]], dtype[floating]]

The q values for each phonon.

select_phonon(branch: int, iq: int) → Phonon[S]

select_phonon(branch: int, iq: None = None) → Phonons[S]

Select a single phonon by branch and q point.

property system: S

The system that this normal mode belongs to.

property vectors: ndarray[tuple[int, int, Literal[3]], dtype[complex128]]

The vector of the mode, an (n_modes, n_atoms, 3) array.

phonon_lifetime.phonon.animate_phonon_1d_x(phonon: Phonon, times: ndarray[Any, dtype[floating]] | None = None, *, ax: Axes | None = None) → tuple[Figure, Axes, ArtistAnimation]

phonon_lifetime.phonon.animate_phonon_xy(phonon: Phonon, times: ndarray[Any, dtype[floating]] | None = None, *, ax: Axes3D | None = None, bond_cutoff: float = inf, scale_bond_lines: bool = True, scale_displacement: float = 1.0) → tuple[Figure, Axes3D, ArtistAnimation]

phonon_lifetime.phonon.animate_phonon_xyz(phonon: Phonon, times: ndarray[Any, dtype[floating]] | None = None, *, ax: Axes3D | None = None, bond_cutoff: float = inf, scale_bond_lines: bool = True) → tuple[Figure, Axes3D, ArtistAnimation]

phonon_lifetime.phonon.as_gamma_phonon(phonon: MeshPhonon[StrainSystem]) → GammaPhonon[StrainSystem[SuperCell]]

Convert a phonon mesh phonon of a primitive cell to a phonon mesh phonon of the corresponding supercell.

phonon_lifetime.phonon.as_gamma_phonons(phonons: MeshPhonons[StrainSystem]) → GammaPhonons[StrainSystem[SuperCell]]

Convert a phonon mesh of a primitive cell to Gamma phonons of the matching supercell.

phonon_lifetime.phonon.as_supercell_phonon(phonon: Phonon[StrainSystem], n_repeats: tuple[int, int, int]) → Phonon[StrainSystem[SuperCell]]

Convert a phonon mesh phonon of a primitive cell to a phonon mesh phonon of the corresponding supercell.

phonon_lifetime.phonon.as_supercell_phonons(phonons: Phonons[StrainSystem], n_repeats: tuple[int, int, int]) → Phonons[StrainSystem[SuperCell]]

Convert a phonon mesh of a primitive cell to a phonon mesh of the corresponding supercell.

phonon_lifetime.phonon.get_dispersion_path(system: S, path: DispersionPath) → DispersionPathPhonons

Get the normal modes of the system.

phonon_lifetime.phonon.get_dispersion_segment(system: S, segment: DispersionSegment) → DispersionSegmentPhonons

Get the normal modes of the system.

phonon_lifetime.phonon.get_displacement(phonon: Phonon, time: float = 0.0) → ndarray[tuple[int, Literal[3]], dtype[floating]]

Get the displacement of the mode at a given time.

returns an array of displacements (n_atoms, 3) at the given time.

phonon_lifetime.phonon.get_gamma_phonon(system: S, *, branch: int) → GammaPhonon

Get the phonon mesh phonon of the system at a given q point and branch.

phonon_lifetime.phonon.get_gamma_phonons(system: S) → GammaPhonons

Get the phonon mesh of the system.

phonon_lifetime.phonon.get_mesh_phonon(system: S, q: int | tuple[int, int, int], branch: int = 0, n_repeats: tuple[int, int, int] = (1, 1, 1)) → MeshPhonon

Get the phonon mesh phonon of the system at a given q point and branch.

phonon_lifetime.phonon.get_mesh_phonons(system: S, n_repeats: tuple[int, int, int] = (1, 1, 1)) → MeshPhonons

Get the phonon mesh of the system.

phonon_lifetime.phonon.get_phonon(system: S, q: tuple[float, float, float], branch: int = 0) → Phonon

Get the normal mode of the system at a given q point and branch.

phonon_lifetime.phonon.get_phonons(system: S, *, q_values: ndarray[tuple[int, Literal[3]], dtype[floating]]) → Phonons

Get a set of phonons for the system.

phonon_lifetime.phonon.plot_dispersion_path(phonons: DispersionPathPhonons, branch: int = 0, *, ax: Axes | None = None) → tuple[Figure, Axes, Line2D]

phonon_lifetime.phonon.plot_dispersion_segment(phonons: DispersionSegmentPhonons, branch: int = 0, *, ax: Axes | None = None) → tuple[Figure, Axes, Line2D]

phonon_lifetime.phonon.plot_phonon_1d_x(phonon: Phonon, time: float = 0, *, ax: Axes | None = None) → tuple[Figure, Axes, Line2D]

phonon_lifetime.phonon.plot_phonon_xy(phonon: Phonon, time: float = 0, *, ax: Axes3D | None = None, bond_cutoff: float = inf, scale_bond_lines: bool = True, scale_displacement: float = 1.0) → tuple[Figure, Axes3D, tuple[PathCollection, Artist]]

phonon_lifetime.phonon.plot_phonon_xyz(phonon: Phonon, time: float = 0, *, ax: Axes3D | None = None, bond_cutoff: float = inf, scale_bond_lines: bool = True) → tuple[Figure, Axes3D, tuple[PathCollection, Artist]]