Phonopy

Warnings

• breaking As 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).
• deprecated The `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`.
• breaking From 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.
• gotcha Incorrect `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.
• gotcha The 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.
• gotcha Imaginary (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.

Install

• pip install phonopy PyPI
• conda install -c conda-forge phonopy Conda

Imports

• Phonopy

  from phonopy import Phonopy

• PhonopyAtoms

  from phonopy.structure.atoms import PhonopyAtoms

Quickstart

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.