The quickest (and the luckiest) way to compile the EXC code and obtain a program running is to give the command sequence

 \$ ./configure 
 \$ make 
 \$ make test 
 \$ sudo make install 

However due to the non-standard location or multiple presence of fortran compilers, linear algebra subroutine or fft libraries, it is much better to explicitly give the location of all this stuff to the configure line. Example

$ ./configure --prefix=/dir/where/to/install CC=gcc F90=/path/to/f90compiler \
              CFLAGS="-O3" F90FLAGS="-O3" LDFLAGS="-nofor-main" \
              --with-blas="-L/dir/where/blas -lblas" \
              --with-lapack="-L/dir/where/lapack -llapack" --with-fftw=/dir/where/fftw

If any of these steps fails, see the Common Problems section.

This will compile, test and install EXC.
The EXC default directory is /opt/etsf/share/exc/. If you want to install it anywhere else, run configure with the prefix command.

Installation tree:

\$prefix	
  |--bin/
  |--share/exc/
            |--files/

General features:

--help	produces a more extensive help 
--prefix=DIR	directory where to install EXC 
--enable-static=ARG	if yes, prevents the use of shared object 
   ARG=no	(the same as --disable-static) shared object linked (default) 
   ARG=yes	that is suggested for portability 

Libraries and Packages

--with-fftw3=DIR	provides FFTW3 in DIR, (get it! www.fftw.org) 
  DIR=/path/to/main/location/of/fftw3
--with-blas=LOCATION	provides blas in DIR, (get it! www.netlib.org/blas) 
  LOCATION="-L/path/to/blas/location/lib -lblas"
--with-lapack=LOCATION	provides lapack in DIR (get it! www.netlib.org/lapack/) 
  LOCATION="-L/path/to/lapack/location/lib -llapack"

Some influential environment variables:

F90       Fortran 90 compiler command 
F90FLAGS  Fortran 90 compiler flags 
LDFLAGS	  linker flags, e.g. -L if you have libraries in a nonstandard directory  
CC	  C compiler command 
CFLAGS	  C compiler flags 

Many other options are available. For a list, type

$ ./configure --help

This is a list of known configure script command line, with different architectures and compilers.
These configures are supposed to generate (through the Makefile) big-endian executables (when applicable).

• Intel Fortran Compiler - parallel openmp
  

   ./configure F90=ifort F90FLAGS="-O3 -openmp" --with-fftw3="/path/to/fftw3/" \
    --with-blas="-L/path/to/blas/lib -lblas" --with-lapack="-L/path/to/lapack/lib -llapack" \
    LDFLAGS="-nofor_main" --enable-openmp
  

• IBM with xlf - parallel mpi
  

  ./configure F90=xlf90 F90FLAGS="-O3 -qsuffix=f=f90 -q64" --with-fftw3=/path/to/fftw3/ \
    --with-blas="-L/path/to/blas/lib -lblas" --with-lapack="-L/path/to/lapack/lib -llapack" \
    FORPRE='-traditional-cpp' --enable-mpi
  

• Gfortran - sequential
  

  ./configure F90=gfortran F90FLAGS="-O3" --with-fftw3=/path/to/fftw// \
    --with-blas="-L/path/to/blas/lib -lblas" --with-lapack="-L/path/to/lapack/lib -llapack" \
    --with-gfortran-endianness=big

• G95 - sequential
  

  ./configure F90=g95 F90FLAGS="-O3 -fno-second-underscore -i4" --with-fftw3="/path/to/fftw3/" \
    --with-blas="-L/path/to/blas/lib -lblas" --with-lapack="-L/path/to/lapack/lib -llapack" 
  

• SUN Compiler - sequential
  

  ./configure F90=f90 F90FLAGS="-O3 -xfilebyteorder=big16:%all -m64" --with-fftw3=/path/to/fftw3/ \
    --with-blas="-L/path/to/blas/lib -lblas" --with-lapack="-L/path/to/lapack/lib -llapack"
  

• Portland Compiler - sequential
  

  ./configure F90=pgf90 F90FLAGS="-O3 -byteswapio" --with-fftw3=/path/to/fftw3/ \
    --with-blas="-L/path/to/blas/lib -lblas" --with-lapack="-L/path/to/lapack/lib -llapack" \
    LDFLAGS_SPECIAL="-Mnomain"
  

• Pathscale - sequential
  

  ./configure F90="pathf90" F90FLAGS="-O3 -fno-second-underscore" --with-fftw3=/path/to/fftw3/ \
    --with-blas="-L/path/to/blas/lib -lblas" --with-lapack="-L/path/to/lapack/lib -llapack"
  

