Vasprun.xml

The vasprun.xml file contains output from a calculation in XML format. It is written along with OUTCAR **and contains all of the same physical output - i don't think that that's true**, but in a more structured, hierarchical, tree-like form that is easy to process programmetically. A third option for output is the vaspout.h5 format.

It records the complete set of input parameters, the crystal structure, and all computed quantities for every ionic step of the calculation. - check if this is correct

In addition to OUTCAR, vasprun.xml is written automatically for every VASP run. All physical output that appears in OUTCAR is also present here, but in a structured, hierarchical XML form that is straightforward to process programmatically.

File format

The root element is <modeling>. The file uses four repeating XML primitives throughout:

• value — a named scalar (real, integer, logical, or string).
• <v name="...">x y z</v> — a named row vector.
• <varray name="..."> — a named array of vectors, each on a <v> line.
• <array> — a labelled multi-field table with named dimensions; rows are stored as <r> elements inside <set> blocks.

The overall layout of vasprun.xml is:

<modeling>
  <generator>   ...  </generator>
  <incar>       ...  </incar>
  <primitive_cell> ... </primitive_cell>
  <kpoints>     ...  </kpoints>
  <parameters>  ...  </parameters>
  <atominfo>    ...  </atominfo>
  <structure name="initialpos"> ... </structure>

  <structure> ... </structure>
  <varray name="forces"> ... </varray>
  <varray name="stress"> ... </varray>
  <energy> ... </energy>
   ... 
  ...

  <calculation> ... </calculation>

  <structure name="finalpos"> ... </structure>
</modeling>

Sections

Generator

Contains the VASP version, build details, and the date and time of the run.

 <generator>
   <i name="program"    type="string">vasp </i>
   <i name="version"    type="string">6.5.0  </i>
   <i name="subversion" type="string">29Jan2024 (build Feb 14 2024) complex parallel</i>
   <i name="platform"   type="string">LinuxGNU </i>
   <i name="date"       type="string">2024 01 01 </i>
   <i name="time"       type="string">12:00:00 </i>
 </generator>

INCAR

Contains only the tags explicitly set in the INCAR file, without defaults. This is a compact record of the user-specified settings for the run.

 <incar>
   <i type="string" name="SYSTEM">diamond Si</i>
   <i type="string" name="ALGO">Normal</i>
   <i name="ENCUT">    500.00000000</i>
   <i type="int" name="ISMEAR">     0</i>
   <i name="SIGMA">      0.05000000</i>
 </incar>

Primitive cell

Contains the structure and lattice of the primitive unit cell, along with the mapping of primitive-cell ion indices to the full simulation-cell ion indices.

 <primitive_cell>
   <structure name="primitive_cell">
     <crystal>
       <varray name="basis">            <!-- lattice vectors in A -->
         <v>  1.92  1.92  0.00 </v>
         <v>  0.00  1.92  1.92 </v>
         <v>  1.92  0.00  1.92 </v>
       </varray>
       <i name="volume">     28.35 </i>  <!-- volume in A^3 -->
       <varray name="rec_basis">        <!-- reciprocal lattice vectors in A^-1 -->
         <v>  0.26  0.26 -0.26 </v>
         <v> -0.26  0.26  0.26 </v>
         <v>  0.26 -0.26  0.26 </v>
       </varray>
     </crystal>
     <varray name="positions">          <!-- fractional (direct) coordinates -->
       <v> 0.00  0.00  0.00 </v>
       <v> 0.25  0.25  0.25 </v>
     </varray>
   </structure>
   <varray name="primitive_index">      <!-- index of each primitive ion in the full cell -->
     <v type="int"> 1 </v>
     <v type="int"> 2 </v>
   </varray>
 </primitive_cell>

k points

Specifies the k-point sampling of the Brillouin zone, mirroring the KPOINTS file.

 <kpoints>
   <generation param="Gamma">             <!-- generation scheme: Gamma, Monkhorst-Pack, or Explicit -->
     <v type="int" name="divisions"> 4 4 4 </v>
     <v name="usershift"> 0.0  0.0  0.0 </v>
     <v name="genvec1">   0.25 0.00 0.00 </v>
     <v name="genvec2">   0.00 0.25 0.00 </v>
     <v name="genvec3">   0.00 0.00 0.25 </v>
     <v name="shift">     0.00 0.00 0.00 </v>
   </generation>
   <varray name="kpointlist">             <!-- '''k'''-point coordinates in reciprocal space -->
     <v>  0.000  0.000  0.000 </v>
     <v>  0.250  0.000  0.000 </v>
     ...
   </varray>
   <varray name="weights">               <!-- integration weights, normalized to sum to 1 -->
     <v> 0.00463 </v>
     <v> 0.03704 </v>
     ...
   </varray>
 </kpoints>

Parameters

Contains a complete record of all effective INCAR parameters, including those not set explicitly (with their default values). The block is organized into named <separator> subsections corresponding to groups of related tags, for example:

