Input parameters in `inp`
=========================

The following is a list of the various namelists that can be specified
in the input files. Not all of these will be used; in fact, generally
very few of these will, since the program picks reasonable defaults.
This list is a modification/expansion of one originally put together
by Cesare Franchini. Although most of the variables and defaults
should be correct, some of the more obscure parameters may not be
correct; however, those will (probably) never need to be changed.

The important namelists, i.e., the ones that are used often, are
`&input`, `&allatoms`, `&atom`, `&comp`, `&conv`, `&exco`, `&geo`,
`&kpt`, `&mix`, `&out`,
`&relax`. Although the list seems long, only some of the parameters are
likely to be used; some of the most commonly used ones are highlighted.
Although the
order of the runtime namelists is unimportant (those that can be put
after the structural input on the file `inp` or in the file `para`), for
the structural properties, the order is important; these namelists
(see :ref:`main_input`.) are given in `italics`.

A number of parameters  (mainly in
`&conv` and `&mix`) can be changed during the run by writing the
new values to the file `conv` which is reread every iteration; see below.

Defaults, where applicible, are given.

.. _all_parameters:


All namelists
--------------

.. index:: pair: namelist, structural;allatoms

*allatoms*
"""""""""""""""""""""

   :dir:`dx`
      log. mesh parameter (`default: 0.028`)

   :dir:`jri`
      number of radial mesh points in muffin tins (`default: 361`)

   :dir:`lmax`
      max. l to include for charge/potential (`default: 8`)

   :dir:`lmax_wf`
      max. l to include for wave functions (`default: 8`)

   :dir:`lnonsph`
      :math:`\Delta l` for nonspherical contributions to matrix elements (`default: 4`) 

   :dir:`rmt`
      muffin-tin radius

   .. parameter:: non_rel

      if true, then non-relativistic calculation (`default: false`)


.. index:: pair: namelist, structural;atoms

*atom*
""""""""""""""""""

   .. parameter:: econfig

      electronic config: program will pick a reasonable configuration;
      core/valence states separated by '|'; scalar core states have a 's' appended

      Examples::

          B: econfig='1s2 | 2s2 2p2'
          B 1s-corehole: econfig='1s1 | 2s2 2p2'
          Co: econfig = '[Ar] | 3d7 4s2'
          Co, scalar 3p: econfig = '[Ne] 3s2 3p6s | 3d7 4s2'
   
      To specify (core) occupations of relativistic levels, give j value::

          econfig='1s2 2s2 2p(1/2)1 2p(3/2)4 | 3s2 3p2'

      By default core holes are put in the highest j level.

   .. parameter:: element

      | atom name
      | Example: `element='Ni'`

   .. parameter:: dx

      log. mesh parameter (`default: 0.028`)

   .. parameter:: id 

      atom identifier used in atomic positions

   .. parameter:: jri

      Number of radial mesh points in muffin tins (`default: 361`).

   .. parameter:: lmax

      max. l to include for charge/potential (`default: 8`)

   .. parameter:: lmax_wf

      max. l to include for wave functions (`default: 8`)

   .. parameter:: lnonsph

      :math:`\Delta l` for nonspherical contributions to matrix elements (`default: 4`) 

   .. parameter:: majority_spin_core

      majority_spin_core ={0|1|2}; for magnetic systems with core hole, core
      moment parallel to spin {1|2} or no net core moment (0) (`default: 1`} 

   .. parameter:: rmt 

      muffin-tin radius (`default: from internal table`)

   .. parameter:: z 

      atomic number (better to use element ) (`default: same as id`) 

   .. parameter:: ldau_l

      LDA+U: l of states 

   .. parameter:: ldau_u

      LDA+U: U (eV) (`default: 0`)

   .. parameter:: ldau_j

      LDA+U: J (eV); only U-J important (`default: 0`)

   .. parameter:: ldau_alpha

      LDA+U: :math:`\alpha=1` (FLL), 0 (AMF), -1 interpolate (`default: 1`)


.. index:: pair: namelist;bands

*bands*
""""""""""""""""""

contains information about band structure plots; this namelist is in the 
file `bskpts` and is only read when `bsplot=t` in `&out`

   .. parameter:: nkpts

      total number of k-points to plot 

   .. parameter:: cc #2

      whether k-points are in scaled Cartesian (or lattice) units
      (`default: false`, corresponding to lattice units))

      The endpoints of the segments are given in `bskpts` after this
      namelist, as::

       0   0 0 0 ! Gamma
       1   1 0 0

      The first number tells whether a segment ends (=1) or not. (The first
      is generally set =0). The k-points will be distributed as equally as
      possible. 

   .. parameter:: k_projected 

      do a "k-projected" bandstructure, .i.e., project the (supercell) bands 
      onto a primitive cell. The k-points are given in terms of the cell 
      the calculation is being done in. See following inputs also.
      (`default: false`)

   .. parameter:: unitcell 

      the lattice vectors of the primitive cell to use for the projection, 
      given as row vectors (same as in the input) with the same units. 
      For example, a hexagonal :math:`\sqrt{3}\times\sqrt{3}` calculation 
      would have inputs::

       3/2 -1/2  0    ! a1
       3/2  1/2  0    ! a2
       0    0    1    ! a3
       1   -3   -8/3  ! scaling factors

       unitcell = 1/2 -1/2 0 ! primitive a1
                  1/2  1/2 0 ! a2
                   0    0  1
   
   .. parameter:: l_layer 

      logical to determine whether to get a layer projection
      also (useful for surfaces) (`default: false`)

   .. parameter:: zlay1,zlay2 

      if `l_layer=t`, determines the layer to use; always given in scaled 
      cartesian and assumes that a3 (for both cells) is along z 

   .. parameter:: k_shift

      integer array in terms of the supercell reciprocal lattice vectors
      that shifts the origin outside the BZ of the
      supercell in order to choose a particular folded-back k-point
      without having to calculate the wave functions again.
      (`default: (0,0,0)`)

.. index:: pair: namelist;cdn

*cdn*
""""""""""""""""

   .. parameter:: chg2cdn 

      read ascii charge file (not needed; set if file chg1 exists)
      (`default:  false`)

   .. parameter:: ctail1 

      use core tails in generation of initial cdn
      (`default:  true`)

   .. parameter:: lflip 

      flip magnetization options
      (`default:  false`)

   .. parameter:: strho 

      generates new charge density file; taken care of automatically 
      (`default:  false`)

   .. parameter:: swsp 

      magnetize options (generally not need; see `&swsp` )
      (`default:  false`)

