
This is an interface to GSL (GNU scientific library), for the
Objective Caml langage. 


* REQUIREMENTS
- gsl >= 1.8
- ocaml >= 3.07
- awk and GNU make
- gcc or MSVC

The platform must not need to align doubles on double-word addresses,
i.e. ARCH_ALIGN_DOUBLE must be undefined in <caml/config.h>


* BUILDING & INSTALLING
- have a look at the variables in Makefile and gcc.mak/msvc.mak.
  comment out DYNAMIC_LINKING if it isn't supported on your platform.
- make
- (optional) make install INSTALLDIR=/absolute/path/to/installdir 
        or : make install-findlib

to link :
  ocamlopt -I gsldir bigarray.cmxa gsl.cmxa my_prog.ml
or :
  ocamlc -I gsldir -dllpath gsldir bigarray.cma gsl.cma my_prog.ml


* CHANGES
in 0.5.2
  - fix Gsl_sf.legendre_array_size
in 0.5.1
  - fix wrong declaration of externals in gsl_wavelet (Will M. Farr)
  - rewrite the blurb about callbacks raising exceptions (see below)
  - drop the mode argument Gsl_cheb.eval ("not for casual use")
  - fix GC bug in Gsl_cheb
in 0.5.0
  - sync with GSL 1.8
    - fix Gsl_cdf
    - wrap new functions: 
       gsl_multifit_linear_est, gsl_linalg_cholesky_decomp_unit,
       gsl_ran_gamma_mt, gsl_ran_gaussian_ziggurat, 
       gsl_sf_debye_5, gsl_sf_debye_6
  - sync with GSL 1.7
    - add Gsl_randist.binomial_knuth, add Gsl_multifit._linear_svd
in 0.4.1
  - make several record types 'private'. This disallows building bogus values
    that could crash the program.
  - remove several unsafe manual memory-management functions from
    module signatures
  - added Associated Legendre Polynomials and Spherical Harmonics in
    Gsl_sf (Will M. Farr)
  - fixed the type Gsl_fft.Complex.direction (Joe Shirron)
  - fixed the type of Gsl_randist.negative_binomial and negative_binomial_pdf 
    (Martin Willensdorfer)

in 0.4.0
  - sync with GSL 1.6
    - new module Gsl_wavelet for DWT
    - new module Gsl_sort
    - in Gsl_linalg, support for LQ and P^T LQ decompositions
    - add a mode argument in Gsl_cheb.eval
    - add RK2SIMP in Gsl_odeiv.step_kind
    - a couple of other small additions
  - bugfix for functions in Gsl_sf returning a result_e10
  - better support for Cygwin (James Scott, Lexifi)

in 0.3.5
  - improve build system a bit so that it works better on cygwin 
    (thanks to Brian Wilfley)
  - fix bugs in Gsl_odeiv (thanks to Will M. Farr)

in 0.3.4
  - fix a GC bug in the error handler, simplify exception raising code
  - add Qrng.dimension and Qrng.sample

in 0.3.3
  - report an error when building on a platform with ARCH_ALIGN_DOUBLE
    defined
  - findlib support
	 
in 0.3.2
  - complex functions (contributed by Paul Pelzl)

in 0.3.1 :
  - bugfix in Gsl_interp.eval_array
  - mlgsl_ieee.c now compiles with gcc 2.9x
  - build system improvements

in 0.3.0 :
  - sync with GSL 1.4
    - new module Gsl_cdf for cumulative distributions
    - new function Gsl_randist.binomial_tpe
  - compiles with MSVC (contributed by Lexifi)
  - memory bugfix in adaptative integration routines
  - bugfix in Gsl_ieee.set_mode, added FPU status word querying
  - changed arguments order in Gsl_matrix.transpose :
      first arg is destination, second is source

in 0.2.2 :
  - sync with GSL 1.3
    - new multidimensional minimizer (Nelder Mead Simplex algorithm)
    - new random distributions : Dirichlet and multinomial
    - new function Gsl_math.fcmp for approximate floating point values
    comparisons
  - fixed some potential problems with the GC

in 0.2.1 :
  - Gsl_linalg.matmult is now Gsl_linalg.matmult
  - Gsl_matrix.mul is now Gsl_matrix.mul_elements (same for
  Gsl_matrix.div)
  - vector/matrix macros work with gcc 2.9x (old_gcc target
  in Makefile)

in 0.2 :
  - rewrote the vector/matrix modules to add single precision
  bigarrays and complex values
  - added complex functions in Gsl_linalg and Gsl_eigen
  - added Ordinary Differential Equations
  - added Simulated Annealing
  - added Statistics and Histograms

in 0.1.1 :
  - fixed install target in Makefile
  - fixed several C stub function names
  - fixed a bug in ext_quot in quot.ml


WARNING : the code is not heavily tested !


* DOCUMENTATION
Check the GSL manual ! You can browse the module interfaces with the
ocamldoc-generated HTML files in the doc/ directory.


* VECTOR / MATRICES
There are several datatypes for handling vectors and matrices.

 - modules Gsl_vector, Gsl_vector.Single, Gsl_vector_complex,
   Gsl_vector_complex.Single and the corresponding matrix modules use
   bigarrays with single or double precisions real or complex values.

 - modules Gsl_vector_flat, Gsl_vector_complex_flat and the
   corresponding matrix modules use a record wrapping a regular caml
   float array. This is the equivalent of the gsl_vector and
   gsl_matrix structs in GSL.

 - module Gsl_vectmat defines a sum type with polymorphic variants
   that regroups these two representations. For instance :

     Gsl_vectmat.v_add (`V v1) (`VF v2)

   adds a vector in a caml array to a bigarray.

  - modules Gsl_blas Gsl_blas_flat and Gsl_blas_gen provide a (quite
    incomplete) interface to CBLAS for these types.

* ERROR HANDLING
Errors in GSL functions are reported as exceptions :
  Gsl_error.Gsl_exn (errno, msg)
You have to call Gsl_error.init () so as to initialize error
reporting; otherwise, the default GSL error handler is used and aborts
the program, leaving a core dump (not so helpful with caml).

If a callback (for minimizers, solvers, etc.) raises an exception,
ocamlgsl either return GSL_FAILURE or NaN to GSL, depending on the
type of callback. In either case the original caml exception is not
propagated. The GSL function will either return normally (but probably
with values containing NaNs somewhere) or raise a Gsl_exn exception.
