Electronic Structure

The Electronic structure menu groups the major electronic-property post-processing workflows available in VQkit.

It is available from:

VQkit
 -> Post-processing
 -> [3] Electronic structure

The current menu contains:

[1] Total density of states (DOS)
[2] Projected DOS (PDOS)
[3] Band structure
[4] Band gap
[5] Fermi energy
[6] Work function

The same top-level workflow supports both VASP and Quantum ESPRESSO where the required source data are available.

This page is a reference overview. Detailed procedural tutorials are provided separately for:

DOS / PDOS;
Band Structure;
Work Function.

General workflow

A practical sequence is:

Complete the underlying VASP or Quantum ESPRESSO calculation.
Run General calculation analysis and confirm that the calculation is complete.
Open Electronic structure.
Choose the desired property.
Confirm that the required source files are present.
Inspect both the numerical output and generated plots.

DOS - VASP

The VASP DOS workflow reads:

DOSCAR

VQkit detects whether the DOS is spin-polarized and extracts:

energy grid;
DOS values;
Fermi energy;
energy range;
number of DOS points.

The visual guide shows the VASP DOS workflow.

Energy reference

When the Fermi energy is available, VQkit reports and exports:

\[E - E_F\]

so that:

E - E_F = 0

corresponds to the Fermi level.

For a non-spin-polarized system, the plot contains one DOS curve.

For a spin-polarized system, VQkit plots:

spin-up DOS as positive;
spin-down DOS as negative.

The negative spin-down values are a plotting convention only.

The underlying exported data retain both the physical positive DOS and the negative plotting column.

VASP DOS outputs

VQkit writes:

VQkit_DOS.dat
VQkit_DOS.png

The data file contains either:

Energy_eV
E_minus_EF_eV
DOS

or, for spin-polarized calculations:

Energy_eV
E_minus_EF_eV
DOS_up
DOS_down
DOS_down_plot

VQkit also reports the DOS at the energy-grid point nearest to the Fermi energy for VASP.

This value can be useful as a quick indicator of metallic character, but it should not replace a full electronic-structure interpretation.

DOS - Quantum ESPRESSO

For QE, VQkit reads numerical DOS data generated by the QE DOS workflow.

Typical source files include:

dos.dat
*.dos
*dos*.dat
*DOS*.dat

VQkit excludes unrelated input/log files and parses common QE DOS layouts.

Supported layouts include:

Non-spin form:

Energy   DOS   Integrated_DOS

Spin-polarized form:

Energy   DOS_up   DOS_down   Integrated_DOS

The Fermi energy is obtained from nearby QE calculation metadata/output when available.

The same standard VQkit outputs are written:

VQkit_DOS.dat
VQkit_DOS.png

If the Fermi energy cannot be identified, VQkit retains the absolute energy axis instead of shifting the data incorrectly.

Projected DOS (PDOS)

The PDOS workflow resolves electronic states by atom and orbital.

VQkit supports both:

VASP atom-projected DOS from DOSCAR;
Quantum ESPRESSO projected DOS generated by projwfc.x.

Atom selection

For VASP, VQkit reads species information from:

POSCAR
CONTCAR

when possible.

It displays species ranges such as:

C  : atoms 1-12
O  : atoms 13-16
Fe : atom 17

An atom can be selected using either:

global atom number, for example 17;
species-local notation, for example C7.

This makes atom selection easier in large systems.

Orbital groups

Depending on the available projected data, VQkit can resolve:

s
p
d
f

and, when lm-resolved information is present, individual components.

Typical p channels include:

px
py
pz

Typical d channels include:

dxy
dyz
dzx
dz2
dx2-y2

The exact available channels depend on the source data.

VASP users normally need projected DOS output such as that produced with an appropriate LORBIT setting.

If the source contains only total p, d, or f contributions, VQkit does not invent missing component resolution.

Spin-resolved PDOS

For spin-polarized calculations, each selected orbital can contain:

orbital_up
orbital_down
orbital_down_plot

As in the total DOS workflow, the negative down-spin values are used only for visualization.

PDOS output filenames

The output filename identifies:

global atom index;
species;
selected orbital/group.

A typical output stem is:

VQkit_PDOS_atom017_Fe_d

Outputs include:

VQkit_PDOS_atom017_Fe_d.dat
VQkit_PDOS_atom017_Fe_d.png

If a file with the same name already exists, VQkit creates a numbered alternative rather than silently overwriting it.

For the full procedural workflow, see:

Tutorials -> DOS / PDOS

Band structure - VASP

The VASP band-structure workflow primarily reads:

EIGENVAL

The Fermi energy is obtained from:

OUTCAR

with DOSCAR as a fallback.

The visual guide shows VQkit reading the VASP band data and generating a band plot.

