                       =========
                       WANNIER90
                       =========                            
                                                            
 The Maximally-Localised Generalised Wannier Functions Code 



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

 Requirements: A Fortran 95 compiler (most f90 compilers are really f95)
               LAPACK and BLAS libraries
	       (Optional) MPI libraries for parallel execution of the
                  postw90.x executable

 Configuration:
   The system dependent parameters (e.g. compiler name) are contained in a file
   called 'make.inc'. Sample files may be found in the ./config/ directory.
   Choose one that is nearest to your setup and copy it to make.inc. You may 
   need to edit it, for example to give the correct library path for your 
   machine.
   
    On a linux system with the intel compiler build Wannier90 by typing

         cp ./config/make.inc.ifort ./make.inc
         make 

   IMPORTANT NOTE: a GNU version of the make utility is needed to compile
     Wannier90.
     To know if your make version is GNU, type
       make -v
     If you have a GNU make utility, the first line of the output should
     read somethink like
       GNU Make 3.81
     Refer to your local system administrator for further information.

   See at the end of this file for some preprocessor flags that may be used
   to change some behavior of the code.

   Options to make include:

   make wannier    build the wannier90.x executable
   make post       build the postw90.x executable
   make default    (default) build wannier90.x and postw90.x
   make lib        build the wannier90 library
   make w90chk2chk build the w90chk2chk.x utility (see 'Utility' section of
                   the user guide)
   make w90vdw     build the van der Waals code
   make w90pov     build the ray-tracing code
   make install    install the built binaries
   make tests      run test cases
   make doc        build the documentation
   make dist       make a tar-ball of the distribution
   make dist-lite  make a tar-ball of the src and tests only
   make clean      remove object files etc
   make veryclean  remove all non-distribution file

 'make -j NN' will allow compilation using NN multiple threads.
 On a multicore CPU this will build the executables in a shorter time.

 'make install' supports DESTDIR and PREFIX variables.
 Executables will be installed into $(DESTDIR)$(PREFIX)/bin directory,
 libraries will be installed into $(DESTDIR)$(PREFIX)/lib directory.
 The default DESTDIR is empty, and the default PREFIX is /usr.

 In order to compile the postw90.x executable in its parallel version, you have
 to specify 
  COMMS=mpi
 inside the make.inc file (some of the example files already contain this line)
 and moreover define the parallel compiler using the MPIF90 flag, for instance:
  MPIF90=mpiifort
 
 Compiler: If your operating system came with a Fortran compiler or you have a
 commercial compiler (such as ifort) this should give the best performance.
  
 Libraries: For Wannier90 to perform well a well optimised BLAS library should
 be used. Many commercial operating systems and compilers provide well optimised
 BLAS libraries.
  ATLAS is one of the fastest implementations
     http://math-atlas.sourceforge.net/
  ACML AMD provides optimised BLAS for AMD processors 
    http://developer.amd.com/acml.aspx  
  LAPACK can be obtained from the netlib website. It also includes a 
  non-optimised BLAS.
     http://www.netlib.org/lapack/


Linux x86,x86-64
----------------

  1- make.inc.ifort
     Compiler:  Intel (ifc,ifort,iforte)
     Libraries: Intel mkl
                (ATLAS BLAS is faster for AMD processors) 

  2- make.inc.pathscale
     Compiler:  Pathscale (pathf90)
     Libraries: acml 

  3- make.inc.nag   
     Compiler:  NAG (f95)
     Libraries: ATLAS + LAPACK (maybe acml)
 [note in our experience the NAG compiler does not produce well optimised code]

  4- make.inc.sun
     Compiler: Sun-studio f90
     Libraries: sunperf (ATLAS is faster)
     avaible as a free beta for Linux

Generic: Most architectures
---------------------------
  1- make.inc.g95
     Compiler: g95
     Libraries: ATLAS + LAPACK

  2- make.inc.gfort
     Compiler: gfortran
     Libraries: ATLAS + LAPACK
     (the official gcc f90 compiler - often faster than g95)


Alpha/HP/Compaq/DEC Tru64 UNIX
------------------------------

   1- make.inc.alpha
      Compiler: f90
      Libraries: cxml

Sun / Solaris  (sparc or x86)
----------------------------

   1- make.inc.sun
      Compiler: f95
      Libraries: sunperf

Mac OS X
--------

   1- make.inc.macosx
      Compiler: gfortran
      Libraries: Accelerate library
      (check comments in the make.inc.macosx file!)

IBM PowerPC/power series. Linux or AIX
--------------------------------------

  1- make.inc.xlf
     Compiler:  xlf95
     Libraries: ESSL + LAPACK
       Note: ESSL does not provide a complete lapack installation.
         If your machine does not have a full LAPACK install, 
         download the netlib LAPACK. You might want to use
         the essl wrappers from 
         http://www.netlib.org/lapack/essl/

Windows
-------
 There are many commercial Fortran compilers for windows.
 We haven't included make.inc files for these as we don't 
 have access to them. Wannier90 should compile just fine.

 I use cygwin (http://www.cygwin.com/) which provides a bash shell.

  1- make.inc.g95
     Compiler: g95  (within cygwin)
     Libraries: LAPACK and ATLAS (cygwin comes with a lapack and blas library,
     but I think they have been compiled with g77. I had problems making 
     a working executable. I suggest building your own)

 2- make.inc.pgf90
    Compiler: Portland Group (pgf90)
    Libaries: pg supplied lapack and blas
 
PREPROCESSOR FLAGS
------------------
To add a preprocessor flag, add it to the FCOPTS and LDOPTS variables in the 
make.inc file.
For instance, if the flag is called EXIT_FLAG, you can simply append
  -DEXIT_FLAG
(note that -D is prepended to the name of the flag)
to the FCOPTS variable and LDOPTS variable, separating it with a space from
what is already defined. Example:
FCOPTS=-O2 -DEXIT_FLAG
LDOPTS=-O2 -DEXIT_FLAG

Alternatively, after the definition of the FCOPTS and LDOPTS variables,
at the end of the make.inc file, you can add the lines
  FCOPTS+=-DEXIT_FLAG
  LDOPTS+=-DEXIT_FLAG

Flags
-----

* EXIT_FLAG 
  If defined (and if your compiler supports it), returns an exit status =/= 0
  when the code exits due to an error (while it returns 0 on correct
  completion).
  By default, when this flag is not present, the value of the exit code is
  not sensible.
* CODATA2006
  Use physical constants from 2006 version of CODATA tables
  (http://physics.nist.gov/cuu/Constants/index.html)
  (Note that this is the default choice if nothing is specified)
* CODATA2010
  Use physical constants from 2010 version of CODATA tables
  (http://physics.nist.gov/cuu/Constants/index.html)
* USE_WANNIER90_V1_BOHR
  Use the value of the bohr radius (expressed in angstrom) that
  was adopted in versions 1.x of the Wannier90 code, instead of
  the values taken from the CODATA database.
  (This is intended for backward compatibility only)
