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:

1. Determine what elements and functional you need
2. Find appropriate pseudopotentials online
3. Download them to your workspace
4. 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

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:

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

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

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

4. Run SCF

   /path/to/pw.x < scf.in > scf.out
   

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

6. Run bands and post-process

   pw.x < bands.in > bands.out
   bands.x < bands_pp.in > bands_pp.out
   

7. Analyze

   • Extract band gap from output
   • Si has indirect gap ~0.5 eV (LDA underestimates, exp ~1.1 eV)

Binary Locations

QE is configured via environment variables (set in .claude/settings.json or shell):

# From environment variables
QE_CPU="${QE_CPU:-/usr/local/qe/bin}"   # CPU build directory
QE_GPU="${QE_GPU:-$QE_CPU}"              # GPU build (optional)

# Check your config
echo $QE_CPU

Execution

CPU:

$QE_CPU/pw.x < input.in > output.out

GPU (first source environment if using NVHPC):

source $QE_ENV_SCRIPT  # If set
$QE_GPU/pw.x < input.in > output.out

Calculation Types

Crystal Structure Input

Common ibrav Values

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:

Test convergence for production calculations.

K-point Selection

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

1. "Error reading pseudo file"

   • Check pseudo_dir path
   • Verify file was downloaded correctly
   • Check filename matches ATOMIC_SPECIES

2. Convergence failure

   • Reduce mixing_beta to 0.3-0.5
   • Increase ecutwfc
   • Check structure for overlapping atoms

3. Memory issues

   • Reduce k-points
   • Use disk_io = 'low'

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

1. Identify the elements
2. Choose appropriate functional
3. Find and download pseudopotentials
4. Note recommended cutoffs
5. Reference correctly in input

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