CHAPTER 02 · BASICS · GETTING STARTED

Input file structure

The two-layer pw.x input format: namelists (&CONTROL/&SYSTEM/&ELECTRONS) and cards, dissected on a minimal input.

On this page

Two layers: namelists and cards

A pw.x input consists of two kinds of blocks.

  • Namelists: Fortran namelists such as &CONTROL, &SYSTEM, &ELECTRONS, opened with &NAME and closed with /. Entries are variable = value, and the order is fixed: &CONTROL → &SYSTEM → &ELECTRONS → (&IONS) → (&CELL).
  • Cards: blocks such as ATOMIC_SPECIES, ATOMIC_POSITIONS, K_POINTS, CELL_PARAMETERS, and HUBBARD, with an uppercase title followed by tabular data. They come after the namelists, and some take a unit or option in parentheses, as in ATOMIC_POSITIONS (crystal).

Strings use single quotes ('scf'), logicals are .true./.false., and comments start with !.

A minimal input, dissected: the silicon SCF

Make your first calculation a simple semiconductor like silicon. If you jump straight to an Fe system, you cannot tell whether a convergence failure is physics or a setup error.

&CONTROL
  calculation  = 'scf'        ! scf / nscf / bands / relax / vc-relax / md
  prefix       = 'si'         ! output prefix (must match follow-up runs)
  outdir       = './tmp/'
  pseudo_dir   = './pseudo/'
  verbosity    = 'high'       ! always 'high' while learning
  tprnfor      = .true.       ! print forces
  tstress      = .true.       ! print stress
/
&SYSTEM
  ibrav        = 2            ! fcc; 0 means CELL_PARAMETERS given explicitly
  celldm(1)    = 10.26        ! bohr (= 5.43 Å)
  nat          = 2
  ntyp         = 1
  ecutwfc      = 30           ! Ry, wavefunction cutoff
  ecutrho      = 240          ! Ry, density cutoff (8x for PAW/US)
  occupations  = 'fixed'      ! insulator/semiconductor
/
&ELECTRONS
  conv_thr     = 1.0d-8       ! Ry
  mixing_beta  = 0.7
/

ATOMIC_SPECIES
  Si  28.0855  Si.pbe-n-kjpaw_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)
  8 8 8  0 0 0

What each block is responsible for:

Block Role Details
&CONTROL What to compute and where to write it Calculation types: Chapter 08, Chapter 09
&SYSTEM What the system is (cell, atoms, basis, occupations) Units and coordinates: Chapter 03; occupations: Chapter 06
&ELECTRONS How to converge the SCF Chapter 07
ATOMIC_SPECIES Label, mass, pseudopotential file Chapter 04
ATOMIC_POSITIONS Atomic coordinates (plus optional if_pos flags) Chapter 03
K_POINTS Brillouin-zone sampling Chapter 05

Full card syntax is collected in the R2 card reference.

Running it

pw.x -in si.scf.in > si.scf.out                       # serial
mpirun -np 8 pw.x -nk 4 -in si.scf.in > si.scf.out    # parallel, 4 k-point pools

Output goes to standard output, so redirect it with >. Intermediate files accumulate in outdir/prefix.save/, and follow-up runs (nscf, post-processing) locate that directory through the same prefix and outdir.

Common mistakes

Forgetting the closing / of a namelist raises namelist not found. Double quotes around strings and bare true for logicals are classic parse failures. A typo in a card name shows up as Error in routine card_xxx. Input syntax errors in general are collected in the R3 error dictionary.