Run Quantum ESPRESSO DFT calculations. Use when asked to perform first-principles calculations, SCF, structural relaxation, band structure, DOS, phonons, or any ab initio quantum mechanical calculation.
You are executing Quantum ESPRESSO density functional theory calculations.
You must find and download pseudopotentials yourself.
Pseudopotentials are NOT stored locally. You need to:
Step 1: Determine requirements
Element(s): Si, O, Li, etc.
Functional: PBE (most common), LDA, PBEsol
Type: NC (norm-conserving), US (ultrasoft), PAW (projector augmented wave)
Step 2: Find pseudopotentials online
| Source | URL | Best For |
|---|---|---|
| SSSP | https://www.materialscloud.org/discover/sssp/table/efficiency | Production - curated, tested |
| PseudoDojo | http://www.pseudo-dojo.org/ | High accuracy |
| QE Library | https://www.quantum-espresso.org/pseudopotentials | Quick access |
| Materials Cloud | https://www.materialscloud.org/ | Various libraries |
Step 3: Download the files
Use WebFetch or Playwright:
Search for: "silicon PBE pseudopotential SSSP download"
Navigate to SSSP table, find Si row, download .UPF file
Example file names:
Si.pbe-n-rrkjus_psl.1.0.0.UPF (PBE, ultrasoft)Si.pz-vbc.UPF (LDA, norm-conserving)O.pbe-n-kjpaw_psl.1.0.0.UPF (PBE, PAW)Step 4: Save to workspace
workspaces/your-project/pseudo/Si.pbe-n-rrkjus_psl.1.0.0.UPF
Step 5: Note recommended cutoffs
SSSP provides recommended cutoffs. If not available:
Step 6: Reference in input
&CONTROL
pseudo_dir = './pseudo'
/
ATOMIC_SPECIES
Si 28.0855 Si.pbe-n-rrkjus_psl.1.0.0.UPF
Given only: "Calculate the band structure of silicon"
You do:
Get crystal structure
# From Materials Project
from mp_api.client import MPRester
import os
with MPRester(os.environ.get("MP_API_KEY")) as mpr:
si = mpr.get_structure_by_material_id("mp-149")
# Note: a = 5.431 Å, diamond structure, Fd-3m
Find and download pseudopotential
Create SCF input
&CONTROL
calculation = 'scf'
prefix = 'si'
outdir = './tmp'
pseudo_dir = './pseudo'
/
&SYSTEM
ibrav = 2 ! FCC
celldm(1) = 10.26 ! a in Bohr (5.43 Å)
nat = 2
ntyp = 1
ecutwfc = 40.0 ! From SSSP recommendation
ecutrho = 320.0 ! 8x for US pseudo
/
&ELECTRONS
conv_thr = 1.0d-8
/
ATOMIC_SPECIES
Si 28.0855 Si.pbe-n-rrkjus_psl.1.0.0.UPF
ATOMIC_POSITIONS crystal
Si 0.00 0.00 0.00
Si 0.25 0.25 0.25
K_POINTS automatic
8 8 8 0 0 0
Run SCF
/path/to/pw.x < scf.in > scf.out
Create bands input
&CONTROL
calculation = 'bands'
prefix = 'si'
outdir = './tmp'
pseudo_dir = './pseudo'
/
...
K_POINTS crystal_b
5
0.5 0.5 0.5 20 ! L
0.0 0.0 0.0 20 ! Gamma
0.5 0.0 0.5 20 ! X
0.5 0.25 0.75 20 ! W
0.5 0.5 0.5 1 ! L
Run bands and post-process
pw.x < bands.in > bands.out
bands.x < bands_pp.in > bands_pp.out
Analyze
Local GPU-accelerated QE (RTX 5080):
# GPU Build (NVHPC-compiled, sm_120)
QE_GPU="/home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/build-gpu/bin"
# CPU Build (GCC/MPI)
QE_CPU="/home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/build-cpu/bin"
# Environment setup for GPU build
QE_ENV="/home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/env/setup_nvhpc.sh"
CPU (general purpose):
/home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/build-cpu/bin/pw.x < input.in > output.out
# With MPI
mpirun -np 4 /home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/build-cpu/bin/pw.x < input.in > output.out
GPU (RTX 5080 accelerated - recommended for production):
# First source NVHPC environment
source /home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/env/setup_nvhpc.sh
# Run GPU-accelerated QE
/home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/build-gpu/bin/pw.x < input.in > output.out
# Or with wrapper variables
$QE_GPU/pw.x < input.in > output.out
Test scripts available:
bash /home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/scripts/run_example01_cpu.sh
bash /home/sf2/Workspace/main/39-GPUTests/1-GPUTests/dft-qe/scripts/run_example01_gpu.sh
| Type | Use For |
|---|---|
scf | Ground state energy, charge density |
relax | Optimize atomic positions |
vc-relax | Optimize cell + positions |
bands | Band structure (after SCF) |
nscf | DOS, more k-points (after SCF) |
| ibrav | Lattice | Example |
|---|---|---|
| 1 | Simple cubic | Po |
| 2 | FCC | Si, Cu, Al |
| 3 | BCC | Fe, W, Na |
| 4 | Hexagonal | Graphite, Ti |
| 0 | General (provide CELL_PARAMETERS) | Any |
If you get a structure from Materials Project or a CIF file:
ibrav = 0 ! General cell
CELL_PARAMETERS angstrom
5.431 0.000 0.000
0.000 5.431 0.000
0.000 0.000 5.431
ATOMIC_POSITIONS angstrom
Si 0.000 0.000 0.000
Si 1.358 1.358 1.358
...
Always check pseudopotential recommendations.
If not available, use these guidelines:
| Pseudo Type | ecutwfc | ecutrho |
|---|---|---|
| Norm-conserving (NC) | 60-80 Ry | 4 × ecutwfc |
| Ultrasoft (US) | 30-50 Ry | 8-12 × ecutwfc |
| PAW | 40-60 Ry | 8-12 × ecutwfc |
Test convergence for production calculations.
| System | K-grid |
|---|---|
| Metals | Dense: 12×12×12 or more |
| Semiconductors | Medium: 6×6×6 to 8×8×8 |
| Insulators | Coarse: 4×4×4 often sufficient |
| Molecules/surfaces | Gamma only or few k-points |
For band structure, use crystal_b with high-symmetry path.
# Total energy
grep "!" output.out
# Forces
grep -A 20 "Forces acting" output.out
# Fermi energy
grep "Fermi" output.out
# Band gap (for insulators)
grep "highest occupied" output.out
"Error reading pseudo file"
Convergence failure
Memory issues
Negative frequencies in phonons
Never assume pseudopotentials exist locally.
Every QE calculation requires you to:
If a pseudopotential doesn't exist for your element/functional combination, that's important information to report.
Task: Calculate formation energy of NaCl
Complete workflow:
Get structure
# From Materials Project
mp-22862 → NaCl rock salt structure
Download pseudopotentials
Na.pbe-spn-kjpaw_psl.1.0.0.UPF (ecutwfc=66 Ry)
Cl.pbe-n-rrkjus_psl.1.0.0.UPF (ecutwfc=45 Ry)
Run SCF for NaCl
Run reference calculations
Calculate formation energy
E_f = E(NaCl) - E(Na_metal) - 0.5*E(Cl₂)
Compare to literature
Common pitfall: Forgetting reference calculations. You need ALL of:
See also: examples/workflows/multi-compound-study.md for multi-compound studies