{"id":5005,"library":"phono3py","title":"Phono3py: Anharmonic Lattice Dynamics","description":"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.","status":"active","version":"3.30.1","language":"python","source_language":"en","source_url":"https://github.com/phonopy/phono3py","tags":["materials science","physics","solid-state physics","lattice dynamics","simulation","thermodynamics","first-principles"],"install":[{"cmd":"pip install phono3py","lang":"bash","label":"Install phono3py"}],"dependencies":[{"reason":"Essential for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Provides scientific computing tools, including linear algebra and signal processing.","package":"scipy","optional":false},{"reason":"Used for reading and writing HDF5 files, a common format for storing force constants.","package":"h5py","optional":false},{"reason":"Used for plotting results.","package":"matplotlib","optional":true},{"reason":"Used for parsing YAML configuration files.","package":"PyYAML","optional":true}],"imports":[{"symbol":"Phono3py","correct":"from phono3py import Phono3py"},{"note":"As of phono3py v3.x, cell definitions typically require `phonopy.structure.atoms.PhonopyAtoms` rather than `ase.Atoms` for consistency with the underlying Phonopy library.","wrong":"from ase.atoms import Atoms","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\nfrom phono3py import Phono3py\n\n# Define a simple silicon unit cell (diamond structure) for demonstration\na = 5.43  # Lattice parameter for Si\n\n# Unit cell basis vectors (face-centered cubic)\nlattice = np.array([\n    [a/2, a/2, 0],\n    [a/2, 0, a/2],\n    [0, a/2, a/2]\n])\n\n# Atoms in the unit cell (fractional coordinates)\npositions = np.array([\n    [0, 0, 0],\n    [0.25, 0.25, 0.25]\n])\nsymbols = ['Si', 'Si']\n\n# Create a PhonopyAtoms object for the unit cell\nunit_cell = PhonopyAtoms(cell=lattice, scaled_positions=positions, symbols=symbols)\n\n# Define supercell matrix (e.g., 2x2x2 supercell)\nsupercell_matrix = np.diag([2, 2, 2])\n\n# Initialize Phonopy object (a prerequisite for Phono3py)\nphonon = Phonopy(unit_cell, supercell_matrix)\n\n# Define a primitive matrix if different from the unit cell. \n# For FCC structures, a typical primitive cell matrix is:\nprimitive_matrix = np.array([\n    [0, 0.5, 0.5],\n    [0.5, 0, 0.5],\n    [0.5, 0.5, 0]\n])\n\n# Initialize Phono3py object with the Phonopy object and supercell matrix\nph3 = Phono3py(phonon, supercell_matrix, primitive_matrix=primitive_matrix)\n\nprint(\"Phono3py object initialized successfully.\")\nprint(f\"Number of atoms in primitive cell: {ph3.primitive.numbers.shape[0]}\")\nprint(f\"Number of atoms in supercell: {ph3.supercell.numbers.shape[0]}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Phono3py 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.","severity":"breaking","affected_versions":"3.x and later"},{"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.","message":"Phono3py 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.","severity":"gotcha","affected_versions":"All"},{"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).","message":"Calculations 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Phono3py 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).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'3.30.1':60 'activ':64 'anharmon':2,12 'approach':27 'cadenc':68 'calcul':11,44 'code':45 'common':36 'conduct':20 'conjunct':39 'constant':33 'counterpart':75 'current':57 'develop':65 'dynam':4,14,85 'e.g':46 'espresso':49 'first':42,89 'first-principl':41,88 'forc':32,54 'harmon':74 'inform':55 'lattic':3,13,18,84 'lifetim':23 'maintain':62 'materi':77 'necessari':53 'often':69 'order':31 'packag':9 'phono3py':1,5 'phonon':22 'phonopi':76 'physic':79,83 'principl':43,90 'properti':15 'provid':51 'python':8 'quantum':48 'releas':67 'scienc':78 'simul':86 'solid':81 'solid-st':80 'state':82 'supercel':26 'sync':71 'thermal':19 'thermodynam':87 'third':30 'third-ord':29 'use':24,37 'vasp':47 'version':58","created_at":"2026-04-12T16:50:00.098827+00:00","updated_at":"2026-04-16T18:00:07.134748+00:00","problems":[{"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.","cause":"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.","error":"ImportError: ... undefined symbol: LAPACKE_dsyev"},{"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.","cause":"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.","error":"Crystal structure file \"None\" was not found. Crystal structure file \"unitcell.in\" was not found."},{"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.","cause":"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.","error":"Number of files to be read (...) don't match to the number of displacements (...) in phono3py_disp.yaml."},{"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.","cause":"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.","error":"cElementTree.ParseError: no element found: line XXXX, column X"},{"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.","cause":"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.","error":"memory error / segmentation fault"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.4.0","cli_name":"phono3py","cli_version":"usage: phono3py [-h] [--abinit] [--crystal] [--qe] [--turbomole] [--vasp]","type":"library","homepage":"https://phonopy.github.io/phono3py/","github":"https://github.com/phonopy/phono3py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/phono3py/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}