cgal/QP_solver/test/QP_solver

*******************************************************************************
IMPORTANT NOTE: Currently, test_solver.C does not run the nonstandard-form
with all pricing strategies. Once these pricing strategies are implemented for
nonstandard-form problems, you should fix test_solver.C (see the line
beginning with the comment "// temporary (todo): exit if pricing strategy is
different from FE") and remove this note.
*******************************************************************************

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 DERIVATIVES 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.)

If you do not want derivatives to be generated for a given master
MPS-file, add the comment "Derivatives: none", see for instance
test_solver_data/masters/additional/QRECIPE.mps.