Quantum ESPRESSO
A Practical Guide

Quantum ESPRESSO (QE) is an open-source first-principles (DFT) package built on plane waves and pseudopotentials. It computes electronic structure, total energies, forces and stress, band structures and densities of states, phonons, and ab initio molecular dynamics for crystals, surfaces, and molecules, and it is free for academic use.

This guide is written so that a newcomer does not get lost in front of pw.x. It starts from the simplest possible silicon SCF and works through input syntax, convergence testing, structure optimization, and post-processing, then continues into spin polarization and antiferromagnetism, the HUBBARD card for DFT+U, computing U with hp.x, and slabs with ab initio MD. In other words, it covers the full path you need for transition-metal oxide research (the Fe–O system in particular).

Three principles to hold on to

1. QE is less a program than a piece of lab equipment. Every input parameter corresponds to a physical approximation. ecutwfc = 60 is not "the number 60"; it is a physical decision about where to truncate the plane-wave basis. Asking "what does this value approximate?" every time, instead of memorizing the manual, is what determines how fast you learn.

2. A number that has not passed a convergence test is not a number. The most common beginner mistake is equating "the calculation ran" with "the result is right". QE will happily print physically wrong results in a perfectly clean format. Chapter 05 and Example E3 cover the procedure.

3. Check the version before trusting third-party tutorials. A large share of QE examples on the internet use obsolete syntax. The prime case is DFT+U: in v7.1 the lda_plus_u / Hubbard_U(i) style was replaced by the HUBBARD card. Pasting old examples gets you input that is silently ignored or fails. This guide uses the new syntax only.

About this guide

• The target version is QE 7.5 (released August 2025). All 13 examples were actually executed with QE 7.5 (conda-forge build, WSL Ubuntu), and the pages report the measured numbers and figures from those runs. Every example page links its input files, and a complete bundle is available.
• The chapters (01–18) are organized by concept; the examples (E1–E13) are organized by system. Look up "what does this variable mean" in the chapters and "how do I run this system" in the examples, and follow the cross-links between them.
• The reference pages (R1–R4) are for searching, not reading: keyword, card, and error-message dictionaries.
• The final authority on input variables is always the Doc/INPUT_PW.txt of your installed version (online version).

Where to start

Basics · Getting started

Basics · Core concepts

Basics · Calculation types

Advanced · Magnetism and correlation

Advanced · Applications and operations

Reference

Examples · Hands-on

Each example is a self-contained page in a fixed order: goal, new cards and variables, input files (downloadable), how to run, what to check in the output, exercises, and common mistakes. All numbers are measured from real QE 7.5 runs.

The shortest path to the Fe–O system

If transition-metal oxides (say, iron oxidation) are your end goal, you can compress the examples into this sequence.

1. Si (E1–E3, E6–E8). Learn the syntax, convergence, and optimization instincts. Two or three days is enough.
2. bcc Fe (E9). A metal plus ferromagnetism. Meet the difficulties of smearing and magnetization convergence here, on an easy system.
3. FeO in the AFM phase (E10). Verify for yourself that without DFT+U the calculation comes out metallic.
4. FeO with U (E11–E12). Turn on U with the HUBBARD card, observe the Hubbard splitting (and walk into the famous trap of the ideal cubic cell), then compute U from first principles with hp.x. This one cycle is the heart of the whole curriculum.
5. Slab and AIMD (E13). The starting point for generating training data for machine-learned potentials.

If ML training data is the goal, one criterion changes: converge with respect to forces, not energies, and keep the cutoffs, k-grid, smearing, and U absolutely identical across every structure. A dataset with mixed settings cannot be repaired at the training stage.

Self-check list

Move on only when you can answer these.

• Basics (E1–E3). You can explain the physical difference between ecutwfc and ecutrho. You can convert between alat, crystal, and angstrom coordinates. You can explain why absolute total energies must not be compared.
• System types (E4–E6). You know which occupations to use for a metal, a semiconductor, and a molecule. You know the difference between starting_magnetization and tot_magnetization. You can explain why a fresh scf is required after vc-relax (Pulay stress).
• Post-processing (E7–E8). You know the role of prefix and outdir in the scf, nscf, dos.x chain. You know why the tetrahedron method requires a Γ-centered, unshifted grid.
• Magnetism and correlation (E9–E12). You know why the same element needs two labels to build an AFM state. You can classify a magnetic solution from total vs absolute magnetization. You know that the meaning of U depends on the projector. You have seen GGA predict metallic FeO with your own eyes.

How to cite

When publishing work that used Quantum ESPRESSO, the convention is to cite the following papers, together with the original papers of any modules you used (such as hp.x) and the source of your pseudopotentials.

• P. Giannozzi et al. J. Phys.: Condens. Matter 2009, 21, 395502.
• P. Giannozzi et al. J. Phys.: Condens. Matter 2017, 29, 465901.
• P. Giannozzi et al. J. Chem. Phys. 2020, 152, 154105.
• (if you use hp.x) I. Timrov, N. Marzari, M. Cococcioni. Comput. Phys. Commun. 2022, 279, 108455.