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. Every input parameter is a physical approximation. ecutwfc = 60 sets where the plane-wave basis is truncated. For each value you set, ask what it approximates; that helps more than memorizing the manual.

2. Run convergence tests before trusting a number. The most common beginner mistake is equating "the calculation ran" with "the result is right". QE will 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). I ran all 13 examples with QE 7.5 (conda-forge build, WSL Ubuntu), and the pages report the 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 testing, and structure optimization. Two or three days is enough.
2. bcc Fe (E9). A metal plus ferromagnetism. Deal with smearing and magnetization convergence here, on an easy system.
3. FeO in the AFM phase (E10). Check 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 the ideal-cubic-cell pitfall), then compute U from first principles with hp.x. This is the core of the Fe–O part of the guide.
5. Slab and AIMD (E13). The starting point for generating training data for machine-learned potentials.

If ML training data is the goal, converge with respect to forces rather than energies, and keep every setting identical across structures; see Chapter 16.

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 run GGA on FeO and seen it come out metallic.

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.