DOS and PDOS

This tutorial explains how to analyze total density of states (DOS) and projected density of states (PDOS) with VQkit for both VASP and Quantum ESPRESSO.

VQkit supports:

total DOS;
spin-resolved DOS;
atom-resolved PDOS;
orbital-resolved PDOS;
individual orbital components where available;
Fermi-level shifting;
export of plot-ready numerical data;
automatic DOS/PDOS plotting.

DOS workflow

Purpose

The DOS workflow reads the total electronic density of states from a completed VASP or Quantum ESPRESSO calculation.

VASP input for DOS analysis

For VASP, VQkit expects:

DOSCAR

The working directory may also contain:

OUTCAR
POSCAR
CONTCAR

but DOSCAR is the primary DOS source.

Quantum ESPRESSO input for DOS analysis

For Quantum ESPRESSO, VQkit looks for numerical output from dos.x.

Typical filenames include:

dos.dat
*.dos
*dos*.dat
*dos*.txt

Files containing pdos in the filename are excluded from total-DOS detection.

Running DOS analysis

From the Electronic Structure menu choose:

VQkit automatically detects the calculation type and searches for the appropriate source file.

For VASP:

DOSCAR

For Quantum ESPRESSO:

dos.x numerical output

DOS report

Before exporting the data, VQkit reports information such as:

Code
Source
DOS points
Energy range
Fermi energy
Spin polarized

For VASP, VQkit also reports the DOS at the grid point nearest the Fermi level.

Fermi-level reference

When the Fermi energy is available, VQkit uses:

