LMTO-ASA and basic package (v7.0)

This file documents the basic LMTO and TBE program packages.
  Written by M. van Schilfgaarde, A.T.Paxton, J. Klepeis and M. Methfessel
  email      Mark.vanSchilfgaarde@asu.edu
  Documentation for Version 7.0, July 2009

1. Purpose of the LMTO and supplemental packages

This documentation is oriented mainly for basic package ASA.vsn.tar.gz, the electronic structure program implementing the local-density approximation (LDA) in a basis of linear muffin tin orbitals (LMTOs). (This text documents vsn=7.0.) The program described in this document makes an additional shape approximation to the LDA potential, known as the "Atomic Spheres Approximation" (ASA). The ASA restricts space to overlapping spheres (with a geometry violation), and the potential is assumed to be spherically symmetric inside the spheres. Much of the description and input is relevant for the other packages as well, in particular the full-potential package (FP.vsn.tar.gz), documented here. Relatively minor additional input are needed for any of the other packages.

`LMTO' is an acronym for 'Linear Muffin-Tin Orbitals,' which is a basis set for ab initio electronic structure calculations, usually within the context of the LDA. It was originally formulated (together with the LAPW method --- Linear Augmented Plane Wave method) by O. K. Andersen. For a long time, LMTO was implemented in the Atomic Spheres Approximation (ASA), an additional approximation that replaces the proper charge density and potentials by their spherical averages.

At present the basic package consists of an ASA program with supporting programs as described below, and is implemented for what Andersen calls `second-generation' LMTO --- namely a reworking of the original method into a tight-binding form, so that the orbitals are short-ranged. Since then Andersen has devised a `third-generation' LMTO, and more recently a `NMTO' scheme [See O. K. Andersen, T. Saha-Dasgupta, R. W. Tank, and G. K. C. Arcangeli O. Jepsen, in Electronic Structure and Physical Properties of Solids: The Uses of the LMTO Method, edited by H. Dreysse (Springer-Verlag, Berlin, 2000)] which while formally make significant improvements over the `second-generation' LMTO, there remain difficulties with implementation. At present, this package has non-self-consistent NMTO scheme implementation, but it should largely be regarded as experimental, as there are practical pitfalls associated that haven't been fully worked out.

There is also a full-potential implementation. It is more accurate than the ASA, but it also significantly slower. It uses an LMTO basis where the envelope functions are not screened but generalized to smoothed Hankel functions [See M. Methfessel, M. van Schilfgaarde, and R. A. Casali, ``A full-potential LMTO method based on smooth Hankel functions,'' in Electronic Structure and Physical Properties of Solids: The Uses of the LMTO Method, Lecture Notes in Physics, 535. H. Dreysse, ed. (Springer-Verlag, Berlin) 2000; there is a postscript file included in this directory.] The full-potential extension requires a supplemental package, distributed as FP.vsn.tar.gz, and documented in fp.html.

The basic package contain a variety of auxillary programs, described below. Extension packages, e.g. FP.vsn.tar.gz, and TBE.vsn.tar.gz, contain a variety of electronic structure programs, including an empirical tight-binding program tbe whose hamiltonian is taken from a user-chosen model. See Getting_Started.html for brief descriptions and hyperlinks.

This file is the main documentation of the ASA package, and most of the auxillary programs. See file README for installation notes, the ASA tutorial for help in getting started, the FP tutorial for a tutorial using the full-potential program.

2. Overview of the LMTO-ASA method.

Augmented-wave programs, including the present suite, divide into an ``atomic'' part and a ``band'' part. In general the ``band'' part requires potential parameters and structure constants as its input, from which it generates bands, energy moments, densities-of-states, etc. The ``atomic'' part takes moments as its input and produces potential parameters from it. The atomic part requires very little information beyond the moments and boundary conditions to completely specify the electronic structure within an atomic sphere, and the atomic program here embodies that idea.

An LMTO-ASA calculation is self-consistent when the atomic part produces, from moments generated by the solid part, once again the same potential parameters that the solid part used to generate the moments in the first place. The self-consistency works by alternating between the solid part and atomic part, generating moments, then potential parameters, then moments again until the process converges. The program can be started either with the solid part, specifying potential parameters, or with the atomic part, specifying the moments.

Because the method is a linear one, and because the density is (assumed to be) spherical, only three functions can carry charge inside a sphere per l channel (φl2, φl×(dφl /dE), (dφl /dE)2) and therefore the properties of a sphere, for a spherical potential and a linear method are completely determined by the first three energy moments Q0, Q1, and Q2 of the density of states for each l channel, which are called the atomic number and the boundary conditions at the surface of the sphere. In some sense these numbers are ``fundamental'' to a sphere; the atomic program will generate a self-consistent potential for a specified set of moments Q0..Q2 and boundary conditions. This simplification depends on assumption of spherical densities, and is unique to the ASA.

These codes (both ASA and full-potential codes) use "logarithmic derivative parameters" Pl to fix boundary conditions at the sphere surface; they are described here. Note: Pl should not be confused with the "potential functions" O.K. Andersen defines in his ASA theory.

Once a potential is specified, "potential parameters" can be generated. "Potential parameters" are a compact representation of information needed in a linear method to specify the hamiltonian. A description of how the parameters are generated and their significance is too involved to be described here; moreover, what parameters are generated depends on the choice of basis. (The 2nd generation potential parameters are particularly helpful because they refer to conceptually accessible quantities, such as the band-center parameter C, and the bandwidth parameter delta.) Particularly useful for the 2nd generation LMTO are Andersen's notes in the following references:
  O.K. Andersen, A.V. Postnikov, and S. Yu. Savrasov, in "Applications of
  Multiple Scattering Theory to Materials Science," eds. W.H. Butler,
  P.H. Dederichs, A. Gonis, and R.L. Weaver, MRS Symposia Proceedings
  No. 253 (Materials Research Society, Pittsburgh, 1992) pp 37-70.

  O.K. Andersen, O. Jepsen and M. Sob, in Lecture Notes in Physics:
  Electronic Band Structure and Its Applications, eds.  M. Yussouff
  (Springer-Verlag, Berlin, 1987).
and later descriptions, evolving beyond 2nd generation LMTO:
  O.K. Andersen, O. Jepsen, and G. Krier in Lectures on Methods of
  Electronic Structure Calculations, edited by V. Kumar, O. K. Andersen,
  and A. Mookerjee (World Scientific Publishing Co., Singapore, 1994),
  pp. 63-124.

  O.K. Andersen, C. Arcangeli, R.W. Tank, T. Saha-Dasgupta, G.  Krier,
  O. Jepsen, and I. Dasgupta in Tight-Binding Approach to Computational
  Materials Science, Eds. L. Colombo, A. Gonis, P. Turchi, Mat.
  Res. Soc. Symp. Proc. Vol. 491 (Materials Research Society, Pittsburgh,
  1998) pp 3-34.
