Input File Description

Program: cp.x / CP / Quantum Espresso

TABLE OF CONTENTS

INTRODUCTION

&CONTROL

calculation | title | verbosity | isave | restart_mode | nstep | iprint | tstress | tprnfor | dt | outdir | saverho | prefix | ndr | ndw | tabps | max_seconds | etot_conv_thr | forc_conv_thr | ekin_conv_thr | disk_io | pseudo_dir | tefield

&SYSTEM

ibrav | celldm | A | B | C | cosAB | cosAC | cosBC | nat | ntyp | nbnd | tot_charge | tot_magnetization | ecutwfc | ecutrho | nr1 | nr2 | nr3 | nr1s | nr2s | nr3s | nr1b | nr2b | nr3b | occupations | degauss | smearing | nspin | ecfixed | qcutz | q2sigma | input_dft | lda_plus_u | Hubbard_U | assume_isolated

&ELECTRONS

electron_maxstep | electron_dynamics | conv_thr | niter_cg_restart | efield | epol | emass | emass_cutoff | orthogonalization | ortho_eps | ortho_max | ortho_para | electron_damping | electron_velocities | electron_temperature | ekincw | fnosee | startingwfc | tcg | maxiter | passop | n_inner | ninter_cold_restart | lambda_cold | grease | ampre

&IONS

ion_dynamics | ion_positions | ion_velocities | ion_nstepe | remove_rigid_rot | ion_temperature | tempw | fnosep | tolp | nhpcl | nhptyp | nhgrp | fnhscl | ndega | tranp | amprp | greasp

&CELL

cell_parameters | cell_dynamics | cell_velocities | cell_damping | press | wmass | cell_factor | cell_temperature | temph | fnoseh | greash | cell_dofree

&PRESS_AI

abivol | abivol | P_ext | pvar | P_in | P_fin | Surf_t | rho_thr | dthr

&WANNIER

wf_efield | wf_switch | sw_len | efx0 | efy0 | efz0 | efx1 | efy1 | efz1 | wfsd | wfdt | maxwfdt | nit | nsd | wf_q | wf_friction | nsteps | tolw | adapt | calwf | nwf | wffort | writev

ATOMIC_SPECIES

X | Mass_X | PseudoPot_X

ATOMIC_POSITIONS

X | x | y | z | if_pos(1) | if_pos(2) | if_pos(3)

ATOMIC_VELOCITIES

V | vx | vy | vz

CELL_PARAMETERS

v1 | v2 | v3

CONSTRAINTS

nconstr | constr_tol | constr_type | constr(1) | constr(2) | constr(3) | constr(4) | constr_target

OCCUPATIONS

f_inp1 | f_inp2

PLOT_WANNIER

iwf

INTRODUCTION

Input data format: { } = optional, [ ] = it depends, | = or

All quantities whose dimensions are not explicitly specified are in
HARTREE ATOMIC UNITS

BEWARE: TABS, DOS <CR><LF> CHARACTERS ARE POTENTIAL SOURCES OF TROUBLE
Comment lines in namelists can be introduced by a "!", exactly as in
fortran code. Comments lines in ``cards'' can be introduced either by
a "!" or a "#" character in the first position of a line.

Structure of the input data:
===============================================================================

&CONTROL
  ...
/

&SYSTEM
 ...
/

&ELECTRONS
...
/

[ &IONS
  ...
 / ]

[ &CELL
  ...
 / ]

[ &WANNIER
  ...
 / ]

ATOMIC_SPECIES
 X  Mass_X  PseudoPot_X
 Y  Mass_Y  PseudoPot_Y
 Z  Mass_Z  PseudoPot_Z

ATOMIC_POSITIONS { alat | bohr | crystal | angstrom }
  X 0.0  0.0  0.0  {if_pos(1) if_pos(2) if_pos(3)}
  Y 0.5  0.0  0.0
  Z O.0  0.2  0.2

[ CELL_PARAMETERS { bohr | angstrom }
   v1(1) v1(2) v1(3)
   v2(1) v2(2) v2(3)
   v3(1) v3(2) v3(3) ]

[ OCCUPATIONS
   f_inp1(1)  f_inp1(2)  f_inp1(3) ... f_inp1(10)
   f_inp1(11) f_inp1(12) ... f_inp1(nbnd)
 [ f_inp2(1)  f_inp2(2)  f_inp2(3) ... f_inp2(10)
   f_inp2(11) f_inp2(12) ... f_inp2(nbnd) ] ]

[ CONSTRAINTS
   nconstr  { constr_tol }
   constr_type(.)   constr(1,.)   constr(2,.) [ constr(3,.)   constr(4,.) ] { constr_target(.) } ]
   

Namelist: CONTROL

calculation CHARACTER
Default: 'cp'
a string describing the task to be performed:
   'cp',
   'scf',
   'nscf',
   'relax',
   'vc-relax',
   'vc-cp',
   'cp-wf'

   (vc = variable-cell).
         
title CHARACTER
Default: 'MD Simulation '
reprinted on output.
         
verbosity CHARACTER
Default: 'low'
In order of decreasing verbose output:
 'debug' | 'high' | 'medium' | 'low','default' | 'minimal'
         
isave INTEGER
Default: 100
See: ndr
See: ndw
Number of steps between successive savings of
information needed to restart the run.
         
restart_mode CHARACTER
Default: 'restart'
'from_scratch'   : from scratch
'restart'        : from previous interrupted run
'reset_counters' : continue a previous simulation,
                   performs  "nstep" new steps, resetting
                   the counter and averages
         
nstep INTEGER
Default: 1 if calculation = 'scf', 'nscf', 'bands'; 50 for the other cases
number of ionic + electronic steps
         
iprint INTEGER
Default: 10
Number of steps between successive writings of relevant
physical quantities to standard output and to files "fort.3?"
or "prefix.???" depending on "prefix" parameter
         
tstress LOGICAL
Default: .false.
Write stress tensor to standard output each "iprint" steps.
It is set to .TRUE. automatically if
calculation='vc-relax'
         
tprnfor LOGICAL
Default: .false.
print forces. Set to .TRUE. when ions are moving.
         
dt REAL
Default: 1.D0
time step for molecular dynamics, in Hartree atomic units
(1 a.u.=2.4189 * 10^-17 s : beware, PW code use
 Rydberg atomic units, twice that much!!!)
         
