Registry / data / phono3py

phono3py

JSON →
library4.4.0pypypi✓ verified 28d ago

Phono3py is a Python package for calculating anharmonic lattice dynamics properties, such as lattice thermal conductivity and phonon lifetimes, using a supercell approach and third-order force constants. It is commonly used in conjunction with first-principles calculation codes (e.g., VASP, Quantum ESPRESSO) that provide the necessary force information. The current version is 3.30.1. It maintains an active development and release cadence, often in sync with its harmonic counterpart, Phonopy.

pip install phono3py
INSTALL
IMPORT
SIG · PHONO3PY
P
phono3py
datapythonv4.4.0
Install
12.7s avg
Import
915ms
Disk
358MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v4.4.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
✓ 13s
py 3.11
✕ build_error
✓ 12.5s
py 3.12
✕ build_error
✓ 12.6s
py 3.13
✕ build_error
✓ 12.5s
py 3.9
✕ build_error
✕ build_error
358MB installed
● package 358MB
Code
Verified usage

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

Phono3py
✓ from phono3py import Phono3py
PhonopyAtoms
✓ from phonopy.structure.atoms import PhonopyAtoms
✗ from ase.atoms import Atoms
As of phono3py v3.x, cell definitions typically require `phonopy.structure.atoms.PhonopyAtoms` rather than `ase.Atoms` for consistency with the underlying Phonopy library.

This quickstart demonstrates how to initialize the core `Phono3py` object. It sets up a dummy silicon unit cell and supercell, then creates a `Phonopy` object, which is passed to `Phono3py`. This is the fundamental first step before loading force constants and running calculations.