.. index:: pair: namelist;cdnslice

*cdnslice*
"""""""""""""""""""""

   .. parameter:: e1s 

      min. energy range (relative to E F )
      (`default:  0`)

   .. parameter:: e2s 

      max. energy range (relative to E F )
      (`default:  0`)

   .. parameter:: kk 

      k-points kk is taken into account (if 0 all k-points are considered)
      (`default:  0`)

   .. parameter:: nnne 

      number of bands to include if e1s=e2s=0.0
      (`default:  0`)

   .. parameter:: pallst 

      bands above Fermi energy taken into account
      (`default:  false`)

   .. parameter:: plpot 

      plot potential
      (`default:  false`)

   .. parameter:: slice 

      calculate density of energy range or single state
      (`default:  false`)

.. index:: pair: namelist;comp

*comp*
"""""""""""""""""

   .. parameter:: ctail 

      calculate core tails
      (`default: true`)

   .. parameter:: epfloat 

      use floating energy parameters
      (`default:  true`)

   .. parameter:: frcor 

      frozen core approx (requires cdn1, cdnc, enpara)
      (`default:  false`)

   .. parameter:: gmax

      max. G-vector
      (`default:  12`)

   .. parameter:: gmaxxc 

      gmax for ex-corr. potential
      (`default:  1.5*gmax`)

   .. parameter:: isec1 

      iteration to start iterative diag at
      (`default:  9999`)

   .. parameter:: jspins 

      number of spins
      (`default:  1`)

   .. parameter:: kmax

      max k
      (`default:  8/min(rmt)`)

   .. parameter:: nstates

      number of eigenvalues to be calculated 


.. index:: pair: namelist;conv

