quantum-espresso

name	quantum-espresso
description	Generate and manage Quantum ESPRESSO (pw.x) DFT calculations. Use when the user requests QE, Quantum ESPRESSO, pw.x, or plane-wave pseudopotential calculations outside VASP.
compatibility	Requires Quantum ESPRESSO installed on the HPC target. Pseudopotential files (UPF) must be available in the configured pseudo_dir.

Quantum ESPRESSO (pw.x)

When to Use

• User explicitly requests Quantum ESPRESSO / QE / pw.x
• User needs norm-conserving or ultrasoft pseudopotentials (not PAW-only like VASP)
• User wants open-source plane-wave DFT
• User needs ph.x phonon calculations (hand off to analysis/phonopy/SKILL.md for post-processing)

Prerequisites

1. QE binaries (pw.x, pp.x) accessible on HPC
2. Pseudopotential library (SSSP or PseudoDojo recommended) in a known directory
3. Structure loaded in viewer — verify with catgo_view(action="get_state")

Workflow Steps

1. Verify structure

catgo_view(action="get_state")

2. Create workflow

catgo_workflow_engine(action="create", params={"name": "QE relaxation - TiO2"})

3. Add QE task

CatGo does not yet have a native QE engine. Use task_type: "shell" with input file generation.

catgo_workflow_engine(action="add_task", params={
  "workflow_id": "wf_xxx",
  "task_type": "shell",
  "name": "qe_relax",
  "command": "pw.x -in relax.in > relax.out",
  "input_files": {
    "relax.in": "<pw.x input content>"
  },
  "system_name": "TiO2_relax"
})

When a @register_engine("qe") is added to CatGo, use task_type: "geo_opt" with software: "qe" instead.

4. Submit

catgo_workflow_engine(action="submit", params={"workflow_id": "wf_xxx"})

Input File Template — SCF

&CONTROL
  calculation = 'scf'
  pseudo_dir  = './pseudo/'
  outdir      = './tmp/'
  tprnfor     = .true.
  tstress     = .true.
/
&SYSTEM
  ibrav       = 0
  nat         = <natoms>
  ntyp        = <ntypes>
  ecutwfc     = 60.0
  ecutrho     = 480.0
  occupations = 'smearing'
  smearing    = 'mv'
  degauss     = 0.02
/
&ELECTRONS
  conv_thr    = 1.0d-6
  mixing_beta = 0.3
/
ATOMIC_SPECIES
  <element>  <mass>  <element>.UPF
CELL_PARAMETERS angstrom
  <a1x> <a1y> <a1z>
  <a2x> <a2y> <a2z>
  <a3x> <a3y> <a3z>
ATOMIC_POSITIONS angstrom
  <element> <x> <y> <z>
K_POINTS automatic
  <k1> <k2> <k3> 0 0 0

Parameter Guidance

Parameter	Typical value	Notes
ecutwfc	40-80 Ry	Depends on pseudopotential; SSSP suggests per-element values
ecutrho	4-12x ecutwfc	NC: 4x, US: 8-12x
conv_thr	1.0d-6	SCF convergence; tighten to 1.0d-8 for phonons
mixing_beta	0.3-0.7	Lower for metals/magnetic systems
K_POINTS	auto from cell	~0.03 A^-1 spacing, Gamma for molecules
smearing	'mv'	Marzari-Vanderbilt cold smearing; use 'gaussian' for insulators

Relaxation-Specific Parameters

Add to input for geometry optimization:

&CONTROL
  calculation = 'relax'    ! ions only
  ! or 'vc-relax'          ! ions + cell
/
&IONS
  ion_dynamics = 'bfgs'
/
&CELL                      ! only for vc-relax
  cell_dynamics = 'bfgs'
  press = 0.0
/

• Use relax for slabs (fixed cell), vc-relax for bulk
• For slabs: constrain bottom atoms with if_pos flags (0 = fixed)

Common Pitfalls

1. ecutrho too low for US pseudopotentials — NC needs 4x ecutwfc, US needs 8-12x. Check pseudopotential header.
2. Mixing divergence for metals — reduce mixing_beta to 0.1-0.2 and try mixing_mode = 'local-TF'
3. Wrong ibrav — always use ibrav = 0 with explicit CELL_PARAMETERS to avoid ambiguity
4. Missing pseudo files — ensure UPF filenames match ATOMIC_SPECIES exactly (case-sensitive)
5. Slab vacuum too thin — need at least 15 A vacuum; add assume_isolated = '2D' for 2D corrections
6. K-points along vacuum direction — slabs must use k3=1 (single k-point in z)