High-symmetry labels

VQkit attempts to identify high-symmetry path information from:

KPOINTS
KPOINTS_band

when line-mode labels are available.

It can also use:

KPATH_INTERPOLATED.dat

generated by VQkit pre-processing.

When suitable path metadata are unavailable, VQkit may use structural symmetry information to reconstruct useful path labels.

Band structure - Quantum ESPRESSO

For QE, VQkit searches for band data files such as:

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

VQkit supports several numerical layouts, including:

blank-line-separated band blocks;
k-coordinate resets;
wide band tables.

The visual guide shows the corresponding QE band-structure workflow.

VQkit band structure for Quantum ESPRESSO

QE high-symmetry information can be obtained from:

KPATH_INTERPOLATED.dat

or suitable K_POINTS {crystal_b} input data.

Band outputs

The current band workflow can generate:

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

The main data file contains plot-ready band energies.

The high-symmetry file reports band energies associated with recognized high-symmetry positions.

Spin-polarized bands

VQkit detects spin-resolved band data when available.

Spin-up and spin-down bands are handled separately in the internal band representation and can be plotted accordingly.

The detailed band-structure workflow, including K-path generation and interpretation, is documented under:

Tutorials -> Band Structure

Band-gap analysis

Choose:

[4] Band gap

VQkit uses the parsed band energies together with a Fermi-energy reference.

Required data

For VASP, the current workflow requires:

EIGENVAL

plus a Fermi-energy source:

OUTCAR
DOSCAR

For Quantum ESPRESSO, it requires band-energy data such as:

bands.dat.gnu

together with a pw.x output containing an electronic reference.

Metallic / gapless classification

VQkit checks whether any band crosses the Fermi level.

If so:

Band gap      : 0.000000 eV
Classification: Metallic / gapless

is reported.

Semiconductor / insulator analysis

If no band crosses the Fermi level, VQkit identifies:

valence-band maximum (VBM);
conduction-band minimum (CBM);
fundamental band gap;
k-point location of VBM;
k-point location of CBM.

The gap is:

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

Direct gap

The gap is classified as direct when the VBM and CBM occur at the same k-point and, for spin-resolved data, in the same spin channel.

Otherwise it is classified as indirect.

Representative output

Example:

BAND GAP
----------------------------------------------------

Code          : VASP
Band source   : EIGENVAL
Fermi energy  : 2.314527 eV
Band gap      : 1.842100 eV
Gap type      : Indirect
VBM           : -0.214300 eV at GAMMA
CBM           :  1.627800 eV at K

The VBM and CBM energies are displayed relative to the Fermi energy.

Band-gap output

VQkit writes:

VQkit_BAND_GAP.dat

The file contains:

Band_gap_eV
Classification

and, for non-metallic systems:

VBM_EminusEF_eV
CBM_EminusEF_eV
VBM_location
CBM_location

Band-gap cautions

The numerical gap is only as reliable as the underlying electronic-structure calculation.

Important considerations include:

k-point path coverage;
spin polarization;
spin-orbit coupling;
exchange-correlation functional;
Hubbard U;
hybrid functional treatment;
quasiparticle corrections.

A DFT Kohn-Sham gap should not automatically be interpreted as the experimental optical gap.

Fermi energy

Choose:

[5] Fermi energy

VQkit reports the electronic Fermi reference without running a full DOS or band analysis.

VASP

VQkit first searches:

OUTCAR

for:

E-fermi :

If unavailable, it tries:

DOSCAR

Quantum ESPRESSO

For QE, VQkit uses the QE status/output parser.

Recognized forms include output statements such as:

the Fermi energy is ... eV

and occupied-level reports when those are the available electronic references.

Representative output

FERMI ENERGY
----------------------------------------------

Code         : VASP
Fermi energy : 4.527341 eV
Source       : /path/to/OUTCAR

If VQkit cannot locate a suitable value, it reports a warning rather than inventing an energy reference.

Work function

Choose:

[6] Work function

The work function is evaluated as:

\[\Phi = V_{\mathrm{vacuum}} - E_F\]

This analysis is mainly intended for slabs and surfaces.

VASP work function

VASP requires:

LOCPOT

The Fermi energy is read from:

OUTCAR

with DOSCAR as a fallback.

VQkit asks for the slab-normal axis:

Slab-normal axis [z]:

and supports:

x
y
z

The electrostatic potential is planar averaged along the chosen axis.

Vacuum windows

By default, VQkit evaluates approximately the outer:

10%

of the potential profile on each side.

It calculates:

lower-side vacuum level;
upper-side vacuum level;
standard deviation in each vacuum window.

The side-specific work functions are:

\[\Phi_{\mathrm{lower}} = V_{\mathrm{vac,lower}} - E_F\]

