=== ecalj package === (this document is checked at Augl2014)
This is README at https://github.com/tkotani/ecalj

>git clone https://github.com/tkotani/ecalj.git
to get a ecalj package here. (you need "git" installed).

The homepage of ecalj, https://github.com/tkotani/ecalj,
shows current status and this README.

==================================================================
ecalj is a first-principle electronic structure calculation package in
f90,  especially for the PMT-QSGW. 
We have another home page at http://pmt.sakura.ne.jp/wiki/, but
not well-organized yet, little in English yet. We will renew it.

At least, three citations are required for your publications.
 1. PMT-QSGW, Takao Kotani, J. Phys. Soc. Jpn., Vol.83, No.9, Article ID: 094711
    http://dx.doi.org/10.7566/JPSJ.83.094711, DOI: 10.7566/JPSJ.83.094711
 2. QSGW, 10.1103/PhysRevLett.93.126406
 3. ecalj package, https://github.com/tkotani/ecalj

For developers, I like to add your branch on ecalj/master.
Eventually, I like to take your development into my master.
Let me know your git address.
===================================================================

##### Unique features in ecalj package #####
(1)All electron full-potential PMT method: a mixed basis method of two
   kinds of augmented waves, that is, L(APW+MTO). 
   In principle, it is possible to perform default calculations just
   from atomic structures.
   Relaxiation of atomic positions is possible in GGA/LDA and LDA+U.
   A converter between POSCAR(VASP) and our crystal strucrue file
   'ctrls.*' is included. (a small program---but slight buggy; let
   T.Kotani know problems in it; need to supply numerically accurate
   atomic positions to judge crystal symmetry from atomic positions).
   Our recent development shows that very localized MTO (damping
   factor is \sim 1 a.u), together with APW
   (cutoff is \sim 3 to 4 Ry) works well to get good convergences.
   
(2)The PMT-QSGW method, that is,
   the Quasiparticle self-consistent GW method (QSGW) based on the PMT method. 
   In addion, we can calculate dielectric functions, spin fluctuations,
   spectrum function of the Green's functions and so on.
   GW-related codes are in ecalj/fpgw/.
   For paralellized calculations, 
   we can use lmf-MPIK and mpi version of hvccfp0,hx0fp0_sc,hsfp0_sc.
   (although we have so much room to improve it).

(3) Wannier function generator and effective model generator
    (Maxloc Wannier and effective interaction between them). 
    This is mainly due to Dr.Miyake,Dr.Sakuma, and Dr.Kino.
    fpgw/Wannier/README

##### Install and test #####
To get a ecalj package, do
>git clone https://github.com/tkotani/ecalj.git
Then follow these steps explained below.
 (0) Get ecalj package and get tools.
 (1) make for single-core LDA part, 
 (2) make for MPIK LDA part, 
 (3) make for MPIK GW part.
 (4) Install test
 (5) crystal structure tools
In the following explanation, we assume gfortran in ubuntu. 
But we can also use ifort, and others. 

------------
(0) Get ecalj package and get tools.
--- Let us assume you use ubuntu. ---
You need following tools and libraries to be installed.
>sudo apt-get install git  #version control and to get source from github
>sudo apt-get install gitk #git gui. 
>sudo apt-get install gfortran      # GFORTRAN
>sudo apt-get install openmpi-bin openmpi-dev     # MPI 
>sudo apt-get install libfftw3-3     or something else # FFTW
>sudo apt-get install libblas3gf     or something else # BLAS
>sudo apt-get install liblapack3gf   or something else  # LAPACK
>sudo apt-get install etags csh bash tcsh gawk  # shells

Note that you need to use python 2.x is also assumed 
(usually already in ubuntu. Type >python (ctrl+D for quit)).

Version ctrl is by git (which makes things easier, but not
necessarily required for installation).

After you have installed git (version control software), 
you can get ecalj package by
>git clone https://github.com/tkotani/ecalj.git # Get source code for ecalj.
or get it in *.zip from the page https://github.com/tkotani/ecalj
(push zip button). I recommend you to use git, 
to check your changes (>git diff), and know version id.
After the above git clone command, a directory ecalj/ appears
(under the directory at which you did git clone).

