------------------------------------------------------------------------
INPUT FILE DESCRIPTION

Program: pw.x / PWscf / Quantum Espresso (version: 6.0)
------------------------------------------------------------------------


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

All quantities whose dimensions are not explicitly specified are in
RYDBERG ATOMIC UNITS. Charge is "number" charge (i.e. not multiplied
by e); potentials are in energy units (i.e. they are multiplied by e).

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 by
either a "!" or a "#" character in the first position of a line.
Do not start any line in cards with a "/" character.


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

&CONTROL
  ...
/

&SYSTEM
  ...
/

&ELECTRONS
  ...
/

[ &IONS
  ...
 / ]

[ &CELL
  ...
 / ]

ATOMIC_SPECIES
 X  Mass_X  PseudoPot_X
 Y  Mass_Y  PseudoPot_Y
 Z  Mass_Z  PseudoPot_Z

ATOMIC_POSITIONS { alat | bohr | crystal | angstrom | crystal_sg }
  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

K_POINTS { tpiba | automatic | crystal | gamma | tpiba_b | crystal_b | tpiba_c | crystal_c }
if (gamma)
   nothing to read
if (automatic)
   nk1, nk2, nk3, k1, k2, k3
if (not automatic)
   nks
   xk_x, xk_y, xk_z,  wk

[ CELL_PARAMETERS { alat | 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(.) } ]

[ ATOMIC_FORCES
   label_1 Fx(1) Fy(1) Fz(1)
   .....
   label_n Fx(n) Fy(n) Fz(n) ]



========================================================================
NAMELIST: &CONTROL

   +--------------------------------------------------------------------
   Variable:       calculation
   
   Type:           CHARACTER
   Default:        'scf'
   Description:   
                   A string describing the task to be performed. Options are:
                        'scf'
                        'nscf'
                        'bands'
                        'relax'
                        'md'
                        'vc-relax'
                        'vc-md'
    
                   (vc = variable-cell).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       title
   
   Type:           CHARACTER
   Default:        ' '
   Description:    reprinted on output.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       verbosity
   
   Type:           CHARACTER
   Default:        'low'
   Description:   
                   Currently two verbosity levels are implemented:
                        'high'
                        'low'
    
                   'debug' and 'medium' have the same effect as 'high';
                   'default' and 'minimal' as 'low'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       restart_mode
   
   Type:           CHARACTER
   Default:        'from_scratch'
   Description:   
                   Available options are:
    
                   'from_scratch' :
                        From scratch. This is the normal way to perform a PWscf calculation
    
                   'restart' :
                        From previous interrupted run. Use this switch only if you want to
                        continue an interrupted calculation, not to start a new one, or to
                        perform non-scf calculations.  Works only if the calculation was
                        cleanly stopped using variable "max_seconds", or by user request
                        with an "exit file" (i.e.: create a file "prefix".EXIT, in directory
                        "outdir"; see variables "prefix", "outdir").  Overrides "startingwfc"
                        and "startingpot".
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       wf_collect
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    This flag controls the way wavefunctions are stored to disk :
                   
                   .TRUE.  collect wavefunctions from all processors, store them
                           into the output data directory "outdir"/"prefix".save,
                           one wavefunction per k-point in subdirs K000001/,
                           K000001/, etc.. Use this if you want wavefunctions
                           to be readable on a different number of processors.
                   
                   .FALSE. do not collect wavefunctions, leave them in temporary
                           local files (one per processor). The resulting format
                           will be readable only by jobs running on the same
                           number of processors and pools. Requires less I/O
                           than the previous case.
                   
                   Note that this flag has no effect on reading, only on writing.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nstep
   
   Type:           INTEGER
   Description:    number of molecular-dynamics or structural optimization steps
                   performed in this run
   Default:        1  if "calculation" == 'scf', 'nscf', 'bands';
                   50 for the other cases
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       iprint
   
   Type:           INTEGER
   Default:        write only at convergence
   Description:    band energies are written every iprint iterations
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       tstress
   
   Type:           LOGICAL
   Default:        .false.
   Description:    calculate stress. It is set to .TRUE. automatically if
                   "calculation" == 'vc-md' or 'vc-relax'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       tprnfor
   
   Type:           LOGICAL
   Description:    calculate forces. It is set to .TRUE. automatically if
                   "calculation" == 'relax','md','vc-md'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       dt
   
   Type:           REAL
   Default:        20.D0
   Description:    time step for molecular dynamics, in Rydberg atomic units
                   (1 a.u.=4.8378 * 10^-17 s : beware, the CP code uses
                    Hartree atomic units, half that much!!!)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       outdir
   
   Type:           CHARACTER
   Default:        value of the ESPRESSO_TMPDIR environment variable if set;
                   current directory ('./') otherwise
   Description:    input, temporary, output files are found in this directory,
                   see also "wfcdir"
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       wfcdir
   
   Type:           CHARACTER
   Default:        same as "outdir"
   Description:    This directory specifies where to store files generated by
                   each processor (*.wfc{N}, *.igk{N}, etc.). Useful for
                   machines without a parallel file system: set "wfcdir" to
                   a local file system, while "outdir" should be a parallel
                   or networkfile system, visible to all processors. Beware:
                   in order to restart from interrupted runs, or to perform
                   further calculations using the produced data files, you
                   may need to copy files to "outdir". Works only for pw.x.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       prefix
   
   Type:           CHARACTER
   Default:        'pwscf'
   Description:    prepended to input/output filenames:
                   prefix.wfc, prefix.rho, etc.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lkpoint_dir
   
   Type:           LOGICAL
   Default:        .true.
   Description:    If .false. a subdirectory for each k_point is not opened
                   in the "prefix".save directory; Kohn-Sham eigenvalues are
                   stored instead in a single file for all k-points. Currently
                   doesn't work together with "wf_collect"
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       max_seconds
   
   Type:           REAL
   Default:        1.D+7, or 150 days, i.e. no time limit
   Description:    Jobs stops after "max_seconds" CPU time. Use this option
                   in conjunction with option "restart_mode" if you need to
                   split a job too long to complete into shorter jobs that
                   fit into your batch queues.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       etot_conv_thr
   
   Type:           REAL
   Default:        1.0D-4
   Description:    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. Note that "etot_conv_thr"
                   is extensive, like the total energy.
                   See also "forc_conv_thr" - both criteria must be satisfied
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       forc_conv_thr
   
   Type:           REAL
   Default:        1.0D-3
   Description:    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
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       disk_io
   
   Type:           CHARACTER
   Default:        see below
   Description:   
                   Specifies the amount of disk I/O activity:
    
                   'high' :
                        save all data to disk at each SCF step
    
                   'medium' :
                        save wavefunctions at each SCF step unless
                        there is a single k-point per process (in which
                        case the behavior is the same as 'low')
    
                   'low' :
                        store wfc in memory, save only at the end
    
                   'none' :
                        do not save anything, not even at the end
                        ('scf', 'nscf', 'bands' calculations; some data
                        may be written anyway for other calculations)
    
                   Default is 'low' for the scf case, 'medium' otherwise.
                   Note that the needed RAM increases as disk I/O decreases!
                   It is no longer needed to specify 'high' in order to be able
                   to restart from an interrupted calculation (see "restart_mode")
                   but you cannot restart in "disk_io"=='none'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       pseudo_dir
   
   Type:           CHARACTER
   Default:        value of the $ESPRESSO_PSEUDO environment variable if set;
                   '$HOME/espresso/pseudo/' otherwise
   Description:    directory containing pseudopotential files
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       tefield
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .TRUE. a saw-like potential simulating an electric field
                   is added to the bare ionic potential. See variables "edir",
                   "eamp", "emaxpos", "eopreg" for the form and size of
                   the added potential.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       dipfield
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .TRUE. and "tefield"==.TRUE. a dipole correction is also
                   added to the bare ionic potential - implements the recipe
                   of L. Bengtsson, PRB 59, 12301 (1999). See variables "edir",
                   "emaxpos", "eopreg" for the form of the correction. Must
                   be used ONLY in a slab geometry, for surface calculations,
                   with the discontinuity FALLING IN THE EMPTY SPACE.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lelfield
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .TRUE. a homogeneous finite electric field described
                   through the modern theory of the polarization is applied.
                   This is different from "tefield" == .true. !
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nberrycyc
   
   Type:           INTEGER
   Default:        1
   Description:    In the case of a finite electric field  ( "lelfield" == .TRUE. )
                   it defines the number of iterations for converging the
                   wavefunctions in the electric field Hamiltonian, for each
                   external iteration on the charge density
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lorbm
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .TRUE. perform orbital magnetization calculation.
                   If finite electric field is applied ("lelfield"==.true.)
                   only Kubo terms are computed
                   [for details see New J. Phys. 12, 053032 (2010)].
                   The type of calculation is 'nscf' and should be performed
                   on an automatically generated uniform grid of k points.
                   Works ONLY with norm-conserving pseudopotentials.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lberry
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .TRUE. perform a Berry phase calculation.
                   See the header of PW/src/bp_c_phase.f90 for documentation.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       gdir
   
   Type:           INTEGER
   Description:    For Berry phase calculation: direction of the k-point
                   strings in reciprocal space. Allowed values: 1, 2, 3
                   1=first, 2=second, 3=third reciprocal lattice vector
                   For calculations with finite electric fields
                   ("lelfield"==.true.) "gdir" is the direction of the field.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nppstr
   
   Type:           INTEGER
   Description:    For Berry phase calculation: number of k-points to be
                   calculated along each symmetry-reduced string.
                   The same for calculation with finite electric fields
                   ("lelfield"==.true.).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lfcpopt
   
   Type:           LOGICAL
   See:            fcp_mu
   Default:        .FALSE.
   Description:    If .TRUE. perform a constant bias potential (constant-mu) calculation
                   for a static system with ESM method. See the header of PW/src/fcp.f90
                   for documentation.
                   
                   NB:
                   - The total energy displayed in 'prefix.out' includes the potentiostat
                     contribution (-mu*N).
                   - "calculation" must be 'relax'.
                   - "assume_isolated" = 'esm' and "esm_bc" = 'bc2' or 'bc3' must be set
                     in "SYSTEM" namelist.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       monopole
   
   Type:           LOGICAL
   Default:        .FALSE.
   See:            zmon, realxz, block, block_1, block_2, block_height
   Description:    In the case of charged cells ("tot_charge" .ne. 0) setting monopole = .TRUE.
                   represents the counter charge (i.e. -tot_charge) not by a homogenous
                   background charge but with a charged plate, which is placed at "zmon"
                   (see below). Details of the monopole potential can be found in
                   T. Brumme, M. Calandra, F. Mauri; PRB 89, 245406 (2014).
                   Note, that in systems which are not symmetric with respect to the plate,
                   one needs to enable the dipole correction! ("dipfield"=.true.).
                   Currently, symmetry can be used with monopole=.true. but carefully check
                   that no symmetry is included which maps z to -z even if in principle one
                   could still use them for symmetric systems (i.e. no dipole correction).
                   For "nosym"=.false. verbosity is set to 'high'.
   +--------------------------------------------------------------------
   