• general
• electronic (with sub-separators: smearing, projectors, startup, spin, exchange-correlation, convergence, mixer, dipolcorrection)
• grids
• ionic and ionic md
• symmetry
• dos
• writing
• performance
• miscellaneous
• orbital magnetization
• response functions (GW/BSE calculations)
• vdW DFT

There are several other groups that we have not included here. The full documentation for each tag is found on its individual tag page.

Atom info

Contains the atomic species and per-ion type information.

 <atominfo>
   <atoms> 2 </atoms>               <!-- total number of ions -->
   <types> 1 </types>               <!-- number of distinct species -->
   <array name="atoms">             <!-- per-ion element label and type index -->
     <dimension dim="1">ion</dimension>
     <field type="string">element</field>
     <field type="int">atomtype</field>
     <set>
       <rc><c>Si </c><c>   1</c></rc>
       <rc><c>Si </c><c>   1</c></rc>
     </set>
   </array>
   <array name="atomtypes">         <!-- per-species data -->
     <dimension dim="1">type</dimension>
     <field type="int">atomspertype</field>
     <field type="string">element</field>
     <field>mass</field>            <!-- atomic mass in u -->
     <field>valence</field>         <!-- number of valence electrons -->
     <field type="string">pseudopotential</field>   <!-- PAW potential label -->
     <set>
       <rc><c>   2</c><c>Si </c><c>     28.08500000</c><c>      4.00000000</c><c>PAW_PBE Si 05Jan2001</c></rc>
     </set>
   </array>
 </atominfo>

Initial structure

The ionic positions at the start of the run, read from POSCAR. For molecular-dynamics runs, this block also contains the initial ionic velocities.

 <structure name="initialpos">
   <crystal>
     <varray name="basis">            <!-- lattice vectors in A -->
       <v>  5.43  0.00  0.00 </v>
       <v>  0.00  5.43  0.00 </v>
       <v>  0.00  0.00  5.43 </v>
     </varray>
     <i name="volume">   160.10 </i>  <!-- cell volume in A^3 -->
     <varray name="rec_basis">
       <v>  0.184  0.000  0.000 </v>
       <v>  0.000  0.184  0.000 </v>
       <v>  0.000  0.000  0.184 </v>
     </varray>
   </crystal>
   <varray name="positions">          <!-- fractional (direct) coordinates -->
     <v>  0.000  0.000  0.000 </v>
     <v>  0.250  0.250  0.250 </v>
   </varray>
   <!-- MD only: -->
   <varray name="velocities">         <!-- ionic velocities in A/fs -->
     <v>  0.0005 -0.0004  0.0002 </v>
     <v> -0.0009  0.0004  0.0005 </v>
   </varray>
 </structure>

Ionic steps

For runs with ionic motion (relaxations, MD, NEB), each ionic step is written as a sequence of flat blocks directly under <modeling>. There is no enclosing <calculation> element; each step contains:

 <!-- ionic step i (repeated for each step) -->
 <structure>
   <crystal>
     <varray name="basis"> ... </varray>
     <i name="volume"> ... </i>
     <varray name="rec_basis"> ... </varray>
   </crystal>
   <varray name="positions"> ... </varray>   <!-- fractional coordinates -->
 </structure>
 <varray name="forces">               <!-- Hellmann-Feynman forces in eV/A -->
   <v>  0.12 -0.03  0.00 </v>
   ...
 </varray>
 <varray name="stress">               <!-- stress tensor in kB -->
   <v> -0.16  0.00  0.11 </v>
   <v>  0.00  0.00  0.00 </v>
   <v>  0.11  0.00 -0.08 </v>
 </varray>
 <energy>
   <i name="e_fr_energy"> -53.93 </i>  <!-- free energy F = E - TS (eV) -->
   <i name="e_wo_entrp">  -53.93 </i>  <!-- energy without entropy (eV) -->
   <i name="e_0_energy">  -53.93 </i>  <!-- energy extrapolated to sigma->0 (eV) -->
   <!-- MD only: -->
   <i name="kinetic">       0.10 </i>  <!-- ionic kinetic energy (eV) -->
   <i name="lattice kinetic"> 0.00 </i> <!-- lattice kinetic energy, e.g. for NPT (eV) -->
   <i name="total">       -53.83 </i>  <!-- total energy E + E_kin, conserved in NVE (eV) -->
 </energy>
 <time name="totalsc"> 0.04 0.01 </time>   <!-- CPU and wall time for this step (s) -->

Mind: For IBRION=0 (MD) with a large number of steps (NSW >> 1), vasprun.xml can become very large. Consider using vaspout.h5 instead, or reading with a streaming XML parser (see below).

Electronic-structure calculation block

For single-point calculations (NSW=0) and post-DFT methods (GW, BSE), VASP writes a single <calculation> block instead of per-step ionic-step blocks. It contains eigenvalues, the density of states, and — for optical calculations — the dielectric function.

