##### Copyright (C) 1997-2009 ABINIT group (DCA, XG)
This file is distributed under the terms of the GNU General Public License, see ~abinit/COPYING or http://www.gnu.org/copyleft/gpl.txt .
For the initials of contributors, see ~abinit/doc/developers/contributors.txt .

    This directory, fast, contains tests which exercise parts
    of the ABINIT package.

    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 minimal, i.e.
    the calculations are underconverged.

    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 "fast" (for Tests_fast) and either
       the index of a test case, i.e.
       (run-standard-tests name_of_machine fast 22) >& log_file
       or a whole range of test cases (two indices), i.e.
       (run-standard-tests name_of_machine fast 02 08) >& log_file
       or, if you want to run all the test cases of this directory
       (run-standard-tests name_of_machine fast) >& log_file
       This will send stdout and stderr to log_file.
       The script 'run-standard-tests', will create a subdirectory of
       ~abinit/tests/fast, 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 "ibmtest" subdirectory output files,
       and a 'difnew.xxx' file, automatically created by making
       a 'diff' with respect to the "Refs" subdirectory output files.
       The first one contains output files from the Plane_Wave code,
       while the second one 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 'difnew.xxx' file to understand what was going wrong.

    The comparison of intermediate results between the ABINIT code
    and the Plane_Wave code needs some caution :
    - the basic algorithm is different, so that the speed of convergence
       per iteration (istep=1 ... nstep) can be different, and also
       the meaning of residm has changed. Usually, for the same level
       of convergence if the total energy, the residual in ABINIT is
       much lower than in Plane_Wave. This means that wftol has to be
       initialized to a much lower value in ABINIT.
    - the mean of the potential is sometimes not the same in the two
       codes. This means that, although the converged total energy must
       be the same, the absolute values of the converged eigenvalues
       can be different. Only differences in eigenvalues are meaningful.
    - with respect to speed, usually the CPU time per iteration step is
       lower by a factor of 2 in ABINIT, but this is usually compensated
       by an increase of the number of step needed to reach the
       same convergence in the total energy (usually not a factor of 2, though).
       However, the initialisation
       of pseudopotential is much faster in the ABINIT code, so that
       altogether, these tests are much faster with ABINIT.
    - in the spin-polarized case, the definition of zeta is slightly
       changed on the ABINIT coded, and scaled by a factor (1.0d0-1.0d-6),
       in order divergences for fully spin-polarized systems. This will affect
       total energies at the level of 1 microHartree or so.

    **********

    Test cases:

    01. Single H atom in box.  Uses local psp, which makes initialization
        time much shorter.  This calculation is iterated to convergence.
        This test case is a good choice for running alone just to get
        something working fast.

    02. H2 diatomic molecule, static, to check accurate forces.

    03. 2 special k point Si in 2-atom diamond unit cell.  Uses symmetry.
        mkmem=mkpt, mffmem=1 ("in core" solution),
        This calculation is also iterated to convergence.  ecut too small.
        Uses original Teter extended norm conserving psp 14si.psp.

    04. Same as case03, but with mkmem = 0, and mffmem=0 (out-of-core).

    05. Same as 03 but run with newer Troullier-Martins psp
        with core density 14si.pspnc.  Start from wf.03 and run irdwfk=1.
        Also iterated to convergence.

    06. Restart 05 with wf.05 (irdwfk=1).  Instant convergence.

    07. Restart 05 again, but use ALL 48 cubic symmetries (the above tests
        don't bother with the nonsymmorphic ones) to test nonsymmorphic
        symmetrization.

    08. Run with frozen wf (wf.05 again)--irdwfk=1, nstep=0.  Use same job
        to produce density file t08o_DEN using prtden=1.  Note that energy
        and stresses should agree among 05, 06, and 08.  Slightly different
        result for stress in case 06 shows evidence of the sensitivity of
        stress to convergence.

    09. Run non-scf (iscf=-2) on 2 special points by reading t5o_DEN.
        Eigenvalues should now agree among 05, 06, and 08, except that 08 will
        include some unoccupied bands.

    10. Run newsp to get crudely interpolated starting wf from 2 special
        points (wf.09) to band structure points Gamma, X, and L.
        Call resulting wf file wf.10.

    11. Run non-scf (iscf=-2) for Gamma, X, L band structure for Si.

    12. Same as 11 but with mkmem = 0, mffmem=0 (out-of-core).

    13. Raise ecut slightly to make boxcut<2 (keeping ng same);
        get new starting wf by running newsp using wf.05 and t14.in
        Call new starting wf wf.13.

    14. Same as 05 but with ecut raised, reading wf.13 to start.
        Tests boxcut<2.

    15. Modify acell slightly (in.16) and run newsp again to get starting wf.
        Call new starting wf wf.15.

    16. Same as 03 but with slightly larger acell.  Again has boxcut<2.

    17. Si2 molecule, static, spin-polarized.  Write t17o_DEN (prtden=1).

    18. Test newsp by slightly enlarging box of t17.in.  Make starting wf
        for t19.in

    19. Re-run 17 but in slightly larger box, same ecut, larger ng.
        (Box is still too small for proper model of Si2.)

    20. Conduct relaxation of molecule starting from wf.19, using ionmov=2
        (Broyden method).

    21. Conduct same relaxation but use ionmov=1 (molecular dynamics).

    22. Run newsp to get starting wf for two k pts from wf.17.  Aim
        at t23.in.  Also tests variable band number in newsp.

    23. Compute a few unoccupied state eigenvalues for case 17, at two
        k points.
        Also checks reading of a density file (t17o_DEN) which was created with
        a different number of k points (perfectly ok).
        (Shows inadequacy of this box for Si2 molecule--note enormous
         dispersion in eigenvalues from k=0 to BZ boundary.)

    24. Test an ionic system: KCl.  2 sp k-points.

    25. Same as 24 but with mkmem = 0, mffmem=0.

    26. Test an f-electron system: fcc Yb (Z=70).  2 sp

    27. 8-atom Si cube to set up brdmin and MD runs with natfix.
        Output also DEN, POT and GEO files

    28. brdmin with natfix.
        Output also DEN, POT and GEO files

    29. move with natfix.
        Output also GEO files

    30. This test is due to Z. Levine. It is a run on Si with the bond center
        at the origin. Also write density and potential with prtden=9 and prtpot=2 .