<html>
<head>
<title>libxc : README</title>
</head>
<body>

<h5>Copyright (C) 2006-2012 ABINIT group (YP)
<br>This file is distributed under the terms of the GNU General Public License, see
~abinit/COPYING or <a href="http://www.gnu.org/copyleft/gpl.txt">
http://www.gnu.org/copyleft/gpl.txt </a>.
<br> For the initials of contributors, see ~abinit/doc/developers/contributors.txt .
</h5>

<pre>

This directory, libxc, contains tests which exercise parts 
of the ABINIT package, related to the use of the libXC library.
This file gives first a very brief description
of the tests, then a much longer one.

These tests are designed primarily to exercise parts of the code
quickly, NOT necessarily to give physically sensible results.
For tests of correctness, see directory physics (under development).
For greater speed, some tests are not run to full convergence.
Also the quality parameters (especially ecut) are sometimes minimal, i.e.
the calculations are underconverged.

A classification of the tests is provided now. Later, each test is described
in more detail, with accompanying notes and references (some of the notes
might have to be updated, due to the small possible drift related to improvement
of the accuracy of the code).

Tests 1 to 20 examine different exchange-correlation functionals from
the ETSF exchange-correlation library, concerning XC energies and XC potentials. 
For the hybrid functionals, see tests 41 and beyond

Tests 21 to 40 examine different exchange-correlation functionals from
the ETSF exchange-correlation library, concerning XC kernels (second derivatives of the energy),
e.g. for response functions.

Tests 41 and beyond, to examine hybrid functionals (those that include a fraction of Fock exchange,
possibly screened).


**********

To run these tests, do the following:

0. Be sure that the perl script "run-standard-tests", in the main directory,
   has been generated from the primitive file "run-standard-tests.pl",
   thanks to the command "make perl"
   issued in ~abinit (see the installation notes on the Web).

1. Submit the "run-standard-tests" script, specifying a machine, and
   the keyword "libxc" (for Tests_libxc) and either
   the index of a test case, i.e.
   (run-standard-tests name_of_machine libxc 22) >& log_file
   or a whole range of test cases (two indices), i.e.
   (run-standard-tests name_of_machine libxc 02 08) >& log_file
   or, if you want to run all the test cases of this directory
   (run-standard-tests name_of_machine libxc) >& log_file
   This will send stdout and stderr to log_file. 
   The script 'run-standard-tests', will create a subdirectory of ~abinit/tests/libxc,
   with the name_of_machine and the
   date, where all the results will be placed.

2. In that directory, you will find for each test case that you have
   run, a log file (with the name of the test case), an output
   file, but also a 'diff.xxx' file, automatically created by making
   a 'diff' with respect to the "Refs" subdirectory output files.
   It contains output files from a recent version of the ABINIT code.
   There may be large differences in timing but there should only
   be minor differences in the output of physical quantities.

3. There is also a global report file, generated by the use of the
   fldiff script. Its name is fldiff.report . See the last
   version of the  ~abinit/doc/install_notes/install** file
   in the Infos directory for information about the use of this file.
   This file is the most convenient for a quick look at the correctness
   of results. When the results are not correct, one has often to
   rely on the 'diff.xxx' file to understand what was going wrong.

**********

Test cases:

00. Isolated Bismuth atom
    Very quick built-in test, to check that LibXC is installed.

01. Isolated Helium atom
    Compare the results using the native XC library and the
    corresponding ones of LibXC, in the non-spin-polarized case :
    5 LDAs (Teter93, Perdew-Zunger, Wigner, Hedin-Ludqvist, PW92)
    7 GGAs (PBE, RPBE, HCTH93, HCTH120, HCTH147, HCTH407, WuCohen)
    Results are excellent (better than 10 microHa).

02. Isolated Bismuth atom
    Compare the results using the native XC library and the
    corresponding ones of LibXC, in the spin-polarized case :
    2 LDAs (Teter93, PW92)
    7 GGAs (PBE, RPBE, HCTH93, HCTH120, HCTH147, HCTH407, WuCohen)
    Results are excellent (better than 10 microHa), except for Wu Cohen (must be a bug somewhere).

03. Isolated Oxygen atom
    Test a few functionals for which HGH pseudopotentials are available (from M. Krack),
    that are present also in the lib XC, but not in the native ABINIT set of functionals.

04. Isolated Helium atom
    Test functionals from libXC that were present in ABINITv5 (LDAs and GGAs). 
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). Less than 15 secs to test 45 functionals ...

05. Isolated Bismuth atom
    Test functionals from libXC that were present in ABINITv5 (LDAs and GGAs). 
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). Less than 20 secs to test 45 functionals ...

06. Isolated Helium atom
    Test functionals from libXC that have been added in ABINITv6 or were untested in ABINITv5 (LDAs and GGAs). 
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). Less than 15 secs to test 22 functionals ...

07. Isolated Bismuth atom
    Test functionals from libXC that have been added in ABINITv6 or were untested in ABINITv5 (LDAs and GGAs).
    Spin-polarized case.
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). Less than 20 secs to test 22 functionals ...

