Quantum ESPRESSO DFT Calculations

You are executing Quantum ESPRESSO density functional theory calculations.

CRITICAL: Pseudopotentials Are NOT Pre-Installed

You must find and download pseudopotentials yourself.

Pseudopotentials are NOT stored locally. You need to:

Determine what elements and functional you need
Find appropriate pseudopotentials online
Download them to your workspace
Reference them in your input file

How to Acquire Pseudopotentials

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:

NC: ecutwfc ~40-80 Ry, ecutrho = 4 × ecutwfc
US: ecutwfc ~30-50 Ry, ecutrho = 8-12 × ecutwfc
PAW: ecutwfc ~40-60 Ry, ecutrho = 8-12 × ecutwfc

Step 6: Reference in input

&CONTROL
    pseudo_dir = './pseudo'
/
ATOMIC_SPECIES
Si  28.0855  Si.pbe-n-rrkjus_psl.1.0.0.UPF

Complete Agentic Workflow

Example: Silicon Band Structure

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
- Search: "silicon PBE pseudopotential SSSP"
- Navigate to SSSP table
- Download Si.pbe-n-rrkjus_psl.1.0.0.UPF
- Note: recommended ecutwfc = 30 Ry

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
- Extract band gap from output
- Si has indirect gap ~0.5 eV (LDA underestimates, exp ~1.1 eV)

Binary Locations

QE binaries are referenced through environment variables, set in config.yaml (keep machine-specific paths out of the repo):

CPU (MPI): $QE_CPU/pw.x. Parallel runs: mpirun -np N $QE_CPU/pw.x -in input.in (set OMP_NUM_THREADS=1 for multi-rank runs to avoid OpenMP oversubscription).

GPU: $QE_GPU/pw.x. Note some GPU builds (e.g. NVHPC OpenACC+CUDA) are serial-only by design — do not mpirun them; check your build.

Sanity-check a new build on a bulk-Si SCF (CPU and GPU energies should agree to ~1e-8 Ry) before trusting production runs.

The old WSL-era builds under ~/work/archive/gpu-tests-wsl/ remain archive-only and unsupported — do not route runs to them.

Archived WSL-era builds (historical record; do NOT execute): The old dead builds live under ~/work/archive/gpu-tests-wsl/1-GPUTests/dft-qe/ ($QE_CPU/$QE_GPU no longer point there — repointed to the 7.5 builds, see .claude/settings.json env and config.yaml). Known failure signatures, kept for diagnosis:

CPU build: error while loading shared libraries: libmpi_mpifh.so.40 (exit 127) — the honest root-cause symptom (OpenMPI-4 runtime rot).
GPU build: liblapack_lp64.so.0 missing — a red herring; the root cause is the same NVHPC/OpenMPI runtime rot, not LAPACK.
Do not source .../env/setup_nvhpc.sh and retry: under the current ~/hpc-sdk hpcx env the binaries hang indefinitely in MPI init instead of failing fast.

Alternatives if local QE is unavailable

Vast.ai cloud — vast-cloud skill, "QE on VAST" section (build-from-source recipe; pay-per-hour, no queue).
CU Alpine — compute-strategy skill → backends/alpine.md (QE via modules on the cluster; owner-sanctioned SSH session required).
MLIP screening substitute — for tasks where DFT accuracy is not the point (relative-energy screening, structure triage), mlip-simulation / torch-sim can stand in; state the substitution and its accuracy limits explicitly in your report. (Requires the ML stack installed — check --verify.)

Calculation Types

| 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) |

Crystal Structure Input

Common ibrav Values

| 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 |

From Materials Project or CIF

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
...

Cutoff Selection

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.

K-point Selection

| 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.

Output Parsing

# 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

Common Issues

"Error reading pseudo file"
- Check pseudo_dir path
- Verify file was downloaded correctly
- Check filename matches ATOMIC_SPECIES
Convergence failure
- Reduce mixing_beta to 0.3-0.5
- Increase ecutwfc
- Check structure for overlapping atoms
Memory issues
- Reduce k-points
- Use disk_io = 'low'
Negative frequencies in phonons
- Structure not fully relaxed
- Reduce forc_conv_thr and re-relax

Key Principle

Never assume pseudopotentials exist locally.

Every QE calculation requires you to:

Identify the elements
Choose appropriate functional
Find and download pseudopotentials
Note recommended cutoffs
Reference correctly in input

If a pseudopotential doesn't exist for your element/functional combination, that's important information to report.

Example: Formation Energy Calculation

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
- ecutwfc = 66 Ry (use max of both elements)
- k-points: 6x6x6 automatic
- Check convergence
Run reference calculations
- Na metal (BCC structure)
- Cl₂ molecule (in large box)

Calculate formation energy

E_f = E(NaCl) - E(Na_metal) - 0.5*E(Cl₂)

Compare to literature
- Expected: ~-4.2 eV/atom
- If different by >10%, investigate

Common pitfall: Forgetting reference calculations. You need ALL of:

The compound (NaCl)
The elemental references (Na metal, Cl₂)

See also: examples/workflows/multi-compound-study.md for multi-compound studies