*conv*
""""""""""""""""""" 

   .. parameter:: cdist_eps 

      convergence criteria for charge density
      (`default:  1.0e-3`)

   .. parameter:: cputimelimit 

      cpu time limit
      (`default:  unlimited`)

   .. parameter:: dforce_eps 

      convergence criteria for forces
      (`default:  1.0e-5`)

   .. parameter:: eps_force 

      convergence criteria for full forces (force_mode=2,3)
      (`default: 1.0e-5`)

   .. parameter:: evar_delta

      convergence criteria for total energy
      (`default:  1.0e-7`) 

   .. parameter:: force_mode 

      | 0: full forces are not calculated
      | 1: 1 (last) iteration with full forces
      | 2: using the force convergence as criterion
      | 3: full forces, convergence=2
      | <0: convergence is not checked
      | (`default:  1`)

   .. parameter:: itmax

      max. number of iterations for total run
      (`default:  itmax_scf*maxstep`)

   .. parameter:: itmax_scf

      max. number of iterations for each atomic step
      (`default:  50`) 

   .. parameter:: itmin

      min. number of iterations
      (`default:  0`)

.. index:: pair: namelist;efield

*efield*
""""""""""""""""""" 

For films only.

   .. parameter:: zel_delta 

      additional charge to generate an electric field
      (`default:  0`)

   .. parameter:: zsigma

      distance of the sheet of charge from the surface e.g., for zsigma=10, 
      zel_delta=0.05,E = -6.947E+07 V/cm
      (`default:  10`)

.. index:: pair: namelist;end

*end*
""""""""""""""""
   `&end` on a line will stop reading input 

.. index:: pair: namelist;epar

*epar*
"""""""""""""""""

Generally should **not** be needed/used with floating parameters. Must come 
after `&comp`.

   .. parameter:: fixed 

      keep this energy parameter fixed
      (`default:  false`)

   .. parameter:: id #2 

      atomic id (label)

   .. parameter:: l 

      l quantum number
      (`default:  none`)

   .. parameter:: shift 

      shift the energy band
      (`default:  0`)

   .. parameter:: type 

      atom type

.. index:: pair: namelist;exco

*exco*
"""""""""""""""""

Exchange-correlation: either lda or gga. Default is `lda='pz'`.

   .. parameter:: lda

      xa, wign, hl, bh, mjw, vwn, pz

   .. parameter:: gga

      l91, pw91, pbe, rpbe, wc

   .. parameter:: relcor

      relativistic core correction
      (`default:  true`)

.. index:: pair: namelist, structural;factor

*factor*
"""""""""""""""""""

Scale all atomic positions; must come directly after atomic positions 
(and `&shift` if used)::

    atompos(:,:)=atompos(:,:)/factor(:) 

.. index:: pair: namelist;files

*files*
"""""""""""""""""""

   .. parameter:: w_stat 

      write info on last completed iteration and step
      (`default:  false`)

   .. parameter:: w_tlst 

      write full tlst file (list of basis function)
      (`default:  false`)

   .. parameter:: l_all_its 

      keep a cdn file for each iteration
      (`default:  false`)

.. index:: pair: namelist;flip

*flip*
""""""""""""""""""

   Flips the magnetic moment(s) within the MT;
   either give {1|-1} for **all** atom types::

       &flip 1 -1 1 -1 /

   or just the atom type(s) to change::

       &flip type 3 6 /

.. index:: pair: namelist, structural;gen
 
*gen*
"""""""""""""""""

   number and generators of the space group in
   internal coordinates (ngen>0) or Cartesian (ngen<0).
   See output files for examples (can cut and paste).
   Must come after atomic positions, but before runtime parameters; will
   set `cal_symm=f`

.. index:: pair: namelist;geo

