----------------------------------------------------------------------------------
                   R E G R E S S I O N   T E S T S
----------------------------------------------------------------------------------

INFORMATION ON CREATING NEW REGRESSION TESTS
----------------------------------------------------------------------------------

See the documentaion of how to run the regression tests by running:

   "python test_run.py -h"

To add a new regression test please provide:

   - input.xml (and all the files required by it)

   - test_settings.dat 
     This file specifies the driver_model and flags that will be used when running
     the driver to perform the regression test.
     For examples including the usage of option flags, please see:
         tests/NVE/NVE_1/harmonic_python/test_settings.dat
         tests/NVE/NVE_1/harmonic/test_settings.dat

     *Please note that the driver can be run with the same syntax when one
     creates the reference files for the regression tests.

     **Please note that in the case of different drivers one should start to
     describe the setup of each driver by specifying driver_model xxxx in the 
     first line
   
   - file_to_check.txt specifying the files serving as reference with their
     respective filenames

     the syntax of file_to_check.txt includes a two-line header, followed 
     by a list of files. each line contains the name of the reference file 
     (see below), the format (xyz, or numpy for files that can be read by
     numpy.loadtxt). Both are read as a 2D array, and one can optionally
     specify a list of columns that should be compared (this is useful e.g.
     to ignore noisy quantities). Each column entry should be 
     
     icol[,rtol,atol]

     where icol is an integer (0-based) index optionally followed by a 
     specification of rtol and atol tolerances, that correspond to the 
     parameters of numpy.allclose. 
    
     Alternatively, it is posible to speciy the same rtol and atol for all
     the columns (only numpy data for the moment) as
 
     all[,rtol,atol]

     For existing examples, please see:
	tests/INSTANTON/200K/files_to_check.txt  [standard case]
        tests/NEB/FIRE/zundel/files_to_check.txt [verbose case] 
        tests/NEB/DAMPED_BFGS/zundel/files_to_check.txt [super verbose case] 

   - reference files that are listed in the files_to_check.txt file. Currently,
     the available formats are .xyz and numpy-accessible which should be
     specified with the keywords 'xyz' and 'numpy'.

   - (For the moment) We assume a very specific syntax for the file names. 
     The reference file name should be the same as the output file name with the addition of 'ref_' at the beginning, example:

     reference file: ref_simulation.out
     output to be genererated from i-pi: simulation.out
   
   - Folder names terminating with '.NOAUTO' (e.g. 'PLUMED.NOAUTO') are ignored 
     when run without specifying the folder name explicitly. This is useful when the
     test requires an external program (e.g. PLUMED) that may not be available on
     the testing platform


Important: 

   The extension *.out appears in the .gitignore  file
   This means that the 'ref_simulation.out' file has to be added manually to your commit.
   You can do that by typing:

    "git add -f ref_simulation.out"


