LMTOASA 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
This documentation is oriented mainly for basic package
ASA.vsn.tar.gz, the electronic structure program implementing the
localdensity 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 fullpotential
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
MuffinTin 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 `secondgeneration' LMTO  namely a reworking of the
original method into a tightbinding form, so that the orbitals are
shortranged. Since then Andersen has devised a `thirdgeneration' LMTO,
and more recently a `NMTO' scheme [See O. K. Andersen, T. SahaDasgupta,
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 (SpringerVerlag, Berlin, 2000)] which while formally make
significant improvements over the `secondgeneration' LMTO, there remain
difficulties with implementation. At present, this package has
nonselfconsistent 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 fullpotential 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 fullpotential 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. (SpringerVerlag, Berlin) 2000; there is a postscript
file included in this directory.] The fullpotential 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 tightbinding program
tbe whose hamiltonian is taken from a
userchosen 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 fullpotential program.
Augmentedwave 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, densitiesofstates, 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 LMTOASA calculation is selfconsistent 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 selfconsistency 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 (φ_{l}^{2},
φ_{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 Q_{0},
Q_{1}, and Q_{2} 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
selfconsistent potential for a specified set of moments
Q_{0}..Q_{2} and boundary conditions. This
simplification depends on assumption of spherical densities, and is
unique to the ASA.
These codes (both ASA and fullpotential codes) use "logarithmic
derivative parameters" P_{l} to fix boundary
conditions at the sphere surface; they are described here.
Note: P_{l} 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 bandcenter 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 3770.
O.K. Andersen, O. Jepsen and M. Sob, in Lecture Notes in Physics:
Electronic Band Structure and Its Applications, eds. M. Yussouff
(SpringerVerlag, 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. 63124.
O.K. Andersen, C. Arcangeli, R.W. Tank, T. SahaDasgupta, G. Krier,
O. Jepsen, and I. Dasgupta in TightBinding 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 334.
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 Q_{0}..Q_{2}
from the eigenvectors of the Hamiltonian. (Alternatively, they may be
generated via a Green's function, using programs lmgf or
lmpg). Full selfconsistency 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 specialpurpose function such as generating
energy bands,
lm works by iterating to selfconsistency, 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 selfconsistency.
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 selfconsistent 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 selfconsistent 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 selfconsistent).
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 E_{l}, so that
φ_{l}(E) ≈
φ_{l}(E_{l}) +
(dφ_{l} /dE)_{El}
×
[φ_{l}(E)φ_{l}(E_{l})]
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
E_{l}. Alternatively equivalent information is
contained in the logarithmic derivative
D_{l}. For a given potential, there is a unique
correspondence between the logarithmic derivative D_{l}
of φ,
D_{l}=dlnφ_{l}/dlnE
at the sphere radius and E_{l}, so in principle, it is
possible to specify either one.
D_{l} is a cotangentlike 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 D_{l}, one branch for each principal quantum number.
For that reason we define a smooth quantity
P_{l}, which may be thought of as a smooth version of
D_{l}, and which also contains
information about both the principal quantum number and
the logarithmic derivative. P_{l} is defined as
P_{l} = 0.5  arctan(D_{l})/π + (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: P_{l} should not be confused with the "potential
function" O.K. Andersen defines in his ASA theory.
The above description of P_{l} applies to both ASA and FP codes. In the
free atom code lmfa, P_{l} and Q_{l}, where
Q_{l} 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 P_{l}, 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 selfconsistent).
In the ASA codes (lm, lmgf, lmpg), P_{l} together with
the moments Q, completely determine the potential in the crystal.
Both must be supplied for lm to work. P_{l} and Q are both input
directly through the control file. (As mentioned, the programs will
supply default values for both P_{l} and Q, which for the most part are
sufficient to get the program to converge to selfconsistency.) Once
you can make a band pass, the fractional part of P_{l} 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 P_{l} 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 P_{l}: .3 is quite free electronlike and suitable for
freeelectron like l channels such as Si d electrons, while .8 is
quite tightbinding 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 felectron elements like Gd.
NOTE: In
the case of spinpolarized calculations, the moments should all be
half of what they are in nonspin polarized calculations.
When iterating to selfconsistency, you have a choice, through the
parameter IDMOD described in the Documentation of
Categories and Tokens section, regarding the related pair of
parameters P_{l} and E_{l}. You may let P_{l} and E_{l} float to the center of
gravity of the occupied part of the band (most accurate for
selfconsistent calculations); this is the default. You may also
freeze alternatively P_{l} or E_{l} in the selfconsistency 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 selfconsistency by mixing the moments and
the parameters P_{l} 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.
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 selfconsistent band program for the ASA
lmstr generates the realspace 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 densityofstates (DOS) and
related quantities as a function of energy for plotting
or other analysis. It can generate the total DOS (or
DOSrelated quantities), or resolve the total into
partial contributions DOSrelated 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) . directionvector
which is the Landauer `ballistic' conductance along some
unit directionvector
*corelevel spectroscopy such as EELS derived from the
fullpotential program
catdos concatenates densityofstates generated from different
files into a single file.
lmscell generates supercells from smaller unit cells.
lmxbs generates an input file for Methfessel's ballandstick
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 specialpurpose 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
tightbinding hamiltonians, whose form the user specifies. They are
included in the basic package. there is some documentation
HERE.
tbe empirical tightbinding energy, forces, and dynamics
With extension packages, there are also the following programs or extensions:
lmf (FP) the selfconsistent fullpotential band program
lmfa (FP) computes the freeatom 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 (realspace GF in one dimension,
kspace in the other two)
lmfgwd (GW) a driver for T. Kotani's allelectron 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 fortrancompatible
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 densityofstates
(pldos), bands (plbnds) and other xy plots. In includes a
generalpurpose plotting program,
fplot, which creates xy 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.
The control file, called ctrl.extension is the main input file for
all programs. It together with command line arguments (see section
"Commandline 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 commandline argument. If no
extension is supplied on the commandline, `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
programname [switches] [fileextension]
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 commandline switches.
Other input files are:
symmetryline file : input for plotting energy bands along
selected symmetry lines or for generating constantenergy
contours such as a Fermi surface. This file (whose name is
specified as a modifier with the commandline argument
band, described in the "Commandline 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 qpoints,
respectively. Note that the last line must contain zeros.
Second format: generate bands for a 2D mesh in a specified
plane for Fermisurface 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
commandline switch rpos=`filename'; and some programs (eg
lmctl) will create this file when commandline switch
wpos=`filename' is supplied.
qpts file : Programs needing to loop over the Brillouin zone
normally generate their own table of qpoints. However, you
may specify your own set of points (with certain
restrictions; see description of token GETQP= in
"tokens.html"). Here is a sample
qpoints 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.
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) realspace 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 densityofstates
information into into Rl (or Rlm) channels. For large
systems, this file can become large, particularly if the
dos need to be mresolved. See also the pdos
commandline 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
selfconsistency. 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
atomfiles (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
spinorbit 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" P_{l} 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) densityofstates, in tabular
form. See description of plotting package FPLOT.*.gz for
plotting dos.
sv (lm,lmgf,lmpg) records the total energy deviation from
selfconsistency for each iteration.
save (lm,lmgf,lmpg,lmf) outputs the magnetization and total
energy each iteration in the selfconsistency cycle,
together with some variables assigned by the user. Used
in conjunction with script startup/vextract, the total
energy as a function of some userspecified parameters
can be conveniently extracted in tabular form.
atm (lmfa) freeatom densities and related information, needed
to start fullpotential 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 qpoints, if user chooses to
specify them.
hssn (lm,lmgf,lmpg,lmf) hessian matrix, containing densities of
prior iterations, used for charge mixing in the
selfconsistency cycle.
gfqp (lmgf;binary) temporary file holding Green's functions for
each qpoint in the BZ at one energy. Used in branches
where the GF over the entire zone is need at once,
(e.g. linearresponse branches). For large systems or
many kpoints, this file can become extremely large.
psta (lm,lmgf) bare ASA response function for e>0, q>0.
See documentation file linearresponseasa.txt
sigm (lm:sx) ASA selfenergy, generated using sx branch
vshft (lmgf,lmpg) a list of site potential shifts
For a description of the generic structure of input files and its
organization into categories and tokens, see
inputfilestyle.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 LMASA6 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=1e4 CONV=0
MIX MODE=A,b=.8
START NIT=7 CNVG=1e4
BEGMOM=T (=T to begin with moments, =F to begin with bandstructure)
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 inputfilestyle.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 commandline switch input in the call; Section 9 describes many commandline
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 commandline arguments
CONST opt chr 1, 0
Constants may declared for use in expressions
Variables may also be set from the commandline: 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 commandline: 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 commandline: 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 commandline: 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
Volumeconserving 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 nonselfconsistent 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.
Commandline `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 intrasite contribution to vbare each kth iteration
Add 100*k to compute response function on every kth iteration
* The following are ASAspecific
OPTIONS_ASA reqd 
Contains the following ASAspecific 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
Twocenter 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
Spinorbit 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 = 1e6
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 freeatom 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 CeperlyAlder
2 for BarthHedin (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 LangrethMehl
2 for PW91
3 for PBE
4 for PBE with Becke exchange
HAM_RDSIG opt i4 1, 1 default = 0
Controls how selfenergy 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 = 5e6
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
Muffintin 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 Pfunctions.
Enter values for l=0..nl:
0: no minimum constraint
#: with #<1, floor of fractional P is #
1: use freeelectron value as minimum
HAM_PMAX opt r8v 10, 1 default = 0 0 0 ...
Global maximum in fractional part of Pfunctions.
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 => diagonalonly 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 nonES 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
lcutoff 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 selfconsistency 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_CHOLE opt chr 1, 0
Channel for core hole
SPEC_ATOM_CHQ opt r8v 2, 2 default = 1 0
Charge in core hole. Optional 2nd entry is moment of core hole:
Q(spin1) = full + CHQ(1)/2 + CHQ(2)/2
Q(spin2) = full + CHQ(1)/2  CHQ(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 3point scheme
BZ_TETRA opt lg 1, 1 default = T
Tetrahedron integration
BZ_N opt i4 1, 1 default = 0
N>0: Polynomial order for MethfesselPaxton sampling
N=0: Conventional Gaussian sampling
N<0: Broadening by FermiDirac distribution
To be used in conjunction with W= ; see next
BZ_W opt r8 1, 1 default = 5e3
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 mresolved
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
Fixedspin moment (fixedspin 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 = 1e8
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 selfconsistency 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 = 1e4
Tolerance in energy change from prior iteration for selfconsistency
ITER_CONVC opt r8 1, 1 default = 1e4
Tolerance in outputinput charge for selfconsistency
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 onthefly 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
Bandtoband 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 selfconst 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 LandauGilbert 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 etotehf>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 selfconsistent 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.
For documentation on the categories and tokens listed in Section 6 see the file
tokens.html.
One of the biggest nuisances for augmentedwave programs is the choice
of sphere radius. Results are much more sensitive to choice of
spheres in the ASA than in the fullpotential 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 fullpotential 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 spacefilling spheres

The ASA functional pretty much requires that the sumofsphere 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.
 lconvergence 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 fullpotential 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 alreadychosen (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).
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+rjrij is constrained to be less than OMAX1
x rij

ri+rjrij 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.
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 freeatom
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.
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 closepacked 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.
All of the programs have special branches that may be (and
sometimes must be) set from commandline switches.
Here is an example:
lmf vns=4 vnm=5 rpos=pos
Following unix style, switches always begin with `'. There are many
commandline 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 MSDOS. You can also put these
switches in the CMD category in the input file. The function is similar to
a commandline 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 commandline 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 inputfilestyle.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 inputfilestyle.txt
for a description of the interactive mode.
iactive=no
noiactive 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=classlist tells the program to adjust the sphere sizes
to space filling.
*By default, `classlist' 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 `classlist'.
*A second alternative specification a classlist 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 classlist 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[16]'
Switches special to `lm':
band[~option~option...] tells lm to generate energy bands instead
of making a selfconsistent calculation. The energy
bands can be generated in one of several formats.
See generatingenergybands.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 spinpolarized collinear case, tells the program that
the spinup and spindown hamiltonians are equivalent
(special antiferromagnetic case)
sh=cmd invoke the shell `cmd' after every iteration
pdos[:mode=#][nl=#][:sites=sitelist] 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 mresolved.
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 fullpotential
lmf; the following documents the options to
this switch for both programs.
sites=sitelist 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 sitelist syntax,
see Syntax of Integer Lists
nl=# tells lmf to make the dos to a constant
lcutoff (l=#1), independent of site.
By default lmf uses a sitedependent
lcutoff = lmxa. lm ignores this switch.
mode 0: weights for all sites atomresolved
(available only for lmf at present)
1: weights for all sites lresolved
2: weights for all sites lmresolved
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 spinpolarized moments into a nonpolarized set
spinf exchange up and down moments
mad also write out the ves at RMAX.
Commandline 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 sumofsphere 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~sitelist tells lmchk to shuffle atom positions in sitelist 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, sitelist' 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 `classlist'. lmchk will expand
the classlist into a sitelist. For this alternative, use
`mino~style=1~classlist', e.g. `mino~style=1~1,6'
*Another alternative, or "style" to specifying a classlist uses
the following: `mino~style=2~expression'
It is just like `sfill~style=2 ... above, but now the class
list is expanded into a sitelist.
*Similarly, you can specify a classlist 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=sitelist 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=sitelist loops over only sites in sitelist
:bonds=sitelist prints out table only for triples
: whose neighbors are in sitelist
Example : angles/r=3/sites/style=3/Si/bonds/style=3/Cr
terse print out minimum information about overlaps
Program `lmdos' and its commandline arguments:
lmdos reads in the partial dos weights from a (binary) weights
file, which must have been generated previously by some program that has
a capability to decompose the dos into channels (lm, lmf,
tbe). By default, lmdos reads weights from file `moms',
which is a file automatically generated by program lm. Programs
lm, lmf and tbe can decompose the dos into to Rl or
Rlm channels at the various sites. Note: lm and tbe
normally generate dos weights for inequivalent classes only; the weights
are ordered by class. lmf will not generate a weights file by
default, but can make it do so by using the pdos commandline
argument; in that case, you supply a list of sites. (The pdos
switch also works in program lm, in which case the weights
file is created for a specified site list as in program lmf.)
lmdos reads the dos weights file as input, and generates as its
output an (ascii) file containing the partial dos resolved by energy for
each channel. If you have the fplot plotting package installed,
program pldos can translate this file into a figure.
lmdos doesn't need to know what the origin of the channels is; it
simply reads the number of channels from the the weights file. However,
to assist you in making an identification of the channels with
(atomcentered) functions, lmdos will print out what it thinks
the connection is. If you use the generating program inconsistently
with lmdos, it may print out an erroneous table.
pdos[:mode=#][:lst=sitelist] 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
commandline argument to lm.
dos:option1:option2... various options that affect action of lmdos.
Options are:
wtfn=filename filename 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 energyintegrated dos
npts=# number of energy points. If not specified with
commandline dos, user is prompted for input.
window=#,# energy window over which data is to be computed.
#,# are minimum, maximum energies. If not
specified using commandline 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(EE_k)
(DOS)
1 1/2 integral dk grad_1 E_k delta(EE_k)
(Ballistic conductance, Landauer formula)
2 integral dk grad_1 E_k grad_2 E_k delta(EE_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 classlist 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=classlist tells the program to adjust the sphere sizes to space filling.
Program `lmimp' and its commandline arguments:
lmimp is a kind of 'restart file' editor, to import data either
from restart files, or from older versions (or Stuttgart versions) of
the lmtoASA packages. Importation is done in in one of two flavors:
either you import parts of restart files, or you read atom files
from earlier (or Stuttgart) versions of the code.

Restart files (invoked by rs commandline argument):
In this most you invoke a ``restart file'' editor.
Use this editor to read site potential data from
one or more restart files and poke the information into site
data for the current lattice. After entering the name of a restart
file, the program will the number of sites in that file and
prompt you for a list of sites from which to import sitepotential data
(P,Q for the ASA).
You can enter a single site or a list of sites.
If you enter only one site, it can be distributed to whatever sites you choose for the
destination sites. If you enter a list of more than one site,
the list of destination sites must be the same number as the list
of importing sites.
Translate atom files (invoked by one of the commandline arguments
4 5 or 3s 4s 47u 5s for Stuttgart formats):
In this mode, lmimp will attempt to read files following older formats
(or Stuttgart formats). Data is read by class. NB: Stuttgart atom
files have no extension and the names are in capital letters.
lmimp will list the classes and data for which the conversion was successful.
Program `lmscell' and its commandline arguments:
lmscell is a supercell generator. User must supply a set of
new (supercell) lattice vectors. You can do so using token SLAT=
in category STRUC; if you do not, you will be prompted to input 9
numbers from the terminal. lmscell works by generating a
list of lattice vectors from the primitive lattice vectors, and
adding these lattice vectors to the basis vectors. Basis vectors
which differ by a lattice vector in the supercell are discarded An
expanded list of basis vectors is thus generated. Warning:
lmscell may fail if you choose a supercell significantly
elongated from the original, because the list of lattice vectors
may not encompass all the translations needed to create the new
basis.
Commandline arguments special to lmscell:
wsite=name writes a sitefile to disk, which can be used to
wsite=name read structural and site data.
shorten shorten basis vectors
shorten
sort:'expr [expr2 ...]'
sort basis vectors, ordering positions by increasing
value of `expr'. Allowed values in expr are x, y, and z
coordinates of basis. Optional `expr2' sorts subsets of
sites with equivalent values of `expr1'
pl:expr Used in conjunction with the layer codes (lmpg).
Assign principallayer index according to `expr'.
Sites with equivalent values of `expr' are
assigned the same index.
sites:sitelist
Generate supercell only for sites in the sitelist. For
the sitelist syntax, see Syntax of Integer Lists
wrsj[:fn=name][:scl=#]
Used in writing the pairwise exchange parameters of the
supercell generated, e.g., from a Green's function code.
Input file 'rsj' must be present.
fn=name writes to file 'name' (default name is rsj2)
scl=# scales the parameters by #
first Not documented
disp:fnam:sitelist
This switch is intended to displace sites within a certain
range of a specified site (or list of sites), according to
displacements read from file fnam.
(NB: you can use this switch in conjunction with lmchk, using
switch shell:tab:disp=fnam).
In this mode, a displacements file is read, which contains a
neighbor table for both undisplaced relative positions and
displaced positions around a particular site.
The undisplaced (relative) positions identify particular sites
in the neighborhood of the site in sitelist. Each sites
corresponding to the undiplaced relative position in the
neighbor table is identified, and is position is displaced by
the same amount as the displacements in the neighbor table.
Example:
lmscell wsite=site sort:'x3 x2'
will order the sites by increasing z; those with (nearly) identical
z will be ordered by increasing y.
For an illustration of lmchk and lmscell used to generate a displaced
positions table, invoke testing/test.lmscell 2.
Program `lmplan' and its commandline arguments:
lmplan is a specialpurpose code originally designed for
analysis of layered systems, and for changing relative positions of
planes, etc. A prompt appears at which you can do a variety of
things. However, this code is somewhat obsolete; at present it is not
carefully maintained, and many of the options can be better done other
ways. However, there are a couple of useful options:

Write site files (invoke by typing wsite to the prompt):
You can also create sites files with `lmscell'... however this one
is useful in the context of the layer Green's function code, because
it will write out the padded site information, if you invoke
wsite pad , or wsite ppad.
Analysis of layer electrostatic potentials
This is useful for computing, e.g. band offsets. Invoke by qsum
or qsum i1 i2 , where i1 and i2 are layer indices.
Syntax of integer lists used in some commandline 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.
*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.
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 stouthearted, 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
delectrons 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 energyindependent 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
basisone 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 E_{l}. (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 E_{l} since then the eigenvalues are exact at
E_{l}, 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 = E_{l} 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 E_{l}. This is called
folding down about 1/P(E_{l}).
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(E_{l}) 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 porbitals in
transition metals and dorbitals in Al. In Fe, the forbitals
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!)