tessl/pypi-phonopy

Comprehensive Python library for phonon calculations that enables lattice dynamics simulations and vibrational property analysis of crystalline materials.

—

Pending

Overview

Eval results

Files

Phonopy

Name: tessl/pypi-phonopy
Author: tessl

A comprehensive Python library for phonon calculations that enables lattice dynamics simulations and vibrational property analysis of crystalline materials. Phonopy provides computational tools for phonon band structures, density of states, thermal properties, and advanced analyses including Grüneisen parameters and quasi-harmonic approximation calculations.

Package Information

Package Name: phonopy
Language: Python
Installation: pip install phonopy
Version Access: from phonopy import __version__

Core Imports

import phonopy
from phonopy import Phonopy, PhonopyGruneisen, PhonopyQHA, load, __version__

For specific functionality:

from phonopy.structure.atoms import PhonopyAtoms
from phonopy.interface.vasp import read_vasp
from phonopy.interface.phonopy_yaml import PhonopyYaml

Basic Usage

import numpy as np
from phonopy import Phonopy
from phonopy.structure.atoms import PhonopyAtoms

# Create unit cell structure
lattice = [[4.0, 0.0, 0.0],
           [0.0, 4.0, 0.0], 
           [0.0, 0.0, 4.0]]
positions = [[0.0, 0.0, 0.0],
             [0.5, 0.5, 0.5]]
numbers = [1, 1]

unitcell = PhonopyAtoms(cell=lattice, 
                        scaled_positions=positions,
                        numbers=numbers)

# Create Phonopy instance with 2x2x2 supercell
supercell_matrix = [[2, 0, 0], [0, 2, 0], [0, 0, 2]]
ph = Phonopy(unitcell, supercell_matrix)

# Generate displacements for force calculations
ph.generate_displacements(distance=0.01)
print(f"Number of displacements: {len(ph.displacements)}")

# Set force constants (after obtaining forces from ab initio calculations)
# ph.forces = forces_from_calculations
# ph.produce_force_constants()

# Calculate thermal properties
temperatures = np.arange(0, 1000, 10)
ph.run_thermal_properties(temperatures=temperatures)
thermal_props = ph.get_thermal_properties_dict()

Architecture

Phonopy is built around a multi-layered architecture optimized for crystalline material analysis:

Core Engine: The Phonopy class orchestrates all phonon calculations with 100+ methods
Structure Management: PhonopyAtoms, Supercell, Primitive classes handle crystal structures
Calculator Interfaces: Support for 10+ ab initio codes (VASP, Quantum ESPRESSO, ABINIT, etc.)
Analysis Modules: Specialized classes for band structures, DOS, thermal properties, group velocities
Advanced Features: Grüneisen parameters, quasi-harmonic approximation, machine learning potentials
File I/O: Comprehensive support for YAML, HDF5, and calculator-specific file formats

This modular design enables phonopy to serve as the foundation for phonon analysis workflows across the materials science community.

Capabilities

Core Phonopy API

Main Phonopy class providing comprehensive phonon calculation capabilities including displacement generation, force constant calculation, band structure analysis, density of states, and thermal property calculations.

class Phonopy:
    def __init__(
        self,
        unitcell: PhonopyAtoms,
        supercell_matrix: ArrayLike = None,
        primitive_matrix: ArrayLike | str = None,
        nac_params: dict = None,
        factor: float = None,
        frequency_scale_factor: float = None,
        dynamical_matrix_decimals: int = None,
        force_constants_decimals: int = None,
        group_velocity_delta_q: float = None,
        symprec: float = 1e-5,
        is_symmetry: bool = True,
        store_dense_svecs: bool = True,
        use_SNF_supercell: bool = False,
        hermitianize_dynamical_matrix: bool = True,
        calculator: str = None,
        set_factor_by_calculator: bool = False,
        log_level: int = 0
    ): ...
    
    def generate_displacements(
        self,
        distance: float | None = None,
        is_plusminus: Literal["auto"] | bool = "auto",
        is_diagonal: bool = True,
        is_trigonal: bool = False,
        number_of_snapshots: int | Literal["auto"] | None = None,
        random_seed: int | None = None,
        temperature: float | None = None,
        cutoff_frequency: float | None = None,
        max_distance: float | None = None,
        number_estimation_factor: float | None = None
    ) -> None: ...
    
    def produce_force_constants(
        self,
        fc_calculator: str = "traditional",
        fc_calculator_options: str = None,
        show_log: bool = True
    ): ...
    
    def run_band_structure(
        self,
        paths: ArrayLike,
        with_eigenvectors: bool = False,
        with_group_velocities: bool = False,
        is_band_connection: bool = False,
        path_connections: ArrayLike = None,
        labels: list = None,
        is_legacy_plot: bool = False
    ): ...
    
    def run_mesh(
        self,
        mesh: ArrayLike,
        shift: ArrayLike = None,
        is_time_reversal: bool = True,
        is_mesh_symmetry: bool = True,
        with_eigenvectors: bool = False,
        with_group_velocities: bool = False,
        is_gamma_center: bool = False
    ): ...
    
    def run_thermal_properties(
        self,
        t_min: float = 0,
        t_max: float = 1000,
        t_step: float = 10,
        temperatures: ArrayLike = None,
        cutoff_frequency: float = None,
        pretend_real: bool = False,
        band_indices: ArrayLike = None,
        is_projection: bool = False,
        classical: bool = False
    ): ...

Core Phonopy API

Grüneisen Parameters