We suppose you have ecalj/ and bin/ at your home directory, 
but it can be at any directory. All are described with relative path.
(except ~/bin, which is a directory containing all required binaries and scripts.
 You can also specify other directory instead of ~/bin in makefiles.).

We can check history of ecalj code development by
">gik --all" at ecalj/ directory after you did git clone.

------------
(1) make single core LDA part (it is in ecalj/lm7K/).
Let us assume gfortran case.
Move to ecalj/lm7K/, then do "make PLATFORM=gfortran". 
Then make process start.
The main makefile is ecalj/lm7K/Makefile, which contains lines
  PLATFORM=gfortran   #default is PLATFORM=gfortran
  ...
  include MAKEINC/Make.inc.$(PLATFORM)
This means that this Makefile uses ecalj/lm7K/MAKEINC/Make.inc.gfortran
as a part of the Makefile. Thus we have to check settings in it 
in advance to run "make PLATFORM=...".
LIBMATH= should contain path to the math libraries, FFTW, BLAS and LAPACK.
An example is 
  LIBMATH= /usr/lib/libfftw3.so.3 /usr/lib/liblapack.so.3gf /usr/lib/libblas.so.3gf
I think FFLAGS=, FFLAGS_LESS=... can be choosed by your own manner. But usually
Make.inc.gfortran worsk as it is.

Let us think about an ifort case.
In this case, "make PLATFORM=ifort" usually.
There are several MAKEINC/Make.inc.ifort*
(not _mpik*) with which we installed to machines. 
You can choose one of them or you can set your own Make.inc.ifort.*
(compilar, compilar options, math library).
I think "make PLATFORM=ifort" works well for ifort. But you may need
to add -heap-arrays 1 (for large calculations. Because we use large
stacksize; but I am not so sure about this).

For other cases, run "make PLATFORM=foobar" where foobar can be ifort
or something else. foobar corresponds to an include file 
lm7K/MAKEINC/Make.inc.foobar. 

Warning messages like ": warning: ignoring old commands for target `/vxcnls.o'" is
just because of problem of Makefile. you can neglect this. We will fix it..

Current ecalj with gfortran4.6 or 4.7 works fine with FFLAGS=-O2, but failed with FFLAGS=-O3.

Parallel make like
>make -j24 PLATFORM=gfortran
may speed it up for multicore machines(24 core in this case). 
But it stops because of dependency is not well-described in current Makefile. 
In such case, repeat it a few times, or repeat it without -j24.

Finally do "make PLATFORM=gfortran install"
This just copy required files (binaries and scripts) to your ~/bin.
(check it in Makefile). If you don't like to copy them to your ~/bin,
replace ~/bin to a directory you like, at the bottom of Makefile.

(For CMD workshop participants: rum
 >make PLATFORM=ifort.cmd 
 which corresponds to MAKEINC/Make.inc.ifort.cmd)

------------
(2) make MPI LDA part.
lmf-MPIK and lmfgw-MPIK are needed for gwsc. These are k-point
parallel version of lmf, and gw driver lmfgw. To make it, do
"make PLATFORM=gfortran_mpik". 
For ifort, set PLATFORM=ifort_mpik
Then Makefile uses ecalj/lm7K/MAKEINC/Make.inc.ifort_mpik is used.
You may need to add -heap-arrays 1 (for large calculations. Because we
use large stacksize) to ecalj/lm7K/MAKEINC/Make.inc.ifort_mpi, but I
am not so sure about this.

Clean up:
If something wrong. do "make clean" or "make cleanall" and start over.
Look into Makefile if you like to know what they do.
"make cleanall" removes all *.o *.a modules, and binaries.

---
* Move binaries to your bin by 
>make install
at ecalj/lm7K. It just moves all requied binaries to your ~/bin.
In advance, you have to make your bin, and add ~/bin to  your path
(e.g. "export PATH=$HOME/bin:$PATH" in .bashrc . Then login again or "source .bashrc")

---------------------
(3) Installation for fpgw/
At ecalj/fpgw/exec/ directory, you have to a softlink make.inc such as
>lrwxrwxrwx 1 takao takao 17 Aug 25 13:18 make.inc -> make.inc.gfortran

For each machine you have to prepare your own make.inc.foobar 
(There are samples. Here is the case of make.inc.ifort.cmd), 
and do
>ln -s make.inc.ifort.cmd make.inc
to make a soft like make.inc -> make.inc.cmd
(Q. What is soft link foo -> bar? 
 A. foo is an alias of bar).