08. Isolated Carbon atom
    Test the Becke-Johnson mGGA functional, generating directly XC potentials. 
    Convergence parameters are quite high, and the test is reasonably portable.
    Test provided by Micael Oliveira.

09. Diamond
    Test the mGGA functional from Tran and Blaha (correction to Becke-Johnson).

10. Stishovite (a polymorph of SiO2)
    Test PBEsol in the PAW formalism, using PAW datasets created with atompaw linked with libxc.
    Note that the value of ixc is not present in the input file, but it is present in the ATOMPAW dataset (pspxc = -116133)
    Test provided by J. Zwanziger

11. Isolated Helium atom
    Test energy mGGA functionals from libXC.
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). 

12. Isolated Bismuth atom
    Test energy mGGA functionals from libXC
    Spin-polarized case.
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). 

13. Isolated Carbon atom
    Test the mGGA functionals generating directly XC potentials.
    Similar to test 08, but with smaller acell and ecut.
    Without the use of al "large" xc_denpos, Tran-Blaha is hard to converge. Hypothesis : there is a strong non-linear
    region, preventing the Anderson method to work effectively.
    Note that iscf=7 does not allow to converge with the default xc_denpos !
    By contrast, things are much better behaved with xc_denpos on the order of 1.0e-7 .

14. Silicon:
    Calculation of GW corrections (one-shot with PPM and QPSCGW) starting from one metaGGA functional
    (Tran and Blaha 2009). Test of the variables cd_use_tangrid, cd_max_freq, cd_halfway_freq and
    cd_subset_freq. Datasets 9 and 10 prepares two screening files to be merged in test 15.
    (the pseudopotential used has been made with the becke-johnson exchange-correlation and without
    non linear core corrections)
    Test contributed by D. Waroquiers and M. Stankovski

15. Test of mrgscr utility:
    Merging of the two screening files from datasets 9 and 10 of test 14.
    Test contributed by D. Waroquiers and M. Stankovski

16. Silicon:
    Sigma calculation using the merged screening file of test 15 and kss file of test 14. The results
    obtained should be exactly the same as the ones obtained in dataset 6 of test 14.
    (the pseudopotential used has been made with the becke-johnson exchange-correlation and without
    non linear core corrections)
    Test contributed by D. Waroquiers and M. Stankovski

17. Isolated Helium atom
    Test functionals from libXC 1.1 that were untested before ABINIT v6.12 (libxc 1.0.0.1 was used).
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). Less than 15 secs to test 19 functionals ...
    
18. Isolated Bismuth atom
    Test functionals from libXC that were untested before ABINIT v6.12 (libxc 1.0.0.1 was used).
    Spin-polarized case.
    This is to check the portability for different platform.
    Extremely quick (nstep=1, nline=1). Less than 20 secs to test 19 functionals ...

19. Argon solid, experimental lattice parameter.
    Realistic parameters are used (ecut=20, ngkpt=2x2x2 shifted 4 times, but centered on Gamma).
    Test the mGGA functional from Tran and Blaha (correction to Becke-Johnson).
    The LDA gap is observed at Gamma : 8.071 eV, is in reasonable agreement with the gap from the TB paper PRL 102, 226401 (2009),
    where it is mentioned to be 8.16 eV.
    The mGGa gap is 14.688 eV. The TB paper mentions 13.91 eV. The experimental value is 14.20 eV.
    The reading of the kinetic energy density, to start a non-SCF calculation is not yet implemented,
    as of ABINITv6.12.0 .
    This test was used to examine the speed of the convergence in case of elongated cells, up to 16 atoms.
    The mGGA convergence was found to be similar to the LDA convergence.
    Also, test non-self-consistent mGGA calculation, with reading of the previously produced _DEN and _KDEN files.

21. Silicon
    Test the equivalence between the internal and LibXC implementations
    of various XC functionals for the response functions
    (thus, the XC kernel is also tested).
    The test includes 3 different functionals:
    1) Perdew-Zunger: ixc=2 and ixc=-001009
    2) PBE: ixc=11 and ixc=-101130
    3) Perdew-Wang92: ixc=7, ixc=-001012, and ixc=-001013
    The results for PBE and Perdew-Wang92 (ixc=-001013) are not equivalent
    unless some constants are changed in 56_xc/xcpbe.F90 by uncommenting
    some lines indicated by GMR.
    Note that the underlying FFT grid does not have the symmetry of the
    lattice.
    Test provided by G.-M. Rignanese

22. Silicon
    Test the equivalence between the internal and LibXC implementations
    of the Perdew-Zunger XC functionals for the response functions
    (thus, the XC kernel is also tested) in PAW.
    Test provided by G.-M. Rignanese

41. Diamond: hybrid functional calculation with the GW code
    Perturbative approach to the HSE06, PBE0, and B3LYP band gaps
    Test contributed by F. Bruneval
    (note : HSE06 and PBE0 tests temporarily disabled, waiting for the next version of the libxc)

42. Diamond: hybrid functional calculation with the GW code
    Self-consistent approach to the HSE06 band structure
    based on a unitary transform of a subset of LDA wavefunctions
    Test contributed by F. Bruneval
    (note : test temporarily disabled, waiting for the next version of the libxc)

</pre>
