Registry / data / phonopy

phonopy

JSON →
library4.2.0pypypi✓ verified 84d ago

Phonopy is an open-source Python package designed for calculating phonon properties at harmonic and quasi-harmonic levels. It integrates with various first-principles density functional theory (DFT) codes, such as VASP, Quantum ESPRESSO, and ABINIT, to compute interatomic forces. Using the finite displacement method and crystal symmetry, Phonopy can derive phonon band structures, densities of states (DOS), thermal properties (free energy, heat capacity, entropy), group velocities, and more. The library is actively maintained and regularly updated, with version 3.5.0 being the current release.

pip install phonopy
INSTALL
IMPORT
SIG · PHONOPY
P
phonopy
datapythonv4.2.0
Install
12.0s avg
Import
857ms
Disk
351MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 12.43s
py 3.11
✕ build_error
✓ 11.83s
py 3.12
✕ build_error
✓ 11.83s
py 3.13
✕ build_error
✓ 11.85s
py 3.9
✕ build_error
✕ build_error
351MB installed
● package 351MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Phonopy
from phonopy import Phonopy
PhonopyAtoms
from phonopy.structure.atoms import PhonopyAtoms

This quickstart demonstrates how to initialize a `Phonopy` object with a unit cell and supercell matrix, and generate the necessary atomic displacements for subsequent DFT force calculations. The example uses a Silicon diamond structure, a common test case in phonon calculations. After generating displacements, the `supercells_with_displacements` can be used to create input files for an external DFT code. Once the forces are computed, they would be fed back into Phonopy for full phonon property analysis.

