Osman Goni Ridwan

VASP cheat sheet · Essentials

Reading VASP output

Where VASP writes each result and the one-line commands that pull it out of OUTCAR, OSZICAR and vasprun.xml, tested on real output files from VASP 5.2 to 6.3. Includes which energy to report and what every OSZICAR column means.

Checked against VASP 6.6.1 · Updated

The short version

  1. Use grep "free energy TOTEN" with two and three spaces: a plain grep TOTEN also matches every SCF step.
  2. A relaxation is done only if OUTCAR says reached required accuracy and its last SCF converged.
  3. Take the last occurrence of anything printed per step: energies, forces, stress, moments.
  4. Forces and stress belong to the free energy TOTEN (OSZICAR F=); with Gaussian smearing, report energy(sigma->0) (E0=).
  5. Error boxes, above all the last one before a crash, are reliably only in the standard output (your vasp.out); some warnings are also copied to OUTCAR. Keep the standard output.

Find a command

Type what you want to know, such as fermi, force, magnetic or converged, and jump to the command. Or open the list to see every command on this sheet.

What each file holds

FileHoldsNote
OUTCARThe full log: parameters used, symmetry, k-points, energies, forces, stress, moments, timing.Its detail is set by NWRITE.
OSZICAROne line per SCF step and one summary line per ionic step.The quickest view of progress.
standard outputThe SCF lines plus every ERROR, WARNING and ADVICE box.Redirect it: srun vasp_std > vasp.out.
CONTCARThe latest structure, in POSCAR format; after MD also velocities.Written after every ionic step.
vasprun.xmlEverything in XML: inputs, every ionic step, eigenvalues, DOS, projections.Complete only if the last line is </modeling>.
vaspout.h5HDF5 output for py4vasp (HDF5 builds only).Holds a copy of your POTCAR: do not share it.
CHGCAR / CHGCharge density; CHGCAR adds the PAW on-site data.Restart with CHGCAR only (ICHARG = 1 or 11); CHG is for plotting.
WAVECAROrbitals (binary).Restart file for ISTART = 1, which also works after the cell or ENCUT changed; the k-points and number of bands must match.
DOSCAR / PROCARTotal and projected DOS; orbital character of each band.Projections need LORBIT ≥ 10 (or RWIGS).
EIGENVALEigenvalues at each k-point.
XDATCARThe trajectory of a relaxation or MD run.
IBZKPTThe irreducible k-points and weights actually used.Explicit KPOINTS format.

Energy: which number to report

OUTCAR labelOSZICARWhat it is
free energy TOTENF=The free energy E − TS. Forces and stress are consistent with it: use it for relaxations, phonons and NEB profiles at fixed smearing.
energy(sigma->0)E0=Extrapolated to zero smearing; the number to report with Gaussian smearing (ISMEAR = 0), provided SIGMA is small.
energy without entropy—E without the TS term; rarely reported.

With the tetrahedron method (ISMEAR = −5) all three are equal. Compare energies only between runs with the same ENCUT, PREC, LREAL, smearing and POTCAR files.

Final energies
grep "free  energy   TOTEN" OUTCAR | tail -1 | awk '{print $5}'   # final TOTEN in eV (two spaces, then three)
grep "energy(sigma->0)" OUTCAR | tail -1 | awk '{print $NF}'       # final E0 in eV
awk '/F=/{for(i=1;i<NF;i++){if($i=="F=")f=$(i+1);if($i=="E0=")e=$(i+1)}} END{print f, e}' OSZICAR   # final F and E0 (relaxation or MD)
grep '<i name="e_fr_energy">' vasprun.xml | tail -1                # free energy in vasprun.xml

In VASP 5 vasprun.xml the e_0_energy and e_wo_entrp labels of each ionic step are swapped; read those from OUTCAR instead.

Did it converge?

Convergence checks
grep -c "reached required accuracy" OUTCAR               # relaxation done? 1 = it met EDIFFG
grep -c "aborting loop because EDIFF is reached" OUTCAR  # ionic steps whose SCF converged
grep "soft stop encountered" OUTCAR                      # stopped early by a STOPCAR?
tail -1 vasprun.xml                                      # is vasprun.xml complete? Last line is </modeling>
SCF steps per ionic step (relaxation runs)
awk '/^[A-Za-z]+ *:/{n++} / F= /{printf "ionic %s  SCF %d  F=%s  E0=%s\n",$1,n,$3,$5; n=0}' OSZICAR   # SCF steps, F and E0 per ionic step

An ionic step that used NELM SCF steps (60 by default) did not converge. VASP 6 also prints a warning box saying the electronic self-consistency was not achieved within NELM steps.

Forces and stress

Largest force on any atom, per ionic step (eV/A)
awk '/TOTAL-FORCE/{inb=1;max=0;getline;next}
     inb && /^ -+/{inb=0;printf "step %d  max|F| %.4f\n",++s,max;next}
     inb{f=sqrt($4^2+$5^2+$6^2); if(f>max)max=f}' OUTCAR   # largest force per ionic step

The block lists every atom, including those fixed by selective dynamics: leave those out before comparing with EDIFFG. A total drift comparable to |EDIFFG| means noisy forces.

Stress and pressure (kB)
grep "in kB" OUTCAR | tail -1             # stress tensor in kB: XX YY ZZ XY YZ ZX
grep "external pressure" OUTCAR | tail -1 # pressure, with the Pulay stress

A positive diagonal value means the cell is compressed and wants to expand; 1 kB = 0.1 GPa. With ISIF = 1 only the pressure is valid; hybrid runs compute no stress unless ISIF is set.

Fermi energy, gap, bands and k-points