Calculate mode Grüneisen parameters that quantify anharmonicity by measuring how phonon frequencies change with volume variations.

class PhonopyGruneisen:
    def __init__(
        self,
        phonon: Phonopy,
        phonon_plus: Phonopy, 
        phonon_minus: Phonopy,
        delta_strain: float = None
    ): ...
    
    def set_mesh(
        self,
        mesh: ArrayLike,
        is_gamma_center: bool = False,
        shift: ArrayLike = None,
        is_time_reversal: bool = True,
        is_mesh_symmetry: bool = True
    ): ...
    
    def set_band_structure(self, bands: ArrayLike): ...

Grüneisen Parameters

Quasi-Harmonic Approximation

Perform quasi-harmonic approximation calculations to study temperature and pressure effects on material properties through phonon calculations at multiple volumes.

class PhonopyQHA:
    def __init__(
        self,
        volumes: ArrayLike = None,
        electronic_energies: ArrayLike = None,
        temperatures: ArrayLike = None,
        free_energy: ArrayLike = None,
        cv: ArrayLike = None,
        entropy: ArrayLike = None,
        t_max: float = None,
        energy_plot_factor: float = None,
        pressure: float = None,
        eos: str = "vinet",
        verbose: bool = False
    ): ...
    
    def get_bulk_modulus(self): ...
    def get_helmholtz_volume(self): ...
    def get_volume_temperature(self): ...
    def get_thermal_expansion(self): ...
    def get_heat_capacity_P_numerical(self): ...

Quasi-Harmonic Approximation

Crystal Structure Handling

Handle crystalline structure representations, transformations, and symmetry operations for phonon calculations.

class PhonopyAtoms:
    def __init__(
        self,
        symbols: Optional[Sequence] = None,
        numbers: Optional[Union[Sequence, np.ndarray]] = None,
        masses: Optional[Union[Sequence, np.ndarray]] = None,
        magnetic_moments: Optional[Union[Sequence, np.ndarray]] = None,
        scaled_positions: Optional[Union[Sequence, np.ndarray]] = None,
        positions: Optional[Union[Sequence, np.ndarray]] = None,
        cell: Optional[Union[Sequence, np.ndarray]] = None,
        atoms: Optional["PhonopyAtoms"] = None,
        magmoms: Optional[Union[Sequence, np.ndarray]] = None,
        pbc: Optional[bool] = None
    ): ...
    
    def copy(self) -> PhonopyAtoms: ...
    def get_cell(self) -> ndarray: ...
    def get_positions(self) -> ndarray: ...
    def get_scaled_positions(self) -> ndarray: ...
    def get_masses(self) -> ndarray: ...
    def get_chemical_symbols(self) -> list: ...
    def get_atomic_numbers(self) -> ndarray: ...

Crystal Structure Handling

Loading and File Operations

Load phonopy calculations from various file formats and manage input/output operations with different ab initio calculation codes.

def load(
    phonopy_yaml: str | os.PathLike | io.IOBase | None = None,
    supercell_matrix: ArrayLike | None = None,
    primitive_matrix: ArrayLike | str | None = None,
    is_nac: bool = True,
    calculator: str | None = None,
    unitcell: PhonopyAtoms | None = None,
    supercell: PhonopyAtoms | None = None,
    nac_params: dict | None = None,
    unitcell_filename: os.PathLike | str | None = None,
    supercell_filename: os.PathLike | str | None = None,
    born_filename: os.PathLike | str | None = None,
    force_sets_filename: os.PathLike | str | None = None,
    force_constants_filename: os.PathLike | str | None = None,
    fc_calculator: Literal["traditional", "symfc", "alm"] | None = None,
    fc_calculator_options: str | None = None,
    factor: float | None = None,
    produce_fc: bool = True,
    is_symmetry: bool = True,
    symmetrize_fc: bool = True,
    is_compact_fc: bool = True,
    use_pypolymlp: bool = False,
    mlp_params: dict | None = None,
    store_dense_svecs: bool = True,
    use_SNF_supercell: bool = False,
    symprec: float = 1e-5,
    log_level: int = 0
) -> Phonopy: ...

Loading and File Operations

Command-line Tools

Comprehensive command-line interface providing phonopy calculations, plotting utilities, and file format conversions through specialized scripts.

# Main phonopy command-line interface
def main(): ...

# Plotting utilities  
def phonopy_bandplot(): ...
def phonopy_pdosplot(): ...
def phonopy_propplot(): ...
def phonopy_tdplot(): ...
def phonopy_gruneisenplot(): ...

# Calculation scripts
def phonopy_gruneisen(): ...
def phonopy_qha(): ...

# Utility scripts
def phonopy_calc_convert(): ...
def create_FORCE_SETS(): ...

Command-line Tools

Common Types

# Standard library imports
import os
import io
from typing import Optional, Union, Sequence, Literal
from pathlib import Path

# NumPy imports
import numpy as np
from numpy import ndarray
from numpy.typing import ArrayLike

# Type aliases for common array-like inputs (following phonopy source)
ArrayLike = Union[list, tuple, Sequence, np.ndarray]

# File path types (explicit module references as in source)
PathLike = Union[str, os.PathLike, Path]
IOBase = io.IOBase

# Common calculator interfaces
Calculator = Literal[
    "vasp", "qe", "abinit", "aims", "castep", 
    "cp2k", "crystal", "wien2k", "siesta", "lammps"
]

# Force constants calculator types
ForceConstantsCalculator = Literal["traditional", "symfc", "alm"]

Install with Tessl CLI