documentation

6 files changed, 77 insertions, 37 deletions

diff --git a/README b/README
index e2b7aa3..f117a26 100644
--- a/README
+++ b/README
@@ -1,3 +1,6 @@
+A simple scientific library for Haskell
+---------------------------------------
+
 REQUIREMENTS
 
 1) GNU Scientific Library (http://www.gnu.org/software/gsl) development packages
@@ -7,19 +10,20 @@ REQUIREMENTS
 
 INSTALLATION
 
-(More detailed information is included in the "tutorial",
-available in the web page of the project.)
-
 $ 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
@@ -46,10 +50,12 @@ Prelude Numeric.LinearAlgebra> u <> d <> trans v
 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 \C{hssl} (a simple scientific library for Haskell) because only
+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
@@ -57,35 +63,18 @@ which admits both C and Fortran matrices and avoids many transposes.
 
 There are only minor API changes:
 
-- the matrix product operator \C{(<>)} is now overloaded only for matrix-matrix,
-matrix-vector and vector-matrix, with the same base type. The dot product and the scaling
-of vectors or matrices is now denoted by `dot` and `scale`. Conversions from real to
-complex objects must be explicit.
+- 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.
+  ident or constant are now polymorphic.
 
-- Runtime errors produced by GSL or LAPACK can be handled using \C{Control.Exeception.catch}.
+- Runtime errors produced by GSL or LAPACK can be handled using Control.Exeception.catch.
 
 Old GSLHaskell code will work with small modifications.
 
-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.
-
 INSTALLATION ON WINDOWS
 
 1) Download the developer files gsl-1.8-lib.zip from
@@ -109,3 +98,20 @@ INSTALLATION ON WINDOWS
 Unfortunately the lapack dll supplied by the R system does not include zgels_ and zgelss_,
 so the functions depending on them (linearSolveLS and linearSolveSVD for complex data)
 will produce a "non supported" runtime error.
+
+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.
diff --git a/examples/speed.hs b/examples/speed.hs
index a937f31..865e3e1 100644
--- a/examples/speed.hs
+++ b/examples/speed.hs
@@ -1,3 +1,23 @@
+{- speed tests
+
+$ ghc --make -O speed
+In my machine:
+$ ./speed 5 100000 1
+(3><3)
+ [ -1.7877285611885504e-2, 0.0,    -0.9998401885597121
+ ,                    0.0, 1.0,                    0.0
+ ,     0.9998401885597168, 0.0, -1.7877285611891697e-2 ]
+0.29 CPU seconds
+
+GNU-Octave:
+./speed.m
+  -0.017877255967426   0.000000000000000  -0.999840189089781
+   0.000000000000000   1.000000000000000   0.000000000000000
+   0.999840189089763   0.000000000000000  -0.017877255967417
+9.69 seconds
+
+-}
+
 import Numeric.LinearAlgebra
 import System
 import Data.List(foldl1')
diff --git a/examples/speed.m b/examples/speed.m
index 10dbf78..2f41665 100644
--- a/examples/speed.m
+++ b/examples/speed.m
@@ -12,9 +12,10 @@ end
 t0=time();
 x = linspace(0,1,1E5);
 ac = eye(3);
-for a=x
-    ac = rot(a)*ac;
+for a = x
+    ac = ac*rot(a);
 end
 
+format long
 disp(ac);
-disp(time()-t0)
+printf("%.2f seconds\n",time()-t0)
diff --git a/examples/tests.hs b/examples/tests.hs
index b44d140..9388671 100644
--- a/examples/tests.hs
+++ b/examples/tests.hs
@@ -12,6 +12,7 @@ import qualified Numeric.GSL.Matrix as GSL
 import Test.QuickCheck hiding (test)
 import Test.HUnit hiding ((~:),test)
 import System.Random(randomRs,mkStdGen)
+import System.Info
 
 type RM = Matrix Double
 type CM = Matrix (Complex Double)
@@ -323,7 +324,9 @@ tests = do
     quickCheck (invTest . sqm   :: SqM (Complex Double) -> Bool)
     putStrLn "--------- pinv ------"
     quickCheck (pinvTest . sqm   :: SqM Double -> Bool)
-    quickCheck (pinvTest . sqm   :: SqM (Complex Double) -> Bool)
+    if os == "mingw32"
+        then putStrLn "complex pinvTest skipped in this OS"
+        else quickCheck (pinvTest . sqm   :: SqM (Complex Double) -> Bool)
     putStrLn "--------- chol ------"
     runTestTT $ TestList
      [ test "cholR" cholRTest
diff --git a/lib/Data/Packed/Internal/Matrix.hs b/lib/Data/Packed/Internal/Matrix.hs
index 77906dc..605a6f3 100644
--- a/lib/Data/Packed/Internal/Matrix.hs
+++ b/lib/Data/Packed/Internal/Matrix.hs
@@ -48,12 +48,14 @@ import Data.List(transpose)
 - we could carry both the matrix and its (lazily computed) transpose.
   This may save some transpositions, but it is necessary to keep track of the
   data which is actually computed to be used by functions like the matrix product
-  which admit both orders. Therefore, maybe it is better to have something like
-  viewC and viewF, which may actually perform a transpose if required.
+  which admit both orders.
 
 - but if we need the transposed data and it is not in the structure, we must make
-  sure that we touch the same foreignptr that is used in the computation. Access
-  to such pointer cannot be made by creating a new vector.
+  sure that we touch the same foreignptr that is used in the computation.
+
+- a reasonable solution is using two constructors for a matrix. Transposition just
+  "flips" the constructor. Actual data transposition is not done if followed by a
+  matrix product or another transpose.
 
 -}
 
@@ -66,7 +68,7 @@ data Matrix t = MC { rows :: Int, cols :: Int, cdat :: Vector t, fdat :: Vector
 -- MC: preferred by C, fdat may require a transposition
 -- MF: preferred by LAPACK, cdat may require a transposition
 
--- | matrix transpose
+-- | Matrix transpose.
 trans :: Matrix t -> Matrix t
 trans MC {rows = r, cols = c, cdat = d, fdat = dt } = MF {rows = c, cols = r, fdat = d, cdat = dt }
 trans MF {rows = r, cols = c, fdat = d, cdat = dt } = MC {rows = c, cols = r, cdat = d, fdat = dt }
diff --git a/lib/Data/Packed/Matrix.hs b/lib/Data/Packed/Matrix.hs
index e94d038..a705975 100644
--- a/lib/Data/Packed/Matrix.hs
+++ b/lib/Data/Packed/Matrix.hs
@@ -193,6 +193,14 @@ dsp' sep as = unlines . map unwords' $ transpose mtp where
     pad n str = replicate (n - length str) ' ' ++ str
     unwords' = concat . intersperse sep
 
+{- | Creates a string from a matrix given a separator and a function to show each entry. Using
+this function the user can easily define any desired display function:
+
+@import Text.Printf(printf)@
+
+@disp = putStrLn . format \"  \" (printf \"%.2f\")@
+
+-}
 format :: (Field t) => String -> (t -> String) -> Matrix t -> String
 format sep f m = dsp' sep . map (map f) . toLists $ m