PGSL version 3.0 readme.

Copyright (C) Benny Raphael  

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or  any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-------------------------------------------------------------------------

PGSL MATLAB Interface readme.

Copyright (C) Benny Raphael  

1.  You can compile the PGSL files in matlab using the command
mex pgslmex.c PGSL.c memory.c error.c
It is recommended to use the Compiler: Lcc C 2.4 which is set using the command
mex -setup 

2.  Write your objective function to be minimised in objective1.m

3.  Call PGSL by setting the bounds and precision of variables and other 
parameters in runpgsl.m

4.  Invoke PGSL from matlab like this:
runpgsl

I have noted that the PGSL MATLLAB interface is about 10 times slower than the 
pure C version.  I think it has something to do with the way Matlab passes parameters 
to C functions and the way it manages memory. I recommend that you directly use the
pure C version of PGSL

-------------------------------------------------------------------------

Changes from Version 3.

1.  Added 
srand(setup->randomSeed); 
at the beginning of the function findMinimum.  
Thanks to Prof. Neumeier for pointing this out.

2.  Added in sample.c to illustrate the use of precision
setup->axes[i]->axisPrecision = 1e-5;

Note: The axis precision makes a big difference to the time required to 
reach the threshold. Start with a low precision.  Do a few runs with
increasing precision and choose the best.  There is no simpler way to
fix the precision required.  You do not need to do this tuning if you
do not mind the number of evaluations taken.  PGSL will restart itself
once it has converged to a region below the specified precision.  So you
can keep it running indefinitely without manual restart.

--------------------------------------------------------------------------

Notes from Version 3.

Remember:  PGSL is more suitable for continuous variables with nonlinear 
objective functions and nonlinear constraints.  There is no point in using 
PGSL for linear programming!  The power of PGSL is in handling blackbox
objective functions and constraints.  If you have discrete unordered variables,
you get good results by calling PGSL repeatedly like in multistart methods


See also ConstraintSolver/README-ConstraintSolver.txt


PGSL algorithm was developed by me while working at
IMAC, EPFL.  All the code was also implemented by me. 
The code is not as clean as my usual C code because the
algorithm and the code evolved over a large number of trials
and errors over a period of about six months during 1998-1999.  
I would like to thank Prof. Ian Smith for employing
me at EPFL and for his help in writing the first PGSL journal paper published
in the journal of applied mathematics and computation.

- Benny Raphael


---------------------------------------------------------------------------

The main PGSL code is in PGSL.c.  PGSL.h is the header file.  
sample.c is a sample problem to illustrate the use.  

memory.c,  error.c and PGSL.c should be compiled with your files
to create an executable.  Using PGSL involves the following steps:

1.  Create an instance of struct ProblemSetup using the function
ProblemSetup_create

2.  Create axis corresponding to each variable using the function
PAxis_create (specifying the minimum and maximum values of each
variable).

3.  Writing your own objective function and storing its function
pointer in ProblemSetup

4.  Call PGSL using the function
findMinimum

5.  Writing the main function to perform the above operation


There is a Visual C++ 6.0 project for a sample application and for
the ConstraintSolver in the respective directories.  Look at those 
applications to understand the usage.
--------------------------------------------------------------------

Important changes in Version 3

- there is automatic restart when subdomain size becomes smaller than
the precision of the variables.  So you can specify a large value for 
NSDC and keep optimization running as long as you can wait.  NFC can 
be set to be 20*NumVars and should work fine for most problems.





