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

REQUIREMENTS

1) GNU Scientific Library (http://www.gnu.org/software/gsl) development packages
   for your system (typically "gsl" and "gsl-devel").

2) ATLAS BLAS AND LAPACK (http://www.netlib.org/lapack). Usually included with GNU-Octave.

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.

USING ATLAS

$ ln -s /usr/lib/atlas/libblas.so.3.0 $HOME/lib/hssl-0.1/ghc-6.6.1/libcblas.so
$ ln -s /usr/lib/atlas/liblapack.so.3.0 $HOME/lib/hssl-0.1/ghc-6.6.1/liblapack.so

(More info in the tutorial, available from the web page of the project.)

TESTS

$ runhaskell examples/tests.hs

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 few 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.6.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

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 where 
   hssl has been installed: C:\Program Files\haskell\hss-0.1\ghc-6.6.1.
   They are needed to compile programs.
   These three dlls are also available from http://perception.inf.um.es/~aruiz/darcs/HSSL/dll1.zip

4) Copy the dlls at 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.

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: I get a syntax error when compiling LAPACK.hs in Windows with ghc-opts -O.
      Please change it to ghc-opts -O0 in hssl.cabal and build again.
      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.