eplf/README.org

#+TITLE: EPLF
#+AUTHOR: Anthony Scemama
#+EMAIL: scemama@irsamc.ups-tlse.fr
#+date: 2020-06-02

Computes the Electron Pair Localization Function.

* Dependencies

    - Python3
    - resultsFile : https://gitlab.com/scemama/resultsFile
    - IRPF90 : http://irpf90.ups-tlse.fr
    - GFortran or Intel Fortran

 =resultsFile= and =IRPF90= can both be installed with pip.

  #+begin_src shell 
  python3 -m pip install resultsFile
  python3 -m pip install irpf90
  #+end_src
  
 =./configure= should detect suitable defaults for your system. You can 
  update the =make.config= file if you want. It is important to give the
  Fortran compiler the option to accept infinitely long lines (with
  gfortran, the option is =-ffree-line-length-none=).
  The =configure= script will also create a file =$HOME/.eplfrc= that you
  will need to source before running the program.

* Using EPLF

 GAMESS or Gaussian can be used to produce the wave function.
 With Gaussian, the following keywords are required:
 #+begin_example
 # GFPRINT pop=Full 6d 10f
 #+end_example

 Go into the =test= directory and execute the following commands to make
 a test run with an Gaussian output file.

 1. Run the =to_ezfio.py= script to convert the output file into an
    EZFIO directory containing all the data required for the
    computation:

    #+begin_src shell 
    to_ezfio.py c2h.out
    #+end_src
   
    The =c2h.out.ezfio= directory is produced.
   
 2. Edit the parameters by running =eplf_edit.py=
   
    #+begin_src shell 
    eplf_edit.py c2h.out.ezfio
    #+end_src

    The editor defined with the =$EDITOR= environment variable will open
    and let you change the parameters. To compute the density and the
    EPLF, just add an =X= character between the brackets next to =eplf=
    and =density=:

    #+begin_example
    ( ) density ->   (X) density
    ( ) eplf    ->   (X) eplf
    #+end_example

 3. Run the program to compute the data and save it in the EZFIO directory

    #+begin_src shell
    eplf c2h.out.ezfio
    #+end_src
    
    If the program is compiled with MPI, run

    #+begin_src shell
    mpirun eplf c2h.out.ezfio
    #+end_src

 4. Now you can convert the data into cube files as:
    #+begin_src shell 
    to_cube.py c2h.out.ezfio density
    to_cube.py c2h.out.ezfio eplf
    #+end_src

    The parameters of the grid can be changed by first clearing the
    data, and the updating the grid parameters. This can be done with
 =eplf_edit.py= by un-commenting the lines =clear(all)=
    and =edit(grid_parameters)=.

* References

  Scemama, A., Chaquin, P., Caffarel, M. (2004).
  "Electron pair localization function: A practical tool to visualize electron
  localization in molecules from quantum Monte Carlo data".
 /J. Chem. Phys./ *121* (4), 1725–1735.
  [[https://dx.doi.org/10.1063/1.1765098][doi:10.1063/1.1765098]]

  Scemama, A., Caffarel, M., Chaudret, R., & Piquemal, J.-P. (2011),
  "Electron Pair Localization Function (EPLF) for Density Functional
  Theory and ab Initio Wave Function-Based Methods: A New Tool for
  Chemical Interpretation".
 /J. Chem. Theory Comput./ *7* (3), 618–624.
  [[https://dx.doi.org/10.1021/ct1005938][doi:10.1021/ct1005938]]