and:

\[\Phi_{\mathrm{upper}} = V_{\mathrm{vac,upper}} - E_F\]

VQkit also reports their mean.

Vacuum-flatness warning

If either vacuum-window standard deviation exceeds approximately:

0.10 eV

VQkit prints a warning.

Possible causes include:

insufficient vacuum thickness;
strong residual field;
unsuitable slab-normal axis;
missing/incorrect dipole correction;
asymmetric slab electrostatics.

Quantum ESPRESSO work function

For QE, VQkit searches for a planar-average potential profile such as:

VQkit_QE_PLANAR_POTENTIAL.dat
average.dat
avg.dat
planar_average.dat
planar_potential.dat
potential.avg

If no profile is available, VQkit prepares the required QE post-processing inputs.

Generated files can include:

VQkit_QE_WORKFUNCTION_PP.in
VQkit_QE_WORKFUNCTION_AVERAGE.in
VQkit_QE_WORKFUNCTION_STEPS.txt

The workflow uses:

pp.x
average.x

The pp.x input uses:

plot_num = 11

to obtain the required electrostatic potential information.

When the required QE executable tools and <prefix>.save data are locally accessible, VQkit can attempt this post-processing automatically.

Otherwise, it provides the generated inputs and instructions for execution on the HPC system.

QE potential units

If the QE planar-potential source is identified as Rydberg, VQkit converts it to eV before calculating the work function.

Work-function outputs

VQkit writes:

VQkit_WORK_FUNCTION.dat
VQkit_WORK_FUNCTION.png
VQkit_WORK_FUNCTION.pdf

The numerical output contains:

Fermi energy;
lower vacuum level;
upper vacuum level;
planar potential profile.

The report includes:

Work function, lower
Work function, upper
Mean of two sides
Vacuum-window standard deviations

The visual guide includes a work-function example in the electronic-structure section.

For the full procedural workflow, see:

Tutorials -> Work Function

Relationship between the six menu items

The electronic-structure tools are related but answer different questions.

DOS

Answers:

How many electronic states are available at each energy?
Is there finite DOS near the Fermi level?
Is the calculation spin-polarized?

PDOS

Answers:

Which atom contributes to the states?
Which orbital contributes?
Which spin channel contributes?

Band structure

Answers:

How do eigenvalues vary along reciprocal-space paths?
Where do bands disperse?
Where are high-symmetry features located?

Band gap

Answers:

Is the system metallic/gapless or gapped?
What is the fundamental gap?
Is the gap direct or indirect?
Where are VBM and CBM?

Fermi energy

Answers:

What electronic energy reference did the calculation report?

Work function

Answers:

What energy is required to move an electron from the Fermi level to vacuum?
Are the two surfaces of a slab electrostatically equivalent?

Recommended analysis sequence

For a typical bulk electronic-structure calculation:

Run General calculation analysis.
Confirm the calculation is complete.
Analyze DOS.
Analyze PDOS where orbital/atomic contributions are required.
Analyze band structure.
Run band-gap analysis.
Record the Fermi level.

For a surface/slab calculation:

Confirm the static calculation is complete.
Analyze DOS/PDOS if needed.
Confirm the Fermi energy.
Analyze the planar electrostatic potential.
Calculate the work function.
Inspect vacuum flatness.
Compare lower and upper surface values when relevant.

Common cautions

Fermi-energy alignment

DOS, PDOS, and band plots are usually most interpretable when referenced to the same Fermi level.

Do not combine datasets from unrelated calculations without verifying their energy reference.

Spin polarization

For magnetic systems, inspect both spin channels.

A total DOS alone may hide spin-selective electronic behavior.

DOS versus band gap

A small DOS near the Fermi level does not by itself provide a rigorous band gap.

Use the band-gap workflow and inspect the band structure.

Band path

A band plot is meaningful only if the k-path corresponds to the actual structure/cell being used.

If VQkit generated a standardized primitive path, use the matching primitive structure.

Work function

A work-function value is reliable only when the electrostatic potential reaches a sufficiently flat vacuum plateau.

Asymmetric slabs may legitimately give different work functions on the two sides.

Generated files summary

Depending on the selected workflow, VQkit can generate:

DOS

VQkit_DOS.dat
VQkit_DOS.png

PDOS

VQkit_PDOS_atomNNN_species_selection.dat
VQkit_PDOS_atomNNN_species_selection.png

Band structure

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

Band gap

VQkit_BAND_GAP.dat

Work function

VQkit_WORK_FUNCTION.dat
VQkit_WORK_FUNCTION.png
VQkit_WORK_FUNCTION.pdf

VQkit provides these electronic-structure tools through one common post-processing interface while retaining the code-specific source data required by VASP and Quantum ESPRESSO.