{"id":6769,"library":"phonopy","title":"Phonopy","description":"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.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/phonopy/phonopy","tags":["materials science","physics","solid state","phonons","DFT","ab initio","crystal structure","lattice dynamics"],"install":[{"cmd":"pip install phonopy","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge phonopy","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Core numerical operations for array manipulation.","package":"numpy","optional":false},{"reason":"Plotting phonon band structures, DOS, and thermal properties.","package":"matplotlib","optional":false},{"reason":"Reading and writing YAML-formatted input/output files (e.g., phonopy_disp.yaml, phonopy_params.yaml).","package":"pyyaml","optional":false},{"reason":"Support for HDF5 output files (e.g., mesh.hdf5, band.hdf5).","package":"h5py","optional":false},{"reason":"Scientific computing routines, potentially used in various analysis steps.","package":"scipy","optional":false},{"reason":"Symmetry operations and space group determination, crucial for phonon calculations.","package":"spglib","optional":false},{"reason":"Force constants calculation; became a necessary dependency from v2.30.0, and is the default FC calculator for `phonopy-load`.","package":"symfc","optional":false}],"imports":[{"symbol":"Phonopy","correct":"from phonopy import Phonopy"},{"symbol":"PhonopyAtoms","correct":"from phonopy.structure.atoms import PhonopyAtoms"}],"quickstart":{"code":"import numpy as np\nfrom phonopy import Phonopy\nfrom phonopy.structure.atoms import PhonopyAtoms\n\n# Define a simple unit cell (e.g., Silicon diamond structure)\na = 5.404  # Lattice constant in Angstrom\nunitcell = PhonopyAtoms(\n    symbols=['Si'] * 8,\n    cell=np.diag([a, a, a]),\n    scaled_positions=[\n        [0, 0, 0], [0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0],\n        [0.25, 0.25, 0.25], [0.25, 0.75, 0.75], [0.75, 0.25, 0.75], [0.75, 0.75, 0.25]\n    ]\n)\n\n# Define the supercell matrix (e.g., 2x2x2 supercell)\nsupercell_matrix = [[2, 0, 0], [0, 2, 0], [0, 0, 2]]\n\n# Initialize Phonopy object\n# The primitive matrix is often set based on the crystal structure, e.g., for FCC/diamond-like cells\n# For Si, the primitive cell is usually R-centered hexagonal or face-centered orthorhombic.\n# A common choice for diamond is: [[0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0]]\nprimitive_matrix = [[0, 0.5, 0.5], [0.5, 0, 0.5], [0.5, 0.5, 0]]\n\nphonon = Phonopy(\n    unitcell,\n    supercell_matrix=supercell_matrix,\n    primitive_matrix=primitive_matrix\n)\n\n# Generate displacements for force calculations\n# distance defines the displacement magnitude (default 0.01 Angstrom for VASP-like calculators)\nphonon.generate_displacements(distance=0.03)\n\n# Get the supercells with displacements. These would typically be used to generate input files for DFT calculations.\nsupercells_with_displacements = phonon.supercells_with_displacements\n\nprint(f\"Number of displaced supercells: {len(supercells_with_displacements)}\")\nprint(\"First displaced supercell (symbols and scaled positions):\")\nprint(supercells_with_displacements[0].symbols)\nprint(supercells_with_displacements[0].scaled_positions)\n\n# In a real workflow, you would then run DFT calculations on these supercells to get forces,\n# and then use phonon.set_forces() and further methods to compute phonon properties.","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=3.2.0"},{"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`.","message":"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).","severity":"deprecated","affected_versions":">=2.38.2, >=2.44.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.30.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}