{"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":"en","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,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}