outdir CHARACTER
Default: value of the ESPRESSO_TMPDIR environment variable if set; current directory ('./') otherwise
input, temporary, trajectories and output files are found
in this directory.
         
saverho LOGICAL
This flag controls the saving of charge density in CP codes:
If  .TRUE.        save charge density to restart dir,
If .FALSE. do not save charge density.
         
prefix CHARACTER
Default: 'cp'
prepended to input/output filenames:
prefix.pos, prefix.vel, etc.
         
ndr INTEGER
Default: 50
Units for input and output restart file.
         
ndw INTEGER
Default: 50
Units for input and output restart file.
         
tabps LOGICAL
Default: .false.
.true. to compute the volume and/or the surface of an isolated
system for finete pressure/finite surface tension calculations
(PRL 94, 145501 (2005); JCP 124, 074103 (2006)).
         
max_seconds REAL
Default: 1.D+7, or 150 days, i.e. no time limit
jobs stops after max_seconds CPU time. Used to prevent
a hard kill from the queuing system.
         
etot_conv_thr REAL
Default: 1.0D-4
convergence threshold on total energy (a.u) for ionic
minimization: the convergence criterion is satisfied
when the total energy changes less than etot_conv_thr
between two consecutive scf steps.
See also forc_conv_thr - both criteria must be satisfied
         
forc_conv_thr REAL
Default: 1.0D-3
convergence threshold on forces (a.u) for ionic
minimization: the convergence criterion is satisfied
when all components of all forces are smaller than
forc_conv_thr.
See also etot_conv_thr - both criteria must be satisfied
         
ekin_conv_thr REAL
Default: 1.0D-6
convergence criterion for electron minimization:
convergence is achieved when "ekin < ekin_conv_thr".
See also etot_conv_thr - both criteria must be satisfied.
         
disk_io CHARACTER
'high', 'default'

'high': CP code will write Kohn-Sham wf files and additional
        information in data-file.xml in order to restart
        with a PW calculation or to use postprocessing tools.
         
pseudo_dir CHARACTER
Default: value of the $ESPRESSO_PSEUDO environment variable if set; '$HOME/espresso/pseudo/' otherwise
directory containing pseudopotential files
         
tefield LOGICAL
Default: .FALSE.
If .TRUE. a homogeneous finite electric field described
through the modern theory of the polarization is applied.
         

Namelist: SYSTEM

ibrav INTEGER
Status: REQUIRED
Bravais-lattice index:

  ibrav        structure                   celldm(2)-celldm(6)

    0          "free", see above                 not used
    1          cubic P (sc)                      not used
    2          cubic F (fcc)                     not used
    3          cubic I (bcc)                     not used
    4          Hexagonal and Trigonal P        celldm(3)=c/a
    5          Trigonal R                      celldm(4)=cos(alpha)
    6          Tetragonal P (st)               celldm(3)=c/a
    7          Tetragonal I (bct)              celldm(3)=c/a
    8          Orthorhombic P                  celldm(2)=b/a,celldm(3)=c/a
    9          Orthorhombic base-centered(bco) celldm(2)=b/a,celldm(3)=c/a
   10          Orthorhombic face-centered      celldm(2)=b/a,celldm(3)=c/a
   11          Orthorhombic body-centered      celldm(2)=b/a,celldm(3)=c/a
   12          Monoclinic P                    celldm(2)=b/a,celldm(3)=c/a,
                                               celldm(4)=cos(ab)
   13          Monoclinic base-centered        celldm(2)=b/a,celldm(3)=c/a,
                                               celldm(4)=cos(ab)
   14          Triclinic                       celldm(2)= b/a,
                                               celldm(3)= c/a,
                                               celldm(4)= cos(bc),
                                               celldm(5)= cos(ac),
                                               celldm(6)= cos(ab)

For P lattices: the special axis (c) is the z-axis, one basal-plane
vector (a) is along x, the other basal-plane vector (b) is at angle
gamma for monoclinic, at 120 degrees for trigonal and hexagonal
lattices, at 90 degrees for cubic, tetragonal, orthorhombic lattices

sc simple cubic
====================
v1 = a(1,0,0),  v2 = a(0,1,0),  v3 = a(0,0,1)

fcc face centered cubic
====================
v1 = (a/2)(-1,0,1),  v2 = (a/2)(0,1,1), v3 = (a/2)(-1,1,0).

bcc body entered cubic
====================
v1 = (a/2)(1,1,1),  v2 = (a/2)(-1,1,1),  v3 = (a/2)(-1,-1,1).

simple hexagonal and trigonal(p)
====================
v1 = a(1,0,0),  v2 = a(-1/2,sqrt(3)/2,0),  v3 = a(0,0,c/a).

trigonal(r)
===================
for these groups, the z-axis is chosen as the 3-fold axis, but the
crystallographic vectors form a three-fold star around the z-axis,
and the primitive cell is a simple rhombohedron. The crystallographic
vectors are:
      v1 = a(tx,-ty,tz),   v2 = a(0,2ty,tz),   v3 = a(-tx,-ty,tz).
where c=cos(alpha) is the cosine of the angle alpha between any pair
of crystallographic vectors, tc, ty, tz are defined as
     tx=sqrt((1-c)/2), ty=sqrt((1-c)/6), tz=sqrt((1+2c)/3)

simple tetragonal (p)
====================
   v1 = a(1,0,0),  v2 = a(0,1,0),  v3 = a(0,0,c/a)

body centered tetragonal (i)
================================
   v1 = (a/2)(1,-1,c/a),  v2 = (a/2)(1,1,c/a),  v3 = (a/2)(-1,-1,c/a).

simple orthorhombic (p)
=============================
   v1 = (a,0,0),  v2 = (0,b,0), v3 = (0,0,c)

bco base centered orthorhombic
=============================
   v1 = (a/2,b/2,0),  v2 = (-a/2,b/2,0),  v3 = (0,0,c)

face centered orthorhombic
=============================
   v1 = (a/2,0,c/2),  v2 = (a/2,b/2,0),  v3 = (0,b/2,c/2)

body centered orthorhombic
=============================
   v1 = (a/2,b/2,c/2),  v2 = (-a/2,b/2,c/2),  v3 = (-a/2,-b/2,c/2)

monoclinic (p)
=============================
   v1 = (a,0,0), v2= (b*cos(gamma), b*sin(gamma), 0),  v3 = (0, 0, c)