*geo*
"""""""""""""""""

   .. parameter:: epsdisp 

      limit for displacement to be converged
      (`default:  0.00005`)

   .. parameter:: epsforce 

      limit for forces to be converged
      (`default:  0.00005`)

   .. parameter:: l_geo

      do geometry opimization
      (`default:  false`)

   .. parameter:: maxstep

      max number of optimization steps
      (`default:  1`)

   .. parameter:: thetad 

      approx. debye temperature
      (`default:  330K`)

   .. parameter:: xa 

      limit of displacements
      (`default:   0.25`:math:`a_B`)

   .. parameter:: geo_restart_step

      number of atomic steps that a new starting density is generated;
      for `istep` greater than this value, extrapolation of density used
      (`default:  0`)

   .. parameter:: geofixcdn

      charge renormalization above which a new starting density 
      is generated
      (`default:  0.05`)

.. index:: pair: namelist;ini

*ini*
"""""""""""""""""

   .. parameter:: eig66 

      use existing eigenvalue/vector file
      (`default:  false`)

   .. parameter:: force1st

      calculate force on first iteration
      (`default:  false`)

   .. parameter:: mix1st 

      mix input/output densities (on cdn1) before first iteration
      (`default:  false`)

   .. parameter:: pot8 

      use existing potential files
      (`default:  false`)

.. index:: pair: namelist, structural;input

*input*
"""""""""""""""""""

   .. parameter:: angstrom 

      if .true., then the lattice constant or volume in Angstrom 
      (all other units are in atomic units); simpler to add an "A" 
      after the lattice constant, e.g., `4.08 A`
      (`default:  false`)

   .. parameter:: cal_symm 

      if (`true`) calculate or if (`false`) read in space group symmetry
      info
      (`default:  true`)

   .. parameter:: cartesian

      if `false` specification of atomic positions in lattice units, 
      otherwise if `true` in scaled cartesian coordinates
      (`default:  false`)

   .. parameter:: cc

      same as `cartesian`

   .. parameter:: checkinp 

      program reads/checks input and stops; easier to 
      use -c or --check on the command line
      (`default:  false`)

   .. parameter:: inistop 

      program stops after generating density, etc.; 
      use -s or --setup on the command line
      (`default:  false`)

   .. parameter:: op 

      | Depreciated. Use commandline options instead.
      | =1, checkinp=t
      | =2, inistop=t
      | =3, checkinp=t, inistop=t
      | (`default:  0`)

   .. parameter:: tolerance 

      | ='normal' : symmetry allowing "fuzz" in positions, but warn
      | ='fuzzy': run allowing uncertainity in positions
      | ='tight': use positions as given (symmetry may be lower)
      | (`default:  normal`)

.. index:: pair: namelist;kpt

*kpt*
""""""""""""""""" 

   .. parameter:: div1

      division along :math:`b_1` reciprocal lattice vector
      (`default:  false`)

   .. parameter:: div2

      division along :math:`b_2` reciprocal lattice vector
      (`default:  div1`)

   .. parameter:: div3

      division along :math:`b_3` reciprocal lattice vector
      (`default:  div1`)
   
   Default k-point mesh: div1 = nint( (1024 / number of atoms)^(1/3) ).
   For film calculation, div3 = 1. 

   .. parameter:: cryst_len 

      crystal size (in :math:`a_B`) to determine `divN` via Born-vons
      Karman boundary  conditions

   .. parameter:: kshift

      shift mesh away from zone center if symmetry allowed
      (`default:  false`)

   .. parameter:: origin 

      explicit k-point mesh shift (if `kshift=t`): 0 or 1. is 
      forced to be consistent with symmetry of Bravais lattice.
      Example: `origin=0,0,1`
      (`default:   1,1,1`)

   .. parameter:: tkb

      Fermi function broadening in Htr
      (`default:  0.001`)

   .. parameter:: fixed_moment 

      if /= 0, value of fixed spin moment
      (`default:  0`)

   .. parameter:: q_ef_excited

      charge to excite from below Fermi level to above
      (`default:  0`)

   .. parameter:: b_field 

      external magnetic field; causes the up/down Fermi levels to be 
      separated by 2*b_field
      (`default:  0`)

   .. parameter:: kinv 

      use inversion (time-reversal) when generating k-mesh
      (`default:  true`)

.. index:: pair: namelist, structural;lattice

*lattice*
"""""""""""""""""""""

