unPHold

unPHold unfolds phonon band structures from a supercell Brillouin zone onto a smaller unit cell Brillouin zone.

Documentation: unphold.readthedocs.io

Features

• Handles 3D and 2D systems, moiré superlattices, defective structures, and relaxed or deregistered structures.
• Per-mode unfolding weights and unfolded band structure visualization.
• Mode-character metrics: acoustic participation ratio (APR), longitudinality (L), and out-of-plane verticality (V).
• Visualization of real-space phonon displacements.
• Built on phonopy: unPHold reuses phonopy's force constants and structural data, so it works with any force-constant source, including density-functional theory (DFT) codes and machine-learning interatomic potentials (MLIPs).

Installation

Install from GitHub:

pip install git+https://github.com/sabia-group/unPHold.git

See the installation guide for details.

Quickstart

from unphold import Unfold

unfold = Unfold(
    unitcell=uc_atoms,           # primitive cell (ase.Atoms)
    supercell=sc_atoms,          # supercell (ase.Atoms)
    transformation_matrix=tmat,  # supercell transformation matrix
)
unfold.set_kpts_in_unitcell(kpts, format="fractional")
unfold.calculate_sc_phonon(dyn_sc=ph_sc.dynamical_matrix)
unfold.calculate_weights()
spectral, grid, _ = unfold.calculate_spectral_function_on_grid(grid=freq_grid, sigma=0.1)

Example scripts are available at examples/, including bulk Si, twisted bilayer graphene, and graphene monolayer with a vacancy. Step-by-step walkthroughs are in the tutorials.

Citation

If you use unPHold in your research, please cite this Zenodo record: 10.5281/zenodo.17714099.

License

unPHold is distributed under the MIT license.