This package is a collection of electronic structure codes based on the LMTO method.

  Written by M. van Schilfgaarde, A.T.Paxton, J. Klepeis and M. Methfessel
             with extensions by many others.
  email      [email protected]

The basic package (distributed as ASA.version.tar.gz) contains the
tight-binding lmto-ASA program and some auxillary programs.  There are
supplemental packages which are distributed in separate tar files:

 NC.vsn-no.tar.gz     noncollinear extensions to the LSDA
                      including spin-orbit coupling

 OPTICS.vsn-no.tar.gz calculates epsilon(omega) from LDA bands
                      without local-field corrections.

 GF.vsn-no.tar.gz     a crystal Green's function package

 PGF.vsn-no.tar.gz    a layer Green's function package

 SX.vsn-no.tar.gz     Rucker's screened exchange, which improves
                      bandgaps in semiconductors

 FP.vsn-no.tar.gz     a full-potential code using smooth Hankel functions
                      (starting with 6.9n)

 GW.vsn-no.tar.gz     a driver for T. Kotani's all-electron GW method.

 MOL.vsn-no.tar.gz    a molecules program (installation not automatic)

Each of these packages comes with a separate README, which see.
Additionally you will need to have installed:

 SLATSM.vsn-no.tar.gz a library of generic math functions.

The startup/ directory contains miscellaneous files needed for
installation and some program execution.