where gamma is the angle between axis a and b

base centered monoclinic
=============================
   v1 = (  a/2,         0,                -c/2),
   v2 = (b*cos(gamma), b*sin(gamma), 0),
   v3 = (  a/2,         0,                  c/2),
where gamma is the angle between axis a and b

triclinic
=============================
   v1 = (a, 0, 0),
   v2 = (b*cos(gamma), b*sin(gamma), 0)
   v3 = (c*cos(beta),  c*(cos(alpha)-cos(beta)cos(gamma))/sin(gamma),
         c*sqrt( 1 + 2*cos(alpha)cos(beta)cos(gamma)
                   - cos(alpha)^2-cos(beta)^2-cos(gamma)^2 )/sin(gamma) )
where alpha is the angle between axis b and c
       beta is the angle between axis a and c
      gamma is the angle between axis a and b
         
Either:

celldm(i), i=1,6 REAL
See: ibrav
Crystallographic constants - see description of ibrav variable.

* alat = celldm(1) is the lattice parameter "a" (in BOHR)
* only needed celldm (depending on ibrav) must be specified
* if ibrav=0 only alat = celldm(1) is used (if present)
            
Or:

A, B, C, cosAB, cosAC, cosBC REAL
Traditional crystallographic constants (a,b,c in ANGSTROM),
cosab = cosine of the angle between axis a and b
specify either these OR celldm but NOT both.

The axis are chosen according to the value of ibrav.
If ibrav is not specified, the axis are taken from card
CELL_PARAMETERS and only a is used as lattice parameter.
            
nat INTEGER
Status: REQUIRED
number of atoms in the unit cell
         
ntyp INTEGER
Status: REQUIRED
number of types of atoms in the unit cell
         