import numpy as np from phonopy import Phonopy from phonopy.structure.atoms import PhonopyAtoms # Define a simple unit cell (e.g., Silicon diamond structure) a = 5.404 # Lattice constant in Angstrom unitcell = PhonopyAtoms( symbols=['Si'] * 8, cell=np.diag([a, a, a]), scaled_positions=[ [0, 0, 0], [0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0], [0.25, 0.25, 0.25], [0.25, 0.75, 0.75], [0.75, 0.25, 0.75], [0.75, 0.75, 0.25] ] ) # Define the supercell matrix (e.g., 2x2x2 supercell) supercell_matrix = [[2, 0, 0], [0, 2, 0], [0, 0, 2]] # Initialize Phonopy object # The primitive matrix is often set based on the crystal structure, e.g., for FCC/diamond-like cells # For Si, the primitive cell is usually R-centered hexagonal or face-centered orthorhombic. # A common choice for diamond is: [[0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0]] primitive_matrix = [[0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0]] phonon = Phonopy( unitcell, supercell_matrix=supercell_matrix, primitive_matrix=primitive_matrix ) # Generate displacements for force calculations # distance defines the displacement magnitude (default 0.01 Angstrom for VASP-like calculators) phonon.generate_displacements(distance=0.03) # Get the supercells with displacements. These would typically be used to generate input files for DFT calculations. supercells_with_displacements = phonon.supercells_with_displacements print(f"Number of displaced supercells: {len(supercells_with_displacements)}") print("First displaced supercell (symbols and scaled positions):") print(supercells_with_displacements[0].symbols) print(supercells_with_displacements[0].scaled_positions) # In a real workflow, you would then run DFT calculations on these supercells to get forces, # and then use phonon.set_forces() and further methods to compute phonon properties.
phonopy --version
Debug
Known issues
breakingAs of Version 3.2.0 (March 2026), several parameters in the `Phonopy.__init__()` method were removed: `frequency_scale_factor`, `dynamical_matrix_decimals`, `force_constants_decimals`, `store_dense_svecs`, and `set_factor_by_calculator`. Code using these parameters will break.
fix
Review your `Phonopy` object initialization. Remove the deprecated parameters from the constructor call. Adjust your workflow to use newer API methods if the functionality is still required (e.g., directly handle unit conversions or decimals in post-processing).
affects: >=3.2.0
deprecatedThe `FREQUENCY_CONVERSION_FACTOR` tag (and `--factor` option) is deprecated since Version 2.44.0 (October 2025). Using the `factor` parameter in `Phonopy.__init__()` will now emit a warning. Similarly, `phonopy.interface.calculator.get_default_physical_units` and physical units in `phonopy.units` are deprecated (v2.38.2, April 2025).
fix
For unit conversions, utilize `phonopy.physical_units.get_physical_units()` which returns a `PhysicalUnits` dataclass. For calculator-specific units, use `phonopy.interface.calculator.get_calculator_physical_units()`. Explicitly handle conversion factors rather than relying on the deprecated `factor` parameter in `Phonopy` initialization. Note that `Kb_j` and `Kb` were renamed to `KB_J` and `KB`, and `VaspToTHz` to `DefaultToTHz`.
affects: >=2.38.2, >=2.44.0
breakingFrom Version 2.30.0 (November 2024), the `symfc` package became a *necessary* dependency for Phonopy. Additionally, `symfc` is now the *default* force constants calculator for the `phonopy-load` command.
fix
Ensure `symfc` is installed (`pip install symfc` or `conda install -c conda-forge symfc`). If you prefer the traditional force constant calculation method when using `phonopy-load`, use the `--fc-calculator traditional` option.
affects: >=2.30.0
gotchaIncorrect `PATH` and `PYTHONPATH` environment variables can lead to issues with `phonopy` execution or import, especially with multiple installations or `conda` environments. This is a common source of 'command not found' or 'module not found' errors.
fix
Verify that your `PATH` and `PYTHONPATH` variables correctly point to your desired `phonopy` installation. When using `conda` environments, always activate the correct environment (`conda activate your_env_name`) which typically handles these paths automatically. If installing from source or with `pip` into user site-packages, ensure `~/.local/bin` and `~/.local/lib/pythonX.Y/site-packages` are in your `PATH` and `PYTHONPATH` respectively.
affects: All versions
gotchaThe error 'Remapping of atoms by TrimmedCell failed' often occurs when `phonopy` struggles to determine the primitive cell. This is particularly common when defining primitive axes manually or with certain complex structures.
fix
In configuration files like `band.conf`, try setting `PRIMITIVE_AXES = AUTO`. When using the Python API, ensure the `primitive_matrix` argument to the `Phonopy` constructor is correctly defined for your system, or experiment with omitting it if the structure is simple enough for automatic detection.
affects: All versions
gotchaImaginary (negative) phonon frequencies in results, especially when using the DFPT method, can indicate insufficient k-point sampling in the underlying DFT calculation. High accuracy in forces is critical for stable phonon dispersions.
fix
Increase the k-point sampling density for your DFT calculations. Ensure that your force convergence criteria are very strict (e.g., EDIFFG in VASP). Validate your DFT parameters for accuracy before running phonon calculations.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'phonopy'
The phonopy Python package is not installed or not accessible in the current Python environment.
fix
Install phonopy using pip: `pip install phonopy` or via conda: `conda install -c conda-forge phonopy`.
Input forces are not enough to calculate force constants
The `FORCE_SETS` file (or equivalent input for force constants) does not contain sufficient force data corresponding to the generated displacements and supercell symmetry. This can happen if not all required displacement calculations were completed or if the supercell definition is inconsistent.
fix
Ensure all DFT (VASP, Quantum ESPRESSO, etc.) calculations for the displaced supercells have successfully completed and their output forces are correctly compiled into the `FORCE_SETS` file. Verify that the supercell dimensions and primitive cell settings used in phonopy are consistent with the DFT calculations.
RuntimeError: Remapping of atoms by TrimmedCell failed.
This error typically arises when there is an inconsistency in the primitive cell definition or its relationship to the supercell, often due to incorrect `PRIMITIVE_AXES` (or `--pa`) settings or issues with the `DIM` tag in the configuration file.
fix
Correctly define the primitive cell using `PRIMITIVE_AXES = AUTO` (if applicable) or by providing the explicit primitive matrix. Ensure the supercell dimensions (`DIM`) are consistent with the structure you are using.
Number of files to be read (X) don't match to the number of displacements (Y) in phonopy_disp.yaml.
Phonopy expects a certain number of force calculation output files (e.g., `vasprun.xml` or `FORCE_SETS` entries) based on the displacements listed in `phonopy_disp.yaml`, but it finds a different number. This usually means some DFT calculations failed, or output files are missing/misnamed.
fix
Check if all individual displacement calculations have completed successfully and generated their output files. Ensure the file paths provided to `phonopy -f` (or similar command) correctly point to all expected force output files, and that `phonopy_disp.yaml` reflects the actual displacements.
Upgrade
Version history
4.2.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
numpyrequiredCore numerical operations for array manipulation.
matplotlibrequiredPlotting phonon band structures, DOS, and thermal properties.
pyyamlrequiredReading and writing YAML-formatted input/output files (e.g., phonopy_disp.yaml, phonopy_params.yaml).
h5pyrequiredSupport for HDF5 output files (e.g., mesh.hdf5, band.hdf5).
scipyrequiredScientific computing routines, potentially used in various analysis steps.
spglibrequiredSymmetry operations and space group determination, crucial for phonon calculations.
symfcrequiredForce constants calculation; became a necessary dependency from v2.30.0, and is the default FC calculator for `phonopy-load`.
Agent activity
2 hits · last 30 days
node
2
Resources
phonopy — pip install phonopy · libregistry