Band Structure

This tutorial explains how to prepare, run, and analyze electronic band structures with VQkit for both VASP and Quantum ESPRESSO.

VQkit supports:

• symmetry-guided high-symmetry K-path generation;

• VASP and Quantum ESPRESSO band parsing;

• Fermi-level shifting;

• high-symmetry labels;

• spin-polarized VASP band structures;

• direct/indirect band-gap analysis;

• metallic or gapless classification;

• VBM and CBM reporting;

• publication-oriented PNG and PDF plots;

• export of processed band energies.

Typical workflow

A complete band-structure workflow generally has three stages:

1. Generate a symmetry-guided high-symmetry K-path.

2. Run the band-structure calculation with VASP or Quantum ESPRESSO.

3. Analyze and plot the completed band structure using VQkit.

High-symmetry K-path preparation

VQkit provides a symmetry-standardized K-path generator based on spglib and SeeK-path.

From the VQkit main menu open:

[1] Pre-processing

Then choose the band-structure K-path workflow.

You can also use the smart keyword:

kpath

VQkit searches the current working directory for a readable structure.

For VASP, supported structure files include:

POSCAR
CONTCAR

For Quantum ESPRESSO, VQkit searches suitable input files such as:

*.in
*.inp
*.pwi

The structure must contain enough cell and atomic information for symmetry analysis.

Symmetry path menu

The K-path generator provides:

[1] Symmetry-standardized K-path (spglib + SeeK-path)  [recommended]
    Space-group analysis + HPKOT path + primitive-cell output

[2] Show detected high-symmetry path / points
    Inspect the symmetry-standardized path and high-symmetry points

[0] Back

For normal use, choose:

1

Symmetry tolerance

VQkit performs a short spglib symmetry-tolerance scan and shows the detected space group at several values of symprec.

A prompt similar to the following appears:

Symmetry tolerance symprec (A) [1e-05]:

Press Enter to use the suggested value unless you have a specific reason to override it.

If the cell metric appears highly symmetric but spglib detects P1, VQkit issues a warning so that you can inspect whether small distortions in the atomic coordinates are lowering the detected symmetry.

K-point density along the path

VQkit asks:

Interpolated k-points between adjacent symmetry points [20]:

The entered value is the number of interior points between each pair of high-symmetry endpoints.

For example, entering:

20

generates 20 interior points plus the two segment endpoints.

Generated K-path files

For VASP

VQkit generates a line-mode band path such as:

KPOINTS_band

For the symmetry-standardized workflow it also generates a primitive structure, high-symmetry point information, and an expanded path.

Typical generated files include:

KPOINTS_band
PRIMCELL.vasp
KPATH_INTERPOLATED.dat

Additional symmetry-point information may also be written by the symmetry workflow.

Important

The canonical SeeK-path HPKOT path belongs to the standardized primitive cell.

For VASP, use the generated primitive structure together with the generated KPOINTS_band file for the band calculation.

For Quantum ESPRESSO

VQkit generates a QE K_POINTS {crystal_b} path file such as:

KPOINTS_band.in

It also writes:

KPATH_INTERPOLATED.dat

The generated primitive-cell information and K-path should be used together.

Band calculation: VASP

A typical VASP band workflow uses:

1. A converged SCF calculation.

2. A non-self-consistent band calculation along the high-symmetry path.

At minimum, the completed band-analysis directory should contain:

EIGENVAL
OUTCAR

For high-symmetry labels, also keep:

KPOINTS

or:

KPOINTS_band

For reciprocal-path reconstruction, VQkit also uses:

POSCAR

or:

CONTCAR

Fermi energy

For VASP, VQkit first tries to read the Fermi energy from:

OUTCAR

If that is unavailable, it can fall back to:

DOSCAR

When the Fermi energy is found, VQkit shifts the band energies as:

\[E_{\mathrm{plot}} = E - E_F\]

and plots:

E_F = 0 eV

Spin-polarized VASP bands

If spin-polarized band data are present in EIGENVAL, VQkit detects them automatically.

The plot uses separate spin-up and spin-down curves.

Band calculation: Quantum ESPRESSO

For Quantum ESPRESSO, VQkit expects processed band data from the QE band workflow.

Common supported files include:

bands.dat.gnu

and other files matching patterns such as:

*bands*.gnu
*band*.gnu
*bands*.dat
*band*.dat

VQkit deliberately avoids treating its own previously exported VQkit_BANDS.dat as the original QE source file.

Band-data formats

VQkit supports:

• native QE two-column gnuplot-style band blocks;

• two-column data where a new band is detected when the k-path coordinate resets;

• wide numerical tables containing one k-distance column followed by multiple band-energy columns.

Fermi energy for QE

VQkit searches nearby Quantum ESPRESSO output files for a Fermi energy.

It can detect records such as:

the Fermi energy is ...

If the current band directory does not contain the Fermi level, VQkit also checks nearby SCF or NSCF directories where appropriate.

When the Fermi energy is found, the plotted energies are shifted to:

\[E - E_F\]

High-symmetry labels for QE

VQkit attempts to recover high-symmetry labels from nearby metadata such as:

KPATH_INTERPOLATED.dat
KPOINTS_band.in
bands.in
band.in
nscf_band.in

If VQkit cannot match high-symmetry labels automatically, it asks you to select a metadata file manually.

