Getting Started with Quantum ESPRESSO: Your First SCF Calculation

Quantum ESPRESSO is one of the most widely used open-source packages for electronic-structure calculations based on density functional theory (DFT). If you are a graduate student or researcher taking your first steps into first-principles materials modeling, the self-consistent field (SCF) calculation is where everything begins. This guide walks you through installing the code, writing a complete pw.x input for crystalline silicon, running it, and interpreting the output.

What a Self-Consistent Field Calculation Actually Does

Before touching an input file, it helps to understand what you are asking the code to do. DFT reformulates the many-electron problem into a set of single-particle Kohn–Sham equations:

with the electron density rebuilt from the occupied orbitals:

The catch is circular: the effective potential \(V_{\mathrm{eff}}[n]\) depends on the density \(n\), but \(n\) is built from the orbitals you get by solving with that potential.

The SCF loop resolves this circularity iteratively:

flowchart TD
  A[Initial density n0<br/>atomic superposition] --> B[Build V_eff from n]
  B --> C[Diagonalize KS Hamiltonian]
  C --> D[New orbitals to n_out]
  D --> E[Mix densities with beta]
  E --> F{Below conv_thr?}
  F -->|No| B
  F -->|Yes| G[Converged ground state<br/>E_tot and density]

1. Start from an initial guess for the charge density (usually a superposition of atomic densities).
2. Build the Kohn–Sham effective potential from that density.
3. Diagonalize the Hamiltonian to get new orbitals and a new density.
4. Mix the new density with the old one and check whether it changed.
5. Repeat until the density (and total energy) stops changing within a chosen threshold.

When the change drops below the convergence criterion, the field is self-consistent and you have the ground-state energy and charge density. The main driver for this in Quantum ESPRESSO is pw.x, the plane-wave PWscf executable.

Installing or Accessing Quantum ESPRESSO

You have three practical routes to a working pw.x binary.

• Package managers. On Ubuntu/Debian, sudo apt install quantum-espresso gives you a serial build quickly, though often not the newest version.
• Compile from source. Download from the official site at quantum-espresso.org, then configure and build. This gives you MPI parallelism and lets you link optimized math libraries.
• Run in the cloud. Skip the toolchain entirely and use a preconfigured GPU cluster (more on that at the end).

A typical source build looks like this:

tar -xzf q-e-qe-7.3.tar.gz
cd q-e-qe-7.3
./configure --enable-parallel --with-scalapack=yes
make pw

After a successful build, the binary lives in bin/pw.x. Add it to your PATH so you can call it directly.

The Anatomy of a pw.x SCF Input File

A pw.x input consists of namelists (Fortran-style blocks beginning with & and ending with /) followed by cards (free-format blocks for structure and k-points). For a basic SCF run you need three namelists — &CONTROL, &SYSTEM, &ELECTRONS — and three cards: ATOMIC_SPECIES, ATOMIC_POSITIONS, and K_POINTS.

Here is a complete, working input for bulk silicon in its diamond structure. Save it as si.scf.in:

&CONTROL
    calculation = 'scf'
    prefix      = 'silicon'
    outdir      = './tmp/'
    pseudo_dir  = './pseudo/'
    verbosity   = 'high'
/
&SYSTEM
    ibrav       = 2
    celldm(1)   = 10.26
    nat         = 2
    ntyp        = 1
    ecutwfc     = 30.0
    ecutrho     = 240.0
/
&ELECTRONS
    conv_thr    = 1.0d-8
    mixing_beta = 0.7
/
ATOMIC_SPECIES
 Si  28.0855  Si.pbe-n-rrkjus_psl.1.0.0.UPF

ATOMIC_POSITIONS (alat)
 Si  0.00  0.00  0.00
 Si  0.25  0.25  0.25

K_POINTS (automatic)
 6 6 6 1 1 1

Understanding the Key Variables

• calculation = 'scf' tells pw.x to run a single self-consistent calculation at a fixed geometry.
• ibrav = 2 selects the face-centered cubic Bravais lattice, and celldm(1) = 10.26 sets the lattice parameter in Bohr (the experimental value for silicon).
• nat = 2 and ntyp = 1 declare two atoms of one atomic type in the unit cell.
• ecutwfc = 30.0 is the plane-wave kinetic-energy cutoff for wavefunctions in Rydberg: only plane waves with \(\frac{1}{2}\lvert\mathbf{G}+\mathbf{k}\rvert^{2} < E_{\mathrm{cut}}\) enter the basis. ecutrho is the density cutoff, conventionally \(4\times E_{\mathrm{cut}}\) for norm-conserving pseudopotentials and \(8\)–\(12\times\) for ultrasoft ones.
• conv_thr = 1.0d-8 is the SCF convergence threshold on total energy in Rydberg.

The ATOMIC_POSITIONS (alat) card places the two silicon atoms in units of the lattice parameter, forming the diamond basis. The K_POINTS (automatic) card generates a 6x6x6 Monkhorst-Pack mesh with no offset.

Pseudopotentials: The File You Cannot Skip

