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

<h5>Copyright (C) 1997-2007 ABINIT group (DCA, XG)
<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, 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 .
</pre>
