Phonopy

Optional dependency

PhonopyAnalyzer requires the phonopy extra.

uvpip

uv add "materialsframework[phonopy]"

pip install "materialsframework[phonopy]"

PhonopyAnalyzer

PhonopyAnalyzer(
    calculator: BaseCalculator | None = None,
    phonopy_transformation: PhonopyDisplacementTransformation
    | None = None,
)

A class used to calculate phonon properties using Phonopy.

Generates displaced supercells, calculates forces with a specified calculator, and computes the total density of states (DOS), projected DOS (PDOS), and thermal properties of a given structure.

Initializes the PhonopyAnalyzer object.

Parameters:

Name	Type	Description	Default
calculator	BaseCalculator	The calculator used to compute forces and energies.	None
phonopy_transformation	PhonopyDisplacementTransformation	The transformation object used to generate displaced supercells.	None

calculate

calculate(
    structure: Structure | Atoms,
    is_relaxed: bool = False,
    distance: float = 0.01,
    supercell_matrix: list | None = None,
    primitive_matrix: list | str | None = None,
    mesh: ArrayLike | float | None = None,
    pdos_mesh: ArrayLike | float | None = None,
    sigma: float | None = None,
    freq_min: float | None = None,
    freq_max: float | None = None,
    freq_pitch: float | None = None,
    t_min: float = 0,
    t_max: float = 1000,
    t_step: float = 10,
    log_level: int = 0,
) -> dict[str, dict]

Calculates the phonon properties of the given structure.

This method generates displaced supercells using Phonopy, calculates the forces using the provided calculator, and computes the total density of states (DOS), projected DOS (PDOS), and thermal properties.

Parameters:

Name	Type	Description	Default
structure	Structure | Atoms	The structure to calculate phonon properties for.	required
is_relaxed	bool	Whether the input structure is already relaxed. Defaults to False.	False
distance	float	The distance to displace atoms for force calculations. Defaults to 0.01.	0.01
supercell_matrix	list	The supercell matrix for generating supercells. Defaults to None.	None
primitive_matrix	list | str	The primitive matrix for generating the primitive cell. Defaults to None, which the underlying transformation resolves the same as "auto" (symmetry-detected primitive cell). Pass "P" to use the input structure as is (identity transformation).	None
mesh	ArrayLike | float	The mesh numbers for phonon calculations. Defaults to [20, 20, 20].	None
pdos_mesh	ArrayLike | float	The mesh numbers for projected DOS calculations. Defaults to [10, 10, 10].	None
sigma	float	The smearing width for the total DOS calculation. Defaults to None.	None
freq_min	float	The minimum frequency for the total DOS calculation. Defaults to None.	None
freq_max	float	The maximum frequency for the total DOS calculation. Defaults to None.	None
freq_pitch	float	The interval of frequencies for the total DOS calculation. Defaults to None.	None
t_min	float	The minimum temperature for thermal property calculations. Defaults to 0.	0
t_max	float	The maximum temperature for thermal property calculations. Defaults to 1000.	1000
t_step	float	The step size for temperature increments. Defaults to 10.	10
log_level	int	The log level for the phonon calculations. Defaults to 0.	0

Returns:

Type	Description
dict[str, dict]	dict[str, dict]: Dictionary with keys: - total_dos: Total phonon density of states payload. - thermal_properties: Thermal-properties payload. - projected_dos: Projected phonon density of states payload.

Raises:

Type	Description
ValueError	If the calculator object does not have the 'forces' property implemented.

phonopy_transformation

phonopy_transformation() -> (
    PhonopyDisplacementTransformation
)

Returns the Phonopy transformation object used to generate displaced structures.

Returns:

Name	Type	Description
PhonopyDisplacementTransformation	PhonopyDisplacementTransformation	The transformation object used for phonon property calculations.