Input lattice in terms of lengths, angles, and lattice system. Either
the overall (conventional) lattice parameter (`a0` or `a`) or the volume
of the primitive cell (`vol`) must be given. Appending an "A" denotes
Angstrom units. If `a0` or `vol` is given, then `a` is the scaling
factor (scale(1)) and `b` and `c` are the `b/c` and `c/a` ratios,
respectively; when `a0` (`vol`) are omitted, then `a`, `b`, and `c` are
the conventional lattices constants (all in the same units).
Example: trigonal lattice::

&lattice bravais='hR' a=7.32A alpha=113.57818 / 

The file `inp_new` will include the lattice vectors, scale factors, etc.
in case one wants to modify the cell. For rhombohedral (hR) lattices
when the angle :math:`\alpha` and length `a` are given, this will give
the lattice parameters and scaling (c/a ratio) of the equivalent
hexagonal lattice; to convert to the hexagonal lattice use::

      1/2  -1/2  0
      1/2   1/2  0
       0     0   3

for the lattice vectors of the 3x hexagonal cell. The three primitive
cells are at `(0,0,0)`, `(1/2,1/6,1)=(0,-1/3,1)`,
and `(-1/2,-1/6,-1)=(0,1/3,2)`. (The stacking can be reversed if
desired.) To convert the atomic positions, first output the positions in
cartesian coordinates (see `inp_new_pos` in `&out`), and then switch to
the hexagonal cell.

   .. parameter:: a0

      overall lattice parameter (add A for Angstroms). If `a0` (or
      `vol`) not given, then `a` will be used as the overall lattice
      constant.

   .. parameter:: a 

      relative length of :math:`a_1` (scaling of lattice constant)
      [overall lattice constant if `a0` not given]
      (`default:  1`)

   .. parameter:: b 

      relative length of :math:`a_2` (b/a ratio) [or b] 

   .. parameter:: c  

      relative length of :math:`a_3` (c/a ratio) [or c]

   .. parameter:: alpha 

      angle between :math:`a_2` and :math:`a_3`

   .. parameter:: beta 

      angle between  :math:`a_1` and :math:`a_3`

   .. parameter:: gamma

      angle between :math:`a_1` and :math:`a_2`

   .. parameter:: bravais 

      | crystal structure: required input(s) for each case in "(...)"
      | cP = cubic primitive (`a`)
      | cF = cubic face-centered (`a`)
      | cI = cubic body-centered (`a`)
      | hP = hexagonal primitive ( `a`, `c` )
      | hR = hexagonal rhombohedral/trigonal ( `a`, `alpha` or `a`, `c` of hexagonal cell)
      | tP = tetragonal primitive ( `a`, `c` )
      | tI = tetragonal body-centered (bct) ( `a`, `c` )
      | oP = orthorhombic primitive ( `a`, `b`, `c` )
      | oF = orthorhombic face-centered ( `a`, `b`, `c` )
      | oI = orthorhombic body-centered ( `a`, `b`, `c` )
      | oC, oA, oB = orthorhombic centered ( `a`, `b`, `c` )
      | mP = monoclinic primitive ( `a`, `b`, `c`; `gamma` or `beta` )
      | mA, mB = monoclinic centered ( `a`, `b`, `c`, `gamma` )
      | mA, mC = monoclinic centered ( `a`, `b`, `c`, `beta` )
      | aP = triclinic ( `a`, `b`, `c`, `alpha`, `beta`, `gamma` ) 


   .. parameter:: vol 

      unit cell volume, use instead of a0 (add "A" for Angstroms) 

.. index:: pair: namelist;mix

*mix*
"""""""""""""""""

   .. parameter:: alpha #2

      mixing parameter
      (`default:  0.1`)

   .. parameter:: imix 

      | mixing scheme: 
      | 0= straight mixing
      | 3= Broyden's first method
      | 5= Broyden's second method
      | 7= Generalized Andersen method 
      | (`default:  7`) 

   .. parameter:: maxiter 

      max. depth of of history for Broyden type schemes
      (`default:  20`)

   .. parameter:: aspin 

      spin mixing parameter (spinf=aspin/alpha)
      (`default:  0.0`)

   .. parameter:: spinf 

      spin mixing; if imix>0 and spinf<0, straight mixing of spins
      spin mixing = alpha*|spinf|
      (`default:  5`)

.. index:: pair: namelist;mpi

*mpi* 
"""""""""""""""""