import numpy as np from phonopy import Phonopy from phonopy.structure.atoms import PhonopyAtoms from phono3py import Phono3py # Define a simple silicon unit cell (diamond structure) for demonstration a = 5.43 # Lattice parameter for Si # Unit cell basis vectors (face-centered cubic) lattice = np.array([ [a/2, a/2, 0], [a/2, 0, a/2], [0, a/2, a/2] ]) # Atoms in the unit cell (fractional coordinates) positions = np.array([ [0, 0, 0], [0.25, 0.25, 0.25] ]) symbols = ['Si', 'Si'] # Create a PhonopyAtoms object for the unit cell unit_cell = PhonopyAtoms(cell=lattice, scaled_positions=positions, symbols=symbols) # Define supercell matrix (e.g., 2x2x2 supercell) supercell_matrix = np.diag([2, 2, 2]) # Initialize Phonopy object (a prerequisite for Phono3py) phonon = Phonopy(unit_cell, supercell_matrix) # Define a primitive matrix if different from the unit cell. # For FCC structures, a typical primitive cell matrix is: primitive_matrix = np.array([ [0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0] ]) # Initialize Phono3py object with the Phonopy object and supercell matrix ph3 = Phono3py(phonon, supercell_matrix, primitive_matrix=primitive_matrix) print("Phono3py object initialized successfully.") print(f"Number of atoms in primitive cell: {ph3.primitive.numbers.shape[0]}") print(f"Number of atoms in supercell: {ph3.supercell.numbers.shape[0]}")
phono3py --version
Debug
Known issues
breakingPhono3py v3.x introduced significant API changes, notably requiring Phonopy v2.20 or later and transitioning from `ase.Atoms` to `phonopy.atoms.PhonopyAtoms` for cell definition. Direct use of `ase.Atoms` for input cell data will lead to errors.
fix
Update Phonopy to `>=2.20.0`. Migrate all cell definitions to `phonopy.atoms.PhonopyAtoms`. Review the official documentation for updated API calls, especially for force constant loading and calculation setup functions.
affects: 3.x and later
gotchaPhono3py relies on specific force constant data formats (e.g., `fc2.hdf5`, `fc3.hdf5` or `fc3.phonon3py`). Incorrect indexing (e.g., atomic indices, Cartesian components), shape, or file format can lead to subtle errors, incorrect results, or crashes.
fix
Always refer to the official documentation for the expected force constant data structure and file formats. Ensure the force constant matrices have the correct dimensions and units, and that the order of atoms matches the Phono3py object's internal representation.
affects: All
gotchaCalculations involving large supercells (e.g., > 4x4x4) can be computationally intensive and consume significant memory, especially for third-order force constants, due to the cubic scaling of interactions.
fix
Start with smaller supercells to test your setup and parameters. Monitor memory and CPU usage closely. For production runs, consider using optimized hardware and, if available, leverage parallel computation features (e.g., via MPI if Phono3py was compiled with MPI support).
affects: All
gotchaPhono3py has underlying C/Fortran dependencies (like `spglib` for space group analysis, and `BLAS`/`LAPACK` for linear algebra) that are typically handled by `pip` but can cause installation or runtime issues in specific, non-standard environments (e.g., HPC clusters, systems with custom scientific library installations).
fix
Ensure your environment has necessary compilers (GCC, Fortran) and development headers. For persistent issues, consider using Conda to manage scientific packages, or manually install `spglib` and `numpy`/`scipy` with specific `BLAS`/`LAPACK` implementations (e.g., MKL, OpenBLAS) available on your system.
affects: All
Errors
Common errors & fixes
ImportError: ... undefined symbol: LAPACKE_dsyev
This error indicates that phono3py, which has Fortran/C extensions, was compiled without proper linking to LAPACKE and BLAS libraries, or that the libraries are not found at runtime.
fix
Ensure that development packages for LAPACKE (e.g., `liblapacke-dev`) and optimized BLAS (e.g., `libopenblas-dev` or Intel MKL) are installed on your system. Reinstalling phono3py, preferably within a conda environment using `conda install phono3py`, often resolves this by managing dependencies correctly.
Crystal structure file "None" was not found. Crystal structure file "unitcell.in" was not found.
Phono3py could not locate the necessary crystal structure input file (e.g., `POSCAR`, `unitcell.in`, or `phono3py.yaml`) in the current directory or the path specified.
fix
Provide the correct path to your unit cell file using the `-c` option (e.g., `phono3py -c POSCAR`) or ensure that a default input file like `POSCAR` or `unitcell.in` is present in your working directory.
Number of files to be read (...) don't match to the number of displacements (...) in phono3py_disp.yaml.
This error occurs during the collection of forces (e.g., from `vasprun.xml` or Quantum ESPRESSO output) when the number of actual force calculation output files found does not match the number of displacements that phono3py generated and recorded in `phono3py_disp.yaml`. This typically means some DFT calculations failed or their output files are missing.
fix
Verify that all force calculations corresponding to the displacements in `phono3py_disp.yaml` have completed successfully and that their output files are present and correctly named in their respective directories. You may need to identify and re-run failed DFT calculations.
cElementTree.ParseError: no element found: line XXXX, column X
This specific parsing error usually indicates that one or more of the VASP `vasprun.xml` files are corrupted, incomplete, or truncated, preventing phono3py from extracting force data.
fix
Inspect the `vasprun.xml` files for the calculation runs indicated by the line number in the error message. Identify any corrupted or incomplete XML files, and then fix or re-run the corresponding VASP calculations to ensure complete and valid output.
memory error / segmentation fault
Calculating third-order force constants for systems with a large number of atoms or large supercells can demand an extremely high amount of memory, leading to memory exhaustion or a segmentation fault.
fix
Increase the available RAM for the calculation. Consider using the `--cfc` (compact force constants) option to reduce memory usage by storing force constants more efficiently, or employ a real-space cutoff with `--cutoff-pair` to limit the interaction range if physically justifiable for your system.
Upgrade
Version history
4.4.0latest on PyPI · released Jul 18, 2026
Audit
Dependencies
numpyrequiredEssential for numerical operations and array handling.
scipyrequiredProvides scientific computing tools, including linear algebra and signal processing.
h5pyrequiredUsed for reading and writing HDF5 files, a common format for storing force constants.
matplotliboptionalUsed for plotting results.
PyYAMLoptionalUsed for parsing YAML configuration files.
Agent activity
7 hits · last 30 days
node
6
Resources
phono3py — pip install phono3py · libregistry