A prompt may appear similar to:

High-symmetry K-path metadata was not matched automatically.

Available K-path metadata files:
  [1] KPATH_INTERPOLATED.dat
  ...

Select K-path metadata file [1]:

Choose the file generated from the same path and point density used in the band calculation.

Band-structure analysis

From the main menu open:

[2] Post-processing

Then select:

[3] Electronic structure

and choose the Band Structure option.

VQkit automatically detects whether the directory contains supported VASP or Quantum ESPRESSO band data.

For VASP it searches for:

EIGENVAL

For Quantum ESPRESSO it searches for supported band-data files.

Band report

Before plotting, VQkit reports information such as:

Code
Source
Number of k-points
Number of bands
Spin polarization
Fermi energy
Fermi-energy source
High-symmetry labels

For Quantum ESPRESSO, the report also includes band-data validation information such as the detected number of numerical rows, k-points per band, band count, and block-detection method.

Generated outputs

Processed band data

VQkit writes:

VQkit_BANDS.dat

The file contains:

• cumulative k-path distance;

• all detected band energies;

• spin-up and spin-down bands where applicable;

• Fermi-energy information;

• high-symmetry positions and labels when available.

When a Fermi energy is available, exported energies are reported as:

E - E_F

High-symmetry energies

When high-symmetry labels are available, VQkit also writes:

VQkit_HIGH_SYMMETRY_ENERGIES.dat

This file provides the band energies at the labeled high-symmetry points.

Band plots

VQkit generates:

VQkit_BAND_STRUCTURE.png
VQkit_BAND_STRUCTURE.pdf

The PNG is suitable for quick inspection and the PDF is useful for publication-quality vector output.

High-symmetry points are shown as vertical dashed lines.

If a Fermi energy is available, a horizontal line marks:

E - E_F = 0 eV

VASP example

Assume a completed VASP band directory contains:

POSCAR
KPOINTS
EIGENVAL
OUTCAR

Step 1 — Start VQkit

Open VQkit in the band calculation directory.

Step 2 — Open post-processing

Enter:

2

Step 3 — Open electronic structure

Enter:

3

Step 4 — Select band structure

Choose the Band Structure option.

VQkit reads EIGENVAL, detects the Fermi energy from OUTCAR or DOSCAR, reconstructs the K-path, and generates the processed data and plots.

Step 5 — Inspect outputs

Check:

VQkit_BAND_STRUCTURE.png
VQkit_BAND_STRUCTURE.pdf
VQkit_BANDS.dat
VQkit_HIGH_SYMMETRY_ENERGIES.dat

Quantum ESPRESSO example

Assume a completed QE band directory contains:

bands.dat.gnu
KPATH_INTERPOLATED.dat
bands.in

and the nearby SCF directory contains the output with the Fermi energy.

Step 1 — Start VQkit

Open VQkit in the QE band directory.

Step 2 — Open band analysis

Navigate to:

Post-processing
Electronic structure
Band structure

Step 3 — Check detected band information

VQkit reports:

• number of k-points;

• detected bands;

• Fermi energy if found;

• band-data parsing method;

• high-symmetry labels when metadata are available.

Step 4 — Resolve missing path labels if asked

If VQkit asks for a metadata file, select:

KPATH_INTERPOLATED.dat

provided it corresponds to the same band calculation.

Step 5 — Inspect outputs

Check:

VQkit_BAND_STRUCTURE.png
VQkit_BAND_STRUCTURE.pdf
VQkit_BANDS.dat
VQkit_HIGH_SYMMETRY_ENERGIES.dat

Band-gap analysis

VQkit also provides band-gap analysis in the Electronic Structure menu.

This workflow can report:

• band gap;

• VBM;

• CBM;

• metallic or gapless behavior;

• direct or indirect gap classification where the required data are available.

For a semiconductor, the gap is defined as:

\[E_g = E_{\mathrm{CBM}} - E_{\mathrm{VBM}}\]

If the VBM and CBM occur at the same k-point, the material is classified as having a direct gap.

If they occur at different k-points, the gap is indirect.

Recommended workflow

For reliable band analysis:

1. Relax the structure.

2. Perform a well-converged SCF calculation.

3. Generate the symmetry-standardized high-symmetry K-path.

4. Use the corresponding primitive structure and K-path together.

5. Run the band calculation.

6. Keep the original K-path metadata in the band directory.

7. Run VQkit band analysis.

8. Inspect the Fermi-energy source.

9. Confirm the high-symmetry labels.

10. Inspect the plot and numerical export before publication.

Scientific cautions

Primitive-cell consistency

The SeeK-path HPKOT path is defined for the standardized primitive cell.

Do not combine a primitive-cell K-path with an unrelated conventional cell, because this can produce incorrect or folded band paths.

Fermi-level reference

If VQkit cannot detect a Fermi energy, absolute band energies are plotted.

Before comparing different calculations, verify that the energy reference is consistent.

QE path metadata

The high-symmetry metadata must correspond to the exact K-path and point density used in the QE band calculation.

Spin-orbit coupling and advanced cases

Always verify whether the selected DFT settings, pseudopotentials, spin configuration, spin-orbit coupling, and symmetry treatment are appropriate for the material being studied.

Band plotting cannot correct an incorrectly prepared electronic-structure calculation.