From the point of view of the bands, the ASA Hamiltonian is completely specified by the potential parameters. These are fundamental to the band program; it will generate moments Q0..Q2 from the eigenvectors of the Hamiltonian. (Alternatively, they may be generated via a Green's function, using programs lmgf or lmpg). Full self-consistency is achieved when the ``input moments'' coincide with the ``output moments'', or equivalently when the input potential parameters coincide with the output potential parameters. It is merely a matter of preference to whether to consider the moments as fundamental or the potential parameters.

Unless performing some special-purpose function such as generating energy bands, lm works by iterating to self-consistency, ASA style. By virtue of the moments properties just described in the ASA, the self consistency procedure is a little different from the standard one. lm can start equally as well from either potential parameters or moments, though it is generally customary to start from the moments, mainly because one can usually begin with a very simple starting guess (choosing the zeroth moment to be the charge of the free atom, the first and second to be zero) that is usually good enough to iterate to self-consistency. Actually, you don't need to specify a guess at all. Programs lm, lmgf, and lmpg will assume defaults values if none are supplied.

If you have potential parameters at your disposal, you may choose to begin directly with a band calculation and need not worry about the moments. You will need to put the potential parameters in the proper atom file, described below. If you wish to make a self-consistent calculation, you must also supply the boundary condition for l channel. In these programs, the boundary conditions is encapsulated in the "continuously variable" principal quantum P described in the following paragraphs.

To make a sphere self-consistent one needs the moments and also to specify the boundary condition on the wave function at the sphere radius, or what is essentially equivalent, the Eν of the wave function phi. For a given potential, there is a unique correspondence between the logarithmic derivative Dν at the sphere radius and Eν, so in principle, it is possible to specify either one. As a practical matter, however, it is only straightforward to make the sphere self- consistent by specifying the logarithmic derivative (since the potential changes while the sphere is made self-consistent).

Logarithmic Derivative Parameters

In an augmented wave method, there is the boundary condition on the wave function φ at the augmentation sphere radius. More precisely, φ is called a partial wave since it is only a partial solution to the full Schrodinger equation. Partial waves must be matched to the envelope function at the augmentation sphere radius; the condition that all partial waves match smoothly and differentiably at all surfaces is the quantization condition that determines allowed eigenvalues. In the augmentation sphere we work in spherical coordinates. For the purposes of constructing φ, (both in the ASA and FP methods) a spherical potential is assumed which means that the angular solutions are spherical harmonics and the radial solutions are partial waves φl, with l the usual angular momentum number. In a linear method, φl is assumed to vary smoothly with energy, and we take a Taylor series around some linearization energy El, so that
   φl(E) ≈ φl(El)  +  (dφl /dE)El × [φl(E)-φl(El)]
It is this linearization of φ that simplifies the complicated matching conditions in augmentated wave methods, rendering the (nonlinear) matching conditions to into a linear algebraic eigenvalue problem. Any linear method must specify a linearization energy El. Alternatively equivalent information is contained in the logarithmic derivative Dl. For a given potential, there is a unique correspondence between the logarithmic derivative Dl of φ, Dl=dlnφl/dlnE at the sphere radius and El, so in principle, it is possible to specify either one. Dl is a cotangent-like function, varying between +∞ and -∞: it decreases monotonically with energy varying between (+&infin,-∞) over a finite window of energy. There is thus a multiplicity of energies for a given Dl, one branch for each principal quantum number. For that reason we define a smooth quantity Pl, which may be thought of as a smooth version of Dl, and which also contains information about both the principal quantum number and the logarithmic derivative. Pl is defined as
    Pl = 0.5 - arctan(Dl)/π + (princ.quant.number)
Its integer part is the principal quantum number; its fractional part varies smoothly from 0 (for the bottom extreme of the band for that principal quantum number) to 1 (the top extreme of the band), and can be thought of in some sense as a "continuously variable" principal quantum number. Note: Pl should not be confused with the "potential function" O.K. Andersen defines in his ASA theory.

The above description of Pl applies to both ASA and FP codes. In the free atom code lmfa, Pl and Ql, where Ql is the charge in orbital l, completely determine the density and potential of the free atom. (As noted, another boundary condition can be used in place of Pl, but as a practical matter, however, it is only straightforward to make the sphere self- consistent by specifying the logarithmic derivative (since the potential changes while the sphere is made self-consistent).

Potential functions in the ASA

In the ASA codes (lm, lmgf, lmpg), Pl together with the moments Q, completely determine the potential in the crystal. Both must be supplied for lm to work. Pl and Q are both input directly through the control file. (As mentioned, the programs will supply default values for both Pl and Q, which for the most part are sufficient to get the program to converge to self-consistency.) Once you can make a band pass, the fractional part of Pl will be automatically updated by the output of the band calculation (provided IDMOD is not 1; see description of IDMOD in the documentation on the control file), but Pl must be supplied (in addition to the moments Q) if you choose to begin with moments. A word on choices for the fractional part of Pl: .3 is quite free- electron-like and suitable for free-electron like l channels such as Si d electrons, while .8 is quite tight-binding like and suitable for deep states like Cu d orbitals. To be safe, and probably avoid ghost bands, choose .5 for all l channels. In awkward cases, it is best to set the ADNF switch (see below) in the first few iterations; especially for heavier elements like Hf or f-electron elements like Gd.

NOTE: In the case of spin-polarized calculations, the moments should all be half of what they are in non-spin polarized calculations.

When iterating to self-consistency, you have a choice, through the parameter IDMOD described in the Documentation of Categories and Tokens section, regarding the related pair of parameters Pl and El. You may let Pl and El float to the center of gravity of the occupied part of the band (most accurate for self-consistent calculations); this is the default. You may also freeze alternatively Pl or El in the self-consistency cycle. This is more stable, and is preferable if there is difficulty in achieving convergence or if problems with ghost bands arise.

The program iterates towards self-consistency by mixing the moments and the parameters Pl as come out of the next iteration. A choice of Broyden, Anderson, or linear mixing is available; as explained in the description of category ITER in the file tokens.html.

3. Executable programs

There are a number of executable programs in the basic package, all of which are created from the same source file lmv7.f, using preprocessor ccomp described below. The most useful ones are:
  lm     the self-consistent band program for the ASA

  lmstr  generates the real-space structure constants for the ASA
         It must be invoked prior to invoking `lm'.

  lmchk  displays sphere overlaps.  There is an option to move
         atoms (empty spheres) to minimize the overlap.

  lmctl  writes out moments (to the log file) in the style of the
         input file, so that a complete calculation can be
         retained within a single file.  See here
         for an example.

  lmdos  generates the electron density-of-states (DOS) and
         related quantities as a function of energy for plotting
         or other analysis.  It can generate the total DOS (or
         DOS-related quantities), or resolve the total into
         partial contributions DOS-related quantities lmdos is
         equipped to deal with are:
           *integral d^k delta(E(k)-E) , i.e. just the DOS itself

           *integral d^k delta(E(k)-E) grad_1 E(k) . grad_2 E(k)
            from which a `diffusive' conductivity sigma_12 can easily be
             computed within a relaxation time approximation

           *integral d^k delta(E(k)-E) grad_1 E(k) . direction-vector
            which is the Landauer `ballistic' conductance along some
            unit direction-vector

           *core-level spectroscopy such as EELS derived from the
            full-potential program

  catdos concatenates density-of-states generated from different
         files into a single file.

  lmscell generates supercells from smaller unit cells.

  lmxbs   generates an input file for Methfessel's ball-and-stick
          program xbs, which creates a 3D visual display of
          molecules.  You can create an input to his program to
          view the crystal structure specified in the ctrl file.

  lmplan  is a special-purpose program oriented to analysis of layer
          calculations.

  lmimp  imports potential data from other inputs to create
         trial potentials or densities.
         It can also import data from older versions,
         and Stuttgart versions, of the ASA package.

The following programs to generate electronic structure from empirical tight-binding hamiltonians, whose form the user specifies. They are included in the basic package. there is some documentation HERE.

  tbe    empirical tight-binding energy, forces, and dynamics

With extension packages, there are also the following programs or extensions:
  lmf    (FP) the self-consistent full-potential band program

  lmfa   (FP) computes the free-atom densities and related information.
         lmfa must be invoked prior to invoking lmf.

  lm     may be extended in the following ways.
         (NC) enables noncollinear extensions to the usual LSDA
         (OPTICS) calculates epsilon(omega) from LDA bands
         (SX) an ASA screened exchange, originally designed to correct
              bandgaps in semiconductors in an ab initio way.
              This latter is not well documented.

  lmgf   (GF) an ASA Green's function program.  This program uses Green's
         functions to perform an function approximately similar to program
         lm.  Also a branch to compute magnetic exchange interactions.

  lmpg   (PGF) an ASA layer Green's function program.  It is similar to
         lmgf, but uses a layer technique (real-space GF in one dimension,
         k-space in the other two)

  lmfgwd (GW) a driver for T. Kotani's all-electron GW implementation.

Additionally there are the following executables:
  rdcmd  a program with a function approximately similar to a shell script
         that reads commands and executes them.  It is used extensively
         in the test suites.

  ccomp  a program written in C which provides a fortran-compatible
         functionality approximately similar to that of the unix
         preprocessor, cpp.  It is documented in this file; see section
         `program ccomp'

Plotting bands and DOS  There is a plotting package available, FPLOT.vsn.tar.gz, with a collection of programs suitable for plotting density-of-states (pldos), bands (plbnds) and other x-y plots. In includes a general-purpose plotting program, fplot, which creates x-y and contour plots, in postscript format. (As of this writing, the most recent package is FPLOT.3.39.tar.gz.) Run lm or some other band program to generate energy bands along symmetry lines you choose. Program plbnds reads this file and can either (1) generate a postscript file directly, or (2) generate input and a script to be read by the fplot program. In this way you can tailor a figure to taste. For plotting partial DOS, see the --pdos option below when using either lm or lmf.

4. Input files

The control file, called ctrl.extension is the main input file for all programs. It together with command line arguments (see section "Command-line switches") that affect some program execution flow, are the two principal (often sole) input streams needed to run these packages. The string extension is supplied as a command-line argument. If no extension is supplied on the command-line, `dat' is used as the extension.

Caution: The programs cannot read a ctrl file containing unreadable characters.

Thus the invocation of any `lm' program has a form
  program-name [-switches] [file-extension]
Nearly all files associated with the input file have the same extension appended to them as does the ctrl file. Thus if the ctrl file is called `ctrl.cr3si6', the log file is called `log.cr3si6'. Section 9 documents command-line switches.

Other input files are:
 symmetry-line file : input for plotting energy bands along
    selected symmetry lines or for generating constant-energy
    contours such as a Fermi surface.  This file (whose name is
    specified as a modifier with the command-line argument
    --band, described in the "Command-line switches" section) can
    take on of several forms.

    First format: generate bands along specific symmetry lines.
    The following sample input illustrates input for lines
    X->Gamma and Gamma->M for the simple cubic lattice.
       21  .5 0  0    0  0  0         X to Gamma
       21  0  0  0    .5 .5 0         Gamma to M
       0   0  0  0    0  0  0
    The first number designates how many points along each line.
    The next six label the starting and ending q-points,
    respectively.  Note that the last line must contain zeros.

    Second format: generate bands for a 2D mesh in a specified
    plane for Fermi-surface plotting.  This example applies to
    the bcc structure:
        vx     range  n     vy     range  n   height  band
       1 0 0   -1 1   51   0 1 0   -1 1   51   0.00    4,5
    It saves bands 4,5 on a 51 x 51 mesh in the xy plane that
    passes through the origin.

 site file : Normally site data is read through the ctrl file.
    However you may choose to read structural and site data
    through a separate file.  It is intended that this file
    accommodate any of several formats.  To date there is a
    format `standard' to this program, and one specified by
    Kotani.  See subs/iosite.f for syntax of file structure.

    You specify this option, and the file name using the `FILE='
    token in the ctrl file, described in
    tokens.html.
    Supercell generator `lmscell' has the capability to write a site
    file suitable for reading by other programs.

 positions file : similar to the site file, but limited to
    specification of site positions.  File is read (and named) by
    command-line switch --rpos=`filename'; and some programs (eg
    lmctl) will create this file when command-line switch
    --wpos=`filename' is supplied.

 qpts file : Programs needing to loop over the Brillouin zone
    normally generate their own table of q-points.  However, you
    may specify your own set of points (with certain
    restrictions; see description of token GETQP= in
    "tokens.html").  Here is a sample
    q-points file:

            8    4    4    4       0
            1    0.00    0.00    0.00    0.03125
            2   -0.25    0.25    0.25    0.25000
            3   -0.50    0.50    0.50    0.12500
            4    0.00    0.00    0.50    0.18750
            5   -0.25    0.25    0.75    0.75000
            6   -0.50    0.50    1.00    0.37500
            7    0.00    0.00    1.00    0.09375
            8    0.00    0.50    1.00    0.18750

    The first line specifies the total number of qp; the next
    three numbers are not used; the last should be zero.  Next
    follows lines, one line per qpt, each line with 5 numbers.
    The first merely labels the qp index; the next three are the
    qp in Cartesian coordinates.  The last is the qp weighting
    factor, and the weights should sum to 2.

5. Generated files

The executables above generate many kinds of derivative files, briefly described below. The file extension is suppressed in the following table.
  File  (creator), and description
  ---   --------------
  ctrl  the main input for all programs.
        It is never altered by any program in the package.

  log   (*) records a log of the most important output in
        abbreviated form.

  str   (lmstr;binary) real-space structure constant file
  sdot  (lmstr;binary) file containing energy derivative of str.

  moms (lm,lmf;binary) partial weights of overlap matrix
        decomposed into Rl or Rlm channels.  Used in two
        contexts: (1) to save information needed to the energy
        moments after the sampling weights are known, and (2)
        this is the data needed resolve density-of-states
        information into into Rl (or Rlm) channels.  For large
        systems, this file can become large, particularly if the
        dos need to be m-resolved.  See also the --pdos
        command-line option.  See file asaddq.f for the
        generation of the dos weights and their storage;
        program lmdos reads this or a similar file to
        create a the partial DOS.

  qpp   (lm;binary) information similar to moms, but intended for
        retaining information for nonspherical density inside MT
        spheres.

  wkp   (lm,lmf;binary) table of band weights needed to find Fermi
        level, and corresponding fermi level.

  mixm  (lm,lmgf,lmpg,lmf;binary) retains prior iterations of sets
        of input and output moments.  Used by the Anderson or
        Broyden mixing scheme to accelerate convergence towards
        self-consistency.  Usually you should delete these when
        starting a new calculation (such as changing the lattice
        constant) so it doesn't get used in subsequent runs.  NB
        mixm is the default name of the mixing file, but this
        name may be set by the user.

  tmp   (*,binary) used for virtual memory or temporary storage

  atom-files (ASA) one file is assigned for each inequivalent
        atom in a calculation.  Its name is fixed by the species
        label ATOM= in the SPEC category of the control file, as
        described in tokens.html.  A complete file contains some
        general information, the moments, potential parameters, or
        other parameters such as matrix elements for needed for
        spin-orbit coupling or matrix elements of the gradient
        operator needed for optics calculations, and the ASA potential
        within the sphere, or some subset of this information.  The
        moments and potential parameters are most read from this file
        if they are available; but it is possible to input the moments
        instead from the control file or the restart file as well.
        Data in the atomic file is grouped into categories delineated
        by a nonblank character in the first column.  Examples of
        categories are: GEN: a table of miscellaneous data, such as
        the site atomic number MOMNTS: the "log derivatives" Pl and
        moments Q PPAR: the potential parameters.  POT: the potential


  bnds  (lm,lmf,lmbnd,tbbnd) energy bands, in a tabular form. See
        description of plotting package FPLOT.*.gz for plotting
        bands.

  dos   (lmdos,tbdos) density-of-states, in tabular
        form. See description of plotting package FPLOT.*.gz for
        plotting dos.

  sv    (lm,lmgf,lmpg) records the total energy deviation from
        self-consistency for each iteration.

  save  (lm,lmgf,lmpg,lmf) outputs the magnetization and total
        energy each iteration in the self-consistency cycle,
        together with some variables assigned by the user.  Used
        in conjunction with script startup/vextract, the total
        energy as a function of some user-specified parameters
        can be conveniently extracted in tabular form.

  atm   (lmfa) free-atom densities and related information, needed
        to start full-potential programs

  rst   (lmf,binary) restart file, containing density and related
        information.  Together with the ctrl file, this file contains
        all information needed for a calculation
  rsta  (lmf) same information as rst, but file is formatted, and
        therefore both portable across machines and amenable to
        editing.

  eula  (noncollinear package) holds a table of Euler angles.

  jr    (lmgf) table of pairwise exchange interaction parameters

  qpts  (lm,lmgf,lmpg,lmf) table of q-points, if user chooses to
        specify them.

  hssn  (lm,lmgf,lmpg,lmf) hessian matrix, containing densities of
        prior iterations, used for charge mixing in the
        self-consistency cycle.

  gfqp  (lmgf;binary) temporary file holding Green's functions for
        each q-point in the BZ at one energy.  Used in branches
        where the GF over the entire zone is need at once,
        (e.g. linear-response branches).  For large systems or
        many k-points, this file can become extremely large.

  psta  (lm,lmgf) bare ASA response function for e->0, q->0.
        See documentation file linear-response-asa.txt

  sigm  (lm:sx) ASA self-energy, generated using sx branch

  vshft (lmgf,lmpg) a list of site potential shifts

6. A sample input file: Si

For a description of the generic structure of input files and its organization into categories and tokens, see input-file-style.txt

The following is a typical example of the input file called `ctrl'; the description of each input token is documented in tokens.html Each category in the sample below is displayed as hyperlink which points to the documentation for that category.
VERS    LMASA-6 LM:7 ASA:7
HEADER  Example of an ASA input file : Si with empty spheres
        You can put as many lines as you like.
# Any line beginning with '#' is a comment and is ignored
IO     SHOW=F HELP=f VERBOS=40 WKP=F
CONST   a0=.5292 nk=4 met=0
STRUC   NBAS=4 NSPEC=2 NL=3
        ALAT=5.431/a0 PLAT= 0 .5 .5   .5 0 .5   .5 .5 0
SITE    ATOM=SI   POS= 0 0 0
        ATOM=SI   POS= .25 .25 .25
        ATOM=ES   POS= .5 .5 .5
        ATOM=ES   POS= .75 .75 .75
SPEC    ATOM=SI   R/W=1  Z=14
        ATOM=ES   R/W=1  Z=0
HAM     NSPIN=1 REL=F QASA=0
OPTIONS NSPIN=1 REL=F ASA[ CCOR=F ]
STR     RMAX=3.2 SHOW=t
BZ      NKABC=nk nk nk METAL=met DOSWT=T SAVDOS=F TETRA=T
        BZJOB=1
ITER    MIX=A,b=.8 NIT=7 CONVC=1e-4 CONV=0
MIX     MODE=A,b=.8
START   NIT=7 CNVG=1e-4
        BEGMOM=T (=T to begin with moments, =F to begin with band-structure)
        CNTROL=T (=T to use following to override disk; =F to ignore following)
#           ATOM=SI  P=3.5 3.5 3.5    Q=1 0 0    2 0 0   0 0 0
#           ATOM=ES  P=1.5 2.5 3.5    Q=.5 0 0  .5 0 0   0 0 0
The control file is the main (and typically, only) input file, and also can serve to document a calculation. Data is read from the control file by categories, one category at a time. A category begins with a nonblank character in the first column; it ends with the next occurrence of one. Within each category are tokens, which is where the input is read. In the above example, in the STRUC category displayed above the following strings are parsed as tokens by program lm:
    NBAS= NSPEC= NL= ALAT= PLAT=
Files input-file-style.txt and input.pdf describe the generic structure of the input file, and some categories and tokens shared by most programs. Some tokens (and some categories) are optional; others are required. Which are required depends on the particular program. Some tokens (or categories) may be sought by one program but not by another.

Because the above example has HELP=T, if you invoke a program (or if you include the command-line switch --input in the call; Section 9 describes many command-line switches) the executing program reading that file would not execute what it normally does, but instead prints out what what would input have been attempted had HELP not been true.

Invoking 'lm --input' produces the following output.
 -----------------------  START LM (80000K)  -----------------------

 Token            Input   cast  (size,min)
 ------------------------------------------
 IO_SHOW           opt    i4       1,  1          default = 0
   Echo data as it is read from input file
 IO_HELP           opt    i4       1,  1          default = 0
   Show what input would be sought, without attempting to read data
 VERS_LM           reqd   r8       1,  1
   Input style version check: integer part must be at least as large as:
   Input style version: 7
 VERS_ASA          reqd   r8       1,  1
   Program version check: integer part must be at least as large as:
   Program version: 7
 CMD               opt    chr      1,  0
   Contents are appended to command-line arguments
 CONST             opt    chr      1,  0
   Constants may declared for use in expressions
   Variables may also be set from the command-line:  -vnam=#
 HEADER            opt    chr      1,  0
   Contents displayed at beginning of program execution
 IO_VERBOS         opt    i4v      5,  1          default = 30
   Verbosity stack for printout
   May also be set from the command-line: --pr#1[,#2]
 IO_WKP            opt    lg       1,  1          default = F
   Print size of dynamic arrays when allocated
 IO_IACTIV         opt    i4       1,  1          default = 0
   Turn on interactive mode
   May also be controlled from the command-line:  --iactiv  or  --iactiv=no
 IO_TIM            opt    i4v      2,  2          default = 0 0
   Turns CPU timing log.  Value sets tree depth.
   Optional 2nd arg prints CPU times as routines execute.
   Args may be set through command-line: --time=#1[,#2]

 --- Parameters for crystal structure ---
 STRUC_FILE        opt    chr      1,  0
   Name of site file containing basis and lattice information.
   Read NBAS, PLAT, and optionally ALAT from site file, if specified.
   Otherwise, they are read from the ctrl file.
 STRUC_ALAT        reqd   r8       1,  1
   Scaling of lattice vectors, in a.u.
 STRUC_NBAS        reqd   i4       1,  1
   Size of basis
 STRUC_PLAT        reqd   r8v      9,  9
   Primitive lattice vectors, in units of alat
 STRUC_NSPEC       opt    i4       1,  1
   Number of species to read from SPEC category.
   If not present, NSPEC will be obtained by counting entries in the SPEC category
 STRUC_DALAT       opt    r8       1,  1          default = 0
   added to alat after input is read
 STRUC_NL          opt    i4       1,  1          default = 3
   global default lmax+1 for basis and augmentation
 STRUC_SHEAR       opt    r8v      4,  4
   Volume-conserving shear of PLAT (1=ideal)
 * If token is not parsed, attempt to read the following:
 STRUC_ROT         opt    chr      1,  0
 * If token is not parsed, attempt to read the following:
 STRUC_DEFGRD      opt    r8v      9,  9
 * If token is not parsed, attempt to read the following:
 STRUC_STRAIN      opt    r8v      6,  6
   6 Voigt strain matrix elements
 STRUC_ALPHA       reqd   r8       1,  1
   Amplitude of (Voigt) strain.  Only read if STRAIN input

 --- Program Options ---
 OPTIONS_HF        opt    lg       1,  1          default = F
   T for non-self-consistent Harris
 OPTIONS_SHARM     opt    lg       1,  1          default = F
   Use true spherical harmonics
 OPTIONS_FRZ       opt    lg       1,  1          default = F
   Freeze core
 OPTIONS_SAVVEC    opt    lg       1,  1          default = F
   Save eigenvectors on disk
 OPTIONS_Q         opt    chr      1,  0
   Use Q=show, Q=atom, or Q=band to quit after input, sphere calc or band pass.
   Command-line `--quit=string' overrides input file
 OPTIONS_SCR       opt    i4       1,  1          default = 0
   Use scr to accelerate convergence:
   0 do nothing
   1 Make ASA static response function (see documentation)
   2 Use response to screen output q and ves
   4 Use model response to screen output q
   6 Use response to screen output ves only
     Add 1 to combine mode 1 with another mode
     Add 10*k to compute intra-site contribution to vbare each kth iteration
     Add 100*k to compute response function on every kth iteration

 * The following are ASA-specific
 OPTIONS_ASA       reqd   ---
   Contains the following ASA-specific tokens:
 OPTIONS_ASA_ADNF  opt    lg       1,  1          default = F
   Turn on automatic downfolding
 OPTIONS_ASA_NSPH  opt    lg       1,  1
   generate multipole moments in output density
 OPTIONS_ASA_TWOC  opt    i4       1,  1          default = 0
   Two-center ASA hamiltonian.  Use TWOC=3 for 2C+pert corr
 OPTIONS_ASA_GAMMA opt    i4       1,  1          default = 0
   gamma representation
   1: gamma
  >1: (gamma(1)+gamma(nsp))/2
    : Some noncollinear algorithms automatically
    : average spins this latter representation
 OPTIONS_ASA_CCOR  opt    lg       1,  1          default = T
   Turn on combined correction
 OPTIONS_ASA_ELIN  opt    r8       1,  1          default = 0
   Energy to linearize for CCOR (2nd gen ASA 2C hamiltonian)
 OPTIONS_ASA_NEWREPopt    lg       1,  1          default = F
   Interactively transform representation, (2nd gen ASA)
 OPTIONS_ASA_NOHYB opt    lg       1,  1          default = F
   Turns off hybridisation 
 OPTIONS_ASA_MTCOR opt    lg       1,  1          default = F
   Turns on Ewald MT correction
 OPTIONS_ASA_QMT   opt    r8       1,  1          default = 0
   Override standard background charge for Ewald MT correction
   Input only meaningful if MTCOR=T

 --- Parameters for hamiltonian ---
 HAM_NSPIN         opt    i4       1,  1          default = 1
   Set to 2 for spin polarized calculations
 HAM_REL           opt    i4       1,  1          default = 1
   0 for nonrelativistic Schrodinger equation
   1 for scalar relativistic Schrodinger equation
   2 for Dirac equation
 * To read the magnetic parameters below, HAM_NSPIN must be 2
 HAM_SO            opt    i4       1,  1          default = 0
   Spin-orbit coupling (for REL=1)
   0 : no SO coupling
   1 : Add L.S to hamiltonian
   2 : Add Lz.Sz only to hamiltonian
   3 : Like 2, but also compute  by perturbation
 HAM_NONCOL        opt    lg       1,  1          default = F
   Noncollinear magnetism
 HAM_SS            opt    r8v      4,  4
   Magnetic spin spiral, direction vector and angle
 HAM_BFIELD        opt    lg       1,  1          default = F
   Applied magnetic field (requires NONCOL=t)
 HAM_TOL           opt    r8       1,  1          default = 1e-6
   w.f. tolerance for FT mesh
 HAM_FORCES        opt    i4       1,  1          default = 0
   Controls the ansatz for density shift in force calculation.
   -1 no force   0 no shift
    1 free-atom shift  12 screened core+nucleus
 HAM_ELIND         opt    r8       1,  1          default = 0
   Lindhard energy for model screening
 HAM_XCFUN         opt    i4       1,  1          default = 2
   Specifies local exchange correlation functional:
   1 for Ceperly-Alder
   2 for Barth-Hedin (ASW fit)
   3 for PW91 (same as PBE) 
   4 for PBE (same as PW91)
 HAM_GGA           opt    i4       1,  1          default = 0
   Specifies GGA functional:
   0 for LSDA
   1 for Langreth-Mehl
   2 for PW91
   3 for PBE
   4 for PBE with Becke exchange
 HAM_RDSIG         opt    i4       1,  1          default = 0
   Controls how self-energy is added to local exchange correlation functional:
    1s digit:
      0 do not read Sigma
      1 add sigma to potential
      Add 2 to symmetrize Sigma(T)
      Add 4 to include Re(Sigma(T)) only
    10s digit:
      0 simple interpolation
      1 approx high and low sigma by diagonal (see sigp)
      3 interpolate sigma by LDA evecs
        (In this mode use 100s digit for # interpolation points)
    Add 10000 to indicate sigma has no symops
    Add 20000 to use minimum neighbor table
    Add 40000 to allow file qp mismatch
 HAM_RSRNGE        opt    r8       1,  1          default = 5
   Maximum range in connecting vectors for r.s. sigma (units of alat)
 HAM_RSSTOL        opt    r8       1,  1          default = 5e-6
   Max tolerance in Bloch sum error for r.s. sigma 
 HAM_NMTO          opt    i4       1,  1          default = 0
   Order of polynomial approximation for NMTO hamiltonian
 HAM_KMTO          opt    r8v                     size depends on other input
   Corresponding NMTO kinetic energies
   Read NMTO values, or skip if NMTO=0
 HAM_EWALD         opt    lg       1,  1          default = F
   Make strux by Ewald summation
 HAM_VMTZ          opt    r8       1,  1          default = 0
   Muffin-tin zero defining wave functions
 HAM_QASA          opt    i4       1,  1          default = 3
   0 => Methfessel conventions for 2nd gen ASA moments Q0..2
   1 => Q2 = coff to phidot**2 - p phi**2 in sphere
   2 => Q1,Q2 accumulated as coffs to  and 
   3 => 1+2 (Stuttgart conventions)
 HAM_PMIN          opt    r8v     10,  1          default = 0 0 0 ...
   Global minimum in fractional part of P-functions.
   Enter values for l=0..nl:
   0: no minimum constraint
   #: with #<1, floor of fractional P is #
   1: use free-electron value as minimum
 HAM_PMAX          opt    r8v     10,  1          default = 0 0 0 ...
   Global maximum in fractional part of P-functions.
   Enter values for l=0..nl:
   0: no maximum constraint
   #: with #<1, ceiling of fractional P is #
 HAM_SX            opt    i4       1,  1          default = 0
   Screened exchange:
    0 do nothing
    1 Calculate SX Sigma
   11 Calculate SX Sigma w/ local W
 HAM_SXOPTS        opt    chr      1,  0
   Options for screened exchange,.e.g.  SXOPTS=rssig;nit=3
 HAM_UDIAG         opt    i4       1,  1          default = 0
   nonzero => diagonal-only LDA+U

 --- Symmetry group operations ---
 SYMGRP            opt    chr      1,  0
   Generators for symmetry group

 --- Parameters for species data ---
 * The next four tokens apply to the automatic sphere resizer
 SPEC_SCLWSR       opt    r8       1,  1          default = 0
   Scales sphere radii, trying to reach volume = SCLWSR * cell volume
   SCLWSR=0 turns off this option.
   Add  10  to initially scale non-ES first;
    or  20  to scale ES independently.
 SPEC_OMAX1        opt    r8v      3,  1          default = 0.16 0.18 0.2
   Limits max sphere overlaps when adjusting MT radii
 SPEC_OMAX2        opt    r8v      3,  1          default = 0.4 0.45 0.5
   Sphere overlap constraints of second type
 SPEC_WSRMAX       opt    r8       1,  1          default = 0
   If WSRMAX is nonzero, no sphere radius may exceed its value

 * The following tokens are input for each species. Data sandwiched
   between successive occurences of token ATOM apply to one species.

 SPEC_ATOM         reqd   chr      1,  0
   Species label
 SPEC_ATOM_Z       reqd   r8       1,  1
   Atomic number
 SPEC_ATOM_R       reqd   r8       1,  1
   Augmentation sphere radius rmax
 * If token is not parsed, attempt to read the following:
 SPEC_ATOM_R/W     reqd   r8       1,  1
   rmax relative to average WS radius
 * If token is not parsed, attempt to read the following:
 SPEC_ATOM_R/A     reqd   r8       1,  1
   rmax relative to lattice constant
 SPEC_ATOM_A       opt    r8       1,  1          default depends on other input
   Radial mesh point spacing parameter
 SPEC_ATOM_NR      opt    i4       1,  1          default = 1501
   Number of radial mesh points
 SPEC_ATOM_LMX     opt    i4       1,  1          default depends on other input
   l-cutoff for basis
 SPEC_ATOM_IDXDN   opt    i4v      1,  1          default = 1
   downfolding index: 0, auto; 1, no dnf; 2, fold down; 3, neglect
 SPEC_ATOM_P       opt    r8v      1,  1
   Starting log der. parameters for each l
 SPEC_ATOM_Q       opt    r8v      1,  1
   Starting sphere charges for each l channel
 SPEC_ATOM_MMOM    opt    r8v                     default = 0
   Starting mag. moms for each l channel
 SPEC_ATOM_HCR     opt    r8v      1,  1
   Hard sphere radii for structure constants
 * If token is not parsed, attempt to read the following:
 SPEC_ATOM_HCR/R   opt    r8v      1,  1          default = 0.7
   Hard sphere radii for structure constants, units of R
 SPEC_ATOM_ALPHA   opt    r8v                     default depends on other input
   Screening parameters for structure constants
 SPEC_ATOM_IDMOD   opt    i4v                     default = 0
   idmod=0 floats P to band CG, 1 freezes P, 2 freezes enu
 SPEC_ATOM_DV      opt    r8       1,  1          default = 0
   Artificial constant potential shift added to spheres belonging to this species
 SPEC_ATOM_MIX     opt    lg       1,  1          default = F
   Set to suppress self-consistency of classes in this spec
 SPEC_ATOM_CSTRMX  opt    lg       1,  1          default = F
   Set to exclude this species when automatically resizing sphere radii (SCLWSR>0)
 SPEC_ATOM_GROUP   opt    i4       1,  1          default = 0
 SPEC_ATOM_GRP2    opt    i4       1,  1          default = 0
 * ... The next three tokens are for LDA+U
 SPEC_ATOM_IDU     opt    i4v      4,  1          default = 0 0 0 0
   LDA+U mode:  0 nothing, 1 AMF, 2 FLL, 3 mixed 
 SPEC_ATOM_UH      opt    r8v      4,  1          default = 0 0 0 0
   Hubbard U for LDA+U
 SPEC_ATOM_JH      opt    r8v      4,  1          default = 0 0 0 0
   Exchange parameter J for LDA+U
 SPEC_ATOM_C-HOLE  opt    chr      1,  0
   Channel for core hole
 SPEC_ATOM_C-HQ    opt    r8v      2,  2          default = -1 0
   Charge in core hole.  Optional 2nd entry is moment of core hole:
     Q(spin1) = full + C-HQ(1)/2 + C-HQ(2)/2
     Q(spin2) = full + C-HQ(1)/2 - C-HQ(2)/2
 SPEC_ATOM_EREF    opt    r8       1,  1          default = 0
   Reference energy subtracted from total energy

 --- Parameters for site data ---
 SITE_FILE         opt    chr      1,  0
   Name of site file containing basis and lattice information.
   If this token is specified, read POS from site file,
   and VEC, EULA, VSHFT, PL, RLX, if they are present.
   In this case no attempt is made to read the SITE tokens below.

 * The following tokens are input for each site. Data sandwiched
   between successive occurences of token ATOM apply to one site.
   Alternatively, all site data can be read in via the SITE file.

 SITE_ATOM         reqd   chr      1,  0
   Species label
 SITE_ATOM_POS     reqd   r8v      3,  1
   Atom coordinates, in units of alat
 * If token is not parsed, attempt to read the following:
 SITE_ATOM_XPOS    reqd   r8v      3,  1
   Atom coordinates, as (fractional) multiples of the lattice vectors
 SITE_ATOM_DPOS    opt    r8v      3,  1          default = 0 0 0
   Shift in atom coordinates added to pos
 SITE_ATOM_RELAX   opt    i4v      3,  1          default = 1 1 1
   relax site positions (lattice dynamics) or Euler angles (spin dynamics)
 SITE_ATOM_ROT     opt    chr      1,  0
   Rotation of spin quantization axis at this site
 SITE_ATOM_PL      opt    i4       1,  1          default = 0
   Assign principal layer number to this site

 --- Parameters for Brillouin zone integration ---
 BZ_GETQP          opt    lg       1,  1          default = F
   Read qp from disk
 * If token is not parsed, attempt to read the following:
 BZ_NKABC          reqd   i4v      3,  1
   No. qp along each of 3 lattice vectors.
   Supply one number for all vectors or a separate number for each vector.
 BZ_PUTQP          opt    lg       1,  1          default = F
   Write qp to disk
 BZ_BZJOB          opt    i4v      3,  1          default = 0
   0 centers BZ mesh at origin, 1 centers off origin
   Supply one number for all vectors or a separate number for each vector.
 BZ_METAL          opt    i4       1,  1          default = 1
   0 assume insulator; 1 save evecs on disk; 2 use wgt from prior iter
   3 always make two band passes; 4 BZ integration with 3-point scheme
 BZ_TETRA          opt    lg       1,  1          default = T
   Tetrahedron integration
 BZ_N              opt    i4       1,  1          default = 0
   N>0: Polynomial order for Methfessel-Paxton sampling
   N=0: Conventional Gaussian sampling
   N<0: Broadening by Fermi-Dirac distribution
   To be used in conjunction with W= ; see next
 BZ_W              opt    r8       1,  1          default = 5e-3
   N>=0: Line broadening for sampling integration
   N<0 : Temperature for Fermi distribution (Ry)
 BZ_EF0            opt    r8       1,  1          default = 0
   Initial guess at Fermi energy
 BZ_DELEF          opt    r8       1,  1          default = 0.05
   Initial uncertainty in Fermi energy
 BZ_ZBAK           opt    r8       1,  1          default = 0
   Homogeneous background charge
 BZ_SAVDOS         opt    i4       1,  1          default = 0
   Choose some combination of the following:
   1 Write DOS to directly disk (NPTS and DOS also needed)
   2 Write weights for partial DOS
   4 Same as (2), but weights m-resolved
 BZ_DOS            opt    r8v      2,  1          default = -1 0
   Energy window over which DOS accumulated
 BZ_NPTS           opt    i4       1,  1          default = 1001
   No. DOS points (sampling integration, and lmdos)
 BZ_EFMAX          opt    r8       1,  1          default = 2
   Find evecs up to efmax
 BZ_NEVMX          opt    i4       1,  1          default = 0
   Find at most nevmx eigenvectors
   If NEVMX=0, program uses internal default
   If NEVMX<0, no eigenvectors are generated
 BZ_ZVAL           opt    r8       1,  1          default = 0
   Number of electrons to accumulate in BZ integration
 BZ_NOINV          opt    lg       1,  1          default = F
   Suppress automatic inclusion of inversion symmetry for BZ
 BZ_FSMOM          opt    r8       1,  1          default = 0
   Fixed-spin moment (fixed-spin moment method)
 BZ_DMAT           opt    lg       1,  1          default = F
   Calculate density matrix
 BZ_INVIT          opt    lg       1,  1          default = T
   Use inverse iteration for diagonalization
 BZ_MULL           opt    i4       1,  1          default = 0
   Mulliken population analysis 

 --- Parameters for Ewald sums ---
 EWALD_AS          opt    r8       1,  1          default = 2
   Ewald smoothing parameter
 EWALD_TOL         opt    r8       1,  1          default = 1e-8
   Ewald tolerance
 EWALD_NKDMX       opt    i4       1,  1          default = 800
   Ewald tolerance
 EWALD_RPAD        opt    r8       1,  1          default = 0
   Scale rcutoff by rpad when lattice vectors padded in oblong geometries

 --- Parameters for iterations ---
 ITER_NIT          opt    i4       1,  1          default = 1
   maximum number of iterations in self-consistency cycle
 ITER_NRMIX        opt    i4v      2,  1          default = 80 2
   Sphere program, (1) max iter; (2) no. prior iter for Anderson mixing 
 ITER_MIX          opt    chr      1,  0
   Mixing rules for charge mixing.  Syntax:
   A[nmix][,b=beta][,bv=betv][,n=nit][,w=w1,w2][,nam=fn][,k=nkill][;...]  or
   B[nmix][,b=beta][,bv=betv][,wc=wc][,n=#][,w=w1,w2][,nam=fn][,k=nkill]
 ITER_AMIX         opt    chr      1,  0
   Mixing rules for Euler angles.  Syntax as in MIX
 ITER_CONV         opt    r8       1,  1          default = 1e-4
   Tolerance in energy change from prior iteration for self-consistency
 ITER_CONVC        opt    r8       1,  1          default = 1e-4
   Tolerance in output-input charge for self-consistency
 ITER_XIPMX        opt    i4       1,  1          default = 0
   Mix potential independently of charge:
   XIPMX=1: mix vin and v(qmix)
   XIPMX=2: mix vin and v(qout)
 ITER_UMIX         opt    r8       1,  1          default = 1
   Mixing parameter for densmat in LDA+U
 ITER_TOLU         opt    r8       1,  1          default = 0
   Tolerance for densmat in LDA+U
 ITER_NITU         opt    i4       1,  1          default = 0
   Max number of LDA+U iterations of densmat

 --- Parameters for optics ---
 OPTICS_MODE       opt    i4       1,  1          default = 0
   0: do nothing;
  -1: generate joint DOS
   1: generate linear eps_2
   2: generate linear eps_2 with on-the-fly sampling
   2: Add 10 for SHG
 OPTICS_NPTS       reqd   i4       1,  1          default = 501
   Number of energy points
 OPTICS_WINDOW     reqd   r8v      2,  1          default = 0 1
   Energy window over which to calc. eps
 OPTICS_FILBND     opt    i4v      2,  1          default = 0 0
   Occ. energy bands from which to calc. eps
 OPTICS_EMPBND     opt    i4v      2,  1          default = 0 0
   Unocc energy bands from which to calc. eps
 OPTICS_PART       opt    lg       1,  1          default = F
   Band-to-band decomposition of epsilon
 OPTICS_CHI2       opt    ---
   Parameters second harmonic generation.  If present then:
 OPTICS_CHI2_NCHI2 reqd   i4       1,  1          default = 0
   number of direction vectors for which to calc. chi2
 OPTICS_CHI2_AXES  reqd   i4v                     size depends on other input
   a,b,c direction vectors for each of the nchi2 sets
 OPTICS_ESCISS     opt    r8       1,  1          default = 0
   Scissors operator (energy added to unoccupied bands)

 --- Parameters for dynamics and statics ---
 DYN_SSTAT         opt    ---
   Parameters for spin statics:
 DYN_SSTAT_MODE    opt    i4       1,  1          default = -1
  <0:  No spin statics or dynamics
   0:  output Euler angles generated from density matrix
   1:  relax along force
   Add 10   to mix angles independently of P,Q
   Add 1000 to suppress self-const in P,Q
 DYN_SSTAT_SCALE   opt    r8       1,  1          default = 1
   Scale factor amplifying magnetic forces
 DYN_SSTAT_TAU     reqd   r8       1,  1
   Time step (only read if Landau-Gilbert dynamics specified)
 DYN_SSTAT_MAXT    opt    r8       1,  1          default = 0
   Maximum allowed change in angle
 DYN_SSTAT_ETOL    opt    r8       1,  1          default = 0
   Set tau=0 this iter if etot-ehf>ETOL    

 --- Read potential data (ASA) ---
 START_BEGMOM      opt    i4       1,  1          default = 1
   0 Start from potential parameters (on file)
   1 Create potential and pot pars from P,Q
   2 Create pot pars from file potential
   3 Create potential from restart file
 START_FREE        opt    lg       1,  1          default = F
   (Free atom mode): make self-consistent density for free atoms
 START_CNTROL      opt    lg       1,  1          default = F
   if F, the remainder of this category is ignored
 START_RDVES       opt    lg       1,  1          default = F
   Read Ves(RMT) from this category

 For each class, read the following:
 START_ATOM        opt    chr      1,  0
   Class label
 START_ATOM_P      opt    r8v                     size depends on other input
   Methfessel's Potential functions
 START_ATOM_Q      opt    r8v      3,  7
   Energy moments of the spherical density
 START_ATOM_ENU    opt    r8v                     size depends on other input
   Linearization energies

NB: this program lm was compiled with extension packages nc,optics,sx. Without these extensions, a few tokens may be missing.

7. Documentation of Categories and Tokens

For documentation on the categories and tokens listed in Section 6 see the file tokens.html.

8. Selection of Sphere Radii

One of the biggest nuisances for augmented-wave programs is the choice of sphere radius. Results are much more sensitive to choice of spheres in the ASA than in the full-potential case, in part because the energy functional (and potential) change with MT radii, whereas in the FP case, this only weakly so. Either for the ASA or FP, the radii are chosen by balancing the following competing needs:
MT potentials are exactly solvable
The KKR method is essentially exact for a MT potential, i.e. one that is spherical inside augmentation spheres and flat in the interstitial. The LMTO basis starts from the KKR basis; thus a partitioning of space which best resembles a MT potential is the best choice. This is particularly true for the ASA.
Geometry violation of overlapping spheres
Overlapping spheres count some parts of space twice and others not at all. In the ASA, the "combined correction" term partially undoes this error, but not completely. The full-potential hamiltonian is constructed so that the sphere contributions vanish quadratically for radii approaching the MT radius. Errors tend to be small until overlaps reach about 10% of the internuclear distance.
ASA Requirement for space-filling spheres
The ASA functional pretty much requires that the sum-of-sphere volumes equals the cell volume. More precisely, the density is carried by the spheres (superposition of spherically symmetrical sphere densities).
Large sphere radii assign more volume to augmented functions
Augmented wave functions are very accurate, and the more space covered by them the more reliable the basis set.
l-convergence is most rapid for small sphere radii
The larger the sphere radius, the more l's are required for convergence
Larger spheres better contain shallow semicore states
Ideally the core is completely localized within augmentation spheres. Particularly in the full-potential case where spheres overlap less than in the ASA, shallow semicore states can be an issue.
This program suite helps you set sphere radii in several ways. Programs using already-chosen (or guessed) sphere radii can rescale sphere radii up to a specified volume within constraints you supply. Also program lmchk can supply intelligent values for sphere radii (usually better than you can guess on your own).

Automatic scaling of sphere radii

Programs needing sphere radii can scale sphere radii as large as possible within constraints you supply. This option iteratively adjusts sphere radii as large as possible (or until the combined sphere volumes equals the cell volume) within certain constraints. To set this option, set SPEC token SCLWSR=1. (Actually, the number 1 is just the target sphere volume as a fraction of the cell volume. You can choose any number SCLWSR=n with n between 0 and 1. Usually you just choose n=1. recall that the ASA expects the sphere volumes to add to the cell volume), in which case n should be 1. In the FP case, you still want good sphere packing, so again usually you choose n=1. The constraints come in three flavors (all of them are imposed):
Constraints on sphere overlaps
There are two constraints OMAX1 and OMAX2 on sphere overlaps. If we call ri the radius for sphere i and rij the distance between sites i and j:
ri+rj-rij is constrained to be less than OMAX1 x rij
ri+rj-rij is constrained to be less than OMAX2 x min(si,sj)
Set OMAX1 and OMAX2 in category SPEC.

Maximum sphere radius
No sphere radius is allowed to exceed WSRMAX (set in the SPEC category).

Lock sphere radii of specific species
You can "lock down" the sphere radii of specific species. You set it using token CSTRMX= in the SPEC category for species you want to lock.

Choosing initial values of sphere radii

The ideal choice of sphere radii best approximates a potential that is spherical within the MT spheres and flat outside. Program lmchk has implemented one algorithm that makes a reasonable initial choice for MT radii. The algorithm works by computing the (electrostatic) potential obtained from overlapping free-atom densities along all connecting vectors between a given site and its relatively near neighbors. The MT radius is taken as the first potential maximum along any ray. This choice is a pretty reasonable estimate for the potential being approximately spherical inside. Also, note that for a completely symmetric bond, the potential maximum will fall exactly midway between the bond, so for that case the two sphere radii will exactly touch and have equal potentials. To tell lmchk to find these radii, invoke lmchk as
lmchk --getwsr
Once lmchk determines these radii, you must enter them in (by hand) to the input file using SPEC token RMAX=. There is at present no automatic way to use the radii generated by lmchk.

Finding empty spheres

You can use "empty spheres" as a device to fill space. The ASA requires the sum of sphere volumes to match the cell volume; however this can only be done with reasonable sphere overlaps (<15%) for fairly close-packed systems. The solution, in the ASA, is to pack the volume with "atoms" with atomic number zero ("empty spheres"). This is tedious but quite often necessary. Program lmchk has an automatic "empty sphere" finder that can greatly facilitate this step.
Assigning lower priority to resizing empty spheres
Particularly in the ASA, empty spheres are often needed to get reasonable sphere packing. However, it is reasonable that their radii should be scaled after the real spheres are rescaled. You can tell the resizer to do this through the 10's digit of token SCLWSR. The 10's digit behaves like a flag to cause the resizer to treat empty spheres on a different footing from all the other spheres.
   Add  10 to SCLWSR to initially scale real atoms (those with Z>0) first.
   The scaling is done using radii of size zero for all empty spheres.
   After this initial scaling, the resizer will proceed rescaling
   all the spheres.

  Add 20 to SCLWSR is similar to adding 10.  However, The final
  rescaling applies only to the empty spheres; the real atoms' spheres
  change only in the first scaling, without reference to the empty
  spheres.

9. Command-line switches

All of the programs have special branches that may be (and sometimes must be) set from command-line switches.
Here is an example:
  lmf -vns=4 -vnm=5 --rpos=pos 

Following unix style, switches always begin with `-'. There are many command-line switches that are specific to a particular executable; a number of others a common to most or all programs.

Some switches have a single `-'; some have two (`--'). Those with a single `-' tend to have an `assignment' function, such as a variables declaration (eg -vx=3), while those with two tend to control program flow (eg. --show). Sometimes there is not a clear distinction between the two (eg --pr, described below) and you can use either `-' or `--'

These switches can be set from the command line only for an operating system that accepts them, such as unix or MS-DOS. You can also put these switches in the CMD category in the input file. The function is similar to a command-line argument, but not identical, since preprocessor has already read the input file before the `CMD' switches are read. Thus the "-v" and "-c" variable declarations have a somewhat different effect.

Switches common to most or all programs:
  --h             lists command-line switches for that program
                  and quits.  (warning: sometimes documentation
                  is slightly out of date)

  --input         same as turning on HELP=T in category IO; see
                  HELP= in the description of the IO category
                  above.

  --show          same as turning on SHOW=T in category IO; see
                  SHOW= in the description of the IO category
                  above.

  --showp         prints out input file after having run through
                  the preprocessor, and exits.  This can be
                  useful because it shows the action of the
                  preprocessor.  When trying to parse a
                  complicated input file, it is often simpler to
                  run it through the preprocessor, and use the
                  output of the preprocessor as the input file

  --pr#1[,#2]     sets print verbosities, overriding any
   -pr#1[,#2]     specification in the input file's IO category.
                  #2 is verbosity for the potential generation
                  segment of code and assumes the value of #1
                  unless specified.  See input-file-style.txt for
                  a description of the verbosity.

  --time=#1[,#2]  prints out a summary of timings in various
                  branches of the code at the close of program
                  execution.  Timings are kept to a nesting level
                  of #1.  If #2 is nonzero, timings are printed
                  `on the fly'

  --iactive       turns on `interactive' mode. This overrides
                  specification of interactive mode this in the
                  ctrl file `IO IACTIV=' See input-file-style.txt
                  for a description of the interactive mode.

  -iactive=no     
  --no-iactive    turns off `interactive' mode, overriding
                  specification in the ctrl file.

  -c"name=strn"   declares a character variable and assigns to
                  value `strn'

  -v"name=expr"   declares a numeric variable and assigns to the
                  value of expression `expr'. Be advised that
                  only the first declaration of a variable is
                  used.  Later declarations have no effect.  In
                  addition to the declaration `name=...'  there
                  are assignment operators
                  `*=','/=','+=','-=','^=' modify existing
                  variables, following C syntax, as described in
                  description of category CONST above.

Switches common to programs using site information:
  --rpos=filename tells the program to read site positions from
                  file `filename' after the CTRL file has been
                  read

  --fixpos[:tol=#]
  --fixpos[:#]   tells the symmetry finder to adjust positions
                 to sites that are `slightly displaced', that is that
                 if they were displaced a small amount, would make the
                 basis conform to a group operation.  Optional tolerance
                 specifies the maximum amount of adjustment allowed.
                 Example: lmchk --fixpos:tol=.001

  --sfill=class-list tells the program to adjust the sphere sizes
                 to space filling.
                *By default, `class-list' is a list of integers.
                 These enumerate class indices for which spheres
                 you wish to resize, eg 1,5,9 or 2:11.  See
                 Syntax of Integer Lists for syntax of `class-list'.

                *A second alternative specification a class-list uses
                 the following:  `-sfill~style=2~expression'
                 The expression can involve the class index ic and atomic number z.
                 Any class satisfying expression is included in the list.
                 Example: `-sfill~style=2~ic<6&z==14'

                *A third alternative specification of a class-list is
                 specifically for unix systems.  The syntax is
                 `-sfill~style=3~fnam'.  Here "fnam" is a filename
                 with the usual unix wildcards.  For each class,
                 the program makes a system call `ls fnam | grep
                 class' and any class which grep finds is
                 included in the list.  Example:
                 `-sfill~style=3~a[1-6]'

Switches special to `lm':
 --band[~option~option...] tells lm to generate energy bands instead
                  of making a self-consistent calculation.  The energy
                  bands can be generated in one of several formats.
                  See generating-energy-bands.html
                  for a detailed description of the available options.

 --mix=#          start the density mixing at rule `#'
                  (See category ITER in tokens.html
                  for a description of mixing rules).

 --onesp          in the spin-polarized collinear case, tells the program that
                  the spin-up and spin-down hamiltonians are equivalent
                  (special antiferromagnetic case)

 -sh=cmd          invoke the shell `cmd' after every iteration

 --pdos[:mode=#][nl=#][:sites=site-list] tells lm what to store in the
                  partial weights file `moms'.  By default lm creates
                  the partial weights for all classes, and writes them
                  ordered by class.  This file may become quite large,
                  particularly if the moments are to be m-resolved.
                  Using --pdos you can specify whether the dos are
                  resolved by l or lm, and what sites to store.  Also
                  when invoking --pdos, the partial weights are
                  ordered by site, not by class; which site data is
                  kept depends on the options you use with --pdos.
                  This switch is also used by the full-potential
                  lmf; the following documents the options to
                  this switch for both programs.

		  sites=site-list lets you specify that the partial
                       dos are created only for a specified list
                       of sites.  By default lm or lmf will store
                       the weights for all sites, which can become
                       expensive to store.  For the site-list syntax,
                       see Syntax of Integer Lists

                  nl=# tells lmf to make the dos to a constant
                       l-cutoff (l=#-1), independent of site.
                       By default lmf uses a site-dependent
		       l-cutoff = lmxa.  lm ignores this switch.

                  mode 0: weights for all sites atom-resolved
                         (available only for lmf at present)
                       1: weights for all sites l-resolved
                       2: weights for all sites lm-resolved
                  By default the mode is 2.
	          Caution: at present programs lm and lmf don't
                  symmetrize the moments.  If you resolve dos by m,
                  you should suppress all symmetry operations.

Switches special to `lmf' or `lmfa':
 See fp.html

Switches special to `lmctl':
  -spin1           add spin-polarized moments into a non-polarized set

  -spinf           exchange up- and down- moments

  -mad             also write out the ves at RMAX.

Command-line arguments special to `lmchk':
  --getwsr         tells lmchk to use an algorithm to find reasonable
                   initial sphere radii automatically.

  --findes         tells lmchk to locate empty spheres to fill space.
                   It works by adding adding empty spheres (largest possible first)
                   until space is filled with sum-of-sphere volumes = cell volume.

                   Inputs affecting this switch are:

                   OPTIONS RMAXES=  : maximum allowed radius of ES to use when
                                      when adding new spheres
			   RMINES=  : minimum allowed radius of ES to use

                   SPEC  SCLWSR= OMAX1=  OMAX2=  WSRMAX= 

                   --findes uses these parameters to constrain size of spheres as 
                   new ones are added; see category SPEC.

  --mino~site-list tells lmchk to shuffle atom positions in site-list to minimize some
                   simple function of the overlap. (For now, the function has been set
                   arbitrarily to the sixth power of the overlap).
                  *By default, site-list' is a list of integers.  These enumerate
                   site indices for which positions you wish to move, eg 1,5,9
                   or 2:11.  There are See "Syntax of Integer Lists" below for the
                   complete syntax of a list of this type.
                  *Alternatively, you can enumerate a `class-list'.  lmchk will expand
                   the class-list into a site-list.  For this alternative, use
                   `--mino~style=1~class-list', e.g.  `--mino~style=1~1,6'
                  *Another alternative, or "style" to specifying a class-list uses
                   the following:  `--mino~style=2~expression'
                   It is just like `-sfill~style=2 ... above, but now the class
                   list is expanded into a site-list.
                  *Similarly, you can specify a class-list is with style=3 like
                   the -sfill~style=3, above.
                  *As a special case, you can invoke --mino:z, which specifies in
                   the list all sites with atomic number Z=0 (empty spheres).

  --wpos=filnam    writes the site positions to file `filnam'.



  --shell[:opts]   print out a neighbor table, in one of two styles.

                   Standard style: a table of neighbors is printed, grouped in
                   shells of neighbors centered the site in question.  By
                   default a table is printed for one site of each inequivalent
                   class.
                   Options for this style:

                   :r=# Specifies range of neighbors for this table. Default
                        value is 5.

                   :v   prints electrostatic potential for each pair

                   :e   prints inner product between euler angles
                        (noncollinear magnetism)

                   :sites=site-list restricts neighbors in shell to list.
                        NB this option must be the last one.


                   Tab style: a table of neighbors is printed in a table format
                   suitable for subsequent processing; see in particular the
                   --disp switch in lmscell.  To invoke tab style, use
		   --shell:tab[...].  Options for tab style:

                   :tab[=#] Invokes tab style, optionally in # format.
                            Tab style has several formats.  Defining:

                            ib is the site around which the table is made;
                            jb is the site index of a particular neighbor;
                            dpos(1..3,jb) is the connecting vector between
                            sites ib and jb (relative position)

                          mode format

		  	    1  (default mode)
		  	        ib jb dpos(1..3,jb)

		  	    2  (just the positions)
		  	       dpos(1..3,jb)

                               ... OR if :disp= is also set: two sets of pos:

		  	       dpos0(1..3,jb) dpos(1..3,jb)

                               ... The first set corresponds to the original
                                   positions; the latter for the positions as
                                   specified by the displaced positions file.
                                   In this mode, only neighbors for which there
                                   is some displacement are written. This mode
                                   is useful in conjuction with lmscell.

		  	    3 (sparse matrix format)
		  	         1 jb dpos(1,jb)
		  	         2 jb dpos(2,jb)
		  	         3 jb dpos(3,jb)

		   :fn=fnam write neighbor table to file fnam

		   :disp=fnam
                            read a second (displaced) set of positions from a
		            positions file (file fnam).  In this mode, a
		            neighbor table for both original and displaced
		            positions is written.

                   :r=#     Specifies range of neighbors for this table. Default
                            value is 5.

		   :nn      only print first (closest neighbor) entry for a
		            given pair of indices (ib,jb)

  --angles[opts]   similar to --shell, but prints angles between triples of
                   sites.  opts are as follows (you may substitute another
                   character for `:' below)
                   :r=# Specifies range for this table. Default value is 2.5.
		   :sites=site-list  loops over only sites in site-list
		   :bonds=site-list prints out table only for triples
                   :                   whose neighbors are in site-list
                   Example : --angles/r=3/sites/style=3/Si/bonds/style=3/Cr


  --terse          print out minimum information about overlaps

Program `lmdos' and its command-line arguments:
   --pdos[:mode=#][:lst=site-list]  tells lmdos that the weights file was
                                generated using this switch.  It doesn't
                                affect what lmdos makes but affects the
                                printout making the identification of Rl
                                (or Rlm) indices and DOS channels.  Usually
                                you use this switch only when you also
                                used it when invoking the program (lm
                                or lmf) that creates the weights file.
                                See description of --pdos as a
                                command-line argument to lm.

   --dos:option1:option2...  various options that affect action of lmdos.
              Options are:
                wtfn=file-name  file-name is file containing bands and
                                dos weights.  By default, lmdos uses file
                                `moms'

                cls             equivalent to wtfn=cls

                tbdos           sets defaults for to generate dos from
                                the tbe program, which uses slightly
                                different conventions for the moments file,
                                e.g. the moments file is named 'BAND'

                idos            generate energy-integrated dos

                npts=#          number of energy points.  If not specified with
                                command-line --dos, user is prompted for input.

                window=#,# 	energy window over which data is to be computed.
                           	#,# are minimum, maximum energies.  If not
                           	specified using command-line argument --dos,
                           	the user is prompted for input.

                mode=#  	This mode lets you compute quantities other than
                                the DOS.  depending on mode, lmdos computes:
				mode  calculate
                                0    integral dk delta(E-E_k)
                                     (DOS)
                                1    1/2 integral dk grad_1 E_k delta(E-E_k)
                                     (Ballistic conductance, Landauer formula)
                                2    integral dk grad_1 E_k grad_2 E_k delta(E-E_k)
                                     (`diffusive conductivity' in relaxation
                                      time approximation apart from scattering time)

                vec=#,#,#  	direction vector 1 for conductance; see mode=#

                vec2=#,#,# 	direction vector 2 for `diffusive'
                           	conductance; see mode= above

                totdos     	compute total dos by combining weights from all
                           	partial dos

                bands=list 	compute contribution to dos from a prescribed
                           	list of bands

                classes=list	generate dos for a specified list of classes.
                           	list syntax follows standard class-list syntax;
                           	see description of --sfill, above.
                                Caution: this option is only compatible
                           	with default moments files generated by the
                           	ASA, which stores dos weights by class,
                           	for all classes; it is incompatible
                           	with, e.g., the --pdos switch which stores
                                weights by site.
Example: compute the ballistic conductance in the z direction over an energy range (-0.8,0.5)Ry:
         --dos:mode=1:npts=501:window=-.8,.5:vec=0,0,1
Switches special to `lmxbs':
  -bs=expr    factor that scales the default ball (sphere) size.
              This factor scales the RMAX in the CLASS category.
              By default, the scaling is 0.5 * sphere radius

  -ss=expr    controls the criterion for what length defines a
              connected bond.  This switch scales the default
              factor scaling a 'bond' which must be less close
              than RMAX_i+RMAX_j (RMAX defined in STR).
              The default scaling is 1.

  -scale=val  sets the xbs variable `scale'

  -sp:rule1[:rule2][...]  modifies the species rmax and colors.
              `rule' has the syntax
              [expr],[rmax],[red],[green],[blue] `expr' is a
              logical expression involving the class index ic and
              atomic number z.  Optional rmax, red, green, blue
              are the ball size, and intensity of those colors
              for the ball.  Default values are taken for those
              numbers omitted.  For the colors, the defaults are
              random numbers between 0 and 1.

  -dup=n1,n2,n3[,expr] makes replicas of the unit cell by adding
              all combinations (0..n1,0..n2,0..n3) of the lattice
              translation vectors (p1,p3,p3) to every site in the
              cell.  The optional `expr' is a constraint that can
              be used to exclude sites that don't satisfy it.
              Variables that may be used in `expr' are:
                x1,x2,x3 are (dimensionless) site positions
                p1,p2,p3 are the same positions, as projections onto plat
                ic,z are class index, basis index and atomic number
              Example: select sites in a (dimensionless) cube of
                       size 1 and exclude empty spheres:
              lmxbs "-dup=4,4,4,0<=x1&x1<1.01&0<=x2&x2<1.01&0<=x3&x3<1.01&z>0"

  -sfill=class-list tells the program to adjust the sphere sizes to space filling.


Program `lmimp' and its command-line arguments:

Program `lmscell' and its command-line arguments:

Program `lmplan' and its command-line arguments:

Syntax of integer lists used in some command-line switches or at some input prompts:
 Here is the syntax for a list of integers that some switches
 use.  (slatsm/mkilst.f contains the source the code that
 generates this list).  The syntax is:

       Na,Nb,...

 where each of Na, Nb, ... assumes one of the three following forms:

   (a)   a single integer (or expression)
   (b)   two integers (expressions) separated by a colon, viz
         low:high which gets expanded into
         low, low+1, low+2, ... high
   (c)   three expressions separated by colons, viz low:high:step
         which gets expanded into
         low, low+step, low+2*step, ... high

  Examples:
    `5+1'       becomes a single number, 6.
    `5+1:8+2'   becomes a sequence of numbers, 6 7 8 9 10
    `5+1:8+2:2' becomes a sequence of numbers, 6 8 10.
    `1:4,7:11'  becomes the sequence 1 2 3 4  7 8 9 10 11.

10. Program ccomp


*A preprocessor, ccomp, provides a simplified, FORTRAN compatible
 version of C conditional compilation.  FORTRAN statements
 beginning with C# are preprocessor directives; the ones
 implemented now are C#ifdef, C#ifndef, C#else, C#elseif, C#endif
 (also C#define defines a name).  Directives C#ifdef, C#ifndef,
 C#elseif, and C#endif are followed by a name, eg C#ifdef CRAY.
 when C#ifdef is false (either name is not defined or it lies
 within an #if/#endif block that is false), ccomp comments out
 until a change of state (new C#ifdef, C#ifndef, C#else,
 C#elseif, C#endif encountered); C#ifdef is true, ccomp
 uncomments lines following until another conditional compilation
 directive is encountered.

*Conditional compilation blocks may be nested.  As with C, ccomp
 distinguishes case.  Output is to standard out.

*There is a primitive facility to make logical expressions using
 the AND (&) and OR (|) operators, such C#ifdef john & bill, or
 C#ifdef john | bill, is provided.  Precedence of operators is
 strictly left to right, so that john | bill & mike is equivalent
 to (john | bill) & mike, whereas john & bill | mike is
 equivalent to (john & bill) | mike

*How ccomp determines whether to modify code (i.e. add comments,
 or delete comments from a code segment)

 Whether the lines following a C#ifdef, C#ifndef, C#else,
 C#elseif, C#endif need to be commented out or uncommented
 depends on whether they have been commented out in a previous
 pass.  This information is contained in a `C' following the
 directive, eg C#ifdefC, C#ifndefC, C#elseC, C#elseifC, C#endifC.
 The preprocessor will set this, it is best advised to create any
 new blocks uncommented and let the preprocessor do the
 commenting.

 Programs lm, lmstr, lmdos, lmchk, etc..  are in fact the same
 source code, the only difference being that one is run through
 ccomp with different keywords defined.  ccomp is used
 extensively by `configure' both to create new branches code, to
 and customize code specific to certain compilers, either for
 optimization purposes or to avoid compiler bugs.

11. 2nd generation Orbital Downfolding

This is a procedure for constructing minimal basis sets and for
avoiding ghost bands. The best description is in Ole Andersen's
Varenna Notes (section 4.12), and for the stout-hearted, there is
a full account in Lambrecht and Andersen, Phys. Rev. B, 34, 2439
(1986).  It is implemented here including combined correction
which is described in Ole Andersen's unpublished notes,
"Transformation to a minimal LMTO set; downfolding" Aug 15, 1988.
We include in this documentation a plain TeX source file of notes
dnfpap.tex which may be of some use, and
which concerns our implementation directly (2nd generation lmto
only)

One way to look at the scheme is the following. When an electron
encounters an atomic sphere, the scattering it experiences can be
described in terms of its phase shift, eta_l.  The tangent of the
phase shift is a property of the scattering potential and the
angular momentum of the electron, l, and is a function of energy.
Some electrons are weakly scattered, while others (for example
d-electrons in transition metals) may scatter strongly,
especially when their energy is close to the resonant energy E_l.
In a linear method, the phase shift is parameterized:

    tan eta_l(E) = W_l / ( E_l  -  E)

so that one can construct an energy-independent hamiltonian. In
LMTO, it is customary to use the kappa=0 KKR phase shift in the
following parameterization:

    1 / P_l(E) = Delta / ( E  -  C )   +   gamma         (1)

which is correct to second order in (E - C); Delta is the width W
of the resonance, and C is the band center (analogous to E_l in
KKR theory). gamma is the second order distortion parameter. (In
practice one also includes third order terms using the small
parameter p (see Varenna notes)). 1/P is called the inverse
potential function, and is the LMTO analogue of the tangent of
the phase shift in multiple scattering and KKR theories.

For electrons that scatter only weakly, one can further
approximate the hyperbola (1) by a linear function. This is
exactly what happens if one throws away orbitals from the
basis---one approximates 1/P for these "high" partial waves by a
tangent drawn through the hyperbola (1) at the energy V^0, which
is the depth of a square well pseudopotential with the same
scattering properties as the atomic sphere for energy El. (If
the structure constants have been screened in these channels then
the tangent goes through the potential parameter V^alpha.)

The best possible way to treat weakly scattered electrons is to
make the tangent at El since then the eigenvalues are exact at
El, and the wavefunctions are correct to zeroth order. The way
to do this, is to change the representation of the hamiltonian
before discarding the orbitals. The effect of using a
representation beta is to shift the inverse potential function
(1) rigidly by the amount beta. This is done by choosing a beta
such that V^beta = El so that when the orbitals are then
discarded from the basis, this amounts to approximating their
scattering by a linear tangent to 1/P at El. This is called
folding down about 1/P(El).

If one merely wants to avoid ghost bands, then set the ADNF
switch and keep an eye on which orbitals are being folded down.
The automatic switch will choose to fold down about 1/P(El) or
about alpha depending on how weakly they are scattering. It is
often useful to set the switches manually as the criteria in the
automatic mode are set to cause no loss of accuracy. Very often
one can fold down orbitals and save a lot of time with only a
small error in the eigenvalues. Examples are p-orbitals in
transition metals and d-orbitals in Al. In Fe, the f-orbitals
must be folded down to avoid a ghost band. Another application is
in constructing minimal basis sets. As an exercise try folding
down orbitals in Si right down to s and p on the atoms and s in
the empty spheres (these are the analogues of Vogl's sp^3s*
basis). Now try folding down the empty sphere s as well: any
worse than Harrison's minimal basis? (Try the deformation
potentials!)