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
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.
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).
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).
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.
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.
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.
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
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.
For documentation on the categories and tokens listed in Section 6 see the file
tokens.html.
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).
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.
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.
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.
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:
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 command-line
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
(atom-centered) 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=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:
lmimp is a kind of 'restart file' editor, to import data either
from restart files, or from older versions (or Stuttgart versions) of
the lmto-ASA 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 command-line 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 site-potential 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 command-line 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 command-line 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.
Command-line arguments special to lmscell:
--wsite=name writes a site-file 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 principal-layer index according to `expr'.
Sites with equivalent values of `expr' are
assigned the same index.
--sites:site-list
Generate supercell only for sites in the site-list. For
the site-list 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:site-list
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 site-list. 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 command-line arguments:
lmplan is a special-purpose 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 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.
*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 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!)