A simple scientific library for Haskell
---------------------------------------

REQUIREMENTS

Development packages of:

1) GNU Scientific Library (http://www.gnu.org/software/gsl)

2) BLAS and LAPACK (http://www.netlib.org/lapack)

3) ATLAS (recommended) (http://math-atlas.sourceforge.net/)

For example, in Ubuntu Linux we need:

- libgsl0-dev
- refblas3-dev
- lapack3-dev
- atlas3-base-dev

You can also install an atlas version specifically tuned
for your machine (but see the TESTS section below).

The following packages are used for simple graphics:

- gnuplot
- imagemagick

GNU-Octave can be used to check if the results
obtained by this library are correct.

INSTALLATION

$ runhaskell Setup.lhs configure --prefix=$HOME
$ runhaskell Setup.lhs build
$ runhaskell Setup.lhs haddock
$ runhaskell Setup.lhs install --user

See below for installation on Windows.

TESTS

$ runhaskell examples/tests

Additional tests with big matrices (taking a few minutes):

$ runhaskell examples/tests --big

NOTE: On Ubuntu 6.06 LTS (Dapper) atlas3-sse2-dev (3.6.0-20)
produces segmentation faults when working with big matrices 
on compiled programs. To expose the problem:

$ cd examples
$ ghc --make -O tests.hs
$ ./tests --big

If this crashes, just uninstall atlas3-sse2 (atlas3-base-dev will be used).
Fortunately, atlas3-sse2-dev seems to work well on Ubuntu 7.10 Gutsy.

A similar problem was reported at:

http://article.gmane.org/gmane.linux.debian.devel.bugs.general/323065

EXAMPLES

$ ghci
Prelude> :m + Numeric.GSL
Prelude Numeric.GSL> let quad = integrateQNG 1E-10
Prelude Numeric.GSL> quad (^2) 0 1
(0.3333333333333333,3.700743415417188e-15)

Prelude Numeric.GSL> :m + Numeric.LinearAlgebra
Prelude Numeric.LinearAlgebra> let m = (2><3)[1,2,3,4,5,6::Double]
Prelude Numeric.LinearAlgebra> let (u,d,v) = full svd m
Prelude Numeric.LinearAlgebra> d
(2><3)
 [ 9.508032000695724,                0.0, 0.0
 ,               0.0, 0.7728696356734838, 0.0 ]
Prelude Numeric.LinearAlgebra> u <> d <> trans v
(2><3)
 [ 1.0000000000000004,               2.0, 3.0
 , 3.9999999999999996, 5.000000000000001, 6.0 ]
Prelude Numeric.GSL> :q
Leaving GHCi.

A number of illustrative programs are included in the examples folder.

CHANGES

This is a new version of GSLHaskell. The package is provisionally
called "hssl" (a simple scientific library for Haskell) because only
a small part of GSL is available and linear algebra is based on LAPACK.

The code has been extensively refactored. There is a new internal representation
which admits both C and Fortran matrices and avoids many transposes.

There are only minor API changes:

- The matrix product operator (<>) is now overloaded only for matrix-matrix,
  matrix-vector and vector-matrix, with the same base type. Dot product and scaling
  of vectors or matrices is now denoted by `dot` or (<.>) and `scale` or (.*).
  Conversions from real to complex objects must now be explicit.

- Most linear algebra functions admit both real and complex objects. Utilities such as
  ident or constant are now polymorphic.

- Runtime errors produced by GSL or LAPACK can be handled using Control.Exeception.catch.

Old GSLHaskell code will work with small modifications.

INSTALLATION ON WINDOWS

1) Download the developer files gsl-1.8-lib.zip from
   http://gnuwin32.sourceforge.net/packages/gsl.htm
   and copy the gsl folder (under include) to the include folder of ghc:
   C:\ghc\ghc.6.x.1\include

2) Install the package as usual from the command line in the hssl-0.1 folder:
       runhaskell Setup.lhs configure
       runhaskell Setup.lhs build
       runhaskell Setup.lhs install

2.5) If configure cannot find ld please see:
       http://article.gmane.org/gmane.comp.lang.haskell.cafe/32025

3) Copy libgsl.dll, libcblas.dll (from the binaries package gsl-1.8.bin.zip)
   and liblapack.dll (borrowed from the R system) to the folder in which
   hssl has been installed: C:\Program Files\haskell\hss-0.1\ghc-6.x.1.
   Rename libcblas.dll to libblas.dll.
   They are needed to compile programs.
   These three dlls are available from:
       http://perception.inf.um.es/~aruiz/darcs/HSSL/dll1.zip

4) Copy the dlls available from:
       http://perception.inf.um.es/~aruiz/darcs/HSSL/dll2.zip
   to the working directory or C:\windows\system
   They are required to run the programs and ghci.

5) run the tests

Unfortunately the lapack dll supplied by the R system does not include
zgels_, zgelss_, and zgees_, so the functions depending on them
(linearSolveLS, linearSolveSVD, and schur for complex data)
will produce a "non supported in this OS" runtime error.

If you find an alternative free and complete lapack.dll which works well
for this system please let me know.

NOTE: In windows the library is currently compiled with -O0 -fasm to avoid
      a C syntax error on clapack.h. You won't notice any appreciable difference
      in performance, but I will try to fix it asap.

ACKNOWLEDGEMENTS

I thank Henning Thielemann and all the people in the Haskell mailing lists for their help.

- Nico Mahlo discovered a bug in the eigendecomposition wrapper.

- Frederik Eaton discovered a bug in the design of the wrappers.

- Eric Kidd has created a wiki page explaining the installation on MacOS X:
  http://www.haskell.org/haskellwiki/GSLHaskell_on_MacOS_X

- Fawzi Mohamed discovered a portability bug in the lapack wrappers.

- Pedro E. López de Teruel fixed the interface to lapack.

- Antti Siira discovered a bug in the plotting functions.

- Paulo Tanimoto helped to fix the configuration of the required libraries.