Fermi energy
grep E-fermi OUTCAR | tail -1 | awk '{print $3}'   # Fermi energy in eV

Take it from the self-consistent run, not from a band-structure path. For a semiconductor the default EFERMI = LEGACY places it somewhere in the gap; EFERMI = MIDGAP (VASP 6.4 and later) puts it in the middle.

Band gap (VASP 6.4.3 and later report it in OUTCAR)
grep -i "gap" OUTCAR | tail -5   # band gap report

From VASP 6.4.3 the gap report is controlled by the BANDGAP tag. On older versions compute it from vasprun.xml with pymatgen or py4vasp (below), not from DOS edges or the Fermi energy.

Bands, electrons, k-points
grep "NBANDS=" OUTCAR | tail -1           # bands actually used (VASP may raise NBANDS)
grep NELECT OUTCAR | head -1              # number of electrons
grep "irreducible k-points" OUTCAR        # k-points after symmetry

Magnetic moments

Total and site moments
grep " F= " OSZICAR | tail -1 | grep -o "mag= *[-0-9.E+]*"   # total moment of the cell
grep "number of electron" OUTCAR | tail -1                   # electrons and total magnetization
awk '/magnetization xx/{b="";inb=1;next}
     inb&&/^tot/{inb=0;t=$NF;next}
     inb&&/^ +[0-9]+ /{b=b sprintf("ion %s  %s\n",$1,$NF)}
     END{printf "%s tot %s\n",b,t}' OUTCAR                  # moment of each ion, last block

Site moments need LORBIT ≥ 10 (LORBIT = 11 also splits them by orbital), or RWIGS. They are integrated inside spheres around the atoms, so they do not add up to the cell moment mag=. The block is printed more than once per step: take the last. Noncollinear runs add magnetization (y) and (z) blocks.

Time, memory and the parallel layout

Timing and layout
grep -E "Elapsed time|Total CPU time|Maximum memory used" OUTCAR   # run time and memory; missing = killed
grep "LOOP+" OUTCAR | awk '{print $NF}'   # wall seconds per ionic step
head -6 OUTCAR | grep -E "running|distr" # ranks, threads, KPAR groups and NCORE actually used
head -1 OUTCAR                            # VASP version that wrote the file

Warnings and errors

Find the boxes
grep -c "W    W    AA    RRRRR" vasp.out OUTCAR                            # number of WARNING boxes
grep -n -E "I REFUSE TO CONTINUE|VERY BAD NEWS|internal error" vasp.out   # fatal errors, with line numbers
grep -n "ADVICE to this user running VASP" vasp.out                       # ADVICE boxes

The errors sheet explains each message and its fix.

OSZICAR, column by column

FieldMeaning
DAV: RMM: CG :The algorithm of that SCF step (Davidson, RMM-DIIS, conjugate gradient). ALGO = Fast switches from DAV to RMM.
NSCF step number.
ECurrent free energy.
dEChange of the free energy since the last step; compared with EDIFF.
d epsChange of the band-structure energy.
ncgNumber of Hamiltonian evaluations.
rms, rms(c)Residual of the orbitals; difference between input and output density (blank in the first non-self-consistent steps).
F= E0= d E = mag=Ionic line: free energy (TOTEN), energy at zero smearing, change since the last ionic step, total magnetic moment.
T= E= EK= SP= SK=MD line: temperature, total energy including kinetic and thermostat terms, ionic kinetic energy, thermostat potential and kinetic energy.

The same in Python

pymatgen (reads vasprun.xml, OUTCAR, OSZICAR)
from pymatgen.io.vasp.outputs import Vasprun, Outcar
v = Vasprun("vasprun.xml", parse_potcar_file=False)
v.final_energy, v.converged_electronic, v.converged_ionic
v.ionic_steps[-1]["forces"], v.ionic_steps[-1]["stress"]
v.get_band_structure(efermi="smart").get_band_gap()["energy"]
o = Outcar("OUTCAR")
o.efermi, o.total_mag, o.magnetization
py4vasp (needs vaspout.h5 from an HDF5 build)
from py4vasp import Calculation
calc = Calculation.from_path(".")
calc.energy.read()        # free energy, energy without entropy, energy(sigma->0)
calc.bandgap.read()
calc.electronic_minimization.read()   # the OSZICAR data
ASE
from ase.io import read
atoms = read("OUTCAR")                  # last ionic step
atoms.get_potential_energy()            # energy(sigma->0)
traj = read("XDATCAR", index=":")       # every frame; without index only the last

Common mistakes

  • grep TOTEN | head: an SCF-step energy, not an ionic result.
  • Calling a relaxation converged from reached required accuracy alone, without checking its last SCF.
  • Reading the first magnetization block instead of the last, or expecting site moments to add up to mag=.
  • Taking the Fermi energy or the gap from a band-structure (path) run.
  • Reporting energy(sigma->0) from a Methfessel–Paxton run, or comparing energies with different SIGMA, ENCUT or POTCARs.
  • Not keeping the standard output, where VASP prints its error boxes.
  • Sharing vaspout.h5 publicly: in current versions it contains a copy of your POTCAR.

Other tags on this sheet

BANDGAP
How VASP reports the band gap in OUTCAR (VASP 6.4.3 and later).Default: COMPACT · VASP Wiki: BANDGAP

The physics behind this sheet

  • Lecture 12: Self-consistent field convergence (in preparation)
  • Lecture 19: VASP input files and convergence tests (in preparation)

Further reading

  1. VASP Wiki, “OUTCAR”. · www.vasp.at
  2. VASP Wiki, “OSZICAR” (what each column means). · www.vasp.at
  3. VASP Wiki, “Restart and output files cheat sheet” (which files LWAVE, LCHARG and LH5 write). · www.vasp.at