The Quantum ESPRESSO Input File Explained (pw.x)

The pw.x input file is the control panel for every plane-wave DFT calculation in Quantum ESPRESSO. Get it right and the code does exactly what you intend; get one flag wrong and you waste hours on a nonsensical result. This reference walks through each namelist and card, explains the variables that matter most, and highlights the mistakes that catch newcomers.

The Structure of a pw.x Input

A pw.x input has two kinds of blocks. Namelists are Fortran-style and begin with an ampersand and a name, list key = value pairs, and close with a slash. Cards are free-format text blocks that carry structural and sampling information.

The namelists must appear in this order: &CONTROL, &SYSTEM, &ELECTRONS, then optionally &IONS and &CELL. The cards follow: ATOMIC_SPECIES, ATOMIC_POSITIONS, K_POINTS, and — when you do not use a built-in Bravais lattice — CELL_PARAMETERS.

flowchart TD
  A["&CONTROL<br/>calculation, prefix, outdir"] --> B["&SYSTEM<br/>ibrav, ecutwfc, occupations"]
  B --> C["&ELECTRONS<br/>conv_thr, mixing_beta"]
  C --> D{calculation?}
  D -->|scf / nscf / bands| E[Cards only]
  D -->|relax| F["&IONS"]
  D -->|vc-relax| G["&IONS + &CELL"]
  F --> E
  G --> E
  E --> H[ATOMIC_SPECIES]
  H --> I[ATOMIC_POSITIONS]
  I --> J[K_POINTS]
  J --> K[CELL_PARAMETERS<br/>if ibrav = 0]

Here is a full example for rutile titanium dioxide that exercises most of the machinery:

&CONTROL
    calculation  = 'vc-relax'
    prefix       = 'tio2'
    outdir       = './tmp/'
    pseudo_dir   = './pseudo/'
    tprnfor      = .true.
    tstress      = .true.
/
&SYSTEM
    ibrav        = 0
    nat          = 6
    ntyp         = 2
    ecutwfc      = 50.0
    ecutrho      = 400.0
    occupations  = 'fixed'
/
&ELECTRONS
    conv_thr     = 1.0d-8
    mixing_beta  = 0.7
    diagonalization = 'david'
/
&IONS
    ion_dynamics = 'bfgs'
/
&CELL
    cell_dynamics = 'bfgs'
    press_conv_thr = 0.5
/
ATOMIC_SPECIES
 Ti  47.867  Ti.pbe-spn-rrkjus_psl.1.0.0.UPF
 O   15.999  O.pbe-n-rrkjus_psl.1.0.0.UPF

CELL_PARAMETERS (angstrom)
 4.594  0.000  0.000
 0.000  4.594  0.000
 0.000  0.000  2.959

ATOMIC_POSITIONS (crystal)
 Ti  0.000000  0.000000  0.000000
 Ti  0.500000  0.500000  0.500000
 O   0.305000  0.305000  0.000000
 O   0.695000  0.695000  0.000000
 O   0.195000  0.805000  0.500000
 O   0.805000  0.195000  0.500000

K_POINTS (automatic)
 4 4 6 0 0 0

The &CONTROL Namelist

&CONTROL governs what kind of run you perform and where files go. The single most important variable is calculation, which selects the task.

• 'scf' — a single self-consistent field calculation at fixed geometry.
• 'nscf' — non-self-consistent, used to compute eigenvalues on a denser mesh after an SCF run.
• 'bands' — eigenvalues along a k-path for band structures.
• 'relax' — optimize atomic positions at fixed cell.
• 'vc-relax' — variable-cell relaxation, optimizing atoms and lattice together.
• 'md' — Born-Oppenheimer molecular dynamics.

Other essentials: prefix names all scratch files, outdir points to the scratch directory, and pseudo_dir locates the UPF pseudopotentials. Set tprnfor = .true. and tstress = .true. to print forces and stress, which you need for any relaxation.

The &SYSTEM Namelist

&SYSTEM describes the physical system: the cell, the atoms, and the basis. This is the largest namelist and where most physics decisions live.

Defining the Cell and Atoms

• ibrav selects the Bravais lattice. Setting ibrav = 0 means you will provide an explicit CELL_PARAMETERS card; nonzero values (2 for FCC, 4 for hexagonal, and so on) use celldm parameters instead.
• nat is the number of atoms and ntyp the number of distinct species. These must exactly match your ATOMIC_POSITIONS and ATOMIC_SPECIES cards.

Basis and Occupations

Kohn–Sham orbitals are expanded in plane waves up to a kinetic-energy cutoff:

where only reciprocal-lattice vectors satisfying \(\frac{1}{2}\lvert\mathbf{k}+\mathbf{G}\rvert^{2} \le E_{\mathrm{cut}}\) are retained.

• ecutwfc sets \(E_{\mathrm{cut}}\) for wavefunctions (Ry), the primary accuracy knob.
• ecutrho sets the charge-density cutoff; leave it at the default \(4\times\) ecutwfc for norm-conserving potentials but raise it for ultrasoft or PAW sets.
• occupations controls how states are filled: 'fixed' for insulators, 'smearing' for metals, 'tetrahedra' for accurate density of states.
• For metals you add smearing (e.g. 'mv' for Marzari–Vanderbilt cold smearing) and degauss (the broadening width \(\sigma\) in Ry).
• For magnetic systems, set nspin = 2 and provide starting_magnetization(i) per species.