Plane-wave DFT does not treat core electrons explicitly. Instead, a pseudopotential replaces the nucleus plus tightly bound core electrons with a smoother effective potential, dramatically reducing the number of plane waves needed. Every element in your ATOMIC_SPECIES card must point to a valid pseudopotential file in the UPF format.

Download curated sets such as the SSSP (Standard Solid-State Pseudopotentials) library or the PSlibrary. Place the .UPF file in the directory named by pseudo_dir. The following table summarizes the common flavors.

The filename Si.pbe-n-rrkjus_psl.1.0.0.UPF tells you it uses the PBE exchange-correlation functional and is an ultrasoft (rrkjus) potential from PSlibrary. Match the functional across all species in a calculation.

Running pw.x

With the input and pseudopotential in place, create the output directory and launch the run. In serial:

mkdir -p tmp pseudo
pw.x -in si.scf.in > si.scf.out

For a parallel run across four MPI processes:

mpirun -np 4 pw.x -in si.scf.in > si.scf.out

Quantum ESPRESSO writes progress and results to si.scf.out. The tmp/ directory fills with wavefunction and charge-density files prefixed by silicon, which later post-processing tools can reuse.

Reading the Output File

Open si.scf.out and look for a few landmark lines. Early on you will see a summary of the run: the number of Kohn-Sham states, the plane-wave basis size, and the k-point list. As the SCF loop proceeds, each iteration prints something like:

iteration #  1     ecut= 30.00 Ry     beta= 0.70
     total energy              =     -15.76387 Ry
     estimated scf accuracy    <       0.05821 Ry

iteration #  6     ecut= 30.00 Ry     beta= 0.70
     total energy              =     -15.79632 Ry
     estimated scf accuracy    <       4.2E-09 Ry

The estimated scf accuracy is the quantity compared against conv_thr. When it drops below your threshold, you will see the crucial confirmation:

     convergence has been achieved in   6 iterations

!    total energy              =     -15.79632 Ry

The Numbers That Matter

• The line beginning with ! is the final, converged total energy. The exclamation mark makes it easy to grep: grep '^!' si.scf.out.
• The Fermi energy (for metals) or highest occupied level (for insulators) appears just below.
• A breakdown into one-electron, Hartree, exchange-correlation, and Ewald contributions follows, useful for sanity checks.
• The final total force and, if requested, the pressure confirm whether your geometry is near equilibrium.

Total energies in DFT are meaningful only as differences. A single silicon SCF number tells you little on its own; comparing energies across lattice parameters, phases, or configurations is where the physics lives.

Verifying Your Result Makes Physical Sense

A converged number is not automatically a correct one. Before you build on an SCF result, run a few sanity checks.

• Compare against a reference. The cohesive energy or lattice constant of silicon is well documented. If your relaxed lattice parameter lands within a percent or two of 5.43 Angstrom, your setup is sound. Large deviations usually mean an underconverged cutoff or a mismatched pseudopotential.
• Check the number of Kohn-Sham states. Silicon has eight valence electrons per unit cell, so four doubly occupied bands. The output should report at least four bands; if you requested more with nbnd, the extra ones appear as empty conduction states.
• Look at the total force. With tprnfor = .true. the code prints forces on each atom. For silicon at its ideal diamond positions, symmetry forces them to zero — values on the order of 1e-4 Ry/Bohr or smaller confirm a clean run.
• Watch the iteration count. A healthy insulator SCF converges in well under 20 iterations. If yours takes 50 or more, revisit mixing_beta and your starting parameters.

A Note on Units and Conventions

Quantum ESPRESSO reports energies in Rydberg by default (\(1\,\mathrm{Ry} \approx 13.606\,\mathrm{eV}\)). Distances in celldm are in Bohr (\(1\,a_{0} \approx 0.529\,\mathrm{\AA}\)), while CELL_PARAMETERS and ATOMIC_POSITIONS let you choose angstrom explicitly. Mixing up these units is the single most common source of nonsensical first results, so always confirm what convention each card is using before trusting the geometry.

Next Steps After Your First SCF

Once your SCF run converges cleanly, a whole workflow opens up:

• Convergence testing of ecutwfc and the k-point grid to guarantee your results are numerically reliable.
• Geometry optimization with calculation = 'relax' or 'vc-relax' to find equilibrium structures.
• Band structures and density of states using bands.x and dos.x on the converged density.
• Phonons and response properties via the ph.x code in the Quantum ESPRESSO suite.

For a deeper look at the engines that power these calculations, see our overview of the computational engines behind the platform, and browse more tutorials on the blog.

Run it on Simatra

Setting up compilers, MPI, and pseudopotential libraries can eat a day before you compute a single energy. Simatra runs Quantum ESPRESSO on GPU-accelerated clusters using our GPU-Opt-V2 instances, delivering up to 5x faster convergence and supporting supercells up to ~2,000 atoms — with the toolchain, computational engines, and pseudopotential sets already configured. Start free with $100 in credits at app.simatra.io and run your first SCF calculation in minutes instead of hours.