MPI-related options 

   .. parameter:: eigdir 

      directory for eig file(s). On a cluster with CPP_MEIG set, 
      the default is /tmp; serial is current directory 

      also can use -t eigdir or --tmpdir eigdir on the command line 

   .. parameter:: l_rm_eig

      delete eig file(s) at end of run. With multiple eig files, 
      default is `true`, otherwise `false`

.. index:: pair: namelist, structural;origin

*origin*
""""""""""""""""""""

Shift origin of all atomic positions following up until another `&origin`. 
Must come after number of atoms::

    atompos(:,n)=atompos(:,n)+origin(:) 

.. index:: pair: namelist;out

*out*
"""""""""""""""""

   .. parameter:: bsplot

      band structure calculations
      (`default:  false`)

   .. parameter:: cdinf 

      perform check continuity of cdn
      (`default:  false`)

   .. parameter:: cdnplot

      calculate cdnplot
      (`default:  false`)

   .. parameter:: chgfile 

      write ascii charge file (chg1)
      (`default:  false`)

   .. parameter:: chgfiles 

      write ascii charge files (chg_in, chg_out)
      (`default:  false`)

   .. parameter:: dosform

      | output format:
      | dosform=1 total, l-resolved DOS on different files
      | dosform=2 same as 1, but combined on atom type files
      | dosform=3 total and interstitial DOS
      | (`default:  1`)

   .. parameter:: dosplot

      calculate dos and generate dos plot files
      (`default:  false`)

   .. parameter:: ef0 

      fermi energy (for plotting)
      (`default:  0`)

   .. parameter:: emax0 

      max of plot in eV 

   .. parameter:: emin0 

      min of plot in eV 

   .. parameter:: eonly 

      calculate only eigenvalues (no l-like charge)
      (`default:  false`)

   .. parameter:: eshift 

      fermi energy shift (for plotting)
      (`default:  0`)

   .. parameter:: form66 

      formatted eigenvector file (eig)
      (`default:  false`)

   .. parameter:: geo_all

      write `geo_N.xsf` file for each atomic step
      (`default:  false`)

   .. parameter:: jems 

      write structure files for JEMS
      (`default:  false`)

   .. parameter:: kptfile 

      write kpts file
      (`default:  false`)

   .. parameter:: lpr 

      if > 0, more output (e.g., eigenvectors)
      (`default:  0`)

   .. parameter:: inp_new_pos

      determines the output form of the positions in `inp_new`. Default is
      same form as input; `c` or `C` for scaled Cartesian, and `l`, `L`,
      `d`, or `D` for lattice (direct) cooridinates. (Useful for changing
      format).

   .. parameter:: l_diffraction

      calculates the surface diffraction pattern and generates an xmgrace
      plot. Assumes that `a_3` is the perpendicular direction.
      (`default:  false`)

   .. parameter:: l_reps_only 

      controls output to inp_new when only representatives given; .f. will 
      cause all atoms to be written
      (`default:  true`)

   .. parameter:: nmesh 

      number of mesh point for DOS

   .. parameter:: pdist 

      potential distance is calculated
      (`default:  false`)
   
   .. parameter:: pot_plot 

      plot planar-averaged Coulomb potential for films/surfaces.
      For bulk supercells, a3 must be perpendicular to :math"`a_1, a_2`)
      (`default:  false`)

   .. parameter:: potfile

      write ascii potential file (potential)
      (`default:  false`)

   .. parameter:: symfile 

      write sym ops to file sym (sym.out)
      (`default:  false`)

   .. parameter:: tkb0 

      Fermi broadening for plotting in Htr
      (`default:  0.005`)

   .. parameter:: units 

      e=eV, r=Ry, and h=Htr
      (`default:  e`)

   .. parameter:: valcdnfile 

      write unformatted valence density (valcdn)
      (`default:  false`)

   .. parameter:: vchk 

      perform potential check
      (`default:  false`)

   .. parameter:: fermi_surface 

      plot Fermi surfaces (see ef_fs, fs_range)
      (`default:  false`)

   .. parameter:: ef_fs

      For Fermi surface plots, :math:`E_F` (in hartrees) to use.
      (`default: use calculated` :math:`E_F`)

   .. parameter:: fs_range 

      include all bands within +/- fs_range (eV)
      (`default:  0.5`)

   .. parameter:: stm_plot 

      determines and generates plots for constant current stm. 
      For constant height plots, set stm_height > 0. Can be run using itmax=0. 
      Will generate a file stm.dat that depends on the selected
      bias (=0 corresponds to Fermi level), and requires that the eig
      file(s) be available. the Fermi level used is (in this order): 

      1) ef0 from `&out`, 
      2) :math:`E_F` calculated during the run, or 
      3) will calculate it again.

      The plot area given in the &plot and &plotarea namelists will be used
      if defined; otherwise, will define a rectangular area that includes a
      full unit cell, possibly cut oddly. To do line profiles, set either n1
      or n2 =1 in `&plot`
      (`default:  false`)

   .. parameter:: stm_bias 

      | bias (in eV) to use; 
      | =0, Fermi level; 
      | <0, occupied; 
      | >0, unoccupied states
      | (`default:  0`)

   .. parameter:: stm_surface 

      surface to plot: {'top'|'bottom'} = outward normal
      {increasing|decreasing} z
      (`default:  top`)

   .. parameter:: stm_contour 

      density to follow; if <0, then will pick a reasonable value
      (`default:  -1`)

   .. parameter:: stm_spin 

      | which spin(s) to plot; only meaningful for spin-polarized
      | none : no plotting, but lists range of contours
      | all : all possible (both spins, total) - default
      | total, minority, majority : particular one
      | angle : relative angle between tip and surface; then give stm_angle also all 
      | (`default:  all`)

   .. parameter:: stm_angle 

      angle (in degrees) between polarization directions of the tip and surface
      (`default: 0`) 

   .. parameter:: stm_tip_polarization 

      assumed tip polarization: varies between 0 (unpolarized) and 1 (fully)
      (`default: 1`)

   .. parameter:: stm_height 

      for constant height (as opposed to constant current), 
      set to height in Angstoms above the surface; must be at least 1 A
      (`default:  0`)

   .. parameter:: vasp_poscar

      generates an input `POSCAR` file suitable for use in VASP
      (`default:  false`)

.. index:: pair: namelist;plot

*plot*
""""""""""""""""""

   .. parameter:: cc #3 

      scaled Cartesian coordinates for plot-box
      (`default:  false`)

   .. parameter:: cart 

      full Cartesian coordinates (in a.u.) for plot-box
      (`default:  false`)

   .. parameter:: cdnselect 

      select what to plot: If slice=t (see &cdnslice ), the density in the file
      cdn_slice will be used; must be: 

      | 'c' (charge), 
      | 's' (spin), 
      | 'cs' (charge and spin), 
      | 'c1' (spin up), 'c2' (spin down), or 
      | 'c1c2' (both spins)
      | (`default:  c, cs`)

   .. parameter:: dim 

      dimensiononality of the box (2D or 3D)
      (`default:  3`)

   .. parameter:: n1 

      points along first direction
      (`default:  0`)

   .. parameter:: n2 

      points along second direction
      (`default:  n1`)

   .. parameter:: n3 

      points along third direction

   .. parameter:: nplot 

      number of plots (i.e., # of `&plotarea` namelists)
      (`default:  1`)

   .. parameter:: score 

      remove core charge
      (`default:  false`)

.. index:: pair: namelist;plotarea

*plotarea*
""""""""""""""""""""""

   Plot charge density (2D or 3D) in file `cdn.dat`
   `&plot` must appear before `&plotarea`. Give origin and then vectors 
   for axes.

   Example 2D::

       &plot dim=2 cc=f n1=50 n2=50 nplot=1 cdnselect='c' score=f /
       &plotarea 0.0 0.0 0.5
                 1.0 0.0 0.0
                 0.0 1.0 0.0 /

   Example 3D::

       &plot dim=3 cart=t n1=50 n2=50 n3=40 nplot=1 cdnselect='c' score=t /
       &plotarea 0.0 0.0 0.6
                 8.0 0.0 0.0
                 0.0 8.0 0.0
                 0.0 0.0 8.0 / 