The &ELECTRONS Namelist

&ELECTRONS controls the SCF loop itself — how the density is updated and how convergence is judged.

• conv_thr is the SCF convergence threshold on estimated energy accuracy (Ry). A value of 1.0d-6 suffices for energies; tighten to 1.0d-10 for phonons.
• mixing_beta is the density mixing fraction. The default 0.7 works for many insulators; metals and magnetic systems often need 0.1-0.3.
• mixing_mode chooses the mixing scheme: 'plain', 'local-TF' (good for large or inhomogeneous cells), or 'TF'.
• diagonalization selects the eigensolver, 'david' (Davidson, fast, memory-hungry) or 'cg' (conjugate gradient, robust, slower).

The &IONS and &CELL Namelists

These two are required only when atoms or the cell can move.

• &IONS is read for relax, vc-relax, and md. The key variable ion_dynamics is usually 'bfgs' for relaxations or 'verlet' for molecular dynamics.
• &CELL is read only for vc-relax. cell_dynamics = 'bfgs' optimizes the lattice, and press_conv_thr sets the pressure convergence in kbar. You can also target a nonzero external pressure with press.

Advanced Variables Worth Knowing Early

Beyond the core set, a handful of variables come up constantly once you move past textbook examples.

• nbnd (&SYSTEM) sets the number of Kohn-Sham bands. The code picks a sensible default, but metals need extra empty bands so the smeared Fermi level has room to move — add roughly 20% above the number of occupied states.
• nspin (&SYSTEM) enables spin polarization. Set nspin = 2 for collinear magnetism and provide starting_magnetization per species; use nspin = 4 with noncolin = .true. for noncollinear or spin-orbit calculations.
• input_dft (&SYSTEM) overrides the exchange-correlation functional baked into the pseudopotential, letting you request PBE, PBEsol, or a hybrid without regenerating potentials — use with care, since the functional should match how the pseudopotential was built.
• restart_mode (&CONTROL) accepts 'from_scratch' or 'restart', the latter resuming an interrupted run from saved files.
• max_seconds (&CONTROL) gracefully stops a job before a scheduler wall-clock limit, writing restart files so no work is lost.

The Role of Symmetry

Quantum ESPRESSO automatically detects the crystal symmetry from your cell and atomic positions and uses it to reduce the k-point set and speed up the calculation. If you see fewer irreducible k-points than you expected, that is symmetry working in your favor. Conversely, if the code reports lower symmetry than the structure should have, suspect a small numerical error in your coordinates — even a rounding difference in the fifth decimal place can break a mirror plane. The variable nosym = .true. disables this reduction, which is occasionally necessary for defect or surface calculations where you deliberately want the full k-mesh.

The Structural and Sampling Cards

ATOMIC_SPECIES

One line per type: label, atomic mass (amu), and the UPF pseudopotential filename. The label must match the ones used in ATOMIC_POSITIONS. All species should share the same exchange-correlation functional.

ATOMIC_POSITIONS

The header sets the coordinate convention: (crystal) for fractional coordinates, (angstrom) or (bohr) for Cartesian, (alat) for units of the lattice parameter. (crystal) is the safest choice because it is independent of cell size.

K_POINTS

• (automatic) generates a Monkhorst-Pack grid: three mesh divisions plus three offset flags, e.g. 4 4 6 0 0 0.
• (gamma) uses only the Gamma point — ideal for large or molecular systems and faster because of real wavefunctions.
• (crystal_b) or (tpiba_b) define explicit k-paths for band structures.

CELL_PARAMETERS

Required when ibrav = 0. Provide three lattice vectors as rows, with the unit given in the header, such as (angstrom) or (bohr).

Quick-Reference Table of Key Variables

Running and Common Gotchas

Launch the calculation the usual way:

mpirun -np 8 pw.x -in tio2.vc-relax.in > tio2.vc-relax.out

A handful of mistakes account for most beginner errors:

• Mismatched nat/ntyp. If these do not equal the number of position lines or species, pw.x stops immediately with a clear error. Always double-check after editing structures.
• Wrong ecutrho for ultrasoft potentials. Leaving it at the norm-conserving default of 4x causes egg-box artifacts and bad forces. Use at least 8x for ultrasoft and PAW.
• Forgetting smearing for metals. With occupations = 'fixed' a metal will oscillate and never converge. Switch to 'smearing' and set a sensible degauss.
• Coordinate-unit confusion. Reading Cartesian numbers as (crystal) silently corrupts your geometry. When in doubt use (crystal) fractional coordinates.
• Nonexistent outdir. Create the scratch directory before running or the job aborts on the first write.

For a broader tour of the code and its ecosystem, consult the official documentation at quantum-espresso.org, read our getting started tutorial, and see how the platform’s computational engines fit together.

Run it on Simatra

A correct input file is only half the battle — you still need hardware to run it. Simatra runs Quantum ESPRESSO on GPU-accelerated clusters via our GPU-Opt-V2 instances, giving up to 5x faster convergence and handling supercells up to ~2,000 atoms without you managing a single compiler flag. Our stack pairs Quantum ESPRESSO with KRONOS, our native engine, and the computational engines page explains both. Sign up for a free trial with $100 in credits at app.simatra.io and run your first pw.x job today.