[NOTE: we often see Segmentation fault due to stacksize limit (See by
a command "ulimit -a"). It is needed to run "ulimit -s unimited" 
in the qsub script or before running GW jobs. 
The compilar option of ifort "-heap-arrays 100" try to allocate
automatic array more than 100KB not at stack but at heap (thus
requires less stacks.]

Then you have to run 
>make
>make install
>make install2
Before this, you have to set blas and lapack in fpge/exec/make.inc.
(for ifort, -mkl is enough. LIBMATH= should be the same as that in Make.inc.*.
"make install" copy requied files to your ~/bin.

-----------------------
(4) Install test
We have to check whether binaries works fine or not.
Move to ecalj/TestInstall. Then type make (with no arguments). 
It shows help about how to do test.
To test all of binaries, just do
>make all
. All tests will require ~10min.  (nio_gwsc takes ~300sec)
In cases, nio_gwsc fails. 
However, as long as the difference is small,
not need to care its fail sign. (a minor bug in test).

As the help of make (no arguments), shows
>make lmall
tests only LDA part.
>make gwall
tests only GW part.

NOTE: in principle, repeat make should do nothing when all binaries
are correctly generated. However, because of some problem in makefile, 
you may see some make procedure is repeated. You can neglect it as
long as "All test are passed!" is shown in the (4)install test.

----------------------
(5) Structure tool.
In any calculations, we first have to supply crystal structure correctly.
To help this, we have a converter between POSCAR(VASP's crystal
structure file) and ctrls(that for ecalj). 
In addition, we have a simple tool to invoke crystal strucrure viewer.
It is in \verb+ecalj/Structure/tool/.

In advance, install a viever of crystal structure for POSCAR.
Here we use VESTA at http://jp-minerals.org/vesta/.
Download it, and expand it to a directory. 
VESTA can handle kinds of format of crystal structure.

Then make a softlike by
  ln -s ~/ecalj/StructureTool/viewvesta.py ~/bin/viewvesta
  ln -s ~/ecalj/StructureTool/ctrl2vasp.py ~/bin/ctrl2vasp
  ln -s ~/ecalj/StructureTool/vasp2ctrl.py ~/bin/vasp2ctrl
. With this procedure we can run command viewvesta, ctrl2vasp,
vasp2ctrl from console as long as you have ~/bin/ in the command
search path. In my case, .bashrc have a line
  export PATH=$HOME/bin:$HOME/VESTA-x86_64:$PATH
. It depends on your machine. (after editing .bashrc, you have to do
"source ~/.bashrc" to reflect changes).

Set the variable of VESTA=, at the begining of 
~/ecalj/StructureTool/viewvesta.py to let it know where is VESTA.


--------------------------------------
####### How to do version up? ######

We do not have enough human resource to keep it very well. 
Thus, be careful to do version up. It may cause another problem.
But it is not so difficult to move it back to original version
if you use git.
An important things is your own Make.inc.* files. Keep it by yourself,
or by a command ./mbackup (look into it first).

>cd ecalj
>git log 
   This shows what version you use now.
>git diff > gitdiff_backup   
   This is to save your changes added to the original (to a file git_diff_backup ) for safe.
   I recommend you do take git diff >foobar as backup. >git stash also
   move your changes to stash.
>./mbackup          
    This save makefiles and related files. Look into the ./mbackup file. It is a simple scripts.
    Your customized Makefile MAKEINC/* fpgw/exec/make* are copied to ecalj/MKbackup/. 
    CAUTION: this overwirte old ones.
>git checkout -f             
     CAUTION!!!: this delete your changes in ecalj/.
     This recover files controlled by git to the original which was just downloaded.
>git pull                    
    This takes all new changes.
>./mrestore                  
    Look into this script before you use this.
    This copy make.inc* and MAKEINC/* back to original directory.

I think it is recommended to use 
>gitk --all 
and read this document 
README to check what is added recently. Difference can be easily taken,
e.g. by >git diff d2281:README 81d27:README (here d2281 and 81d27 are
top several digits of version id). 
>git show 81d27:README is also useful.

After ./mrestore, following instruction of the above installation.
Probably, you don't need to make cleanall (this delete all binaries).



###### Documents of ecalj #####################
We have three documents.

1. GetStarted:
ecalj/Document/Manual/EcaljGetstarted.pdf
Almost written OK.
It gives minimum instruction of ecalj.

2. Usage:
ecalj/Document/Manual/EcaljUsage.pdf
Not yet completed.

3. Details:
Two papers (but not yet submitted) are
  ecalj/Document/Manual/pmttheory17.pdf (for PMT)
  ecalj/Document/Manual/pmtqsgw13.pdf   (for PMT-QSGW)
A little extended versions in japanese are
ecalj/Document/Manual/ecalj_pmttheory17j.pdf (for PMT)
ecalj/Document/Manual/ecalj_pmqsgw13j.pdf   (for PMT-QSGW)
We will unify this...


#######  Usage minimum. (e.g, PMT-QSGW(gwsc) for si)  ###################
Read ecalj/Document/Manual/EcaljGetstarted.pdf
Here is very minimum.
-------------------------------------------
(1) Write structure file ctrls.si by hand 
    (you can have ctrls from POSCAR(VASP) with vasp2ctrl in
    ecalj/StructureTool/.)
(2) conver ctrls.si to ctrl.si by ctrlgen2.py si --nk=6 
   (without argument, it shows help). 
   Then you have default ctrl.si (rename ctrlgen2.ctr.si to ctrl.si). 
(3) Run "lmfa si" to prepare atom.

NOTE: If you like to skip them,  run ./job_materials.py Si at /home/takao/ecalj/MATERIALS.
 >cd Si
 >cp ../syml.si
 >job_band_nspin1 si
This shows you band by LDA.

(4) For PMT-QSGW, make GWinput.tmp by mkGWIN_v2 si.
    Copy GWinput.tmp as GWinput. (you supply three numbers for the
    command mkGIWN_V2.)
(5) Then run a script gwsc, e.g. "gwsc 2 si -np 3" 
    (2+1 iteration with 3 nodes).
(6) To continue calculation do "gwsc 5 si -np 3" again.
    (To start, you need ctrl.si rst.si QGpsi ESEAVR sigm.si)
    When you start from these files, 0th iteration is skipped
   ---thus we have just five iteration.
(7) For band, dos, and pdos plot, 
    we have scripts which almost automatically makes these plot in
    gnuplot. Thus easy to modify these plots at your desposal.
-------------------------------------------

###### PROCASR (VASP format) generator #########
PROCASR mode for lmf (not yet in lmf-MPIK)
Band weight decomposition. 
(Size of circles show the size of components. Superposed on band
plot). See ecalj/MATERIALS/MgO_PROCAR/README.
May19.2014



#####################################################
Usage problems, Q&A

1.Bandplot for FSMOMMETHOD/=0 
Even when you use FSMMOMMETHOD/=0 in GWinput for gwsc, 
yuo need to set FSMOMMETHOD=0 (or comment it out) when you run job_band_nspin2.
[If you run job_band_nspin2 with FSMOMMETHOD/=0, it make a shift 
 (adding bias magnetic field).]

2.Note that ctrlgenM1.py automatically set this for --systype=molecule.
   Then we have 
       TETRA=0
       N=-1  #Negative is the Fermi distribution function W= gives temperature.
       W=0.001 #W=0.001 corresponds to T=157K as shown in console
   In addiiton, FSMOM (n_up-n_down) is needed (FSMOMMETHOD=1)if we
   have magnetic moment.

3. core>evalence message.
   Ecore is grater than Evalence.
   For save, we do not allow this.
   Complare ECORE file and valence levels, shown in log file or
   console output.

4. If you see a error message from lmf (e.g., internally called in the gwsc script).;
  Exit -1 rdsigm: Bloch sum deviates more than allowed tolerance (tol=5e-6)
You have to enlarge RSRNG so that lmf finsh normally.
See FAQ at the bottom of http://titus.phy.qub.ac.uk/packages/LMTO/gw.html
E.g. try RSRNGE=8 for Ni...

5. Back ground charge and fractional Z.
   You can use fractional numbers for ATOM_Z, and also can set
   valence charge by BZ_ZBAK (I removed BZ_VAL).
   You see console out put, e.g,
     "Charges:  valence    19.80000   cores     8.00000   nucleii   -28.00000
        hom background       .20000   deviation from neutrality:      0.00000
   . This is a case with BZ_ZBAK=.2.

   NOTE: at the first iteration, Charges: shows such as
     Charges:  valence     8.00000   cores    20.00000   nucleii   -28.00000
      hom background     0.12300   deviation from neutrality: 0.12300
      because of the initial condition by superposition of atoms. It show
      deviation seems nonzero. But charge should be conserved from the
      next iteration.

6. Not converged. --->help
For example, if you try metal such as Bi2Sr2CuO6, it may fail at LDA/GGA level.
Then use ITER MIX=A2,b=.2. or something (.2 means it only mix 20% of output to give
new input for next iteration). Then I see convergence.

7. Use PZ or not.
   If spillout of core is not so small (more then 0.05 or something.),
   it is better to use PZ(lo). Treat the core as valecne.
   Bi4d is such a case. Maybe use PZ=0,0,4.9

8.Core treatment 
  See 10.1103/PhysRevB.76.165106 (Eq.35 and after).
  Now I usually not use CORE2 (CORE1 only).

==========================================
9. Wanneir Branch now under developing (imported from T.Miyake's Wannier code and H.Kino's).
   A. make at ecalj/fpgw/Wannier/ directory, and do make, and make install. 
      (need to check Makefile first). You first have to install fpgw/exec/ in advance.
   B. Samples are at these directories. 
      MATERIALS/CuMLWFs (small samples),
      MATERIALS/CuMLWF/
      MATERIALS/CuMLWFs/
      MATERIALS/FeMLWF/      
      MATERIALS/NiOMLWF/
      MATERIALS/SrVO3MLWF/
   C. With GWinput and ctrl.*, run 
      >genMLWF
      at these directories.
      In GWinput, we supply settings to generate Wannier funcitons. (Sorry,not documentet yet..)
   D. After genMLWF, do
      >grep Wan lwmatK*
      then compare these with Result.grepWanlwmatK
      These are onsite effective interactions (diagonal part only shown).
      *.xsf are for plotting the Maximally localized Wannier funcitons.
Anyway, documentaion on Wannier is on the way half.
Time consuming part (and also the advantage) is for effective interaction in RPA.
Look into the shell script genMLWF; you can skip last part if you don't need the effective interaction.


######## MEMO for developers: ####################################
Real TIME and Memory usage command. (H.Kino). rev.jun23.2014
We set comment lines such as
----
!TIME0
  ... here lines of fortran codes ...
!TIME1 "foo bar"
----
in fortran files, e.g., in fpgw/main/hsfp0.sc.m.F.
This reports computational time at the end of output from each node.
(see stdout.{rankID}.* files).

For example, if we see a line (in stdout.*)
>timediff,id= 106 (foo_bar_____)    420.00 sec     4 times
, we used the CPU time 420 sec (roughly =4 x 105 sec) for
the lines between '!TIME0' and '!TIME1 "foo bar"'.

See fpgw/exec/makefile. At its bottom,
gawk replaces '!TIME*' with fortran codes (time_xxx.F are
generated automatically by this procedure).

--
NOTE: !TIME can be nested as
!TIME0
  ... code1 ...
!TIME0
  ... code2 ...
!TIME1 "foobar1"
!TIME1 "foobar2"

###################################
1.branch x0mpi_merge (6b5e3, Aug2013): 
contains a try to paralellize x0kf
(imaginary part of dielectric function) more. It just show a
strategy, not efficient yet.

2. With FSMOM, Efermi is not uniquely given in job_band_nspin2*.
It is given by a bndfp-bzwtsf-bzwsf L300 block
   if ((.not. lfill) .or. (metal .and. (nkp .eq. 1))) then
   (bisection method to determine a middle of LUMO and HOMO).
It can give some energy between LUMO and HOMO. 
Small changes of computational condition can give large change. 
But no problem.

3. Line length for fortran; Add .emacs the following three lines.
(add-hook 'fortran-mode-hook
	  '(lambda ()
	     (setq fortran-line-length 132)))

--------- end of file -----------------


===================================================
ecalj PDOS sigm_fbz is required.
(when cp sigm,rst,GWinput ->LDA-like result.
 Then cp sigm_fbz ->it fails.
 Need to make new directory, and copy rst,sigm_fbz.)
And how to check it. (whether 
===================================================