The doc/ directory contains a variety of documentation for this
package:

  README                      this file

  ChangeLog                   Documents various changes to the code
  Changes.*                   as it went through various implementations
  CheckLog		      Documents checks made on various architectures
                              
  lmto.html                   documents the ASA package, and its inputs.
                              This is the main documentation for the 
                              basic package.

  fp.html                     Documents the full-potential program.
  FPtutorial.html	      A tutorial for the fp program
  FPoptbas.html		      A tutorial for to choose the basis in the fp program

  gw.html                     Documents the GW driver and use of the GW self-energy

  gf.html		      Documents the Green's function package

  pgf.pdf		      Documents the layer Green's function package
  lmpg_tutorial.v2.0.pdf      A tutorial to compute Landauer-Buttiker transport
			      within the layer GF package

  input-file-style.txt        describes how the input file is structured.
  positions.html              More detailed description of how structural
  			      data can be specified
  rotations.html              A description of how rotations are specified

  file-preprocessor.txt	documents the input preprocessor.
                              The main input file is initially parsed by
			      a preprocessor which enables the input file
			      to have a `programming language' structure.

  nc.txt                      Documents the inputs used by the
                              noncollinear ASA package
  optics.txt		      Documents the inputs used by the
                              ASA optics package
  sx.txt                      Documents the inputs used by the
                              ASA screened-exchange package

  nfp-doc.ps.gz               A postscript file documenting the full-potential
                              method

  linear-response-asa.txt     Documents construction and use of ASA e->,
                              q->0 response function, used to
                              acclerate convergence in self-consistent
                              calculations
  for-developers.txt	      Some useful information for people wanting
                              to modify the code

  emp-tb.txt		      !
  emp-tb-update.txt	      !
  dnfpap.tex		      A description of downfolding, as
                              implemented in the 2nd gen ASA code

  MPI-instructions-for-lmf    Instructions to make an MPI version of lmf

The subs/ directory contains the source code, except for the main routine
Some portions of the source code may require special handling --- either
special compiler switches or some modification of the code.  On machines
for which this package has been installed, the modification should be
completely automatic; see Installation, below.

The source code and Makefile for the main programs is held in the
top-level directory. 

The testing/ directory contains input files and shell scripts to
test various features of the basic package.  See INSTALLATION, below.

Each supplemental package has its own separate directory, e.g. sx/

--------
INSTALLATION
--------

Starting with release 6.9, the installation procedure adapts the GNU
configuration package and is similar except in some minor respects from
installation of standard GNU programs.  Installation uses the 'configure'
script, described below.

--- Installation of the basic package ----
1. You will need to install the slatsm library.
   Installation results in a library archive slatsm.a, which is a
   library of generic math functions, distributed as
   SLATSM.##.tar.gz. You must have already installed the SLATSM
   package before installing this one.  Additionally, the slatsm
   archive should located either at ./slatsm/slatsm.a or at
   ../slatsm/slatsm.a; or you should set environment variable LIBSLA
   to the appropriate path.

   The appropriate version of SLATSM you must install depends on the
   version of the ASA package you install:

                LM              SLATSM
   version     7.0               48  or later
   version     6.15              45  or later
   version     6.14              43  or later
   version     6.10c             38c or later
   version     6.10a             38 or later
   version     6.9m-6.10         37
   version     6.9               36 or later

1. Follow steps 1-4 as discussed in the installation section of
   slatsm/startup/README.  This includes setting appropriate
   environment variables for your fortran and C compilers.
   The following are required:
    Variable    Puropse
     FC          fortran compiler, e.g. fort
     CC          C compiler, e.g. gcc
     LIBLOC      libraries to be linked at runtime, e.g.
                   -L/usr/local/lib -lblas -lcxml -lfftw3
                 It should include LAPACK, BLAS and FFT libraries (e.g. fftw)
                 For FFT, fftw is recommended (http://www.fftw.org)
   The following are optional:
    Variable    Puropse
     MACHINE    Machine mnemonic, to assist configure in determining the
                kind of architecture the package is being compiled on
                Shell script startup/Makemakefile needs information
                in order to determine compile switches.
                For a list of mnemonics it knows about, invoke
                  startup/Makemakefile --show
                For many common architectures, supplying the required FC
                is sufficient.
     LIBSLA     path to slatsm library, e.g. /home/markv/slatsm/slatsm.a
                If not supplied, configure will try and locate slatsm.a.
                configure will fail if it cannot find slatsm.a .


  *Useful public-domain packages:
   This package was designed around the BLAS3 routines, so having a well
   optimized BLAS3 greatly benefits the efficiency of these codes.
   If your machine does not come with a well optimized BLAS3 library, check
   out http://www.netlib.org/atlas/.

  *If you have special libraries such as the atlas library, take some
   care about how arrange the LIBLOC libraries.  For example, using
   the Portland group pgf90 compiler on an Intel box running linux, with
   the ATLAS library (http://www.netlib.org/atlas/), use, e.g.
      env FC=pgf90 LIBLOC='-latlas -llapack -latlas -lblas' ./configure
   so that lapack routines also link in the fast atlas library.

2. Invoke `./configure'.  `configure' will attempt to automatically
   assess your machine architecture, and based on it, create
   appropriate Makefiles. NB: on the DEC alpha running DEC unix, do
   not invoke configure from using /bin/sh -- it is buggy.  Use ksh,
   csh or tcsh.

   If you haven't set the environment variable MACHINE yourself,
   'configure' attempts to assign a 'machine mnemonic' --- a short name
   that is some combination of your machine architecture and compiler,
   as described in slatsm/startup/README.  If it is successful, the
   configure script will display something like

   Try and identify a machine mnemonic ...  found LINUXF

   in which case this package has probably been compiled before on a
   similar machine and should install automatically.  (If not, see below)

   'configure' should create the following:

   Make.inc            contains information about compiler switches,
                       the location of slatsm.a and the location
                       of special libraries, among other things.
   Makefile            A Makefile for the whole package

  *If you have problems, read through slatsm/startup/README.

  *At this point, you may wish to alter the compiler switches.
   `configure' picked a set based on the machine configuration,
   and all the Makefiles use compiler switches in file 'Make.inc'.
   Also, you may want to change LIBLOC in Make.inc.

3. Invoke 'make init' to invoke any pre-compilation needed.  Each Makefile
   has an 'init' rule that may alter the fortran code either to optimize
   for, or avoid bugs in, particular architecture / compiler combinations.
   The 'init' rule looks for scripts subs-to-NAME (NAME is the machine
   mnemonic) and invokes it if present.  Thus, fortran code may be altered
   at this step.

4. Invoke 'make ALL' to compile the archive libraries and the executables.

5. Invoke 'make check' to test the operation of some of the most
   important branches of the code.  The checks are not
   very sophisticated, and in some cases checks may fail when really the
   errors amount to small rounding errors in, e.g., the density of states.
   'make bigcheck' runs much more extensive tests.
   These tests also serve as pedagogical exercises.

   Running 'make check' from the top-level directory will run checks for each
   of the packages separately.  You can also run checks for each
   optional package separately:

     testing/test.lm
     make -f Makefile checkfp
     make -f Makefile checknc
     make -f Makefile checksx
     make -f Makefile checkoptics
     make -f Makefile checkgf
     make -f Makefile checkpgf

   'make' should stop if any one check fails.

   Alternatively, you can run the shell scripts interactively, e.g.
   fp/test/test.fp [--all].  Invoking the scripts this way produces
   more information.  Be advised that the shell scripts may
   require that binary rdcmd be in your path (which should automatically
   be compiled at step 4).

   rdcmd is a program that reads certain lines from a file, parses them
   and substitutes expressions enclosed in curly brackets {...} in a
   variety of ways, and then executes the transformed lines as commands
   in a subshell.  The expression substitution is done the same way as
   input files are read, as described briefly in asa-tb.doc and more
   completely in file slatsm/rdfiln.f.  It is somewhat analogous to a
   unix shell, but the substitution is quite different.  Initially rdcmd
   is compiled in directory main as part of the installation.

7. (optional) Invoke 'make install' to install the programs into your
   bin directory.

--- Installation with optional packages ---
Installation proceeds as in the basic package, except that you invoke
the configure program with one or more of the following switches

  ./configure    \
  --enable-nc  \
  --enable-sx  \
  --enable-pgf \
  --enable-gf  \
  --enable-fp \
  --enable-optics

Extension packages can modify the ASA main program, lm,
or create new programs (lmmc, lmf, etc).
   switch       Other programs
 --enable-gf      lmgf
 --enable-pgf     lmpg
 --enable-fp      lmfa,lmf
 --enable-gw      lmfgw,lmf2gw

--- Platform-specific problems ---
Below are some known platform-specific problems with the code.

* Some versions of the HP 'make' utility doesn't like large macros.
  'make' can fail when parsing subs/Makefile.
  Workaround: get a newer version of the OS.

* SGI R10000 (e.g. mips-sgi-irix6.5)
  There is a difficulty with the supplied library FFT routine.
  It apparently has a memory allocation leakage, so if you run a case
  with very many FFT calls, it will eventually run out of memory.
  Workaround: Change the fftw library for doing fft's, which you 
  can do by recompiling the slatsm library with fftw enabled.

* SUN sparc (e.g. sparc-sun-solaris2.8)
  The Sun awk utility does not function as on other platforms, so the
  testing scripts fail even when programs produce the correct results.
  Workaround: install GNU awk; see prep.ai.mit.edu.

* DEC alpha running true-64 unix
  1. There is a compiler bug when compiling main/rdcmd.f.
  Workaround: recompile rdcmd.f with -O1 optimization or lower.
  2. There is a problem with DEC's dxml library.  After
  invoking configure, substitute -lcxml for -ldxml in Make.inc

--- MPI installation ---
MPI versions of program lm and lmf can be created, but the
installation must be done in part by hand, as follows.
Program lm parallelizes over k-points.  The executable is called lm-MPIK.
Program lmf can parallelize over k-points, or for each k-point
the assembling of hamiltonian, overlap, and density can
be made to run in parallel.  The executable for the first is
lmf-MPIK; for the second it is lmf-MPI.

Install is not automatic, but procedures to install them are described in
doc/MPI-instructions-for-lm  and  doc/MPI-instructions-for-lmf.


--------
Contacts
--------

This package was written by Mark van Schilfgaarde (email
[email protected]), with assistance from a number of
authors, most notably Michael Methfessel, Tony Paxton, and John
Klepeis.