.. index:: pair: namelist;relax

*relax* 
"""""""""""""""""""

   For geometry optimization: ignored unless `l_geo=t` in `&geo`.
   A triplet of {0|1}s specifying whether each (x,y,z) component
   of the atomic position is allowed to relax (1) or not (0).

   Two different formats are allowed:

   *Old style:* each atom type must be specified in order:
   example: `&relax 001 111 000 /` specifies relaxation in z for 1st, 
   all directions for 2nd, and no relaxations for 3rd atom type.

   *New (and preferred) style:* only list the atom types that need to
   be changed using `atom_type = triplet` or `n1:n2 = triplet`
   where `n1:n2` represent a range of atom types; if `n2` is omitted, then
   defaults to ntype. Default can be changed (from 111) by using 
   the keyword `default=`.

   | Example: `&relax 3=000 1=001 /`
   | specifies relaxation in z for 1st, 
     no relaxation for 3rd, all other atom types fully relaxed.

   | Example: `&relax default=001 4=111 2=000 9:=111 /`
   | Default to relax z only, fully relax 4th, freeze 2nd type, and fully
     relax atom types 9 to ntype

   (`default=111`) 

.. index:: pair: namelist, structural;shift

*shift* 
"""""""""""""""""""

   Shift origin of all atomic positions. Must come directly after 
   atomic positions::

      atompos(:,1:nat)=atompos(:,1:nat)+shift(:) 