nbnd INTEGER
Default: for an insulator, nbnd = number of valence bands (nbnd = # of electrons /2); for a metal, 20% more (minimum 4 more)
number of electronic states (bands) to be calculated.
Note that in spin-polarized calculations the number of
k-point, not the number of bands per k-point, is doubled
         
tot_charge REAL
Default: 0.0
total charge of the system. Useful for simulations with charged cells.
By default the unit cell is assumed to be neutral (tot_charge=0).
tot_charge=+1 means one electron missing from the system,
tot_charge=-1 means one additional electron, and so on.

In a periodic calculation a compensating jellium background is
inserted to remove divergences if the cell is not neutral.
         
tot_magnetization REAL
Default: -1 [unspecified]
total majority spin charge - minority spin charge.
Used to impose a specific total electronic magnetization.
If unspecified, the tot_magnetization variable is ignored
and the electronic magnetization is determined by the
occupation numbers (see card OCCUPATIONS) read from input.
         
ecutwfc REAL
Status: REQUIRED
kinetic energy cutoff (Ry) for wavefunctions
         
ecutrho REAL
Default: 4 * ecutwfc
kinetic energy cutoff (Ry) for charge density and potential
For norm-conserving pseudopotential you should stick to the
default value, you can reduce it by a little but it will
introduce noise especially on forces and stress.
If there are ultrasoft PP, a larger value than the default is
often desirable (ecutrho = 8 to 12 times ecutwfc, typically).
PAW datasets can often be used at 4*ecutwfc, but it depends
on the shape of augmentation charge: testing is mandatory.
The use of gradient-corrected functional, especially in cells
with vacuum, or for pseudopotential without non-linear core
correction, usually requires an higher values of ecutrho
to be accurately converged.
         
nr1, nr2, nr3 INTEGER
See: ecutrho
three-dimensional FFT mesh (hard grid) for charge
density (and scf potential). If not specified
the grid is calculated based on the cutoff for
charge density.
         
nr1s, nr2s, nr3s INTEGER
three-dimensional mesh for wavefunction FFT and for the smooth
part of charge density ( smooth grid ).
Coincides with nr1, nr2, nr3 if ecutrho = 4 * ecutwfc ( default )
         
nr1b, nr2b, nr3b INTEGER
dimensions of the "box" grid for Ultrasoft pseudopotentials
must be specified if Ultrasoft PP are present
         
occupations CHARACTER
a string describing the occupation of the electronic states.
In the case of conjugate gradient style of minimization
of the electronic states, if occupations is set to 'ensemble',
this allows ensemble DFT calculations for metallic systems
         
degauss REAL
Default: 0.D0 Ry
parameter for the smearing function, only used for ensemble DFT
calculations
         
smearing CHARACTER
a string describing the kind of occupations for electronic states
in the case of ensemble DFT (occupations == 'ensemble' );
now only Fermi-Dirac ('fd') case is implemented
         
nspin INTEGER
Default: 1
nspin = 1 :  non-polarized calculation (default)

nspin = 2 :  spin-polarized calculation, LSDA
             (magnetization along z axis)
         
ecfixed REAL
Default: 0.0
See: q2sigma
qcutz REAL
Default: 0.0
See: q2sigma
q2sigma REAL
Default: 0.1
ecfixed, qcutz, q2sigma:  parameters for modified functional to be
used in variable-cell molecular dynamics (or in stress calculation).
"ecfixed" is the value (in Rydberg) of the constant-cutoff;
"qcutz" and "q2sigma" are the height and the width (in Rydberg)
of the energy step for reciprocal vectors whose square modulus
is greater than "ecfixed". In the kinetic energy, G^2 is
replaced by G^2 + qcutz * (1 + erf ( (G^2 - ecfixed)/q2sigma) )
See: M. Bernasconi et al, J. Phys. Chem. Solids 56, 501 (1995)
         
input_dft CHARACTER
Default: read from pseudopotential files
Exchange-correlation functional: eg 'PBE', 'BLYP' etc
See Modules/functionals.f90 for allowed values.
Overrides the value read from pseudopotential files.
Use with care and if you know what you are doing!
         
lda_plus_u LOGICAL
Default: .FALSE.
lda_plus_u = .TRUE. enables calculation with LDA+U
                  ("rotationally invariant"). See also Hubbard_U.
                  Anisimov, Zaanen, and Andersen, PRB 44, 943 (1991);
                  Anisimov et al., PRB 48, 16929 (1993);
                  Liechtenstein, Anisimov, and Zaanen, PRB 52, R5467 (1994);
                  Cococcioni and de Gironcoli, PRB 71, 035105 (2005).
         
Hubbard_U(i), i=1,ntyp REAL
Default: 0.D0 for all species
Status: LDA+U works only for a few selected elements. Modify CPV/ldaU.f90 if you plan to use LDA+U with an element that is not configured there.
Hubbard_U(i): parameter U (in eV) for LDA+U calculations.
Currently only the simpler, one-parameter LDA+U is
implemented (no "alpha" or "J" terms)
         
assume_isolated CHARACTER
Default: 'none'
Used to perform calculation assuming the system to be
isolated (a molecule of a clustr in a 3D supercell).

Currently available choices:

'none' (default): regular periodic calculation w/o any correction.

'makov-payne', 'm-p', 'mp' : the Makov-Payne correction to the
         total energy is computed.
         Theory:
         G.Makov, and M.C.Payne,
         "Periodic boundary conditions in ab initio
         calculations" , Phys.Rev.B 51, 4014 (1995)
         

Namelist: ELECTRONS

electron_maxstep INTEGER
Default: 100
maximum number of iterations in a scf step
         
electron_dynamics CHARACTER
Default: 'none'
set how electrons should be moved
'none'    : electronic degrees of freedom (d.o.f.) are kept fixed
'sd'      : steepest descent algorithm is used to minimize
          electronic d.o.f.
'damp'    : damped dynamics is used to propagate electronic d.o.f.
'verlet'  : standard Verlet algorithm is used to propagate
          electronic d.o.f.
'cg'      : conjugate gradient is used to converge the
          wavefunction at each ionic step. 'cg' can be used
          interchangeably with 'verlet' for a couple of ionic
          steps in order to "cool down" the electrons and
          return them back to the Born-Oppenheimer surface.
          Then 'verlet' can be restarted again. This procedure
          is useful when electronic adiabaticity in CP is lost
          yet the ionic velocities need to be preserved.
         
conv_thr REAL
Default: 1.D-6
Convergence threshold for selfconsistency:
estimated energy error < conv_thr
         
niter_cg_restart INTEGER
Default: 20
frequency in iterations for which the conjugate-gradient algorithm
for electronic relaxation is restarted
         
efield REAL
Default: 0.D0
Amplitude of the finite electric field (in a.u.;
1 a.u. = 51.4220632*10^10 V/m). Used only if tefield=.TRUE.
         
epol INTEGER
Default: 3
direction of the finite electric field (only if tefield == .TRUE.)
In the case of a PARALLEL calculation only the case epol==3
is implemented
         
emass REAL
Default: 400.D0
effective electron mass in the CP Lagrangian, in atomic units
( 1 a.u. of mass = 1/1822.9 a.m.u. = 9.10939 * 10^-31 kg )
         
emass_cutoff REAL
Default: 2.5D0
mass cut-off (in Rydberg) for the Fourier acceleration
effective mass is rescaled for "G" vector components with
kinetic energy above "emass_cutoff"
         
orthogonalization CHARACTER
Default: 'ortho'
selects the orthonormalization method for electronic wave
functions
'ortho'        : use iterative algorithm - if it doesn't converge,
                 reduce the timestep, or use options ortho_max
                 and ortho_eps, or use Gram-Schmidt instead just
                 to start the simulation
'Gram-Schmidt' : use Gram-Schmidt algorithm - to be used ONLY in
                 the first few steps.
                 YIELDS INCORRECT ENERGIES AND EIGENVALUES.
         
ortho_eps REAL
Default: 1.D-8
tolerance for iterative orthonormalization
meaningful only if orthogonalization = 'ortho'
         
ortho_max INTEGER
Default: 20
maximum number of iterations for orthonormalization
meaningful only if orthogonalization = 'ortho'
         
ortho_para INTEGER
Default: 0
Status: OBSOLETE: use command-line option " -ndiag XX" instead

         
electron_damping REAL
Default: 0.1D0
damping frequency times delta t, optimal values could be
calculated with the formula :
         SQRT( 0.5 * LOG( ( E1 - E2 ) / ( E2 - E3 ) ) )
where E1, E2, E3 are successive values of the DFT total energy
in a steepest descent simulations.
meaningful only if " electron_dynamics = 'damp' "
         
electron_velocities CHARACTER
'zero'      : restart setting electronic velocities to zero
'default'   : restart using electronic velocities of the
            previous run
         
electron_temperature CHARACTER
Default: 'not_controlled'
'nose'            : control electronic temperature using Nose
                  thermostat. See also "fnosee" and "ekincw".
'rescaling'       : control electronic temperature via velocities
                  rescaling.
'not_controlled'  : electronic temperature is not controlled.
         
ekincw REAL
Default: 0.001D0
value of the average kinetic energy (in atomic units) forced
by the temperature control
meaningful only with " electron_temperature /= 'not_controlled' "
         
fnosee REAL
Default: 1.D0
oscillation frequency of the nose thermostat (in terahertz)
meaningful only with " electron_temperature = 'nose' "
         
startingwfc CHARACTER
Default: 'random'
'atomic': start from superposition of atomic orbitals
          (not yet implemented)


'random': start from random wfcs. See "ampre".
         
tcg LOGICAL
Default: .FALSE.
if .TRUE. perform a conjugate gradient minimization of the
electronic states for every ionic step.
It requires Gram-Schmidt orthogonalization of the electronic
states.
         
maxiter INTEGER
Default: 100
maximum number of conjugate gradient iterations for
conjugate gradient minimizations of electronic states
         
passop REAL
Default: 0.3D0
small step used in the  conjugate gradient minimization
of the electronic states.
         
n_inner INTEGER
Default: 2
number of internal cycles for every conjugate gradient
iteration only for ensemble DFT
         
ninter_cold_restart INTEGER
Default: 1
frequency in iterations at which a full inner cycle, only
for cold smearing, is performed
         
lambda_cold REAL
Default: 0.03D0
step for inner cycle with cold smearing, used when a not full
cycle is performed
         
grease REAL
Default: 1.D0
a number <= 1, very close to 1: the damping in electronic
damped dynamics is multiplied at each time step by "grease"
(avoids overdamping close to convergence: Obsolete ?)
grease = 1 : normal damped dynamics
         
ampre REAL
Default: 0.D0
amplitude of the randomization ( allowed values: 0.0 - 1.0 )
meaningful only if " startingwfc = 'random' "
         

Namelist: IONS

input this namelist only if calculation = 'cp', 'relax', 'vc-relax', 'vc_cp'

ion_dynamics CHARACTER
 Specify the type of ionic dynamics.

 For constrained dynamics or constrained optimisations add the
 CONSTRAINTS card (when the card is present the SHAKE algorithm is
                   automatically used).
'none'    : ions are kept fixed
'sd'      : steepest descent algorithm is used to minimize ionic
            configuration
'cg'      : conjugate gradient algorithm is used to minimize ionic
            configuration
'damp'    : damped dynamics is used to propagate ions
'verlet'  : standard Verlet algorithm is used to propagate ions
         
ion_positions CHARACTER
Default: 'default'
'default '  : if restarting, use atomic positions read from the
              restart file; in all other cases, use atomic
              positions from standard input.

'from_input' : restart the simulation with atomic positions read
              from standard input, even if restarting.
         
ion_velocities CHARACTER
Default: 'default'
See: tempw
initial ionic velocities
'default'     : restart the simulation with atomic velocities read
                from the restart file
'change_step' : restart the simulation with atomic velocities read
                from the restart file, with rescaling due to the
                timestep change, specify the old step via tolp
                as in tolp = 'old_time_step_value' in au
'random'      : start the simulation with random atomic velocities
'from_input'  : restart the simulation with atomic velocities read
                from standard input
                ( see the card 'ATOMIC_VELOCITIES' )
'zero'        : restart the simulation with atomic velocities set
                to zero
         
ion_nstepe INTEGER
Default: 1
number of electronic steps per ionic step.
         
remove_rigid_rot LOGICAL
Default: .FALSE.
This keyword is useful when simulating the dynamics and/or the
thermodynamics of an isolated system. If set to true the total
torque of the internal forces is set to zero by adding new forces
that compensate the spurious interaction with the periodic
images. This allows for the use of smaller supercells.

BEWARE: since the potential energy is no longer consistent with
the forces (it still contains the spurious interaction with the
repeated images), the total energy is not conserved anymore.
However the dynamical and thermodynamical properties should be
in closer agreement with those of an isolated system.
Also the final energy of a structural relaxation will be higher,
but the relaxation itself should be faster.
         
ion_temperature CHARACTER
Default: 'not_controlled'
'nose'           : control ionic temperature using Nose-Hoover
                   thermostat  see parameters "fnosep", "tempw",
                   "nhpcl", "ndega", "nhptyp"
'rescaling'      : control ionic temperature via velocities
                   rescaling. see parameter "tolp"
'not_controlled' : ionic temperature is not controlled
         
tempw REAL
Default: 300.D0
value of the ionic temperature (in Kelvin) forced by the
temperature control.
meaningful only with " ion_temperature /= 'not_controlled' "
or when the initial velocities are set to 'random'
"ndega" controls number of degrees of freedom used in
temperature calculation
         
fnosep REAL
Default: 1.D0
oscillation frequency of the nose thermostat (in terahertz)
[note that 3 terahertz = 100 cm^-1]
meaningful only with " ion_temperature = 'nose' "
for Nose-Hoover chain one can set frequencies of all thermostats
( fnosep = X Y Z etc. ) If only first is set, the defaults for
the others will be same.
         
tolp REAL
Default: 100.D0
tolerance (in Kelvin) of the rescaling. When ionic temperature
differs from "tempw" more than "tolp" apply rescaling.
meaningful only with " ion_temperature = 'rescaling' "
and with ion_velocities='change_step', where it specifies
the old timestep
         
nhpcl INTEGER
Default: 1
number of thermostats in the Nose-Hoover chain
currently maximum allowed is 4
         
nhptyp INTEGER
Default: 0
type of the "massive" Nose-Hoover chain thermostat
nhptyp=1 uses a NH chain per each atomic type
nhptyp=2 uses a NH chain per atom, this one is useful
for extremely rapid equipartitioning (equilibration is a
different beast)
nhptyp=3 together with nhgrp allows fine grained thermostat
control
NOTE: if using more than 1 thermostat per system there will
be a common thermostat added on top of them all, to disable
this common thermostat specify nhptyp=-X instead of nhptyp=X
         
nhgrp(i), i=1,ntyp INTEGER
Default: 0
specifies which thermostat group to use for given atomic type
when >0 assigns all the atoms in this type to thermostat
labeled nhgrp(i), when =0 each atom in the type gets its own
thermostat. Finally, when <0, then this atomic type will have
temperature "not controlled". Example: HCOOLi, with types H (1), C(2), O(3), Li(4);
setting nhgrp={2 2 0 -1} will add a common thermostat for both H & C,
one thermostat per each O (2 in total), and a non-updated thermostat
for Li which will effectively make temperature for Li "not controlled"
         
fnhscl(i), i=1,ntyp REAL
Default: (Nat_{total}-1)/Nat_{total}
these are the scaling factors to be used together with nhptyp=3 and nhgrp(i)
in order to take care of possible reduction in the degrees of freedom due to
constraints. Suppose that with the previous example HCOOLi, C-H bond is
constrained. Then, these 2 atoms will have 5 degrees of freedom in total instead
of 6, and one can set fnhscl={5/6 5/6 1. 1.}. This way the target kinetic energy
for H&C will become 6(kT/2)*5/6 = 5(kT/2). This option is to be used for
simulations with many constraints, such as rigid water with something else in there
         
ndega INTEGER
Default: 0
number of degrees of freedom used for temperature calculation
ndega <= 0 sets the number of degrees of freedom to
[3*nat-abs(ndega)], ndega > 0 is used as the target number
         
tranp(i), i=1,ntyp LOGICAL
Default: .false.
See: amprp
If .TRUE. randomize ionic positions for the
atomic type corresponding to the index.
         
amprp(i), i=1,ntyp REAL
Default: 0.D0
See: amprp
amplitude of the randomization for the atomic type corresponding
to the index i ( allowed values: 0.0 - 1.0 ).
meaningful only if " tranp(i) = .TRUE.".
         
greasp REAL
Default: 1.D0
same as "grease", for ionic damped dynamics.
         

Namelist: CELL

input this namelist only if calculation = 'vc-relax', 'vc-cp'

cell_parameters CHARACTER
'default'      : restart the simulation with cell parameters read
               from the restart file or "celldm" if
               "restart = 'from_scratch'"
'from_input'   : restart the simulation with cell parameters
               from standard input.
               ( see the card 'CELL_PARAMETERS' )
         
cell_dynamics CHARACTER
Default: 'none'
set how cell should be moved
'none'      : cell is kept fixed
'sd'        : steepest descent algorithm is used to optimise the
              cell
'damp-pr'   : damped dynamics is used to optimise the cell
              ( Parrinello-Rahman method ).
'pr'        : standard Verlet algorithm is used to propagate
              the cell ( Parrinello-Rahman method ).
         
cell_velocities CHARACTER
'zero'      : restart setting cell velocity to zero
'default'   : restart using cell velocity of the previous run
         
cell_damping REAL
Default: 0.1D0
damping frequency times delta t, optimal values could be
calculated with the formula :
         SQRT( 0.5 * LOG( ( E1 - E2 ) / ( E2 - E3 ) ) )
where E1, E2, E3 are successive values of the DFT total energy
in a steepest descent simulations.
meaningful only if " cell_dynamics = 'damp' "
         
press REAL
Default: 0.D0
Target pressure [KBar] in a variable-cell md or relaxation run.
         
wmass REAL
Default: 0.75*Tot_Mass/pi**2 for Parrinello-Rahman MD; 0.75*Tot_Mass/pi**2/Omega**(2/3) for Wentzcovitch MD
Fictitious cell mass [amu] for variable-cell simulations
(both 'vc-md' and 'vc-relax')
         
cell_factor REAL
Default: 1.2D0
Used in the construction of the pseudopotential tables.
It should exceed the maximum linear contraction of the
cell during a simulation.
         
cell_temperature CHARACTER
Default: 'not_controlled'
'nose'            : control cell temperature using Nose thermostat
                    see parameters "fnoseh" and "temph".
'rescaling'       : control cell temperature via velocities
                    rescaling.
'not_controlled'  : cell temperature is not controlled.
         
temph REAL
Default: 0.D0
value of the cell temperature (in ???) forced
by the temperature control.
meaningful only with " cell_temperature /= 'not_controlled' "
         
fnoseh REAL
Default: 1.D0
oscillation frequency of the nose thermostat (in terahertz)
meaningful only with " cell_temperature = 'nose' "
         
greash REAL
Default: 1.D0
same as "grease", for cell damped dynamics
         
cell_dofree CHARACTER
Default: 'all'
Select which of the cell parameters should be moved:

all     = all axis and angles are moved
x       = only the x component of axis 1 (v1_x) is moved
y       = only the y component of axis 2 (v2_y) is moved
z       = only the z component of axis 3 (v3_z) is moved
xy      = only v1_x and v_2y are moved
xz      = only v1_x and v_3z are moved
yz      = only v2_x and v_3z are moved
xyz     = only v1_x, v2_x, v_3z are moved
shape   = all axis and angles, keeping the volume fixed

Beware: if axis are not orthogonal, some of the above options
        will break symmetry
         

Namelist: PRESS_AI

input this namelist only when tabps = .true.

abivol LOGICAL
Default: .false.
.true. for finite pressure calculations
         
abivol LOGICAL
Default: .false.
.true. for finite surface tension calculations
         
P_ext REAL
Default: 0.D0
external pressure in GPa
         
pvar LOGICAL
Default: .false.
.true. for variable pressure calculations
pressure changes linearly with time:
Delta_P = (P_fin - P_in)/nstep
         
P_in REAL
Default: 0.D0
only if pvar = .true.
initial value of the external pressure (GPa)
         
P_fin REAL
Default: 0.D0
only if pvar = .true.
final value of the external pressure (GPa)
         
Surf_t REAL
Default: 0.D0
Surface tension (in a.u.; typical values 1.d-4 - 1.d-3)
         
rho_thr REAL
Default: 0.D0
threshold parameter which defines the electronic charge density
isosurface to compute the 'quantum' volume of the system
(typical values: 1.d-4 - 1.d-3)
(corresponds to alpha in PRL 94 145501 (2005))
         
dthr REAL
Default: 0.D0
thikness of the external skin of the electronic charge density
used to compute the 'quantum' surface
(typical values: 1.d-4 - 1.d-3; 50% to 100% of rho_thr)
(corresponds to Delta in PRL 94 145501 (2005))
         

Namelist: WANNIER

only if calculation = 'cp-wf'

Output files used by Wannier Function options are the following

      fort.21: Used only when calwf=5, contains the full list of g-vecs.
      fort.22: Used Only when calwf=5, contains the coeffs. corresponding
               to the g-vectors in fort.21
      fort.24: Used with calwf=3,contains the average spread
      fort.25: Used with calwf=3, contains the individual Wannier
               Function Spread of each state
      fort.26: Used with calwf=3, contains the wannier centers along a
               trajectory.
      fort.27: Used with calwf=3 and 4,  contains some general runtime
               information from ddyn, the subroutine that actually
               does the localization of the orbitals.
      fort.28: Used only if efield=.TRUE. , contains the polarization
               contribution to the total energy.

Also, The center of mass is fixed during the Molecular Dynamics.

BEWARE : THIS WILL ONLY WORK IF THE NUMBER OF PROCESSORS IS LESS THAN OR
         EQUAL TO THE NUMBER OF STATES.

Nota Bene 1:   For calwf = 5, wffort is not used. The
               Wannier/Wave(function) coefficients are written to unit 22
               and the corresponding g-vectors (basis vectors) are
               written to unit 21. This option gives the g-vecs and
               their coeffs. in reciprocal space, and the coeffs. are
               complex. You will have to convert them to real space
               if you want to plot them for visualization. calwf=1 gives
               the orbital densities in real space, and this is usually
               good enough for visualization.
      
wf_efield LOGICAL
Default: .false.
If dynamics will be done in the presence of a field
         
wf_switch LOGICAL
Default: .false.
Whether to turn on the field adiabatically (adiabatic switch)
if true, then nbeg is set to 0.
         
sw_len INTEGER
Default: 1
No. of iterations over which the field will be turned on
to its final value. Starting value is 0.0
If sw_len < 0, then it is set to 1.
If you want to just optimize structures on the presence of a
field, then you may set this to 1 and run a regular geometry
optimization.
         
efx0, efy0, efz0 REAL
See: 0.D0
Initial values of the field along x, y, and z directions
         
efx1, efy1, efz1 REAL
See: 0.D0
Final values of the field along x, y, and z directions
         
wfsd INTEGER
Default: 1
Localization algorithm for Wannier function calculation:
wfsd=1  Steepest-Descent / Conjugate-Gradient
wfsd=2  Damped Dynamics
wfsd=3  Jocobi Rotation
Remember, this is consistent with all the calwf options
as well as the tolw (see below).
Not a good idea to Wannier dynamics with this if you are
using restart='from_scratch' option, since the spreads
converge fast in the beginning and ortho goes bananas.
         
wfdt REAL
Default: 5.D0
The minimum step size to take in the SD/CG direction
         
maxwfdt REAL
Default: 0.3D0
The maximum step size to take in the SD/CG direction
The code calculates an optimum step size, but that may be
either too small (takes forever to converge)  or too large
(code goes crazy) . This option keeps the step size between
wfdt and maxwfdt. In my experience 0.1 and 0.5 work quite
well. (but don't blame me if it doesn't work for you)
         
nit INTEGER
Default: 10
Number of iterations to do for Wannier convergence.
         
nsd INTEGER
Default: 10
Out of a total of NIT iterations, NSD will be Steepest-Descent
and ( nit - nsd ) will be Conjugate-Gradient.
         
wf_q REAL
Default: 1500.D0
Fictitious mass of the A matrix used for obtaining
maximally localized Wannier functions. The unitary
transformation matrix U is written as exp(A) where
A is a anti-hermitian matrix. The Damped-Dynamics is performed
in terms of the A matrix, and then U is computed from A.
Usually a value between 1500 and 2500 works fine, but should
be tested.
         
wf_friction REAL
Default: 0.3D0
Damping coefficient for Damped-Dynamics.
         
nsteps INTEGER
Default: 20
Number of Damped-Dynamics steps to be performed per CP
iteration.
         
tolw REAL
Default: 1.D-8
Convergence criterion for localization.
         
adapt LOGICAL
Default: .true.
Whether to adapt the damping parameter dynamically.
         
calwf INTEGER
Default: 3
Wannier Function Options, can be 1,2,3,4,5

1. Output the Wannier function density, nwf and wffort
   are used for this option. see below.
2. Output the Overlap matrix O_i,j=<w_i|exp{iGr}|w_j>. O is
   written to unit 38. For details on how O is constructed,
   see below.
3. Perform nsteps of Wannier dynamics per CP iteration, the
   orbitals are now Wannier Functions, not Kohn-Sham orbitals.
   This is a Unitary transformation of the occupied subspace
   and does not leave the CP Lagrangian invariant. Expectation
   values remain the same. So you will **NOT** have a constant
   of motion during the run. Don't freak out, its normal.
4. This option starts for the KS states and does 1 CP iteration
   and nsteps of Damped-Dynamics to generate  maximally
   localized wannier functions. Its useful when you have the
   converged KS groundstate and want to get to the converged
   Wannier function groundstate in 1 CP Iteration.
5. This option is similar to calwf 1, except that the output is
   the Wannier function/wavefunction, and not the orbital
   density. See nwf below.
         
nwf INTEGER
Default: 0
This option is used with calwf 1 and calwf 5. with calwf=1,
it tells the code how many Orbital densities are to be
output. With calwf=5, set this to 1(i.e calwf=5 only writes
one state during one run. so if you want 10 states, you have
to run the code 10 times). With calwf=1, you can print many
orbital densities in a single run.
See also the PLOT_WANNIER card for specifying the states to
be printed.
         
wffort INTEGER
Default: 40
This tells the code where to dump the orbital densities. Used
 only with CALWF=1. for e.g. if you want to print 2 orbital
 densities, set calwf=1, nwf=2 and wffort to an appropriate
 number (e.g. 40) then the first orbital density will be
 output to fort.40, the second to fort.41 and so on. Note that
 in the current implementation, the following units are used
 21,22,24,25,26,27,28,38,39,77,78 and whatever you define as
 ndr and ndw. so use number other than these.
         
writev LOGICAL
Default: .false.
Output the charge density (g-space) and the list of g-vectors
This is useful if you want to reconstruct the electrostatic
potential using the Poisson equation. If .TRUE. then the
code will output the g-space charge density and the list
if G-vectors, and STOP.
Charge density is written to : CH_DEN_G_PARA.ispin (1 or 2
depending on the number of spin types) or CH_DEN_G_SERL.ispin
depending on if the code is being run in parallel or serial
G-vectors are written to G_PARA or G_SERL.
         

Card: ATOMIC_SPECIES

Syntax:

ATOMIC_SPECIES
 X(1)   Mass_X(1)   PseudoPot_X(1) 
 X(2)   Mass_X(2)   PseudoPot_X(2) 
 . . .
 X(ntyp)   Mass_X(ntyp)   PseudoPot_X(ntyp) 

Description of items:


X CHARACTER
 label of the atom
                  
Mass_X REAL
mass of the atomic species [amu: mass of C = 12]
not used if calculation='scf', 'nscf', 'bands'
                  
PseudoPot_X CHARACTER
File containing PP for this species.

The pseudopotential file is assumed to be in the new UPF format.
If it doesn't work, the pseudopotential format is determined by
the file name:

*.vdb or *.van     Vanderbilt US pseudopotential code
*.RRKJ3            Andrea Dal Corso's code (old format)
none of the above  old PWscf norm-conserving format
                  

Card: ATOMIC_POSITIONS { alat | bohr | angstrom | crystal }

IF calculation == 'bands' OR calculation == 'nscf' :
Specified atomic positions will be IGNORED and those from the
previous scf calculation will be used instead !!!
            
ELSEIF :

Syntax:

ATOMIC_POSITIONS { alat | bohr | angstrom | crystal }
 X(1)   x(1)   y(1)   z(1)  {  if_pos(1)(1)   if_pos(2)(1)   if_pos(3)(1)  }
 X(2)   x(2)   y(2)   z(2)  {  if_pos(1)(2)   if_pos(2)(2)   if_pos(3)(2)  }
 . . .
 X(nat)   x(nat)   y(nat)   z(nat)  {  if_pos(1)(nat)   if_pos(2)(nat)   if_pos(3)(nat)  }

Description of items:

alat    : atomic positions are in cartesian coordinates,
          in units of the lattice parameter "a" (default)

bohr    : atomic positions are in cartesian coordinate,
          in atomic units (i.e. Bohr)

angstrom: atomic positions are in cartesian coordinates,
          in Angstrom

crystal : atomic positions are in crystal coordinates, i.e.
          in relative coordinates of the primitive lattice vectors (see below)
         
X CHARACTER
 label of the atom as specified in ATOMIC_SPECIES
                        
x, y, z REAL
 atomic positions
                        
if_pos(1), if_pos(2), if_pos(3) INTEGER
Default: 1
component i of the force for this atom is multiplied by if_pos(i),
which must be either 0 or 1.  Used to keep selected atoms and/or
selected components fixed in MD dynamics or
structural optimization run.
                           

Card: ATOMIC_VELOCITIES { a.u }

Optional card, reads velocities (in atomic units) from standard input

when starting with ion_velocities="from_input" it is convenient
to perform few steps (~5-10) with a smaller time step (0.5 a.u.)
      

Syntax:

ATOMIC_VELOCITIES { a.u }
 V(1)   vx(1)   vy(1)   vz(1) 
 V(2)   vx(2)   vy(2)   vz(2) 
 . . .
 V(nat)   vx(nat)   vy(nat)   vz(nat) 

Description of items:


V CHARACTER
 label of the atom as specified in ATOMIC_SPECIES
                  
vx, vy, vz REAL
 atomic velocities along x y and z direction
                  

Card: CELL_PARAMETERS { bohr | angstrom }

Optional card, needed only if ibrav = 0 is specified, ignored otherwise !

Syntax:

CELL_PARAMETERS { bohr | angstrom }
 v1(1)   v1(2)   v1(3) 
 v2(1)   v2(2)   v2(3) 
 v3(1)   v3(2)   v3(3) 

Description of items:

bohr / angstrom: lattice vectors in bohr radii / angstrom.
nothing specified: if a lattice constant (celldm(1) or a)
is present, lattice vectors are in units of the lattice
constant; otherwise, in bohr radii.
         
v1, v2, v3 REAL
Crystal lattice vectors:
    v1(1)  v1(2)  v1(3)    ... 1st lattice vector
    v2(1)  v2(2)  v2(3)    ... 2nd lattice vector
    v3(1)  v3(2)  v3(3)    ... 3rd lattice vector
                  

Card: CONSTRAINTS

Optional card, used for constrained dynamics or constrained optimisations

When this card is present the SHAKE algorithm is automatically used.
      

Syntax:

CONSTRAINTS
nconstr   { constr_tol   }
 constr_type(1)   constr(1)(1)   constr(2)(1)  [  constr(3)(1)    constr(4)(1)   ] {  constr_target(1)  }
 constr_type(2)   constr(1)(2)   constr(2)(2)  [  constr(3)(2)    constr(4)(2)   ] {  constr_target(2)  }
 . . .
 constr_type(nconstr)   constr(1)(nconstr)   constr(2)(nconstr)  [  constr(3)(nconstr)    constr(4)(nconstr)   ] {  constr_target(nconstr)  }

Description of items:


nconstr INTEGER
 Number of constraints.
               
constr_tol REAL
 Tolerance for keeping the constraints satisfied.
                  
constr_type CHARACTER
Type of constrain :

'type_coord'      : constraint on global coordination-number, i.e. the
                    average number of atoms of type B surrounding the
                    atoms of type A. The coordination is defined by
                    using a Fermi-Dirac.
                    (four indexes must be specified).

'atom_coord'      : constraint on local coordination-number, i.e. the
                    average number of atoms of type A surrounding a
                    specific atom. The coordination is defined by
                    using a Fermi-Dirac.
                    (four indexes must be specified).

'distance'        : constraint on interatomic distance
                    (two atom indexes must be specified).

'planar_angle'    : constraint on planar angle
                    (three atom indexes must be specified).

'torsional_angle' : constraint on torsional angle
                    (four atom indexes must be specified).

'bennett_proj'    : constraint on the projection onto a given direction
                    of the vector defined by the position of one atom
                    minus the center of mass of the others.
                    ( Ch.H. Bennett in Diffusion in Solids, Recent
                      Developments, Ed. by A.S. Nowick and J.J. Burton,
                      New York 1975 ).
                  
constr(1), constr(2), constr(3), constr(4)
                      These variables have different meanings
                      for different constraint types:

                     'type_coord' : constr(1) is the first index of the
                                    atomic type involved
                                    constr(2) is the second index of the
                                    atomic type involved
                                    constr(3) is the cut-off radius for
                                    estimating the coordination
                                    constr(4) is a smoothing parameter

                     'atom_coord' : constr(1) is the atom index of the
                                    atom with constrained coordination
                                    constr(2) is the index of the atomic
                                    type involved in the coordination
                                    constr(3) is the cut-off radius for
                                    estimating the coordination
                                    constr(4) is a smoothing parameter

                       'distance' : atoms indices object of the
                                    constraint, as they appear in
                                    the 'ATOMIC_POSITION' CARD

'planar_angle', 'torsional_angle' : atoms indices object of the
                                    constraint, as they appear in the
                                    'ATOMIC_POSITION' CARD (beware the
                                    order)

                   'bennett_proj' : constr(1) is the index of the atom
                                    whose position is constrained.
                                    constr(2:4) are the three coordinates
                                    of the vector that specifies the
                                    constraint direction.
                  
constr_target REAL
Target for the constrain ( angles are specified in degrees ).
This variable is optional.
                     

Card: OCCUPATIONS

Optional card, used only if occupations = 'from_input', ignored otherwise !

Syntax:

OCCUPATIONS
 f_inp1(1)   f_inp1(2)   . . .  f_inp1(nbnd) 
[    f_inp2(1)   f_inp2(2)   . . .  f_inp2(nbnd)    ]

Description of items:


f_inp1 REAL
Occupations of individual states (MAX 10 PER LINE).
For spin-polarized calculations, these are majority spin states.
                  
f_inp2 REAL
Occupations of minority spin states (MAX 10 PER LINE)
To be specified only for spin-polarized calculations.
                     

Card: PLOT_WANNIER

Optional card, indices of the states that have to be printed (only for calf=1 and calf=5).

Syntax:

PLOT_WANNIER
 iwf(1) 
 iwf(2) 
 . . .
 iwf(nwf) 

Description of items:


iwf INTEGER
These are the indices of the states that you want to output.
Also used with calwf = 1 and 5. If calwf = 1, then you need
nwf indices here (each in a new line). If CALWF=5, then just
one index in needed.
                  
This file has been created by helpdoc utility.