===END OF NAMELIST======================================================


========================================================================
NAMELIST: &SYSTEM

   +--------------------------------------------------------------------
   Variable:       ibrav
   
   Type:           INTEGER
   Status:         REQUIRED
   Description:    Bravais-lattice index. If ibrav /= 0, specify EITHER
                     [ "celldm"(1)-"celldm"(6) ] OR [ "A", "B", "C", "cosAB", "cosAC", "cosBC" ]
                     but NOT both. The lattice parameter "alat" is set to
                     alat = celldm(1) (in a.u.) or alat = A (in Angstrom);
                     see below for the other parameters.
                     For ibrav=0 specify the lattice vectors in "CELL_PARAMETERS",
                     optionally the lattice parameter alat = celldm(1) (in a.u.)
                     or = A (in Angstrom), or else it is taken from "CELL_PARAMETERS"
                   
                   ibrav      structure                   celldm(2)-celldm(6)
                                                        or: b,c,cosab,cosac,cosbc
                     0          free
                         crystal axis provided in input: see card "CELL_PARAMETERS"
                   
                     1          cubic P (sc)
                         v1 = a(1,0,0),  v2 = a(0,1,0),  v3 = a(0,0,1)
                   
                     2          cubic F (fcc)
                         v1 = (a/2)(-1,0,1),  v2 = (a/2)(0,1,1), v3 = (a/2)(-1,1,0)
                   
                     3          cubic I (bcc)
                         v1 = (a/2)(1,1,1),  v2 = (a/2)(-1,1,1),  v3 = (a/2)(-1,-1,1)
                   
                     4          Hexagonal and Trigonal P        celldm(3)=c/a
                         v1 = a(1,0,0),  v2 = a(-1/2,sqrt(3)/2,0),  v3 = a(0,0,c/a)
                   
                     5          Trigonal R, 3fold axis c        celldm(4)=cos(alpha)
                         The crystallographic vectors form a three-fold star around
                         the z-axis, the primitive cell is a simple rhombohedron:
                         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, tx, ty, tz are:
                           tx=sqrt((1-c)/2), ty=sqrt((1-c)/6), tz=sqrt((1+2c)/3)
                    -5          Trigonal R, 3fold axis <111>    celldm(4)=cos(alpha)
                         The crystallographic vectors form a three-fold star around
                         <111>. Defining a' = a/sqrt(3) :
                         v1 = a' (u,v,v),   v2 = a' (v,u,v),   v3 = a' (v,v,u)
                         where u and v are defined as
                           u = tz - 2*sqrt(2)*ty,  v = tz + sqrt(2)*ty
                         and tx, ty, tz as for case ibrav=5
                         Note: if you prefer x,y,z as axis in the cubic limit,
                               set  u = tz + 2*sqrt(2)*ty,  v = tz - sqrt(2)*ty
                               See also the note in Modules/latgen.f90
                   
                     6          Tetragonal P (st)               celldm(3)=c/a
                         v1 = a(1,0,0),  v2 = a(0,1,0),  v3 = a(0,0,c/a)
                   
                     7          Tetragonal I (bct)              celldm(3)=c/a
                         v1=(a/2)(1,-1,c/a),  v2=(a/2)(1,1,c/a),  v3=(a/2)(-1,-1,c/a)
                   
                     8          Orthorhombic P                  celldm(2)=b/a
                                                                celldm(3)=c/a
                         v1 = (a,0,0),  v2 = (0,b,0), v3 = (0,0,c)
                   
                     9          Orthorhombic base-centered(bco) celldm(2)=b/a
                                                                celldm(3)=c/a
                         v1 = (a/2, b/2,0),  v2 = (-a/2,b/2,0),  v3 = (0,0,c)
                    -9          as 9, alternate description
                         v1 = (a/2,-b/2,0),  v2 = (a/2, b/2,0),  v3 = (0,0,c)
                   
                    10          Orthorhombic face-centered      celldm(2)=b/a
                                                                celldm(3)=c/a
                         v1 = (a/2,0,c/2),  v2 = (a/2,b/2,0),  v3 = (0,b/2,c/2)
                   
                    11          Orthorhombic body-centered      celldm(2)=b/a
                                                                celldm(3)=c/a
                         v1=(a/2,b/2,c/2),  v2=(-a/2,b/2,c/2),  v3=(-a/2,-b/2,c/2)
                   
                    12          Monoclinic P, unique axis c     celldm(2)=b/a
                                                                celldm(3)=c/a,
                                                                celldm(4)=cos(ab)
                         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.
                   -12          Monoclinic P, unique axis b     celldm(2)=b/a
                                                                celldm(3)=c/a,
                                                                celldm(5)=cos(ac)
                         v1 = (a,0,0), v2 = (0,b,0), v3 = (c*cos(beta),0,c*sin(beta))
                         where beta is the angle between axis a and c
                   
                    13          Monoclinic base-centered        celldm(2)=b/a
                                                                celldm(3)=c/a,
                                                                celldm(4)=cos(ab)
                         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
                   
                    14          Triclinic                       celldm(2)= b/a,
                                                                celldm(3)= c/a,
                                                                celldm(4)= cos(bc),
                                                                celldm(5)= cos(ac),
                                                                celldm(6)= cos(ab)
                         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:
      
      +--------------------------------------------------------------------
      Variable:       celldm(i), i=1,6
      
      Type:           REAL
      See:            ibrav
      Description:    Crystallographic constants - see the "ibrav" variable.
                      Specify either these OR "A","B","C","cosAB","cosBC","cosAC" NOT both.
                      Only needed values (depending on "ibrav") must be specified
                      alat = "celldm"(1) is the lattice parameter "a" (in BOHR)
                      If "ibrav"==0, only "celldm"(1) is used if present;
                      cell vectors are read from card "CELL_PARAMETERS"
      +--------------------------------------------------------------------
      
      OR:
      
      +--------------------------------------------------------------------
      Variables:      A, B, C, cosAB, cosAC, cosBC
      
      Type:           REAL
      See:            ibrav
      Description:    Traditional crystallographic constants:
                      
                        a,b,c in ANGSTROM
                        cosAB = cosine of the angle between axis a and b (gamma)
                        cosAC = cosine of the angle between axis a and c (beta)
                        cosBC = cosine of the angle between axis b and c (alpha)
                      
                      The axis are chosen according to the value of @ref ibrav.
                      Specify either these OR @ref celldm but NOT both.
                      Only needed values (depending on @ref ibrav) must be specified.
                      
                      The lattice parameter alat = A (in ANGSTROM ).
                      
                      If @ref ibrav == 0, only A is used if present, and
                      cell vectors are read from card @ref CELL_PARAMETERS.
      +--------------------------------------------------------------------
      
   \\\---
   
   +--------------------------------------------------------------------
   Variable:       nat
   
   Type:           INTEGER
   Status:         REQUIRED
   Description:    number of atoms in the unit cell (ALL atoms, except if
                   space_group is set, in which case, INEQUIVALENT atoms)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ntyp
   
   Type:           INTEGER
   Status:         REQUIRED
   Description:    number of types of atoms in the unit cell
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nbnd
   
   Type:           INTEGER
   Default:        for an insulator, "nbnd" = number of valence bands
                   ("nbnd" = # of electrons /2);
                    for a metal, 20% more (minimum 4 more)
   Description:    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
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       tot_charge
   
   Type:           REAL
   Default:        0.0
   Description:    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.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       tot_magnetization
   
   Type:           REAL
   Default:        -1 [unspecified]
   Description:    Total majority spin charge - minority spin charge.
                   Used to impose a specific total electronic magnetization.
                   If unspecified then tot_magnetization variable is ignored and
                   the amount of electronic magnetization is determined during
                   the self-consistent cycle.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       starting_magnetization(i), i=1,ntyp
   
   Type:           REAL
   Description:    Starting spin polarization on atomic type 'i' in a spin
                   polarized calculation. Values range between -1 (all spins
                   down for the valence electrons of atom type 'i') to 1
                   (all spins up). Breaks the symmetry and provides a starting
                   point for self-consistency. The default value is zero, BUT a
                   value MUST be specified for AT LEAST one atomic type in spin
                   polarized calculations, unless you constrain the magnetization
                   (see "tot_magnetization" and "constrained_magnetization").
                   Note that if you start from zero initial magnetization, you
                   will invariably end up in a nonmagnetic (zero magnetization)
                   state. If you want to start from an antiferromagnetic state,
                   you may need to define two different atomic species
                   corresponding to sublattices of the same atomic type.
                   starting_magnetization is ignored if you are performing a
                   non-scf calculation, if you are restarting from a previous
                   run, or restarting from an interrupted run.
                   If you fix the magnetization with "tot_magnetization",
                   you should not specify starting_magnetization.
                   In the spin-orbit case starting with zero
                   starting_magnetization on all atoms imposes time reversal
                   symmetry. The magnetization is never calculated and
                   kept zero (the internal variable domag is .FALSE.).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ecutwfc
   
   Type:           REAL
   Status:         REQUIRED
   Description:    kinetic energy cutoff (Ry) for wavefunctions
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ecutrho
   
   Type:           REAL
   Default:        4 * "ecutwfc"
   Description:    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.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ecutfock
   
   Type:           REAL
   Default:        ecutrho
   Description:    Kinetic energy cutoff (Ry) for the exact exchange operator in
                   EXX type calculations. By default this is the same as "ecutrho"
                   but in some EXX calculations significant speed-up can be found
                   by reducing ecutfock, at the expense of some loss in accuracy.
                   Must be .gt. "ecutwfc". Not implemented for stress calculation.
                   Use with care, especially in metals where it may give raise
                   to instabilities.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variables:      nr1, nr2, nr3
   
   Type:           INTEGER
   Description:    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 (see also @ref ecutrho)
                   Note: you must specify all three dimensions for this setting to
                   be used.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variables:      nr1s, nr2s, nr3s
   
   Type:           INTEGER
   Description:    Three-dimensional mesh for wavefunction FFT and for the smooth
                   part of charge density ( smooth grid ).
                   Coincides with @ref nr1, @ref nr2, @ref nr3 if @ref ecutrho = 4 * ecutwfc ( default )
                   Note: you must specify all three dimensions for this setting to
                   be used.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nosym
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    if (.TRUE.) symmetry is not used, which means that:
                   
                   - if a list of k points is provided in input, it is used
                     "as is": symmetry-inequivalent k-points are not generated,
                     and the charge density is not symmetrized;
                   
                   - if a uniform (Monkhorst-Pack) k-point grid is provided in
                     input, it is expanded to cover the entire Brillouin Zone,
                     irrespective of the crystal symmetry.
                     Time reversal symmetry is assumed so k and -k are considered
                     as equivalent unless "noinv"=.true. is specified.
                   
                   A careful usage of this option can be advantageous:
                   - in low-symmetry large cells, if you cannot afford a k-point
                     grid with the correct symmetry
                   - in MD simulations
                   - in calculations for isolated atoms
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nosym_evc
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    if (.TRUE.) symmetry is not used, and k points are
                   forced to have the symmetry of the Bravais lattice;
                   an automatically generated Monkhorst-Pack grid will contain
                   all points of the grid over the entire Brillouin Zone,
                   plus the points rotated by the symmetries of the Bravais
                   lattice which were not in the original grid. The same
                   applies if a k-point list is provided in input instead
                   of a Monkhorst-Pack grid. Time reversal symmetry is assumed
                   so k and -k are equivalent unless "noinv"=.true. is specified.
                   This option differs from "nosym" because it forces k-points
                   in all cases to have the full symmetry of the Bravais lattice
                   (not all uniform grids have such property!)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       noinv
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    if (.TRUE.) disable the usage of k => -k symmetry
                   (time reversal) in k-point generation
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       no_t_rev
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    if (.TRUE.) disable the usage of magnetic symmetry operations
                   that consist in a rotation + time reversal.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       force_symmorphic
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    if (.TRUE.) force the symmetry group to be symmorphic by disabling
                   symmetry operations having an associated fractionary translation
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       use_all_frac
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    if (.TRUE.) do not discard symmetry operations with an
                   associated fractionary translation that does not send the
                   real-space FFT grid into itself. These operations are
                   incompatible with real-space symmetrization but not with the
                   new G-space symmetrization. BEWARE: do not use for phonons
                   and for hybrid functionals! Both still use symmetrization
                   in real space.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       occupations
   
   Type:           CHARACTER
   Description:   
                   Available options are:
    
                   'smearing' :
                        gaussian smearing for metals;
                        see variables "smearing" and "degauss"
    
                   'tetrahedra' :
                        especially suited for calculation of DOS
                        (see P.E. Bloechl, PRB 49, 16223 (1994)).
                        Requires uniform grid of k-points,
                        automatically generated (see below).
                        Not suitable (because not variational) for
                        force/optimization/dynamics calculations.
    
                   'fixed' :
                        for insulators with a gap
    
                   'from_input' :
                        The occupation are read from input file,
                        card "OCCUPATIONS". Option valid only for a
                        single k-point, requires "nbnd" to be set
                        in input. Occupations should be consistent
                        with the value of "tot_charge".
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       one_atom_occupations
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    This flag is used for isolated atoms ("nat"=1) together with
                   "occupations"='from_input'. If it is .TRUE., the wavefunctions
                   are ordered as the atomic starting wavefunctions, independently
                   from their eigenvalue. The occupations indicate which atomic
                   states are filled.
                   
                   The order of the states is written inside the UPF pseudopotential file.
                   In the scalar relativistic case:
                   S -> l=0, m=0
                   P -> l=1, z, x, y
                   D -> l=2, r^2-3z^2, xz, yz, xy, x^2-y^2
                   
                   In the noncollinear magnetic case (with or without spin-orbit),
                   each group of states is doubled. For instance:
                   P -> l=1, z, x, y for spin up, l=1, z, x, y for spin down.
                   Up and down is relative to the direction of the starting
                   magnetization.
                   
                   In the case with spin-orbit and time-reversal
                   ("starting_magnetization"=0.0) the atomic wavefunctions are
                   radial functions multiplied by spin-angle functions.
                   For instance:
                   P -> l=1, j=1/2, m_j=-1/2,1/2. l=1, j=3/2,
                        m_j=-3/2, -1/2, 1/2, 3/2.
                   
                   In the magnetic case with spin-orbit the atomic wavefunctions
                   can be forced to be spin-angle functions by setting
                   "starting_spin_angle" to .TRUE..
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       starting_spin_angle
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    In the spin-orbit case when domag=.TRUE., by default,
                   the starting wavefunctions are initialized as in scalar
                   relativistic noncollinear case without spin-orbit.
                   
                   By setting starting_spin_angle=.TRUE. this behaviour can
                   be changed and the initial wavefunctions are radial
                   functions multiplied by spin-angle functions.
                   
                   When domag=.FALSE. the initial wavefunctions are always
                   radial functions multiplied by spin-angle functions
                   independently from this flag.
                   
                   When "lspinorb" is .FALSE. this flag is not used.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       degauss
   
   Type:           REAL
   Default:        0.D0 Ry
   Description:    value of the gaussian spreading (Ry) for brillouin-zone
                   integration in metals.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       smearing
   
   Type:           CHARACTER
   Default:        'gaussian'
   Description:   
                   Available options are:
    
                   'gaussian', 'gauss' :
                        ordinary Gaussian spreading (Default)
    
                   'methfessel-paxton', 'm-p', 'mp' :
                        Methfessel-Paxton first-order spreading
                        (see PRB 40, 3616 (1989)).
    
                   'marzari-vanderbilt', 'cold', 'm-v', 'mv' :
                        Marzari-Vanderbilt cold smearing
                        (see PRL 82, 3296 (1999))
    
                   'fermi-dirac', 'f-d', 'fd' :
                        smearing with Fermi-Dirac function
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       nspin
   
   Type:           INTEGER
   Default:        1
   Description:    nspin = 1 :  non-polarized calculation (default)
                   
                   nspin = 2 :  spin-polarized calculation, LSDA
                                (magnetization along z axis)
                   
                   nspin = 4 :  spin-polarized calculation, noncollinear
                                (magnetization in generic direction)
                                DO NOT specify "nspin" in this case;
                                specify "noncolin"=.TRUE. instead
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       noncolin
   
   Type:           LOGICAL
   Default:        .false.
   Description:    if .true. the program will perform a noncollinear calculation.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ecfixed
   
   Type:           REAL
   Default:        0.0
   See:            q2sigma
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       qcutz
   
   Type:           REAL
   Default:        0.0
   See:            q2sigma
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       q2sigma
   
   Type:           REAL
   Default:        0.1
   Description:    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)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       input_dft
   
   Type:           CHARACTER
   Default:        read from pseudopotential files
   Description:    Exchange-correlation functional: eg 'PBE', 'BLYP' etc
                   See Modules/funct.f90 for allowed values.
                   Overrides the value read from pseudopotential files.
                   Use with care and if you know what you are doing!
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       exx_fraction
   
   Type:           REAL
   Default:        it depends on the specified functional
   Description:    Fraction of EXX for hybrid functional calculations. In the case of
                   "input_dft"='PBE0', the default value is 0.25, while for "input_dft"='B3LYP'
                   the "exx_fraction" default value is 0.20.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       screening_parameter
   
   Type:           REAL
   Default:        0.106
   Description:    screening_parameter for HSE like hybrid functionals.
                   See J. Chem. Phys. 118, 8207 (2003)
                   and J. Chem. Phys. 124, 219906 (2006) for more informations.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       exxdiv_treatment
   
   Type:           CHARACTER
   Default:        'gygi-baldereschi'
   Description:   
                   Specific for EXX. It selects the kind of approach to be used
                   for treating the Coulomb potential divergencies at small q vectors.
    
                   'gygi-baldereschi' :
                        appropriate for cubic and quasi-cubic supercells
    
                   'vcut_spherical' :
                        appropriate for cubic and quasi-cubic supercells
    
                   'vcut_ws' :
                        appropriate for strongly anisotropic supercells, see also "ecutvcut".
    
                   'none' :
                        sets Coulomb potential at G,q=0 to 0.0 (required for GAU-PBE)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       x_gamma_extrapolation
   
   Type:           LOGICAL
   Default:        .true.
   Description:    Specific for EXX. If .true., extrapolate the G=0 term of the
                   potential (see README in examples/EXX_example for more)
                   Set this to .false. for GAU-PBE.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ecutvcut
   
   Type:           REAL
   Default:        0.0 Ry
   See:            exxdiv_treatment
   Description:    Reciprocal space cutoff for correcting Coulomb potential
                   divergencies at small q vectors.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variables:      nqx1, nqx2, nqx3
   
   Type:           INTEGER
   Description:    Three-dimensional mesh for q (k1-k2) sampling of
                   the Fock operator (EXX). Can be smaller than
                   the number of k-points.
                   
                   Currently this defaults to the size of the k-point mesh used.
                   In QE =< 5.0.2 it defaulted to nqx1=nqx2=nqx3=1.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lda_plus_u
   
   Type:           LOGICAL
   Default:        .FALSE.
   Status:         DFT+U (formerly known as LDA+U) currently works only for
                   a few selected elements. Modify Modules/set_hubbard_l.f90 and
                   PW/src/tabd.f90 if you plan to use DFT+U with an element that
                   is not configured there.
   Description:    Specify "lda_plus_u" = .TRUE. to enable DFT+U calculations
                   See: Anisimov, Zaanen, and Andersen, PRB 44, 943 (1991);
                        Anisimov et al., PRB 48, 16929 (1993);
                        Liechtenstein, Anisimov, and Zaanen, PRB 52, R5467 (1994).
                   You must specify, for each species with a U term, the value of
                   U and (optionally) alpha, J of the Hubbard model (all in eV):
                   see "lda_plus_u_kind", "Hubbard_U", "Hubbard_alpha", "Hubbard_J"
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lda_plus_u_kind
   
   Type:           INTEGER
   Default:        0
   Description:    Specifies the type of DFT+U calculation:
                   
                      0   simplified version of Cococcioni and de Gironcoli,
                          PRB 71, 035105 (2005), using "Hubbard_U"
                   
                      1   rotationally invariant scheme of Liechtenstein et al.,
                          using "Hubbard_U" and "Hubbard_J"
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       Hubbard_U(i), i=1,ntyp
   
   Type:           REAL
   Default:        0.D0 for all species
   Description:    Hubbard_U(i): U parameter (eV) for species i, DFT+U calculation
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       Hubbard_J0(i), i=1,ntype
   
   Type:           REAL
   Default:        0.D0 for all species
   Description:    Hubbard_J0(i): J0 parameter (eV) for species i, DFT+U+J calculation,
                   see PRB 84, 115108 (2011) for details.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       Hubbard_alpha(i), i=1,ntyp
   
   Type:           REAL
   Default:        0.D0 for all species
   Description:    Hubbard_alpha(i) is the perturbation (on atom i, in eV)
                   used to compute U with the linear-response method of
                   Cococcioni and de Gironcoli, PRB 71, 35105 (2005)
                   (only for "lda_plus_u_kind"=0)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       Hubbard_beta(i), i=1,ntyp
   
   Type:           REAL
   Default:        0.D0 for all species
   Description:    Hubbard_beta(i) is the perturbation (on atom i, in eV)
                   used to compute J0 with the linear-response method of
                   Cococcioni and de Gironcoli, PRB 71, 35105 (2005)
                   (only for "lda_plus_u_kind"=0). See also
                   PRB 84, 115108 (2011).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       Hubbard_J(i,ityp)
   
   Default:        0.D0 for all species
   Description:    Hubbard_J(i,ityp): J parameters (eV) for species ityp,
                   used in DFT+U calculations (only for "lda_plus_u_kind"=1)
                   For p orbitals:  J = Hubbard_J(1,ityp);
                   For d orbitals:  J = Hubbard_J(1,ityp), B = Hubbard_J(2,ityp);
                   For f orbitals:  J = Hubbard_J(1,ityp), E2 = Hubbard_J(2,ityp),
                                    E3= Hubbard_J(3,ityp).
                   If B or E2 or E3 are not specified or set to 0 they will be
                   calculated from J using atomic ratios.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       starting_ns_eigenvalue(m,ispin,I)
   
   Type:           REAL
   Default:        -1.d0 that means NOT SET
   Description:    In the first iteration of an DFT+U run it overwrites
                   the m-th eigenvalue of the ns occupation matrix for the
                   ispin component of atomic species I. Leave unchanged
                   eigenvalues that are not set. This is useful to suggest
                   the desired orbital occupations when the default choice
                   takes another path.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       U_projection_type
   
   Type:           CHARACTER
   Default:        'atomic'
   Description:   
                   Only active when "lda_plus_U" is .true., specifies the type
                   of projector on localized orbital to be used in the DFT+U
                   scheme.
                   
                   Currently available choices:
    
                   'atomic' :
                        use atomic wfc's (as they are) to build the projector
    
                   'ortho-atomic' :
                        use Lowdin orthogonalized atomic wfc's
    
                   'norm-atomic' :
                        Lowdin normalization of atomic wfc. Keep in mind:
                        atomic wfc are not orthogonalized in this case.
                        This is a "quick and dirty" trick to be used when
                        atomic wfc from the pseudopotential are not
                        normalized (and thus produce occupation whose
                        value exceeds unity). If orthogonalized wfc are
                        not needed always try 'atomic' first.
    
                   'file' :
                        use the information from file "prefix".atwfc that must
                        have been generated previously, for instance by pmw.x
                        (see PP/src/poormanwannier.f90 for details).
    
                   'pseudo' :
                        use the pseudopotential projectors. The charge density
                        outside the atomic core radii is excluded.
                        N.B.: for atoms with +U, a pseudopotential with the
                        all-electron atomic wavefunctions is required (i.e.,
                        as generated by ld1.x with lsave_wfc flag).
    
                   NB: forces and stress currently implemented only for the
                   'atomic' and 'pseudo' choice.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       edir
   
   Type:           INTEGER
   Description:    The direction of the electric field or dipole correction is
                   parallel to the bg(:,edir) reciprocal lattice vector, so the
                   potential is constant in planes defined by FFT grid points;
                   edir = 1, 2 or 3. Used only if "tefield" is .TRUE.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       emaxpos
   
   Type:           REAL
   Default:        0.5D0
   Description:    Position of the maximum of the saw-like potential along crystal
                   axis "edir", within the  unit cell (see below), 0 < emaxpos < 1
                   Used only if "tefield" is .TRUE.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       eopreg
   
   Type:           REAL
   Default:        0.1D0
   Description:    Zone in the unit cell where the saw-like potential decreases.
                   ( see below, 0 < eopreg < 1 ). Used only if "tefield" is .TRUE.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       eamp
   
   Type:           REAL
   Default:        0.001 a.u.
   Description:    Amplitude of the electric field, in ***Hartree*** a.u.;
                   1 a.u. = 51.4220632*10^10 V/m. Used only if "tefield"==.TRUE.
                   The saw-like potential increases with slope "eamp" in the
                   region from (emaxpos+eopreg-1) to (emaxpos), then decreases
                   to 0 until (emaxpos+eopreg), in units of the crystal
                   vector "edir". Important: the change of slope of this
                   potential must be located in the empty region, or else
                   unphysical forces will result.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       angle1(i), i=1,ntyp
   
   Type:           REAL
   Description:    The angle expressed in degrees between the initial
                   magnetization and the z-axis. For noncollinear calculations
                   only; index i runs over the atom types.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       angle2(i), i=1,ntyp
   
   Type:           REAL
   Description:    The angle expressed in degrees between the projection
                   of the initial magnetization on x-y plane and the x-axis.
                   For noncollinear calculations only.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       constrained_magnetization
   
   Type:           CHARACTER
   See:            lambda, fixed_magnetization
   Default:        'none'
   Description:   
                   Used to perform constrained calculations in magnetic systems.
                   Currently available choices:
    
                   'none' :
                        no constraint
    
                   'total' :
                        total magnetization is constrained by
                        adding a penalty functional to the total energy:
                        
                        LAMBDA * SUM_{i} ( magnetization(i) - fixed_magnetization(i) )**2
                        
                        where the sum over i runs over the three components of
                        the magnetization. Lambda is a real number (see below).
                        Noncolinear case only. Use "tot_magnetization" for LSDA
    
                   'atomic' :
                        atomic magnetization are constrained to the defined
                        starting magnetization adding a penalty:
                        
                        LAMBDA * SUM_{i,itype} ( magnetic_moment(i,itype) - mcons(i,itype) )**2
                        
                        where i runs over the cartesian components (or just z
                        in the collinear case) and itype over the types (1-ntype).
                        mcons(:,:) array is defined from starting_magnetization,
                        (and angle1, angle2 in the non-collinear case). lambda is
                        a real number
    
                   'total direction' :
                        the angle theta of the total magnetization
                        with the z axis (theta = fixed_magnetization(3))
                        is constrained:
                        
                        LAMBDA * ( arccos(magnetization(3)/mag_tot) - theta )**2
                        
                        where mag_tot is the modulus of the total magnetization.
    
                   'atomic direction' :
                        not all the components of the atomic
                        magnetic moment are constrained but only the cosine
                        of angle1, and the penalty functional is:
                        
                        LAMBDA * SUM_{itype} ( mag_mom(3,itype)/mag_mom_tot - cos(angle1(ityp)) )**2
    
                   N.B.: symmetrization may prevent to reach the desired orientation
                   of the magnetization. Try not to start with very highly symmetric
                   configurations or use the nosym flag (only as a last remedy)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       fixed_magnetization(i), i=1,3
   
   Type:           REAL
   See:            constrained_magnetization
   Default:        0.d0
   Description:    total magnetization vector (x,y,z components) to be kept
                   fixed when "constrained_magnetization"=='total'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lambda
   
   Type:           REAL
   See:            constrained_magnetization
   Default:        1.d0
   Description:    parameter used for constrained_magnetization calculations
                   N.B.: if the scf calculation does not converge, try to reduce lambda
                         to obtain convergence, then restart the run with a larger lambda
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       report
   
   Type:           INTEGER
   Default:        100
   Description:    Number of iterations after which the program
                   writes all the atomic magnetic moments.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       lspinorb
   
   Type:           LOGICAL
   Description:    if .TRUE. the noncollinear code can use a pseudopotential with
                   spin-orbit.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       assume_isolated
   
   Type:           CHARACTER
   Default:        'none'
   Description:   
                   Used to perform calculation assuming the system to be
                   isolated (a molecule or a cluster 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. An estimate of the vacuum
                        level is also calculated so that eigenvalues can be
                        properly aligned. ONLY FOR CUBIC SYSTEMS ("ibrav"=1,2,3).
                        Theory: G.Makov, and M.C.Payne,
                             "Periodic boundary conditions in ab initio
                             calculations" , PRB 51, 4014 (1995).
    
                   'martyna-tuckerman', 'm-t', 'mt' :
                        Martyna-Tuckerman correction
                        to both total energy and scf potential. Adapted from:
                        G.J. Martyna, and M.E. Tuckerman,
                        "A reciprocal space based method for treating long
                        range interactions in ab-initio and force-field-based
                        calculation in clusters", J.Chem.Phys. 110, 2810 (1999).
    
                   'esm' :
                        Effective Screening Medium Method.
                        For polarized or charged slab calculation, embeds
                        the simulation cell within an effective semi-
                        infinite medium in the perpendicular direction
                        (along z). Embedding regions can be vacuum or
                        semi-infinite metal electrodes (use 'esm_bc' to
                        choose boundary conditions). If between two
                        electrodes, an optional electric field
                        ('esm_efield') may be applied. Method described in
                        M. Otani and O. Sugino, "First-principles calculations
                        of charged surfaces and interfaces: A plane-wave
                        nonrepeated slab approach", PRB 73, 115407 (2006).
                        
                        NB:
                           - Two dimensional (xy plane) average charge density
                             and electrostatic potentials are printed out to
                             'prefix.esm1'.
                        
                           - Requires cell with a_3 lattice vector along z,
                             normal to the xy plane, with the slab centered
                             around z=0. Also requires symmetry checking to be
                             disabled along z, either by setting "nosym" = .TRUE.
                             or by very slight displacement (i.e., 5e-4 a.u.)
                             of the slab along z.
                        
                        See "esm_bc", "esm_efield", "esm_w", "esm_nfit".
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       esm_bc
   
   Type:           CHARACTER
   See:            assume_isolated
   Default:        'pbc'
   Description:   
                   If "assume_isolated" = 'esm', determines the boundary
                   conditions used for either side of the slab.
                   
                   Currently available choices:
    
                   'pbc' :
                        (default): regular periodic calculation (no ESM).
    
                   'bc1' :
                        Vacuum-slab-vacuum (open boundary conditions).
    
                   'bc2' :
                        Metal-slab-metal (dual electrode configuration).
                        See also "esm_efield".
    
                   'bc3' :
                        Vacuum-slab-metal
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       esm_w
   
   Type:           REAL
   See:            assume_isolated
   Default:        0.d0
   Description:    If "assume_isolated" = 'esm', determines the position offset
                   [in a.u.] of the start of the effective screening region,
                   measured relative to the cell edge. (ESM region begins at
                   z = +/- [L_z/2 + esm_w] ).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       esm_efield
   
   Type:           REAL
   See:            assume_isolated
   Default:        0.d0
   Description:    If "assume_isolated" = 'esm' and esm_bc = 'bc2', gives the
                   magnitude of the electric field [Ry/a.u.] to be applied
                   between semi-infinite ESM electrodes.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       esm_nfit
   
   Type:           INTEGER
   See:            assume_isolated
   Default:        4
   Description:    If "assume_isolated" = 'esm', gives the number of z-grid points
                   for the polynomial fit along the cell edge.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       fcp_mu
   
   Type:           REAL
   See:            lfcpopt
   Default:        0.d0
   Description:    If "lfcpopt" = .TRUE., gives the target Fermi energy [Ry]. One can start
                   with appropriate total charge of the system by giving 'tot_charge'.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       vdw_corr
   
   Type:           CHARACTER
   Default:        'none'
   See:            london_s6, london_rcut, london_c6, london_rvdw, ts_vdw_econv_thr, ts_vdw_isolated, xdm_a1, xdm_a2
   Description:   
                   Type of Van der Waals correction. Allowed values:
    
                   'grimme-d2', 'Grimme-D2', 'DFT-D', 'dft-d'  :
                        Semiempirical Grimme's DFT-D2.
                        Optional variables: "london_s6", "london_rcut", "london_c6", "london_rvdw",
                        S. Grimme, J. Comp. Chem. 27, 1787 (2006),
                        V. Barone et al., J. Comp. Chem. 30, 934 (2009).
    
                   'TS', 'ts', 'ts-vdw', 'ts-vdW', 'tkatchenko-scheffler' :
                        Tkatchenko-Scheffler dispersion corrections with first-principle derived
                        C6 coefficients (implemented in CP only).
                        Optional variables: "ts_vdw_econv_thr", "ts_vdw_isolated"
                        See A. Tkatchenko and M. Scheffler, PRL 102, 073005 (2009).
    
                   'XDM', 'xdm' :
                        Exchange-hole dipole-moment model. Optional variables: "xdm_a1", "xdm_a2"
                        A. D. Becke and E. R. Johnson, J. Chem. Phys. 127, 154108 (2007)
                        A. Otero de la Roza, E. R. Johnson, J. Chem. Phys. 136, 174109 (2012)
    
                   Note that non-local functionals (eg vdw-DF) are NOT specified here but in "input_dft"
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       london
   
   Type:           LOGICAL
   Default:        .FALSE.
   Status:         OBSOLESCENT, same as "vdw_corr"='DFT-D'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       london_s6
   
   Type:           REAL
   Default:        0.75
   Description:    global scaling parameter for DFT-D. Default is good for PBE.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       london_c6(i), i=1,ntyp
   
   Type:           REAL
   Default:        standard Grimme-D2 values
   Description:    atomic C6 coefficient of each atom type
                   
                   ( if not specified default values from S. Grimme, J. Comp. Chem. 27, 1787 (2006) are used;
                     see file Modules/mm_dispersion.f90 )
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       london_rvdw(i), i=1,ntyp
   
   Type:           REAL
   Default:        standard Grimme-D2 values
   Description:    atomic vdw radii of each atom type
                   
                   ( if not specified default values from S. Grimme, J. Comp. Chem. 27, 1787 (2006) are used;
                     see file Modules/mm_dispersion.f90 )
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       london_rcut
   
   Type:           REAL
   Default:        200
   Description:    cutoff radius (a.u.) for dispersion interactions
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ts_vdw_econv_thr
   
   Type:           REAL
   Default:        1.D-6
   Description:    Optional: controls the convergence of the vdW energy (and forces). The default value
                   is a safe choice, likely too safe, but you do not gain much in increasing it
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ts_vdw_isolated
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    Optional: set it to .TRUE. when computing the Tkatchenko-Scheffler vdW energy
                   for an isolated (non-periodic) system.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       xdm
   
   Type:           LOGICAL
   Default:        .FALSE.
   Status:         OBSOLESCENT, same as "vdw_corr"='xdm'
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       xdm_a1
   
   Type:           REAL
   Default:        0.6836
   Description:    Damping function parameter a1 (adimensional). This value should change
                   with the exchange-correlation functional. The default corresponds to
                   PW86PBE.
                   For other functionals, see:
                      http://schooner.chem.dal.ca/wiki/XDM
                      A. Otero de la Roza, E. R. Johnson, J. Chem. Phys. 138, 204109 (2013)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       xdm_a2
   
   Type:           REAL
   Default:        1.5045
   Description:    Damping function parameter a2 (angstrom). This value should change
                   with the exchange-correlation functional. The default corresponds to
                   PW86PBE.
                   For other functionals, see:
                      http://schooner.chem.dal.ca/wiki/XDM
                      A. Otero de la Roza, E. R. Johnson, J. Chem. Phys. 138, 204109 (2013)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       space_group
   
   Type:           INTEGER
   Default:        0
   Description:    The number of the space group of the crystal, as given
                   in the International Tables of Crystallography A (ITA).
                   This allows to give in input only the inequivalent atomic
                   positions. The positions of all the symmetry equivalent atoms
                   are calculated by the code. Used only when the atomic positions
                   are of type crystal_sg.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       uniqueb
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    Used only for monoclinic lattices. If .TRUE. the b
                   unique ibrav (-12 or -13) are used, and symmetry
                   equivalent positions are chosen assuming that the
                   two fold axis or the mirror normal is parallel to the
                   b axis. If .FALSE. it is parallel to the c axis.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       origin_choice
   
   Type:           INTEGER
   Default:        1
   Description:    Used only for space groups that in the ITA allow
                   the use of two different origins. origin_choice=1,
                   means the first origin, while origin_choice=2 is the
                   second origin.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       rhombohedral
   
   Type:           LOGICAL
   Default:        .TRUE.
   Description:    Used only for rhombohedral space groups.
                   When .TRUE. the coordinates of the inequivalent atoms are
                   given with respect to the rhombohedral axes, when .FALSE.
                   the coordinates of the inequivalent atoms are given with
                   respect to the hexagonal axes. They are converted internally
                   to the rhombohedral axes and "ibrav"=5 is used in both cases.
   +--------------------------------------------------------------------
   
   ///---
      BELOW VARIABLES ARE USED ONLY IF "MONOPOLE" = .TRUE.
      
      +--------------------------------------------------------------------
      Variable:       zmon
      
      Type:           REAL
      Default:        0.5
      Description:    used only if "monopole" = .TRUE.
                      Specifies the position of the charged plate which represents
                      the counter charge in doped systems ("tot_charge" .ne. 0).
                      In units of the unit cell length in z direction, "zmon" in ]0,1[
                      Details of the monopole potential can be found in
                      T. Brumme, M. Calandra, F. Mauri; PRB 89, 245406 (2014).
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       realxz
      
      Type:           LOGICAL
      Default:        .FALSE.
      Description:    used only if "monopole" = .TRUE.
                      Allows the relaxation of the system towards the charged plate.
                      Use carefully and utilize either a layer of fixed atoms or a
                      potential barrier ("block"=.TRUE.) to avoid the atoms moving to
                      the position of the plate or the dipole of the dipole
                      correction ("dipfield"=.TRUE.).
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       block
      
      Type:           LOGICAL
      Default:        .FALSE.
      Description:    used only if "monopole" = .TRUE.
                      Adds a potential barrier to the total potential seen by the
                      electrons to mimic a dielectric in field effect configuration
                      and/or to avoid electrons spilling into the vacuum region for
                      electron doping. Potential barrier is from "block_1" to "block_2" and
                      has a height of block_height.
                      If "dipfield" = .TRUE. then "eopreg" is used for a smooth increase and
                      decrease of the potential barrier.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       block_1
      
      Type:           REAL
      Default:        0.45
      Description:    used only if "monopole" = .TRUE. and "block" = .TRUE.
                      lower beginning of the potential barrier, in units of the
                      unit cell size along z, "block_1" in ]0,1[
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       block_2
      
      Type:           REAL
      Default:        0.55
      Description:    used only if "monopole" = .TRUE. and "block" = .TRUE.
                      upper beginning of the potential barrier, in units of the
                      unit cell size along z, "block_2" in ]0,1[
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       block_height
      
      Type:           REAL
      Default:        0.1
      Description:    used only if "monopole" = .TRUE. and "block" = .TRUE.
                      Height of the potential barrier in Rydberg.
      +--------------------------------------------------------------------
      
   \\\---
   
===END OF NAMELIST======================================================


========================================================================
NAMELIST: &ELECTRONS

   +--------------------------------------------------------------------
   Variable:       electron_maxstep
   
   Type:           INTEGER
   Default:        100
   Description:    maximum number of iterations in a scf step
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       scf_must_converge
   
   Type:           LOGICAL
   Default:        .TRUE.
   Description:    If .false. do not stop molecular dynamics or ionic relaxation
                   when electron_maxstep is reached. Use with care.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       conv_thr
   
   Type:           REAL
   Default:        1.D-6
   Description:    Convergence threshold for selfconsistency:
                      estimated energy error < conv_thr
                   (note that conv_thr is extensive, like the total energy).
                   
                   For non-self-consistent calculations, conv_thr is used
                   to set the default value of the threshold (ethr) for
                   iterative diagonalizazion: see "diago_thr_init"
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       adaptive_thr
   
   Type:           LOGICAL
   Default:        .FALSE
   Description:    If .TRUE. this turns on the use of an adaptive conv_thr for
                   the inner scf loops when using EXX.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       conv_thr_init
   
   Type:           REAL
   Default:        1.D-3
   Description:    When "adaptive_thr" = .TRUE. this is the convergence threshold
                   used for the first scf cycle.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       conv_thr_multi
   
   Type:           REAL
   Default:        1.D-1
   Description:    When "adaptive_thr" = .TRUE. the convergence threshold for
                   each scf cycle is given by:
                   max( "conv_thr", "conv_thr_multi" * dexx )
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       mixing_mode
   
   Type:           CHARACTER
   Default:        'plain'
   Description:   
                   Available options are:
    
                   'plain' :
                        charge density Broyden mixing
    
                   'TF' :
                        as above, with simple Thomas-Fermi screening
                        (for highly homogeneous systems)
    
                   'local-TF' :
                        as above, with local-density-dependent TF screening
                        (for highly inhomogeneous systems)
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       mixing_beta
   
   Type:           REAL
   Default:        0.7D0
   Description:    mixing factor for self-consistency
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       mixing_ndim
   
   Type:           INTEGER
   Default:        8
   Description:    number of iterations used in mixing scheme.
                   If you are tight with memory, you may reduce it to 4 or so.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       mixing_fixed_ns
   
   Type:           INTEGER
   Default:        0
   Description:    For DFT+U : number of iterations with fixed ns ( ns is the
                   atomic density appearing in the Hubbard term ).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       diagonalization
   
   Type:           CHARACTER
   Default:        'david'
   Description:   
                   Available options are:
    
                   'david' :
                        Davidson iterative diagonalization with overlap matrix
                        (default). Fast, may in some rare cases fail.
    
                   'cg' :
                        Conjugate-gradient-like band-by-band diagonalization.
                        Typically slower than 'david' but it uses less memory
                        and is more robust (it seldom fails).
    
                   'cg-serial', 'david-serial' :
                        OBSOLETE, use -ndiag 1 instead.
                        The subspace diagonalization in Davidson is performed
                        by a fully distributed-memory parallel algorithm on
                        4 or more processors, by default. The allocated memory
                        scales down with the number of procs. Procs involved
                        in diagonalization can be changed with command-line
                        option -ndiag N. On multicore CPUs it is often
                        convenient to let just one core per CPU to work
                        on linear algebra.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ortho_para
   
   Type:           INTEGER
   Default:        0
   Status:         OBSOLETE: use command-line option "-ndiag XX" instead
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       diago_thr_init
   
   Type:           REAL
   Description:    Convergence threshold (ethr) for iterative diagonalization
                   (the check is on eigenvalue convergence).
                   
                   For scf calculations: default is 1.D-2 if starting from a
                   superposition of atomic orbitals; 1.D-5 if starting from a
                   charge density. During self consistency the threshold
                   is automatically reduced (but never below 1.D-13) when
                   approaching convergence.
                   
                   For non-scf calculations: default is (conv_thr/N elec)/10.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       diago_cg_maxiter
   
   Type:           INTEGER
   Description:    For conjugate gradient diagonalization:  max number of iterations
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       diago_david_ndim
   
   Type:           INTEGER
   Default:        4
   Description:    For Davidson diagonalization: dimension of workspace
                   (number of wavefunction packets, at least 2 needed).
                   A larger value may yield a somewhat faster algorithm
                   but uses more memory. The opposite holds for smaller values.
                   Try "diago_david_ndim"=2 if you are tight on memory or if
                   your job is large: the speed penalty is often negligible
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       diago_full_acc
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .TRUE. all the empty states are diagonalized at the same level
                   of accuracy of the occupied ones. Otherwise the empty states are
                   diagonalized using a larger threshold (this should not affect
                   total energy, forces, and other ground-state properties).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       efield
   
   Type:           REAL
   Default:        0.D0
   Description:    Amplitude of the finite electric field (in Ry a.u.;
                   1 a.u. = 36.3609*10^10 V/m). Used only if "lelfield"==.TRUE.
                   and if k-points ("K_POINTS" card) are not automatic.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       efield_cart(i), i=1,3
   
   Type:           REAL
   Default:        (0.D0, 0.D0, 0.D0)
   Description:    Finite electric field (in Ry a.u.=36.3609*10^10 V/m) in
                   cartesian axis. Used only if "lelfield"==.TRUE. and if
                   k-points ("K_POINTS" card) are automatic.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       efield_phase
   
   Type:           CHARACTER
   Default:        'none'
   Description:   
                   Available options are:
    
                   'read' :
                        set the zero of the electronic polarization (with "lelfield"==.true..)
                        to the result of a previous calculation
    
                   'write' :
                        write on disk data on electronic polarization to be read in another
                        calculation
    
                   'none' :
                        none of the above points
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       startingpot
   
   Type:           CHARACTER
   Description:   
                   Available options are:
    
                   'atomic' :
                        starting potential from atomic charge superposition
                        (default for scf, *relax, *md)
    
                   'file' :
                        start from existing "charge-density.xml" file in the
                        directory specified by variables "prefix" and "outdir"
                        For nscf and bands calculation this is the default
                        and the only sensible possibility.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       startingwfc
   
   Type:           CHARACTER
   Default:        'atomic+random'
   Description:   
                   Available options are:
    
                   'atomic' :
                        Start from superposition of atomic orbitals.
                        If not enough atomic orbitals are available,
                        fill with random numbers the remaining wfcs
                        The scf typically starts better with this option,
                        but in some high-symmetry cases one can "loose"
                        valence states, ending up in the wrong ground state.
    
                   'atomic+random' :
                        As above, plus a superimposed "randomization"
                        of atomic orbitals. Prevents the "loss" of states
                        mentioned above.
    
                   'random' :
                        Start from random wfcs. Slower start of scf but safe.
                        It may also reduce memory usage in conjunction with
                        "diagonalization"='cg'.
    
                   'file' :
                        Start from an existing wavefunction file in the
                        directory specified by variables "prefix" and "outdir".
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       tqr
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .true., use the real-space algorithm for augmentation
                   charges in ultrasoft pseudopotentials.
                   Must faster execution of ultrasoft-related calculations,
                   but numerically less accurate than the default algorithm.
                   Use with care and after testing!
   +--------------------------------------------------------------------
   
===END OF NAMELIST======================================================


========================================================================
NAMELIST: &IONS

   INPUT THIS NAMELIST ONLY IF "CALCULATION" == 'RELAX', 'MD', 'VC-RELAX', OR 'VC-MD'
   
   +--------------------------------------------------------------------
   Variable:       ion_dynamics
   
   Type:           CHARACTER
   Description:   
                   Specify the type of ionic dynamics.
                   
                   For different type of calculation different possibilities are
                   allowed and different default values apply:
                   
                   CASE ( "calculation" == 'relax' )
    
                   'bfgs' :
                        (default)  use BFGS quasi-newton algorithm,
                        based on the trust radius procedure,
                        for structural relaxation
    
                   'damp' :
                        use damped (quick-min Verlet)
                        dynamics for structural relaxation
                        Can be used for constrained
                        optimisation: see "CONSTRAINTS" card
    
                   CASE ( "calculation" == 'md' )
    
                   'verlet' :
                        (default)  use Verlet algorithm to integrate
                        Newton's equation. For constrained
                        dynamics, see "CONSTRAINTS" card
    
                   'langevin' :
                        ion dynamics is over-damped Langevin
    
                   'langevin-smc' :
                        over-damped Langevin with Smart Monte Carlo:
                        see R.J. Rossky, JCP, 69, 4628(1978)
    
                   CASE ( "calculation" == 'vc-relax' )
    
                   'bfgs' :
                        (default)  use BFGS quasi-newton algorithm;
                        cell_dynamics must be 'bfgs' too
    
                   'damp' :
                        use damped (Beeman) dynamics for
                        structural relaxation
    
                   CASE ( "calculation" == 'vc-md' )
    
                   'beeman' :
                        (default)  use Beeman algorithm to integrate
                        Newton's equation
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       ion_positions
   
   Type:           CHARACTER
   Default:        'default'
   Description:   
                   Available options are:
    
                   '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.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       pot_extrapolation
   
   Type:           CHARACTER
   Default:        'atomic'
   Description:   
                   Used to extrapolate the potential from preceding ionic steps.
    
                   'none' :
                        no extrapolation
    
                   'atomic' :
                        extrapolate the potential as if it was a sum of
                        atomic-like orbitals
    
                   'first_order' :
                        extrapolate the potential with first-order
                        formula
    
                   'second_order' :
                        as above, with second order formula
    
                   Note: 'first_order' and 'second-order' extrapolation make sense
                   only for molecular dynamics calculations
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       wfc_extrapolation
   
   Type:           CHARACTER
   Default:        'none'
   Description:   
                   Used to extrapolate the wavefunctions from preceding ionic steps.
    
                   'none' :
                        no extrapolation
    
                   'first_order' :
                        extrapolate the wave-functions with first-order formula.
    
                   'second_order' :
                        as above, with second order formula.
    
                   Note: 'first_order' and 'second-order' extrapolation make sense
                   only for molecular dynamics calculations
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       remove_rigid_rot
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    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.
   +--------------------------------------------------------------------
   
   ///---
      VARIABLES USED FOR MOLECULAR DYNAMICS
      
      +--------------------------------------------------------------------
      Variable:       ion_temperature
      
      Type:           CHARACTER
      Default:        'not_controlled'
      Description:   
                      Available options are:
       
                      'rescaling' :
                           control ionic temperature via velocity rescaling
                           (first method) see parameters "tempw", "tolp", and
                           "nraise" (for VC-MD only). This rescaling method
                           is the only one currently implemented in VC-MD
       
                      'rescale-v' :
                           control ionic temperature via velocity rescaling
                           (second method) see parameters "tempw" and "nraise"
       
                      'rescale-T' :
                           control ionic temperature via velocity rescaling
                           (third method) see parameter "delta_t"
       
                      'reduce-T' :
                           reduce ionic temperature every "nraise" steps
                           by the (negative) value "delta_t"
       
                      'berendsen' :
                           control ionic temperature using "soft" velocity
                           rescaling - see parameters "tempw" and "nraise"
       
                      'andersen' :
                           control ionic temperature using Andersen thermostat
                           see parameters "tempw" and "nraise"
       
                      'initial' :
                           initialize ion velocities to temperature "tempw"
                           and leave uncontrolled further on
       
                      'not_controlled' :
                           (default) ionic temperature is not controlled
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       tempw
      
      Type:           REAL
      Default:        300.D0
      Description:    Starting temperature (Kelvin) in MD runs
                      target temperature for most thermostats.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       tolp
      
      Type:           REAL
      Default:        100.D0
      Description:    Tolerance for velocity rescaling. Velocities are rescaled if
                      the run-averaged and target temperature differ more than tolp.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       delta_t
      
      Type:           REAL
      Default:        1.D0
      Description:    if "ion_temperature" == 'rescale-T' :
                             at each step the instantaneous temperature is multiplied
                             by delta_t; this is done rescaling all the velocities.
                      
                      if "ion_temperature" == 'reduce-T' :
                             every 'nraise' steps the instantaneous temperature is
                             reduced by -"delta_t" (i.e. "delta_t" < 0 is added to T)
                      
                      The instantaneous temperature is calculated at the end of
                      every ionic move and BEFORE rescaling. This is the temperature
                      reported in the main output.
                      
                      For "delta_t" < 0, the actual average rate of heating or cooling
                      should be roughly C*delta_t/(nraise*dt) (C=1 for an
                      ideal gas, C=0.5 for a harmonic solid, theorem of energy
                      equipartition between all quadratic degrees of freedom).
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       nraise
      
      Type:           INTEGER
      Default:        1
      Description:    if "ion_temperature" == 'reduce-T' :
                             every "nraise" steps the instantaneous temperature is
                             reduced by -"delta_t" (i.e. "delta_t" is added to the temperature)
                      
                      if "ion_temperature" == 'rescale-v' :
                             every "nraise" steps the average temperature, computed from
                             the last "nraise" steps, is rescaled to "tempw"
                      
                      if "ion_temperature" == 'rescaling' and "calculation" == 'vc-md' :
                             every "nraise" steps the instantaneous temperature
                             is rescaled to "tempw"
                      
                      if "ion_temperature" == 'berendsen' :
                             the "rise time" parameter is given in units of the time step:
                             tau = nraise*dt, so dt/tau = 1/nraise
                      
                      if "ion_temperature" == 'andersen' :
                             the "collision frequency" parameter is given as nu=1/tau
                             defined above, so nu*dt = 1/nraise
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       refold_pos
      
      Type:           LOGICAL
      Default:        .FALSE.
      Description:    This keyword applies only in the case of molecular dynamics or
                      damped dynamics. If true the ions are refolded at each step into
                      the supercell.
      +--------------------------------------------------------------------
      
   \\\---
   
   ///---
      KEYWORDS USED ONLY IN BFGS CALCULATIONS
      
      +--------------------------------------------------------------------
      Variable:       upscale
      
      Type:           REAL
      Default:        100.D0
      Description:    Max reduction factor for "conv_thr" during structural optimization
                      "conv_thr" is automatically reduced when the relaxation
                      approaches convergence so that forces are still accurate,
                      but "conv_thr" will not be reduced to less that "conv_thr" / "upscale".
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       bfgs_ndim
      
      Type:           INTEGER
      Default:        1
      Description:    Number of old forces and displacements vectors used in the
                      PULAY mixing of the residual vectors obtained on the basis
                      of the inverse hessian matrix given by the BFGS algorithm.
                      When "bfgs_ndim" = 1, the standard quasi-Newton BFGS method is
                      used.
                      (bfgs only)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       trust_radius_max
      
      Type:           REAL
      Default:        0.8D0
      Description:    Maximum ionic displacement in the structural relaxation.
                      (bfgs only)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       trust_radius_min
      
      Type:           REAL
      Default:        1.D-3
      Description:    Minimum ionic displacement in the structural relaxation
                      BFGS is reset when "trust_radius" < "trust_radius_min".
                      (bfgs only)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       trust_radius_ini
      
      Type:           REAL
      Default:        0.5D0
      Description:    Initial ionic displacement in the structural relaxation.
                      (bfgs only)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       w_1
      
      Type:           REAL
      Default:        0.01D0
      See:            w_2
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       w_2
      
      Type:           REAL
      Default:        0.5D0
      Description:    Parameters used in line search based on the Wolfe conditions.
                      (bfgs only)
      +--------------------------------------------------------------------
      
   \\\---
   
===END OF NAMELIST======================================================


========================================================================
NAMELIST: &CELL

   INPUT THIS NAMELIST ONLY IF "CALCULATION" == 'VC-RELAX' OR 'VC-MD'
   
   +--------------------------------------------------------------------
   Variable:       cell_dynamics
   
   Type:           CHARACTER
   Description:   
                   Specify the type of dynamics for the cell.
                   For different type of calculation different possibilities
                   are allowed and different default values apply:
                   
                   CASE ( "calculation" == 'vc-relax' )
    
                   'none' :
                        no dynamics
    
                   'sd' :
                        steepest descent ( not implemented )
    
                   'damp-pr' :
                        damped (Beeman) dynamics of the Parrinello-Rahman extended lagrangian
    
                   'damp-w' :
                        damped (Beeman) dynamics of the new Wentzcovitch extended lagrangian
    
                   'bfgs' :
                        BFGS quasi-newton algorithm (default)
                        "ion_dynamics" must be 'bfgs' too
    
                   CASE ( "calculation" == 'vc-md' )
    
                   'none' :
                        no dynamics
    
                   'pr' :
                        (Beeman) molecular dynamics of the Parrinello-Rahman extended lagrangian
    
                   'w' :
                        (Beeman) molecular dynamics of the new Wentzcovitch extended lagrangian
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       press
   
   Type:           REAL
   Default:        0.D0
   Description:    Target pressure [KBar] in a variable-cell md or relaxation run.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       wmass
   
   Type:           REAL
   Default:        0.75*Tot_Mass/pi**2 for Parrinello-Rahman MD;
                   0.75*Tot_Mass/pi**2/Omega**(2/3) for Wentzcovitch MD
   Description:    Fictitious cell mass [amu] for variable-cell simulations
                   (both 'vc-md' and 'vc-relax')
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       cell_factor
   
   Type:           REAL
   Default:        1.2D0
   Description:    Used in the construction of the pseudopotential tables.
                   It should exceed the maximum linear contraction of the
                   cell during a simulation.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       press_conv_thr
   
   Type:           REAL
   Default:        0.5D0 Kbar
   Description:    Convergence threshold on the pressure for variable cell
                   relaxation ('vc-relax' : note that the other convergence
                               thresholds for ionic relaxation apply as well).
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       cell_dofree
   
   Type:           CHARACTER
   Default:        'all'
   Description:   
                   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 v2_y are moved
    
                   'xz' :
                        only v1_x and v3_z are moved
    
                   'yz' :
                        only v2_y and v3_z are moved
    
                   'xyz' :
                        only v1_x, v2_y, v3_z are moved
    
                   'shape' :
                        all axis and angles, keeping the volume fixed
    
                   'volume' :
                        the volume changes, keeping all angles fixed (i.e. only celldm(1) changes)
    
                   '2Dxy' :
                        only x and y components are allowed to change
    
                   '2Dshape' :
                        as above, keeping the area in xy plane fixed
    
                   BEWARE: if axis are not orthogonal, some of these options do not
                           work (symmetry is broken). If you are not happy with them,
                           edit subroutine init_dofree in file Modules/cell_base.f90
   +--------------------------------------------------------------------
   
===END OF NAMELIST======================================================


========================================================================
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:
   
      +--------------------------------------------------------------------
      Variable:       X
      
      Type:           CHARACTER
      Description:    label of the atom. Acceptable syntax:
                      chemical symbol X (1 or 2 characters, case-insensitive)
                      or chemical symbol plus a number or a letter, as in
                      "Xn" (e.g. Fe1) or "X_*" or "X-*" (e.g. C1, C_h;
                      max total length cannot exceed 3 characters)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       Mass_X
      
      Type:           REAL
      Description:    mass of the atomic species [amu: mass of C = 12]
                      Used only when performing Molecular Dynamics run
                      or structural optimization runs using Damped MD.
                      Not actually used in all other cases (but stored
                      in data files, so phonon calculations will use
                      these values unless other values are provided)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       PseudoPot_X
      
      Type:           CHARACTER
      Description:    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
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
CARD: ATOMIC_POSITIONS { alat | bohr | angstrom | crystal | crystal_sg }

   ________________________________________________________________________
   * IF calculation == 'bands' OR calculation == 'nscf' : 
   
      Specified atomic positions will be IGNORED and those from the
      previous scf calculation will be used instead !!!
      
       
   * ELSE : 
   
      /////////////////////////////////////////
      // Syntax:                             //
      /////////////////////////////////////////
      
         ATOMIC_POSITIONS { alat | bohr | angstrom | crystal | crystal_sg }
            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)  }  
      
      /////////////////////////////////////////
      
       
   ENDIF
   ________________________________________________________________________
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Card's flags:   { alat | bohr | angstrom | crystal | crystal_sg }
      
      Default:        (DEPRECATED) alat
      Description:   
                      Units for ATOMIC_POSITIONS:
       
                      alat :
                           atomic positions are in cartesian coordinates, in
                           units of the lattice parameter (either celldm(1)
                           or A). If no option is specified, 'alat' is assumed;
                           not specifying units is DEPRECATED and will no
                           longer be allowed in the future
       
                      bohr :
                           atomic positions are in cartesian coordinate,
                           in atomic units (i.e. Bohr radii)
       
                      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 as defined either in card "CELL_PARAMETERS"
                           or via the ibrav + celldm / a,b,c... variables
       
                      crystal_sg :
                           atomic positions are in crystal coordinates, i.e.
                           in relative coordinates of the primitive lattice.
                           This option differs from the previous one because
                           in this case only the symmetry inequivalent atoms
                           are given. The variable space_group must indicate
                           the space group number used to find the symmetry
                           equivalent atoms. The other variables that control
                           this option are uniqueb, origin_choice, and
                           rhombohedral.
      +--------------------------------------------------------------------


      +--------------------------------------------------------------------
      Variable:       X
      
      Type:           CHARACTER
      Description:    label of the atom as specified in "ATOMIC_SPECIES"
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      x, y, z
      
      Type:           REAL
      Description:    atomic positions
                      
                      NOTE: each atomic coordinate can also be specified as a simple algebraic expression.
                            To be interpreted correctly expression must NOT contain any blank
                            space and must NOT start with a "+" sign. The available expressions are:
                      
                              + (plus), - (minus), / (division), * (multiplication), ^ (power)
                      
                            All numerical constants included are considered as double-precision numbers;
                            i.e. 1/2 is 0.5, not zero. Other functions, such as sin, sqrt or exp are
                            not available, although sqrt can be replaced with ^(1/2).
                      
                            Example:
                                  C  1/3   1/2*3^(-1/2)   0
                      
                            is equivalent to
                      
                                  C  0.333333  0.288675  0.000000
                      
                            Please note that this feature is NOT supported by XCrysDen (which will
                            display a wrong structure, or nothing at all).
                      
                            When atomic positions are of type crystal_sg coordinates can be given
                            in the following four forms (Wyckoff positions):
                               C  1a
                               C  8g   x
                               C  24m  x y
                               C  48n  x y z
                            The first form must be used when the Wyckoff letter determines uniquely
                            all three coordinates, forms 2,3,4 when the Wyckoff letter and 1,2,3
                            coordinates respectively are needed.
                      
                            The forms:
                               C 8g  x  x  x
                               C 24m x  x  y
                            are not allowed, but
                               C x x x
                               C x x y
                               C x y z
                            are correct.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      if_pos(1), if_pos(2), if_pos(3)
      
      Type:           INTEGER
      Default:        1
      Description:    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.
                      
                      With crystal_sg atomic coordinates the constraints are copied in all equivalent
                      atoms.
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
CARD: K_POINTS { tpiba | automatic | crystal | gamma | tpiba_b | crystal_b | tpiba_c | crystal_c }

   ________________________________________________________________________
   * IF tpiba  OR  crystal  OR  tpiba_b  OR  crystal_b OR tpiba_c OR crystal_c : 
   
      /////////////////////////////////////////
      // Syntax:                             //
      /////////////////////////////////////////
      
         K_POINTS tpiba | crystal | tpiba_b | crystal_b | tpiba_c | crystal_c 
            nks
            xk_x(1)    xk_y(1)    xk_z(1)    wk(1)    
            xk_x(2)    xk_y(2)    xk_z(2)    wk(2)    
            . . . 
            xk_x(nks)  xk_y(nks)  xk_z(nks)  wk(nks)  
      
      /////////////////////////////////////////
      
       
   * ELSE IF automatic : 
   
      /////////////////////////////////////////
      // Syntax:                             //
      /////////////////////////////////////////
      
         K_POINTS automatic
            nk1 nk2 nk3 sk1 sk2 sk3
      
      /////////////////////////////////////////
      
       
   * ELSE IF gamma : 
   
      /////////////////////////////////////////
      // Syntax:                             //
      /////////////////////////////////////////
      
         K_POINTS gamma
      
      /////////////////////////////////////////
      
       
   ENDIF
   ________________________________________________________________________
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Card's flags:   { tpiba | automatic | crystal | gamma | tpiba_b | crystal_b | tpiba_c | crystal_c }
      
      Default:        tbipa
      Description:   
                      K_POINTS options are:
       
                      tpiba :
                           read k-points in cartesian coordinates,
                           in units of 2 pi/a (default)
       
                      automatic :
                           automatically generated uniform grid of k-points, i.e,
                           generates ( nk1, nk2, nk3 ) grid with ( sk1, sk2, sk3 ) offset.
                           nk1, nk2, nk3 as in Monkhorst-Pack grids
                           k1, k2, k3 must be 0 ( no offset ) or 1 ( grid displaced
                           by half a grid step in the corresponding direction )
                           BEWARE: only grids having the full symmetry of the crystal
                                   work with tetrahedra. Some grids with offset may not work.
       
                      crystal :
                           read k-points in crystal coordinates, i.e. in relative
                           coordinates of the reciprocal lattice vectors
       
                      gamma :
                           use k = 0 (no need to list k-point specifications after card)
                           In this case wavefunctions can be chosen as real,
                           and specialized subroutines optimized for calculations
                           at the gamma point are used (memory and cpu requirements
                           are reduced by approximately one half).
       
                      tpiba_b :
                           Used for band-structure plots.
                           k-points are in units of  2 pi/a.
                           nks points specify nks-1 lines in reciprocal space.
                           Every couple of points identifies the initial and
                           final point of a line. pw.x generates N intermediate
                           points of the line where N is the weight of the first point.
       
                      crystal_b :
                           As tpiba_b, but k-points are in crystal coordinates.
       
                      tpiba_c :
                           Used for band-structure contour plots.
                           k-points are in units of  2 pi/a. nks must be 3.
                           3 k-points k_0, k_1, and k_2 specify a rectangle
                           in reciprocal space of vertices k_0, k_1, k_2,
                           k_1 + k_2 - k_0: k_0 + \alpha (k_1-k_0)+
                           \beta (k_2-k_0) with 0 <\alpha,\beta < 1.
                           The code produces a uniform mesh n1 x n2
                           k points in this rectangle. n1 and n2 are
                           the weights of k_1 and k_2. The weight of k_0
                           is not used.
       
                      crystal_c :
                           As tpiba_c, but k-points are in crystal coordinates.
      +--------------------------------------------------------------------


      +--------------------------------------------------------------------
      Variable:       nks
      
      Type:           INTEGER
      Description:    Number of supplied special k-points.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      xk_x, xk_y, xk_z, wk
      
      Type:           REAL
      Description:    Special k-points (xk_x/y/z) in the irreducible Brillouin Zone
                      (IBZ) of the lattice (with all symmetries) and weights (wk)
                      See the literature for lists of special points and
                      the corresponding weights.
                      
                      If the symmetry is lower than the full symmetry
                      of the lattice, additional points with appropriate
                      weights are generated. Notice that such procedure
                      assumes that ONLY k-points in the IBZ are provided in input
                      
                      In a non-scf calculation, weights do not affect the results.
                      If you just need eigenvalues and eigenvectors (for instance,
                      for a band-structure plot), weights can be set to any value
                      (for instance all equal to 1).
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      nk1, nk2, nk3
      
      Type:           INTEGER
      Description:    These parameters specify the k-point grid
                      (nk1 x nk2 x nk3) as in Monkhorst-Pack grids.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      sk1, sk2, sk3
      
      Type:           INTEGER
      Description:    The grid offsets;  sk1, sk2, sk3 must be
                      0 ( no offset ) or 1 ( grid displaced by
                      half a grid step in the corresponding direction ).
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
CARD: CELL_PARAMETERS { alat | bohr | angstrom }

   OPTIONAL CARD, NEEDED ONLY IF "IBRAV" == 0 IS SPECIFIED, IGNORED OTHERWISE !
   
   /////////////////////////////////////////
   // Syntax:                             //
   /////////////////////////////////////////
   
      CELL_PARAMETERS { alat | bohr | angstrom }
         v1(1)  v1(2)  v1(3)  
         v2(1)  v2(2)  v2(3)  
         v3(1)  v3(2)  v3(3)  
   
   /////////////////////////////////////////
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Card's flags:   { alat | bohr | angstrom }
      
      Description:    Unit for lattice vectors; options are:
                      
                      'bohr' / 'angstrom':
                                           lattice vectors in bohr-radii / angstrom.
                                           In this case the lattice parameter alat = sqrt(v1*v1).
                      
                      'alat' / nothing specified:
                                           lattice vectors in units of the lattice parameter (either
                                           "celldm"(1) or "A"). Not specifying units is DEPRECATED
                                           and will not be allowed in the future.
                      
                      If neither unit nor lattice parameter are specified,
                      'bohr' is assumed - DEPRECATED, will no longer be allowed
      +--------------------------------------------------------------------


      +--------------------------------------------------------------------
      Variables:      v1, v2, v3
      
      Type:           REAL
      Description:    Crystal lattice vectors (in cartesian axis):
                          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
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
CARD: CONSTRAINTS 

   OPTIONAL CARD, USED FOR CONSTRAINED DYNAMICS OR CONSTRAINED OPTIMISATIONS
   (ONLY IF "ION_DYNAMICS"=='DAMP' OR 'VERLET', VARIABLE-CELL EXCEPTED)
   
   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:
   
      +--------------------------------------------------------------------
      Variable:       nconstr
      
      Type:           INTEGER
      Description:    Number of constraints.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       constr_tol
      
      Type:           REAL
      Description:    Tolerance for keeping the constraints satisfied.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       constr_type
      
      Type:           CHARACTER
      Description:   
                      Type of constraint :
       
                      '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.
                           G. Roma, J.P. Crocombette: J. Nucl. Mater. 403, 32 (2010)
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      constr(1), constr(2), constr(3), constr(4)
      
      Description:    These variables have different meanings for different constraint types:
                      
                      @b 'type_coord' :
                                     @i constr(1) is the first index of the atomic type involved
                                     @i constr(2) is the second index of the atomic type involved
                                     @i constr(3) is the cut-off radius for estimating the coordination
                                     @i constr(4) is a smoothing parameter
                      
                      @b 'atom_coord' :
                                     @i constr(1) is the atom index of the atom with constrained coordination
                                     @i constr(2) is the index of the atomic type involved in the coordination
                                     @i constr(3) is the cut-off radius for estimating the coordination
                                     @i constr(4) is a smoothing parameter
                      
                      @b 'distance' :
                                     atoms indices object of the constraint, as they appear in
                                     the @ref ATOMIC_POSITIONS card
                      
                      @b 'planar_angle', @b 'torsional_angle' :
                                     atoms indices object of the constraint, as they appear in the
                                     @ref ATOMIC_POSITIONS card (beware the order)
                      
                      @b 'bennett_proj' :
                                     @i constr(1) is the index of the atom whose position is constrained.
                                     @i constr(2:4) are the three coordinates of the vector that specifies
                                     the constraint direction.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       constr_target
      
      Type:           REAL
      Description:    Target for the constrain ( angles are specified in degrees ).
                      This variable is optional.
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
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:
   
      +--------------------------------------------------------------------
      Variable:       f_inp1
      
      Type:           REAL
      Description:    Occupations of individual states (MAX 10 PER ROW).
                      For spin-polarized calculations, these are majority spin states.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variable:       f_inp2
      
      Type:           REAL
      Description:    Occupations of minority spin states (MAX 10 PER ROW)
                      To be specified only for spin-polarized calculations.
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
CARD: ATOMIC_FORCES 

   OPTIONAL CARD USED TO SPECIFY EXTERNAL FORCES ACTING ON ATOMS.
   
   BEWARE: if the sum of external forces is not zero, the center of mass of
           the system will move
   
   /////////////////////////////////////////
   // Syntax:                             //
   /////////////////////////////////////////
   
      ATOMIC_FORCES 
         X(1)    fx(1)    fy(1)    fz(1)    
         X(2)    fx(2)    fy(2)    fz(2)    
         . . . 
         X(nat)  fx(nat)  fy(nat)  fz(nat)  
   
   /////////////////////////////////////////
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Variable:       X
      
      Type:           CHARACTER
      Description:    label of the atom as specified in "ATOMIC_SPECIES"
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      fx, fy, fz
      
      Type:           REAL
      Description:    external force on atom X (cartesian components, Ry/a.u. units)
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


This file has been created by helpdoc utility on Tue Oct 04 14:26:48 CEST 2016