Phono3py

Optional dependency

Phono3pyAnalyzer requires the phono3py extra.

uvpip

uv add "materialsframework[phono3py]"

pip install "materialsframework[phono3py]"

Phono3pyAnalyzer

Phono3pyAnalyzer(
    calculator: BaseCalculator | None = None,
    phono3py_transformation: Phono3pyDisplacementTransformation
    | None = None,
)

A class used to calculate phonon properties using Phono3py.

Generates displaced supercells, calculates forces with the provided calculator, and computes thermal conductivity using the Relaxation Time Approximation (RTA) or the Linearized Boltzmann Transport Equation (LBTE) method.

Initializes the Phono3pyAnalyzer object.

Parameters:

Name	Type	Description	Default
calculator	BaseCalculator	The calculator used to compute forces and energies.	None
phono3py_transformation	Phono3pyDisplacementTransformation	The transformation object used to generate displaced structures.	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,
    phonon_supercell_matrix: list | None = None,
    mesh: ArrayLike | float | None = None,
    is_lbte: bool = False,
    is_isotope: bool = False,
    transport_type: Literal["SMM19", "NJC23", "IBDB19"]
    | None = None,
    boundary_mfp: float | None = None,
    gv_delta_q: float | None = None,
    t_min: float = 0,
    t_max: float = 1000,
    t_step: float = 10,
    log_level: Literal[0, 1, 2] = 0,
) -> dict[
    str, RTACalculator | LBTECalculator | NDArray | None
]

Calculates the phonon properties of the given structure, including thermal conductivity.

This method generates displaced supercells using Phono3py, calculates the forces using the provided calculator, and computes thermal conductivity based on the chosen method (RTA or LBTE).

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 supercells. Defaults to None.	None
phonon_supercell_matrix	list	The supercell matrix for phonon calculations. Defaults to None.	None
mesh	ArrayLike | float	The mesh numbers for phonon calculations. Defaults to [20, 20, 20].	None
is_lbte	bool	Whether to use the Linearized Boltzmann Transport Equation (LBTE). Defaults to False.	False
is_isotope	bool	Whether to include isotope scattering in the calculations. Defaults to False.	False
transport_type	Literal['SMM19', 'NJC23', 'IBDB19']	The inter-band transport formulation to use on top of the standard (intra-band) RTA/LBTE solution: "SMM19" (Simoncelli-Marzari-Mauri Wigner transport equation), "NJC23" (Green-Kubo), or "IBDB19" (quasi-harmonic Green-Kubo). Defaults to None, which uses the standard formulation.	None
boundary_mfp	float	Mean free path in micrometre to calculate simple boundary scattering contribution to thermal conductivity. None ignores this contribution.	None
gv_delta_q	float	Q-distance in 1/Angstrom for the central finite-difference group-velocity scheme. Defaults to None, which selects the analytical derivative of the dynamical matrix (phono3py's default since v4.1.0). Pass 1e-5 to reproduce the finite-difference behavior of phono3py v4.0.x and earlier.	None
t_min	float	The minimum temperature for thermal conductivity calculations. Defaults to 0.	0
t_max	float	The maximum temperature for thermal conductivity calculations. Defaults to 1000.	1000
t_step	float	The step size for temperature increments. Defaults to 10.	10
log_level	Literal[0, 1, 2]	The log level for Phono3py. Defaults to 0.	0

Returns:

Type	Description
dict[str, RTACalculator | LBTECalculator | NDArray | None]	dict[str, RTACalculator | LBTECalculator | NDArray | None]: Dictionary with keys: - thermal_conductivity: Thermal conductivity object (RTA or LBTE). - kappa: Lattice thermal conductivity tensor, shape (sigmas, temperatures, 6), where the last axis holds the independent tensor components (xx, yy, zz, yz, xz, xy).

Raises:

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

phono3py_transformation

phono3py_transformation() -> (
    Phono3pyDisplacementTransformation
)

Returns the Phono3py transformation object used to generate displaced structures.

Returns:

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