Orbital Occupancy Analysis (v1.2)

Overview

VQkit v1.2 adds [7] Orbital occupancy under Post-processing > Electronic Structure. This feature integrates atom- and orbital-projected density of states (PDOS) over occupied energies for VASP and Quantum ESPRESSO calculations.

The results are projected orbital occupancies. They depend on the projector conventions, numerical settings and PDOS completeness of the underlying DFT calculation, and should not be interpreted as uniquely defined atomic charges.

Menu access

VQkit > Post-processing > Electronic Structure

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

Enter your choice: 7

Select VASP or Quantum ESPRESSO when prompted. VQkit calculates all available orbitals for all atoms and writes the occupancy results to the current working directory.

Supported orbital columns

• s

• px, py, pz, ptot

• dz2, dx2-y2, dxy, dyz, dxz, dtot

The total p-orbital occupancy, ptot, is the sum of px, py and pz. The total d-orbital occupancy, dtot, is the sum of the five listed d orbitals. Totals are reported only when all the required components are available.

For spin-polarized calculations, VQkit can also report corresponding _up and _down columns. An unavailable orbital is marked NA, rather than zero.

Calculation method

The Fermi-aligned energy is

\[\varepsilon = E - E_F\]

and the orbital-projected occupancy is calculated by numerical integration of the projected DOS up to the Fermi level:

\[n_{i,\alpha}^{\sigma} = \int_{\varepsilon_{\min}}^{0} D_{i,\alpha}^{\sigma}(\varepsilon)\,d\varepsilon.\]

Here, i identifies an atom, alpha an orbital, and sigma a spin channel when present. VQkit uses trapezoidal integration, interpolating at the integration cutoff. The lower integration bound is the start of the available PDOS energy grid, not literal minus infinity.

VASP workflow

1. Place the original DOSCAR in the working directory.

2. VQkit reads the Fermi energy from DOSCAR.

3. Original DOSCAR energies are shifted once by subtracting that Fermi energy.

4. PDOS values are integrated up to the aligned Fermi level at 0 eV.

VQkit may use POSCAR or CONTCAR to identify species. If species information cannot be read, the occupancy rows can contain unknown element labels.

Important

Do not shift an already Fermi-referenced exported PDOS file again. The v1.2 menu workflow reads the original VASP DOSCAR rather than an externally shifted plotting file.

Quantum ESPRESSO workflow

1. Place the relevant projwfc.x atom-resolved PDOS files in the working directory.

2. Provide an scf.out containing the Fermi energy of the corresponding calculation (or enter a different SCF filename when prompted).

3. VQkit reads the Fermi energy, shifts compatible PDOS energies, and integrates up to 0 eV.

Warning

Check that scf.out and the PDOS files use a consistent energy reference. In some workflows, an NSCF calculation or the PDOS generator may use a different Fermi reference. The menu does not reliably infer whether an arbitrary imported PDOS file has already been shifted. Where no Fermi energy is reported, the current menu workflow stops instead of guessing a value.

Output files

orbital_occupancy.csv

One row per atom, with columns for atom index, element, all supported orbital occupancies, and spin-specific columns when available.

orbital_occupancy_summary.txt

DFT code, Fermi energy, energy-reference source, integration convention, and notes about projection dependence.

Example table (illustrative only)

Example atom-resolved projected occupancies (electrons)

atom	element	s	px	py	pz	ptot	dtot
1	C	1.050	0.920	0.940	1.030	2.890	NA
2	C	1.040	0.930	0.950	1.075	2.955	NA

Note

These values demonstrate the output layout; they are not calculated results or reference data.

Verification and limitations

In a checked 49-atom VASP example, raw DOSCAR yielded E_F = -4.10363265 eV. Its once-aligned atom-49 energy grid matched a previously exported, already-aligned PDOS file within approximately 2.65e-6 eV (rounding difference).

This establishes energy-axis consistency for that example, not complete scientific validation of every atom, spin channel, orbital projection, or QE workflow. Verify numerical occupancies against reference calculations before publication.