Band unfolding#

Often times, we need to perform DFT calculations for a supercell geometry rather than the primitive cell. In such cases the band structure becomes quite sophisticated due to the folding of the BZ, and it is difficult to compare the band structure of supercell with that of the primitive cell. The purpose of the band unfolding scheme is to represent the bands within the primitive cell BZ. By calculating the unfolding weight function and plotting the fat bands with the line width proportional to the weight, the unfolded bands can be highlighted.

Note: The Brillouin zone of a supercell shrinks respect to the primitive cell. For instance, in a hexagonal primitive lattice the point H=(1/3, 1/3, 1/2). This point, in a 2x2x2 supercell corresponds to (2/3, 2/3, 1). Therefore, all the distances in the reciprocal space must be doubled (or increased by the respective size of the supercell).

Usage: First, calculate the band structure in the primitive cell BZ. The PROCAR should be produced with the phase factor included, by setting LORBIT=12 in VASP.

Then the unfold module can be used to plot the unfolded band as follows:

import numpy as np
pyprocar.unfold(
        fname='PROCAR',
        poscar='POSCAR',
        outcar='OUTCAR',
        supercell_matrix=np.diag([2, 2, 2]),
        ispin=None, # None for non-spin polarized calculation. For spin polarized case, ispin=1: up, ispin=2: down
        efermi=None,
        shift_efermi=True,
        elimit=(-5, 15),
        kticks=[0, 36, 54, 86, 110, 147, 165, 199],
        knames=['$\Gamma$', 'K', 'M', '$\Gamma$', 'A', 'H', 'L', 'A'],
        print_kpts=False,
        show_band=True,
        width=4,
        color='blue',
        savetab='unfolding.csv',
        savefig='unfolded_band.png',
        exportplt=False)

Export plot as a matplotlib.pyplot object#

PyProcar allows the plot to be exported as a matplotlib.pyplot object. This allows for further processing of the plot through options available in matplotlib. This can be enabled by setting exportplt = True. Usage:

import matplotlib.pyplot as plt
import pyprocar

plt = pyprocar.unfold('PROCAR', outcar='OUTCAR', exportplt=True)
plt.title('Using matplotlib options')
plt.show()
pyprocar.scripts.scriptUnfold.unfold(code='vasp', dirname='.', mode='plain', unfold_mode='both', transformation_matrix=array([[2, 0, 0], [0, 2, 0], [0, 0, 2]]), spins=None, atoms=None, orbitals=None, items=None, projection_mask=None, unfold_mask=None, fermi=None, fermi_shift=0, interpolation_factor=1, interpolation_type='cubic', vmax=None, vmin=None, kticks=None, knames=None, kdirect=True, elimit=None, ax=None, show=True, savefig=None, old=False, savetab='unfold_result.csv', print_plot_opts: bool = False, **kwargs)[source]#
Parameters:

  • fname (PROCAR filename.)

  • poscar (POSCAR filename)

  • outcar (OUTCAR filename, for reading fermi energy. You can also use efermi and set outcar=None)

  • supercell_matrix (supercell matrix from primitive cell to supercell)

  • ispin (For non-spin polarized system, ispin=None.) – For spin polarized system: ispin=1 is spin up, ispin=2 is spin down.

  • fermi (Fermi energy)

  • fermi_shift (Shift the bands by the Fermi energy.)

  • elimit (range of energy to be plotted.)

  • kticks (the indices of K points which has labels given in knames.)

  • knames (see kticks)

  • print_kpts (print all the kpoints to screen. This is to help find the kticks and knames.)

  • show_band (whether to plot the bands before unfolding.)

  • width (the width of the unfolded band.)

  • color (color of the unfoled band.)

  • savetab (the csv file name of which the table of unfolding result will be written into.)

  • savefig (the file name of which the figure will be saved.)

  • exportplt (flag to export plot as matplotlib.pyplot object.)