\[E' = E - E_F\]

so that:

E_F = 0 eV

For Quantum ESPRESSO, VQkit first checks whether the Fermi energy is written in the DOS file itself.

If not, it attempts to obtain the Fermi level from the nearby QE calculation output.

If no Fermi energy is found, VQkit retains the absolute energy scale.

Spin-polarized DOS

When spin-polarized DOS data are detected, VQkit plots:

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

This gives the familiar mirrored spin-DOS representation.

The exported data retain both the physical positive spin-down values and a negative plotting column.

DOS outputs

VQkit writes:

VQkit_DOS.dat

and, when Matplotlib is available:

VQkit_DOS.png

Non-spin-polarized export

The data file contains columns equivalent to:

Energy_eV
E_minus_EF_eV
DOS

Spin-polarized export

For spin-polarized calculations the exported columns include:

Energy_eV
E_minus_EF_eV
DOS_up
DOS_down
DOS_down_plot

where:

DOS_down_plot = -DOS_down

The negative column is intended only for conventional plotting.

Example: VASP DOS

Assume the directory contains:

DOSCAR
OUTCAR
POSCAR

Step 1 — Start VQkit

Start VQkit in the calculation directory.

Step 2 — Open Post-processing

Enter:

Step 3 — Open Electronic structure

Enter:

Step 4 — Run DOS analysis

Enter:

VQkit reads DOSCAR.

Step 5 — Inspect the report

Confirm:

the number of DOS points;
the energy range;
the Fermi energy;
whether spin polarization was detected.

Step 6 — Inspect outputs

Check:

VQkit_DOS.dat
VQkit_DOS.png

If a Fermi level was detected, the x-axis is:

Energy - E_F (eV)

Quantum ESPRESSO DOS example

Assume a QE DOS directory contains:

dos.dat
scf.out

or a nearby SCF/NSCF directory contains the Fermi-level information.

Run:

Post-processing
Electronic structure
DOS

VQkit detects dos.dat, parses the numerical columns, determines whether the data are spin-polarized, and shifts the energy scale when a Fermi energy is available.

PDOS workflow

Purpose

The PDOS workflow provides atom- and orbital-resolved electronic information.

VQkit allows you to select:

a specific atom;
an orbital group;
an individual orbital component where resolved data are available.

VASP requirements for PDOS

For VASP, atom-projected DOS must be present in:

DOSCAR

VQkit recommends generating projected DOS with:

LORBIT = 11

This provides orbital-component information such as:

px
py
pz
individual d components

when supported by the calculation and DOSCAR layout.

For element labels, keep one of:

POSCAR
CONTCAR

in the same directory.

Quantum ESPRESSO requirements for PDOS

For QE, first run:

projwfc.x

Keep the generated projected-DOS files in the working directory.

Typical filenames follow the QE pattern:

prefix.pdos_atm#1(Element)_wfc#1(s)
prefix.pdos_atm#1(Element)_wfc#2(p)

VQkit identifies:

atom number;
species;
wavefunction index;
orbital type

directly from the filenames.

QE Fermi energy

For PDOS, VQkit requires a Fermi energy.

It searches:

the current directory;
the parent directory;
nearby scf directories;
nearby nscf directories;
nearby dos directories;
nearby pdos directories.

If the Fermi energy cannot be found, VQkit stops and asks you to keep the relevant SCF/NSCF output nearby.

Running PDOS analysis

From the Electronic Structure menu choose:

VQkit detects whether supported projected-DOS data come from VASP or Quantum ESPRESSO.

Atom selection

VQkit first asks which atom you want to analyze.

For VASP, when POSCAR or CONTCAR is available, VQkit displays species ranges.

Example:

C  : atoms 1-24
O  : atoms 25-28
Li : atoms 29-32

You may enter a global atom number:

or a species-local label:

O3

Both refer to a specific atom.

For Quantum ESPRESSO, atom and species information are obtained from the projwfc.x filenames.

Orbital-group selection

After selecting an atom, VQkit displays the available orbital groups.

A typical menu is:

[1] All available valence-orbital channels
[2] s orbital
[3] p orbitals
[4] d orbitals
[5] f orbitals

Only groups actually present in the source data are shown.

p-orbital components

When the source is lm resolved, VQkit can provide individual p components.

For VASP these commonly include:

px
py
pz

For Quantum ESPRESSO, projwfc.x component ordering is interpreted by VQkit and exposed with labels such as:

pz
px
py

The displayed menu lets you select:

all p orbitals;
one individual p component.

d-orbital components

When resolved data are available, VQkit supports individual d components such as:

dxy
dyz
dzx
dz2
dx2-y2

For QE, VQkit maps the standard real spherical-harmonic projwfc.x ordering to these orbital labels.

If the DOS source contains only total d projection and not individual components, VQkit reports that the data are not lm resolved.

PDOS report

After atom and orbital selection, VQkit reports:

Selected atom
Source
Fermi energy
Spin polarized
lm resolved
Selected orbitals

Example:

Selected atom     : Atom 12 = Co1
Fermi energy      : 5.432100 eV
Spin polarized    : Yes
lm resolved       : Yes
Selected orbitals : dxy, dyz, dzx, dz2, dx2-y2

PDOS output naming

VQkit creates filenames containing the selected atom, species, and orbital selection.

A typical output may look like:

VQkit_PDOS_atom012_Co_d.dat
VQkit_PDOS_atom012_Co_d.png

If the same output name already exists, VQkit creates a unique numbered file rather than overwriting it.

PDOS data export

Each PDOS file contains:

absolute energy;
E - E_F;
selected orbital contributions.

For non-spin-polarized data, multiple selected orbitals also include a summed selected-total column.

For spin-polarized data, VQkit exports:

spin-up component;
spin-down component;
negative spin-down plotting component.

When several orbitals are selected, VQkit also exports total selected spin-up and spin-down contributions.

Spin-polarized PDOS plot

For spin-polarized PDOS:

spin-up is plotted positive;
spin-down is plotted negative.

The Fermi energy is shown at:

E - E_F = 0 eV

Example: VASP atom-resolved d-PDOS

Assume the VASP calculation directory contains:

DOSCAR
POSCAR
OUTCAR

and the DOS calculation was performed with:

LORBIT = 11

Step 1 — Open PDOS

Navigate to:

Post-processing
Electronic structure
PDOS

Step 2 — Select an atom

Suppose VQkit displays:

Fe : atoms 1-4
O  : atoms 5-12

To select the second Fe atom, enter:

Fe2

or the corresponding global atom number.

Step 3 — Select d orbitals

Choose the d orbital group.

If the DOSCAR is lm resolved, VQkit offers individual d components.

Choose either:

All d orbitals

or one component such as:

dz2

Step 4 — Inspect outputs

VQkit writes a plot-ready .dat file and a PNG plot.

For an all-d selection, the filename may look like:

VQkit_PDOS_atom002_Fe_d.dat
VQkit_PDOS_atom002_Fe_d.png

Example: Quantum ESPRESSO projected DOS

Assume projwfc.x produced files such as:

prefix.pdos_atm#1(Co)_wfc#1(s)
prefix.pdos_atm#1(Co)_wfc#2(p)
prefix.pdos_atm#1(Co)_wfc#3(d)

and a nearby SCF/NSCF output contains the Fermi energy.

Step 1 — Start VQkit in the PDOS directory

Open:

Post-processing
Electronic structure
PDOS

Step 2 — Select the atom

VQkit identifies the atoms and species from the projwfc.x filenames.

Choose the required atom.

Step 3 — Select the orbital group

Choose:

s
p
d
f

depending on the available projected states.

Step 4 — Select an individual component if needed

For example, for a d-state analysis choose:

dz2

or:

All d orbitals

Step 5 — Inspect the Fermi reference

VQkit reports the detected Fermi energy.

All plotted energies are referenced to:

E - E_F

Step 6 — Inspect the exported file and plot

Use the generated VQkit_PDOS_*.dat and VQkit_PDOS_*.png files.

Orbital interpretation

s states

The s contribution describes states with s-like angular character around the selected atom.

p states

The p contribution may be resolved into:

px
py
pz

where the orientation refers to the coordinate system used in the electronic-structure calculation.

d states

The d contribution may include:

dxy
dyz
dzx
dz2
dx2-y2

These components are especially useful for:

transition-metal bonding analysis;
crystal-field interpretation;
catalytic descriptors;
orbital hybridization analysis.

Common problems

VASP PDOS not found

If VQkit reports:

Atom-projected DOS was not found in DOSCAR.

re-run the VASP DOS calculation with projected-DOS output enabled.

VQkit recommends:

LORBIT = 11

No individual p/d components

If VQkit reports that the DOSCAR is not lm resolved, the source contains only orbital totals.

For VASP, use a suitable LORBIT setting to generate orbital-component information.

QE PDOS files not found

If VQkit reports no QE projected-DOS source, first run:

projwfc.x

and keep the generated:

*pdos_atm#*

files in the working directory.

QE Fermi energy not found

Keep the relevant pw.x SCF or NSCF output in the same directory or a nearby scf / nscf directory.

Inconsistent QE energy grids

All projected files for the selected atom must use the same energy grid.

If they differ, VQkit stops rather than combining inconsistent PDOS data.

Matplotlib unavailable

VQkit can still export numerical DOS/PDOS data even when plotting dependencies are unavailable.

The exported .dat files can be plotted using:

Origin;
gnuplot;
Python;
other scientific plotting tools.

Recommended DOS/PDOS workflow

For reliable electronic-structure analysis:

Converge the structure and SCF calculation.
Use a sufficiently dense k-point mesh for DOS.
Use an adequate energy grid and smearing/broadening.
Generate projected DOS when orbital analysis is needed.
Keep the SCF/NSCF output so the Fermi energy can be identified.
Run VQkit DOS analysis.
Run VQkit PDOS analysis for selected atoms and orbitals.
Verify the Fermi reference.
Compare DOS and PDOS using consistent plotting scales when comparing different systems.

Scientific cautions

DOS broadening

DOS peak widths depend on the underlying sampling and broadening method.

Do not interpret broadening parameters as intrinsic physical linewidths unless the calculation method specifically supports that interpretation.

PDOS is projection dependent

Projected DOS depends on the projection scheme used by VASP or Quantum ESPRESSO.

Orbital populations should therefore be interpreted as projected electronic character rather than uniquely defined atomic observables.

Coordinate dependence

Individual components such as px, py, dxy and dz2 depend on the coordinate system.

When comparing orbital-resolved PDOS across different structures, make sure the coordinate orientation is consistent.

Fermi-level alignment

Using E - E_F is appropriate for many single-system plots, but direct comparison of different materials may require a more appropriate common energy reference.

Spin sign convention

The negative spin-down curve in VQkit plots is a visualization convention.

The physical spin-down DOS itself is not negative.

DOS and PDOS

Open the electronic-structure menu

DOS workflow

Purpose

VASP input for DOS analysis

Quantum ESPRESSO input for DOS analysis

Running DOS analysis

DOS report

Fermi-level reference

Spin-polarized DOS

DOS outputs

Non-spin-polarized export

Spin-polarized export

Example: VASP DOS

Step 1 — Start VQkit

Step 2 — Open Post-processing

Step 3 — Open Electronic structure

Step 4 — Run DOS analysis

Step 5 — Inspect the report

Step 6 — Inspect outputs

Quantum ESPRESSO DOS example

PDOS workflow

Purpose

VASP requirements for PDOS

Quantum ESPRESSO requirements for PDOS

QE Fermi energy

Running PDOS analysis

Atom selection

Orbital-group selection

p-orbital components

d-orbital components

PDOS report

PDOS output naming

PDOS data export

Spin-polarized PDOS plot

Example: VASP atom-resolved d-PDOS

Step 1 — Open PDOS

Step 2 — Select an atom

Step 3 — Select d orbitals

Step 4 — Inspect outputs

Example: Quantum ESPRESSO projected DOS

Step 1 — Start VQkit in the PDOS directory

Step 2 — Select the atom

Step 3 — Select the orbital group

Step 4 — Select an individual component if needed

Step 5 — Inspect the Fermi reference

Step 6 — Inspect the exported file and plot

Orbital interpretation

s states

p states

d states

Common problems

VASP PDOS not found

No individual p/d components

QE PDOS files not found

QE Fermi energy not found

Inconsistent QE energy grids

Matplotlib unavailable

Recommended DOS/PDOS workflow

Scientific cautions

DOS broadening

PDOS is projection dependent

Coordinate dependence

Fermi-level alignment

Spin sign convention