Vasprun.xml: Difference between revisions
Comprehensive rewrite: add ionic steps, calculation block (GW/BSE), reading section (py4vasp, pymatgen, ASE, XML); condense parameters section |
|||
| Line 323: | Line 323: | ||
=== py4vasp === | === py4vasp === | ||
{{py4vasp}} reads {{FILE|vasprun.xml}} (and {{FILE|vaspout.h5}}) transparently. Given a calculation directory: | |||
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
| Line 337: | Line 337: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
See the [ | See the [{{py4vasp}} documentation] for the full list of accessible quantities. | ||
=== pymatgen === | === pymatgen === | ||
Revision as of 14:32, 22 May 2026
The vasprun.xml file is VASP's machine-readable XML output file. It records the complete set of input parameters, the crystal structure, and all computed quantities for every ionic step of the calculation.
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. For large calculations, the HDF5 alternative vaspout.h5 is preferred.
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> vasp 6.5.0 29Jan2024 (build Feb 14 2024) complex parallel LinuxGNU 2024 01 01 12:00:00 </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>
diamond Si
Normal
500.00000000
0
0.05000000
</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">
<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>
28.35
<varray name="rec_basis">
<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">
<v> 0.00 0.00 0.00 </v>
<v> 0.25 0.25 0.25 </v>
</varray>
</structure>
<varray name="primitive_index">
<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">
<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">
<v> 0.000 0.000 0.000 </v>
<v> 0.250 0.000 0.000 </v>
...
</varray>
<varray name="weights">
<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:
generalelectronic(with sub-separators:smearing,projectors,startup,spin,exchange-correlation,convergence,mixer,dipolcorrection)gridsionicandionic mdsymmetrydoswritingperformanceresponse functions(GW/BSE calculations)vdW DFT
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>
<types> 1 </types>
<array name="atoms">
<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">
<dimension dim="1">type</dimension>
<field type="int">atomspertype</field>
<field type="string">element</field>
<field>mass</field>
<field>valence</field>
<field type="string">pseudopotential</field>
<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">
<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>
160.10
<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">
<v> 0.000 0.000 0.000 </v>
<v> 0.250 0.250 0.250 </v>
</varray>
<varray name="velocities">
<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:
<structure>
<crystal>
<varray name="basis"> ... </varray>
...
<varray name="rec_basis"> ... </varray>
</crystal>
<varray name="positions"> ... </varray>
</structure>
<varray name="forces">
<v> 0.12 -0.03 0.00 </v>
...
</varray>
<varray name="stress">
<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>
-53.93
-53.93
-53.93
0.10
0.00
-53.83
</energy>
| 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>
</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.