<calculation>
  <kpoints> ... </kpoints>           

  <dielectricfunction comment="HEAD OF MICROSCOPIC DIELECTRIC TENSOR (INDEPENDENT PARTICLE)">
    <imag>                           
      <array>
        <dimension dim="1">gridpoints</dimension>
        <field>energy</field>        
        <field>xx</field>
        <field>yy</field>
        <field>zz</field>
        <field>xy</field>
        <field>yz</field>
        <field>zx</field>
        <set>
          <r>  0.000   0.000  0.000  0.000  0.000  0.000  0.000 </r>
          <r>  1.066   0.075  0.075  0.075  0.000  0.000  0.000 </r>
          ...
        </set>
      </array>
    </imag>
    <real> ... </real>               
  </dielectricfunction>


  <eigenvalues>                      
    <array>
      <dimension dim="1">band</dimension>
      <dimension dim="2">kpoint</dimension>
      <dimension dim="3">spin</dimension>
      <field>eigene</field>          
      <field>occ</field>             
      <set>
        <set comment="spin 1">
          <set comment="kpoint 1">
            <r>  -10.504   1.0000 </r>
            <r>   11.891   1.0000 </r>
            ...
          </set>
          ...
        </set>
      </set>
    </array>
  </eigenvalues>

  <dos>                              
     6.12      
    <total>
      <array>
        <dimension dim="1">gridpoints</dimension>
        <dimension dim="2">spin</dimension>
        <field>energy</field>        
        <field>total</field>         
        <field>integrated</field>    
        <set> ... </set>
      </array>
    </total>
    <partial> ... </partial>         
  </dos>

   12.3  14.1    
</calculation>

For GW calculations (e.g., ALGO=EVGW0 or GW0), <eigenvalues> contains the quasiparticle energies updated by the GW self-energy. Multiple <dielectricfunction> blocks appear in the same <calculation>, each labelled by its comment attribute.

Final structure

The ionic positions at the end of the run. For MD runs, this block also contains the final ionic velocities, suitable for restarting the trajectory.

<structure name="finalpos">
  <crystal>
    <varray name="basis"> ... </varray>
     ... 
    <varray name="rec_basis"> ... </varray>
  </crystal>
  <varray name="positions"> ... </varray>
  <varray name="velocities"> ... </varray>
</structure>

Reading vasprun.xml

py4vasp

py4vasp reads vasprun.xml (and vaspout.h5) transparently. Given a calculation directory:

import py4vasp

calc = py4vasp.Calculation.from_path(".")

structure = calc.structure.read()   # crystal structure (all ionic steps)
energy    = calc.energy.read()      # total energy (all ionic steps)
forces    = calc.force.read()       # forces in eV/Å
dos       = calc.dos.read()         # density of states
bands     = calc.band.read()        # band structure

See the py4vasp documentation for the full list of accessible quantities.

pymatgen

The pymatgen library provides the Vasprun class:

from pymatgen.io.vasp import Vasprun

vr = Vasprun("vasprun.xml")

print(vr.final_energy)        # total energy of the final ionic step (eV)

# Iterate over ionic steps
for step in vr.ionic_steps:
    e = step["electronic_steps"][-1]["e_fr_energy"]
    print(e)

print(vr.final_structure)     # pymatgen Structure object
dos = vr.complete_dos         # total and projected DOS

ASE

The Atomic Simulation Environment (ASE) reads vasprun.xml as a sequence of Atoms objects:

from ase.io import read

images = read("vasprun.xml", index=":")   # all ionic steps
atoms  = images[-1]                       # final structure

print(atoms.get_potential_energy())       # total energy (eV)
print(atoms.get_forces())                 # forces (eV/Å)

Direct XML parsing

For custom workflows, parse vasprun.xml with Python's standard library:

import xml.etree.ElementTree as ET

tree = ET.parse("vasprun.xml")
root = tree.getroot()

# Read INCAR tags
for tag in root.find("incar"):
    print(tag.attrib.get("name"), "=", tag.text.strip())

# Read forces from each ionic step
for forces in root.iter("varray"):
    if forces.attrib.get("name") == "forces":
        data = [[float(x) for x in v.text.split()] for v in forces]
        print(data)

Mind: For large MD trajectories, use xml.etree.ElementTree.iterparse to stream the file element by element and avoid loading it entirely into memory.

Related tags and articles

• NSW — controls the number of ionic steps written to vasprun.xml.
• IBRION — selects the ionic update algorithm (relaxation or MD).
• MDALGO — selects the molecular-dynamics algorithm.
• LORBIT — controls whether orbital-projected DOS is written.
• LOPTICS — enables optical-property output (adds the dielectric function to the <calculation> block).
• ALGO — setting ALGO=EVGW0, GW0, etc. adds GW quasiparticle eigenvalues and screened-Coulomb blocks.
• IBSE — BSE calculations; adds the excitonic dielectric function.
• NWRITE — controls the verbosity of OUTCAR, but does not affect vasprun.xml.
• OUTCAR — the human-readable counterpart to vasprun.xml.
• vaspout.h5 — the HDF5 alternative to vasprun.xml, preferred for large runs.