
This directory contains the file needed for the build-in tests of the
abinit code (sequential version).

warning : DON'T change the files in the present directory

Copyright (C) 1998-2009 ABINIT group (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 .

_____________________________________________________________________

A set of five build-in tests exist in the abinis code.
These short tests should be used as frequently as possible
in the course of development or modification of the existing code.

1) Usage

In the main directory, type the command make
with one of the following keywords test1 , test2 , test3 or test4, like : 

make test1

The code (sequential version) will run automatically, and print
on screen different status files during the execution, 
followed by an automatic check of the exactness of 
the results obtained (total energy, eigenvalues, nuclei positions, 
forces and stresses). If everything is OK, the final output 
on screen is rather short :

  Status file, reporting on test            1

 OK for total energy 
 OK for eigenvalues 
 OK for nuclei positions 
 OK for forces 
 OK for stresses 

If there is a problem, the final output on screen will describe briefly
the error. 

The computed values are converged up to some level of convergence.
The code takes into account predefined levels of convergence,
in such a way that this suite of test should still be valid if
the algorithm in the code is modified, even profoundly.
Indeed, only the final result is checked, not the intermediate results.
Unlike the basic algorithm, the parameters of the calculation 
(ecut, ngfft, nkpt ...) 
should not change for this suite of test to be valid.

2) Description of the tests

test1 :   H2 molecule, determination of the H-H distance by the Broyden
          algorithm. Less than 18 sec on a Pentium Pro 200MHz

test2 :   Si cristal, self-consistent calculation
          Less than 24 sec on a Pentium Pro 200 MHz

test3 :   HBe molecule, spin-polarized, determination of forces
          Less than 30 sec on a Pentium Pro 200 MHz

test4 :   Yb cristal, self-consistent
          Less than 42 sec on a Pentium Pro 200 MHz

test5 :   Al FCC cristal, self-consistent calculation
          Less than 24 sec on a Pentium Pro 200 MHz

These tests are set up such that they exercise different, complementary
features of the code. Still, it is NOT a complete suite of tests.
For this, see the fast directory.
Also, except for test5, the physical content is weak, 
because the cut-off energies are unreasonably low.
With respect of testing the correctness of the code, 
the main deficiency of these 5 tests comes from never testing
reading and writing files (wavefunctions, density or potentials). 
Consequently, the specific non-self-consistent features are not tested,
as well as the nstep=0 case. Also, the molecular dynamics 
option (ionmov=1) is not tested.

The following table presents the way a few different features are exercised
through this short suite of tests, specially designed to run very fast


         t1    t2    t3    t4    t5

ntype    1     1     2     1     1    t3: more than one type of atom
natom    2     2     2     1     1    one or 2 atoms
psps     GTH   GTH   GTH   TM    GTH  test the 2 formats of pseudopotentials
nonlocal -     s,p   -     p,d,f s,p  local potential for t1, and t3
                                      non-local, up to f for the others 
nsppol   1     1     2     1     1    t3: spin-polarized calculation
nband    1     4     3+2   8     4    t3: occopt=2; t4, up to 8 bands
nkpt     1     2     1     2     10   different numbers of k-points
    (not gamma)   (gamma)
mkmem    1     1     1     2     10   t2: out of core; t4 & t5: in core
nsym     8     48    1     48    24   t2: non-symmorphic set; 
                                      t4 & t5: symmorphic set; t3: no symm.
cell     tetr. FCC   tetr. FCC   FCC  exercice orthogonal and non-orth. cells
intxc    0     1     0     1     0    the xc interpolation is on or off
ionmov   2     0     0     0     0    t1: Broyden optimization
occopt   0     0     2     0     4    t5: metallic occupation numbers


3) Related information

The files that define the suite of tests are contained in the built-in 
directory. These should NOT be changed, even for debugging. It is
much better to do the debugging in the fast directory, or to duplicate
the built-in directory, and not to rely on the "make" mechanism for
the debugging.