.. index:: pair: namelist;soc

*soc*
"""""""""""""""""

   .. parameter:: l_soc 

      logical to determine whether to include spin-orbit
      (`default:  false`)

   .. parameter:: theta 
   
      polar angle
      (`default:  0`)

   .. parameter:: phi

      azimutal angle
      (`default:  0`)

.. index:: pair: namelist;swsp

*swsp*
""""""""""""""""""

   Starting spin moment for the spin-polarized case given in terms of:
   atom kinds (identifiers) as used in positions:

   | Example: `&swsp kind 26=2.0 28=0.5 /` ("kind" optional)
   | Using atom types: `&swsp type 3=2.0 2=0.5 /`
   | List by atom type: `&swsp 0.0 0.5 2.0 0.0 /` 

   Can also give orbital occupations (density matrix) for given atom
   kinds (not types):

   | `&swsp 26=[ up: d_xy=1 d_z2=1 d_xz=1 d_yz=1 down: d_x2-y2=1 ] /`

   "`[`" , "`]`", "`up:`", and "`down:`" are required. 
   Orbitals are denoted by "`p_x, p_y, p_z, d_xy, d_yz, d_xz, d_z2, d_x2-y2`",
   in obvious notation. Occupations should be between 0 and 1.

.. index:: pair: namelist, structural;sym

*sym*
"""""""""""""""""
   Number and operations of the space group in internal coordinates
   see output files and &gen for examples must come after atomic positions, 
   but before runtime parameters.

.. index:: pair: namelist;vdos

*vdos*
"""""""""""""""""" 

   .. parameter:: layers 

      number of layers [0-99] in which the vacuum dos is
      calculated
      (`default:  0`)

   .. parameter:: nstars 

      Number of stars to calculate for each k and energy eigenvalue.
      Example: vacdos=T, layers=3 and nstars=3 gives 9 partial DOS curves
      (`default:  0`)

   .. parameter:: vacdos 

      for dos=T, vacuum DOS calculated
      (`default:  false`)

.. _runtime_changes:

Runtime changes
---------------

A number of parameters can be changed during the run. 

To do so, create a file `conv`. The existence of this file will be checked 
at the end of each iteration. If it exists, it will be read and the parameters
changed. Each line of the file should be of the form `keyword=value` 
(one per line). 

The parameters that currently can be changed are:

Namelist **conv**
"""""""""""""""""
  
  * cdist_eps
  * cputimelimit
  * dforce_eps
  * eps_force
  * evar_delta
  * force_mode
  * itmax
  * itmax_scf
  * itmin
  
Namelist **geo**
""""""""""""""""
  
  * maxstep

Namelist **kpt**
""""""""""""""""
    
  * tkb

Namelist **mix**
""""""""""""""""
  
  * alpha
  * imix
  * spinf