Jump to content

Requests for technical support from the VASP team should be posted in the VASP Forum.

Vasprun.xml

From VASP Wiki
Revision as of 16:20, 1 June 2026 by Csheldon (talk | contribs)

There are three main output files: OUTCAR in human-readable format, vasprun.xml in xml format, and vaspout.h5 in HDF5 format. The vasprun.xml file contains output from a calculation in XML format. It is written along with the human-readable OUTCAR and contains much of the same output in a more structured, hierarchical, tree-like form that is easy to process programmatically. A third option for output is the vaspout.h5 format.

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>
 
   <!-- one block per ionic step (MD, relaxation): -->
   <structure> ... </structure>
   <varray name="forces"> ... </varray>
   <varray name="stress"> ... </varray>
   <energy> ... </energy>
   <time name="totalsc"> ... </time>
   ...
 
   <!-- OR a single calculation block (single-point, GW, BSE): -->
   <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 (DOS), and — for optical calculations — the dielectric function. 

 <calculation>
   <kpoints> ... </kpoints>           <!-- same layout as the top-level <kpoints> block -->
 
   <!-- Present if LOPTICS = .TRUE., or for GW/BSE:
        one or more dielectricfunction blocks, each labelled by a comment attribute -->
   <dielectricfunction comment="HEAD OF MICROSCOPIC DIELECTRIC TENSOR (INDEPENDENT PARTICLE)">
     <imag>                           <!-- imaginary part epsilon_2(omega) -->
       <array>
         <dimension dim="1">gridpoints</dimension>
         <field>energy</field>        <!-- frequency grid in eV -->
         <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>               <!-- real part epsilon_1(omega), same layout -->
   </dielectricfunction>
 
   <!-- For GW/BSE, additional dielectricfunction blocks appear:
        "1 + v P, with REDUCIBLE POLARIZABILITY P=P_0 (1 -(v+f) P_0)^-1"
        "INVERSE MACROSCOPIC DIELECTRIC TENSOR (including local field effects in RPA (Hartree))"
        "screened Coulomb potential"   -->
 
   <eigenvalues>                      <!-- KS (DFT) or quasiparticle (GW) eigenvalues -->
     <array>
       <dimension dim="1">band</dimension>
       <dimension dim="2">kpoint</dimension>
       <dimension dim="3">spin</dimension>
       <field>eigene</field>          <!-- eigenvalue in eV -->
       <field>occ</field>             <!-- occupation number -->
       <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>                              <!-- density of states (present if LORBIT or NEDOS is set) -->
     <i name="efermi"> 6.12 </i>     <!-- Fermi energy in eV -->
     <total>
       <array>
         <dimension dim="1">gridpoints</dimension>
         <dimension dim="2">spin</dimension>
         <field>energy</field>        <!-- energy grid in eV -->
         <field>total</field>         <!-- total DOS in states/eV -->
         <field>integrated</field>    <!-- integrated DOS (number of states) -->
         <set> ... </set>
       </array>
     </total>
     <partial> ... </partial>         <!-- orbital-projected DOS (present if LORBIT >= 10) -->
   </dos>
 
   <time name="total"> 12.3  14.1 </time>   <!-- total CPU and wall time (s) -->
 </calculation>

E.g., 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>
     <i name="volume"> ... </i>
     <varray name="rec_basis"> ... </varray>
   </crystal>
   <varray name="positions"> ... </varray>
   <!-- MD only: -->
   <varray name="velocities"> ... </varray>
 </structure>

Reading vasprun.xml

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

ElementTree

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.

lxml

There are also plenty of other Python packages that can be used to read vasprun.xml, e.g., lxml: 

from lxml import etree

# Parse XML
tree = etree.parse("vasprun.xml")
root = tree.getroot()

# Read INCAR tags
incar = root.find("incar")

for tag in incar:
    name = tag.attrib.get("name")
    value = tag.text.strip() if tag.text else None
    print(name, "=", value)

# Read the final energy
energies = root.xpath(".//i[@name='e_0_energy']/text()")
final_energy = float(energies[-1])

print(final_energy)

# Read forces from each ionic step
forces_blocks = root.xpath(".//varray[@name='forces']")

for forces in forces_blocks:
    data = [
        [float(x) for x in v.text.split()]
        for v in forces
    ]
    print(data)

There are plenty of other Python packages that can be used, or other languages if you prefer, which we will not describe here.

Related tags and articles

References

Retrieved from "https://vasp.at/wiki/index.php?title=Vasprun.xml&oldid=36288"