• blas (or lapack) not found (or not linked)

  The blas library, as well as the lapack, is a mandatory library for the EXC code. If the library is not in a standard directory, the ./configure will not find it. Use the option

  --with-blas="/dir/where/the/blas/are/installed/"

  However there's an important thing to know:
  when linking libraries to fortran code is MUCH RECOMMENDED to compile all libraries with the same compiler (and version) you use to compile EXC.

The endianness issue is one of the most common problems when running codes that, like DP, needs (also) a binary input file. DP relying on a qplda or a kss file (of course this problem doesn't occur if the ETSF_IO interface is used), which are binary files, the endianness of the input file and the endianness of the compiler/environment have to be the same. If you try to read a big-endian file with a little-endian compiled executable, it won't work.

Fortunately most of the machines host compilers that permit to change the endianness either at compilation time or, even better, at runtime. Notable exception are IBM machines and NEC (these are the only ones I know for sure) where the intrinsic big-endian format cannot be changed (this is the reason why the binary files given into the tests directory are big-endian).

Here there's a list of known FLAGS or ENV variable to change the endianness for several compilers

• Endianness change at compilation time
  • SUNSTUDIO: add ``-xfilebyteorder=big16:\%all'' to F90FLAGS
  • PGI: add ``-byteswapio'' to F90FLAGS
  • Compaq f90: add ``-convert big-endian'' to F90FLAGS

• Endianness change at runtime
  • Ifort: ``export F_UFMTENDIAN=big''
  • G95: ``export G95_ENDIAN=BIG''
  • Pathscale: ``export FILENV=.filenv'', where .filenv is a file containing
    

    assign -F f77.mips -N mips g:su
    assign -F f77.mips -N mips g:du
    

  • Open64: same as Pathscale

• Endianness change at configure time
  • gfortran: add --with-gfortran-endianness=big at your configure command to impose the big endianness.

This is an example of input file to be given to EXC. For a complete list of input variables see below.


exciton ! important

exc ! full excitonic calculation. this will imply the use of an abinit SCR file

so ! use a scissor operator which implies a value for soenergy,
! alternatively you might use 'gw' which implies the use of an abinit GW file
soenergy 0.6

shiftk ! put this value if you use shifted k-points

matsh 4 ! this is just an update of the old (still working) npwmat
(but instead of giving the total number of plane waves, you give a closed shell)
npwsh 12 ! this is just an update of the old (still working) npwwfn
(but instead of giving the total number of plane waves, you give a closed shell)

nband 8 ! last band to be considered in the calculation
lomo 1 ! first band to be considered: 1 is default

haydock ! use haydock iterative technique: this avoid the full diagonization
niter 100 ! number of iterations in the haydock iterative scheme

omegai 0.0 ! first frequency (eV)
omegae 10.0 ! last frequency (eV)
domega 0.1 ! step of frequency (eV)
broad 0.1 ! Lorentzian broadening (eV)

q 0. 0. 0. ! momentum transfer: (0,0,0) is default, like for optical regime

savememory ! permits to save a little memory
verboselevel 1 ! this is the default. a value of 3 will print out lots of stuff


!----- Type of calculation (default: linear response:tddft) -------------------
linear ! default: linear response in G space.
! solving the tddft equation for \chi
! this is not implemented in EXC

exciton ! excitonic calculation (the EXC code) in transition space
!--------------------------------------------------------------------------------

!---------- Energies for the diagonal part of H^exc (default:enks) ---------------------------------
enks ! default: use the Kohn-Sham eigenvalues found in the ground-state file
! to construct the diagonal of H^exc
gw ! perturbative GW energies: this variable implies the existence of a gwfile
qpsenergy ! self-consistent quasiparticle energies. this variable implies the
! existence of a qps file
so ! scissor operator correction.
! see below soenergy, stretch_valence, stretch_conduction
soenergy ! value of the scissor correction. default: 0.0
stretch_valence ! stretch = GW bandwidth / DFT bandwidth. default: 1.0
stretch_conduction ! modify energy in a linear way in order to reproduce the GW bandwidth
! like: e_GW = e_DFT * stretch
somult ! multi-scissor operator correction. implies the existence of a file
! called somult.in
!---------------------------------------------------------------------------------------------------

!---------- Wavefunctions for the matrix elements (default:kss) ----------------------------
kss ! default. use the Kohn-Sham wavefunctions found in the ground-state file
! to construct the numerator of \chi^0
qps ! self-consistent quasiparticle eavefunctions. this variable implies the existence
! of a qps file
!-------------------------------------------------------------------------------------------

!------ Tamm-Dancoff Approximation (default) ---------------------------------------------------------
tammdancoff ! if this flag occurs the calculation will use the so-called Tamm-Dancoff approximation,
! i.e. only the resonant part of H^exc will be taken into account
resonant ! equivalent to tammdancoff
!-----------------------------------------------------------------------------------------------------

!--- Exciton solver (default:fulldiago) --------------------------------------------------------------
fulldiago ! default. diagonalization of the excitonic hamiltonian.
haydock ! iterative inversion of the excitonic hamiltonian. implies the variable niter (see below).
! only the final spectrum is obtained but no excitonic eigenvalues and eigenvectors,
! preventing further analysis.
niter ! number of iterations for the haydock iterative procedure. default:100
haydock_restart ! write restart file. default false
!-----------------------------------------------------------------------------------------------------

!---- Screening --------------------------------------------------------------------------
wdiag ! default: only the diagonal (in G) of Wgg' is retained. it turns out to be a good
! approximation for solids
wfull !the whole gg' structure of W is used. important for clusters.

lf ! default: calculate also the exchange term <>.
nlf ! avoid the calculation of the exchange term <>. if rpa this corresponds to
! to a calculation without local fields.
!------------------------------------------------------------------------------------------

!----- Use of shikted k-points --------------------------------------------------
shiftk ! if the ground state structure has been calculated using shifted
! k-points, we have to tell dp about it, otherwise it will try to use
! the symmetries of the system to sample the whole Brillouin zone.
! Alternatively (and deprecatively) you can still use the old way ...
nsymk 1 ! force EXC to consider only the first symmetry (the identity)
noinvk ! do not use inversion
! Remember: either one uses the 'shiftk' flag OR 'nsym 1' + 'noinv'
!--------------------------------------------------------------------------------

!----- convergency parameters ----------------------------------------------------
npwwfn ! number of plane waves to describe the wavefunctions
! default: all plane waves found on the _KSS file will be used
wfnsh ! number of shells of plane waves to describe the wavefunctions
! default:all
! Remark: only one of the above parameters has to be specified

npwmat ! number of G-vectors for the \epsilon matrix (related to local
! fields) ! default:all
matsh ! number of shells og G-vectors for the \epsilon matrix (related
! to local fields) ! default:all
! Remark: only one of the above parameters has to be specified

nbands ! number of the last band (highest energy) to be included in the
! calculation ! default:all
lomo ! number of the first band (lowest energy) to be included in the
! calculation ! default:1
!---------------------------------------------------------------------------------

!-- Pseudopotential --------------------------------------------------------------
novkb ! exclude the nonlocal part of the pseudopotential, which is unfortunately
! the leading term for a big number of transitions
!---------------------------------------------------------------------------------

!----- Momentum Transfer - Polarization of light ---------------------------------
q
! This specifies the momentun transfer (vector) to the
! system. The value of q can range from 0 to very high
! value (several Brilloun zones equivalent)
! Very high q vector can be found in Electron energy loss
! or Inelastic X-ray Scattering. The case q=0 is
! particularly important for optical absorption, where the
! polarization of light can be secified giving a small
! value in one or another direction, e.g.
! q 0.0001 0.0001 0.0
! Remark: q uses the reduced coordinates here, not the
! cartesian ones.
doublegrid ! Allows to read two separate KSS-files for initial and final
! states, which are shifted by q with respect to each other.
! (e.g. k.p perturbation theory will be avoided at small q)
! USAGE: dp -i -k -k
! dp1.kss corresponds to the final states at k,
! dp2.kss corresponds to the initial states at k-q
antieps ! calculation of eps*(-q,-w) instead of eps(q,w), which
! corresponds to exchanging the two kss files in doublegrid
!---------------------------------------------------------------------------------

!----- Other flags -----------------------------------------------------------------
savememory ! if present this flag will make the code calculating the rhotw
! at any transition with a double Fourier transform, rather than
! storing the wave functions in real space. Advantage: reduction
! of the memory. Disadvantage: 3 instead of 2 Fourier
! transform per wavefunction.
verboselevel ! =0,1,2,3
! 0) minimum amount of info written down
! 1) default values. essential things are written down
! 2) Verbose mode: many more things are written down
! 3) Debug mode: to use only in debugging case,
! all the loop indices are written
! (tree and mem files created)
!-----------------------------------------------------------------------------------