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

<h5>Copyright (C) 1998-2009 ABINIT group (RC, 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, etsf_io, contains tests which exercise parts 
of the ABINIT package, especially those features acquired
during the development of the ETSF I/O 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).

Test 1: density output using ETSF I/O
Test 2: density input and KSS output using ETSF I/O
Tests 6 is related to the basic ground state computation with wavelets with ETSF output.
Tests 7 is related to the basic ground state computation with wavelets with ETSF restart.
Tests 8 is related to the basic ground state computation with wavelets with ETSF restart from datasets.

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 "etsf_io" (for Tests_etsf_io) and either
   the index of a test case, i.e.
   (run-standard-tests name_of_machine etsf_io 22) >& log_file
   or a whole range of test cases (two indices), i.e.
   (run-standard-tests name_of_machine etsf_io 02 08) >& log_file
   or, if you want to run all the test cases of this directory
   (run-standard-tests name_of_machine etsf_io) >& log_file
   This will send stdout and stderr to log_file. 
   The script 'run-standard-tests', will create a subdirectory of ~abinit/tests/etsf_io,
   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:

1.   Bulk water ice 1h, made-up with 8 water molecules.
     Density is exported using the ETSF I/O file format.
     Should be a nice system to look at with visualisation tools.

2.   Simple Li-F structure with KSS output. This is a two data set run,
     the first dataset being a ground state calculation and the second put
     nbandkss to non-null value to compute the Kohn-Sham structure. The KSS file
     is generated by ETSF-IO. The density of the first dataset also use ETSF-IO
     and dataset two is a good test for density restart.

3.   Read the density from test #1 and plot it along [1 1 1] direction using
     cut3d. This tests the reading part of cut3d with ETSF support.

4.   KSS file generation for silicon with a different number of bands in the KSS
     computation compared to ground-state.

6.   CO molecule to test the ETSF writing of wavefunctions (need compilation with
     --enable-bigdft).
   
7.   CO molecule to test the ETSF restart on wavefunctions, without wavefunction
      reformating (same parameters, still need compilation with --enable-bigdft).

8.   CO molecule to test the ETSF restart inside several datasets, also test the
     reformating of wavelets after wvl_hgrid changed (need compilation with
     --enable-bigdft).

9.   Ca atom in PAW. Test the output of density in PAW formalism.

10.  Read the density file from test #9 to be sure that values are correctly output.

</pre>
