- added README documentation for the QP_solver testsuite

.gitattributes

@@ -1275,6 +1275,7 @@ Principal_component_analysis/demo/Principal_component_analysis/windows/3d/res/id
 Principal_component_analysis/demo/Principal_component_analysis/windows/3d/res/idb7.bmp -text svneol=unset#unset
 Principal_component_analysis/demo/Principal_component_analysis/windows/3d/res/idb8.bmp -text svneol=unset#unset
 QP_solver/include/CGAL/QP_solver/Bounds.C -text
+QP_solver/test/QP_solver/README -text
 QP_solver/test/QP_solver/create_test_solver_cin -text
 QP_solver/test/QP_solver/data_to_mps-double.C -text
 QP_solver/test/QP_solver/data_to_mps-double.cin -text

QP_solver/test/QP_solver/README

@@ -0,0 +1,106 @@
+This file describes the testsuite of package QP_solver.
+
+THE CGAL TESTSUITE
+
+What CGAL does for us is to compile and call every file in test/QP_solver that
+ends in ".C". If for such a file a corresponding ".cin" file exits, the latter
+is used as input. In our case, this means that the CGAL testsuite will
+automatically perform the following commands:
+
+  ./data_to_mps < data_to_mps.cin
+  ./data_to_mps-double < data_to_mps-double.cin
+  ./data_to_mps-rational < data_to_mps-rational.cin
+  ./master_mps_to_derivatives
+  ./test_MPS < test_MPS.cin
+  ./test_solver < test_solver.cin
+
+The main testing takes place in the last call: ./test_solver obtains from its
+input test_solver.cin a list of names of MPS-files (together with some
+additional parameters like a pricing strategy identifier and a verbosity
+level) and solves each of these files.  Consequently, in order to change or
+update the QP_solver testsuite, you have to change the contents of the file
+test_solver.cin and add additional MPS-files.  The sequel tells you how to do
+this.
+
+
+THE DIRECTORY STRUCTURE
+
+The MPS-files that are listed in test_solver.cin all reside in the directory
+test_solver_data/. If you take a closer look at this directory, you see that
+it contains two subdirectories, one called "masters" and one called
+"derivatives".  The idea behind this is that we put a new testcase into the
+masters/ directory and then use this "master MPS-file" to machine-generate
+some variants of this testcase; these variants (called "derivatives") are
+stored in the derivatives/ directory.  (The derivates are generated by the
+./master_mps_to_derivatives program, which in turn is called from
+./create_test_solver_cin, see below.)
+
+The derivatives/ directory is a flat directory of derived MPS-files. In
+contrast to this, the masters/ directory contains two subdirectories, cgal/
+and additional/, and only these subdirectories contain MPS-files.  This allows
+us to run two testsuites: the files in cgal/ constitute the subset of
+testcases that will be run by the CGAL testsuite.  Some additional testcases
+are contained in additional/; these might take long(er) to solve and are
+therefore not suited for the CGAL testsuite.
+
+
+THE ./create_test_solver_cin SCRIPT
+
+The script ./create_test_solver_cin serves two purposes: it produces the file
+test_solver.cin and generates from the master MPS-files the derivatives.  A
+call to the script should look like this:
+
+  ./create_test_solver_cin CGAL|all verbosity
+
+For instance, "./create_test_solver_cin CGAL 0" will collect all master
+MPS-files in test_solver_data/masters/cgal/ and for each of them make sure
+that all its derivatives are present (generating them if need be, see below);
+finally, it collects a list of all these master and derivative filenames and
+stores it in test_solver.cin.  The test_solver.cin file obtained in this way
+is what gets commited to the CGAL repository.
+
+In contrast to this, "./create_test_solver_cin all 0" collects all master
+MPS-files (i.e., all MPS-files in test_solver_data/masters/), generates (if
+needed) the derivatives and puts the list of the names of all these files into
+test_solver.cin. The resulting test_solver.cin should usually not be commited
+to the CGAL repository (it takes too long to run this suite); so you would run
+"./test_solver < test_solver.cin" only locally.
+
+The ./create_test_solver_cin script is what you need for the daily QP_solver
+work. If you add, for instance, a new testcase, "Test.mps", say, to
+test_solver_data/masters/cgal/, you would call "./create_test_solver_cin CGAL
+0" which will generate the derivatives ("Test_shifted.mps") of the newly added
+testcase (and, by the way, warn you that you should commit these files to the
+SVN repository) and construct the new test_solver.cin.
+
+As a remark: if you start off with a ".data"-file (i.e., with "Test.data")
+then you can solve this file by running
+
+  ./data_to_mps "Simple testcase" "Simple" < Test.data | ./test_MPS 0
+
+where the "0" argument is the verbosity (tune it up if need be).
+
+
+HOW THE DERIVATES ARE GENERATED
+
+The ./create_test_solver_cin script generates the derivates by calling the
+program ./master_mps_to_derivatives (compiling the latter first, if
+needed). The C++-program master_mps_to_derivatives.C reads in a master
+MPS-file and generates all the derivatives.  So if you want to add a new kind
+of derivates then you should look into master_mps_to_derivatives.C; you
+probably want to create a routine like create_shifted_instance().  Please do
+name derived instances with a suffix (like "_shifted"); the prefix MUST stay
+the same for the ./create_test_solver_cin script to work (see routine
+create_output_file() in master_mps_to_derivatives.C).
+
+Note that ./create_test_solver_cin is clever enough not to generate all
+derivatives anew when you call it.  Rather, it searches for all currently
+known derivatives of a given master MPS-file and looks whether the master is
+newer than any of the derivatives; if so, it regenerates the derivatives.  (In
+particular, this means that when you extend master_mps_to_derivatives.C to
+output a new kind of derivatives, you first need to touch the masters by doing
+
+  touch test_solver_data/masters/cgal/*
+  touch test_solver_data/masters/additional/*
+
+This will cause all derivatives to be generated anew.)