minor doc fix, clean Plot

8 files changed, 61 insertions, 83 deletions

diff --git a/examples/parallel.hs b/examples/parallel.hs
index 435e367..c82114f 100644
--- a/examples/parallel.hs
+++ b/examples/parallel.hs
@@ -15,10 +15,10 @@ parMul p x y = fromBlocks [ inParallel ( map (x <>) ys ) ]
 main = do
     n <- (read . head) `fmap` getArgs
     let m = ident n :: Matrix Double
-    time $ print $ vectorMax $ takeDiag $ m <> m
-    time $ print $ vectorMax $ takeDiag $ parMul 2 m m
-    time $ print $ vectorMax $ takeDiag $ parMul 4 m m
-    time $ print $ vectorMax $ takeDiag $ parMul 8 m m
+    time $ print $ maxElement $ takeDiag $ m <> m
+    time $ print $ maxElement $ takeDiag $ parMul 2 m m
+    time $ print $ maxElement $ takeDiag $ parMul 4 m m
+    time $ print $ maxElement $ takeDiag $ parMul 8 m m
 
 time act = do
     t0 <- getClockTime
diff --git a/lib/Data/Packed.hs b/lib/Data/Packed.hs
index bfc2d8b..b8bec8a 100644
--- a/lib/Data/Packed.hs
+++ b/lib/Data/Packed.hs
@@ -1,14 +1,14 @@
 -----------------------------------------------------------------------------
 {- |
 Module      :  Data.Packed
-Copyright   :  (c) Alberto Ruiz 2006-7
+Copyright   :  (c) Alberto Ruiz 2006-2010
 License     :  GPL-style
 
 Maintainer  :  Alberto Ruiz (aruiz at um dot es)
 Stability   :  provisional
 Portability :  uses ffi
 
-The Vector and Matrix types and some utilities.
+Types for dense 'Vector' and 'Matrix' of 'Storable' elements.
 
 -}
 -----------------------------------------------------------------------------
diff --git a/lib/Data/Packed/Internal/Matrix.hs b/lib/Data/Packed/Internal/Matrix.hs
index 7b823de..b616442 100644
--- a/lib/Data/Packed/Internal/Matrix.hs
+++ b/lib/Data/Packed/Internal/Matrix.hs
@@ -75,7 +75,11 @@ import Foreign.C.String
 
 data MatrixOrder = RowMajor | ColumnMajor deriving (Show,Eq)
 
--- | Matrix representation suitable for GSL and LAPACK computations.
+{- | Matrix representation suitable for GSL and LAPACK computations.
+
+The elements are stored in a continuous memory array.
+
+-}
 data Matrix t = MC { irows :: {-# UNPACK #-} !Int
                    , icols :: {-# UNPACK #-} !Int
                    , cdat :: {-# UNPACK #-} !(Vector t) }
@@ -245,9 +249,14 @@ compat m1 m2 = rows m1 == rows m2 && cols m1 == cols m2
 
 ------------------------------------------------------------------
 
--- | Supported element types for basic matrix operations.
---     provides unoptimised defaults for all (Storable a) instances
---     @instance Element Foo where@
+{- | Supported matrix elements.
+
+    This class provides optimized internal
+    operations for selected element types.
+    It provides unoptimised defaults for any 'Storable' type,
+    so you can create instances simply as:
+    @instance Element Foo@.
+-}
 class (Storable a) => Element a where
     subMatrixD :: (Int,Int) -- ^ (r0,c0) starting position 
                -> (Int,Int) -- ^ (rt,ct) dimensions of submatrix
@@ -257,30 +266,23 @@ class (Storable a) => Element a where
     transdata = transdataP -- transdata'
     constantD  :: a -> Int -> Vector a
     constantD = constantP -- constant'
-{-
-    conjugateD :: Vector a -> Vector a
-    conjugateD = id
--}
+
 
 instance Element Float where
     transdata  = transdataAux ctransF
     constantD  = constantAux cconstantF
---    conjugateD = id
 
 instance Element Double where
     transdata  = transdataAux ctransR
     constantD  = constantAux cconstantR
---    conjugateD = id
 
 instance Element (Complex Float) where
     transdata  = transdataAux ctransQ
     constantD  = constantAux cconstantQ
---    conjugateD = conjugateQ
 
 instance Element (Complex Double) where
     transdata  = transdataAux ctransC
     constantD  = constantAux cconstantC
---    conjugateD = conjugateC
 
 -------------------------------------------------------------------
 
diff --git a/lib/Data/Packed/Matrix.hs b/lib/Data/Packed/Matrix.hs
index 1fa8903..50a321d 100644
--- a/lib/Data/Packed/Matrix.hs
+++ b/lib/Data/Packed/Matrix.hs
@@ -7,7 +7,7 @@
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Packed.Matrix
--- Copyright   :  (c) Alberto Ruiz 2007
+-- Copyright   :  (c) Alberto Ruiz 2007-10
 -- License     :  GPL-style
 --
 -- Maintainer  :  Alberto Ruiz <aruiz@um.es>
@@ -16,11 +16,14 @@
 --
 -- A Matrix representation suitable for numerical computations using LAPACK and GSL.
 --
+-- This module provides basic functions for manipulation of structure.
+
 -----------------------------------------------------------------------------
 
 module Data.Packed.Matrix (
+    Matrix,
     Element,
-    Matrix,rows,cols,
+    rows,cols,
     (><),
     trans,
     reshape, flatten,
diff --git a/lib/Data/Packed/Vector.hs b/lib/Data/Packed/Vector.hs
index 2e0a9f5..eaf4b9c 100644
--- a/lib/Data/Packed/Vector.hs
+++ b/lib/Data/Packed/Vector.hs
@@ -11,6 +11,8 @@
 --
 -- 1D arrays suitable for numeric computations using external libraries.
 --
+-- This module provides basic functions for manipulation of structure.
+--
 -----------------------------------------------------------------------------
 
 module Data.Packed.Vector (
diff --git a/lib/Graphics/Plot.hs b/lib/Graphics/Plot.hs
index c5b5a4c..0bdd803 100644
--- a/lib/Graphics/Plot.hs
+++ b/lib/Graphics/Plot.hs
@@ -3,15 +3,13 @@
 -- Module      :  Graphics.Plot
 -- Copyright   :  (c) Alberto Ruiz 2005-8
 -- License     :  GPL-style
--- 
+--
 -- Maintainer  :  Alberto Ruiz (aruiz at um dot es)
 -- Stability   :  provisional
 -- Portability :  uses gnuplot and ImageMagick
 --
--- Very basic (and provisional) drawing tools using gnuplot and imageMagick.
--- 
--- This module is deprecated. It will be replaced by improved drawing tools based
--- on the Gnuplot package by Henning Thielemann.
+-- This module is deprecated. It can be replaced by improved drawing tools
+-- available in the plot\\plot-gtk packages by Vivian McPhail or Gnuplot by Henning Thielemann.
 -----------------------------------------------------------------------------
 
 module Graphics.Plot(
@@ -20,7 +18,7 @@ module Graphics.Plot(
 
     plot, parametricPlot, 
 
-    splot, mesh, mesh', meshdom,
+    splot, mesh, meshdom,
 
     matrixToPGM, imshow,
 
@@ -32,35 +30,14 @@ import Numeric.Matrix
 import Data.List(intersperse)
 import System.Process (system)
 
-size = dim
-
--- | Loads a real matrix from a formatted ASCII text file 
---fromFile :: FilePath -> IO Matrix
---fromFile filename = readFile filename >>= return . readMatrix read
-
--- | Saves a real matrix to a formatted ascii text file
-toFile' :: FilePath -> Matrix Double -> IO ()
-toFile' filename matrix = writeFile filename (unlines . map unwords. map (map show) . toLists $ matrix)
-
-------------------------------------------------------------------------
-
-
 -- | From vectors x and y, it generates a pair of matrices to be used as x and y arguments for matrix functions.
 meshdom :: Vector Double -> Vector Double -> (Matrix Double , Matrix Double)
-meshdom r1 r2 = (outer r1 (constant 1 (size r2)), outer (constant 1 (size r1)) r2)
-
-gnuplotX :: String -> IO ()
-gnuplotX command = do { _ <- system cmdstr; return()} where
-    cmdstr = "echo \""++command++"\" | gnuplot -persist"
-
-datafollows = "\\\"-\\\""
-
-prep = (++"e\n\n") . unlines . map (unwords . (map show))
+meshdom r1 r2 = (outer r1 (constant 1 (dim r2)), outer (constant 1 (dim r1)) r2)
 
 
 {- | Draws a 3D surface representation of a real matrix.
 
-> > mesh (hilb 20)
+> > mesh $ build (10,10) (\\i j -> i + (j-5)^2)
 
 In certain versions you can interactively rotate the graphic using the mouse.
 
@@ -70,15 +47,6 @@ mesh m = gnuplotX (command++dat) where
     command = "splot "++datafollows++" matrix with lines\n"
     dat = prep $ toLists $ m
 
-mesh' :: Matrix Double -> IO ()
-mesh' m = do
-    writeFile "splot-gnu-command" "splot \"splot-tmp.txt\" matrix with lines; pause -1"; 
-    toFile' "splot-tmp.txt" m
-    putStr "Press [Return] to close the graphic and continue... "
-    _ <- system "gnuplot -persist splot-gnu-command"
-    _ <- system "rm splot-tmp.txt splot-gnu-command"
-    return ()
-
 {- | Draws the surface represented by the function f in the desired ranges and number of points, internally using 'mesh'.
 
 > > let f x y = cos (x + y) 
@@ -86,11 +54,15 @@ mesh' m = do
 
 -}
 splot :: (Matrix Double->Matrix Double->Matrix Double) -> (Double,Double) -> (Double,Double) -> Int -> IO () 
-splot f rx ry n = mesh' z where
+splot f rx ry n = mesh z where
     (x,y) = meshdom (linspace n rx) (linspace n ry)
     z = f x y
 
-{- | plots several vectors against the first one -}
+{- | plots several vectors against the first one 
+
+> > let t = linspace 100 (-3,3) in mplot [t, sin t, exp (-t^2)]
+
+-}
 mplot :: [Vector Double] -> IO ()
 mplot m = gnuplotX (commands++dats) where
     commands = if length m == 1 then command1 else commandmore
@@ -102,26 +74,6 @@ mplot m = gnuplotX (commands++dats) where
     dats = concat (replicate (length m-1) dat)
 
 
-{-
-mplot' m = do
-    writeFile "plot-gnu-command" (commands++endcmd)
-    toFile "plot-tmp.txt" (fromColumns m)
-    putStr "Press [Return] to close the graphic and continue... "
-    system "gnuplot plot-gnu-command"
-    system "rm plot-tmp.txt plot-gnu-command"
-    return ()
- where
-    commands = if length m == 1 then command1 else commandmore
-    command1 = "plot \"plot-tmp.txt\" with lines\n"
-    commandmore = "plot " ++ plots ++ "\n"
-    plots = concat $ intersperse ", " (map cmd [2 .. length m])
-    cmd k = "\"plot-tmp.txt\" using 1:"++show k++" with lines"
-    endcmd = "pause -1"
--}
-
--- apply several functions to one object
-mapf fs x = map ($ x) fs
-
 {- | Draws a list of functions over a desired range and with a desired number of points 
 
 > > plot [sin, cos, sin.(3*)] (0,2*pi) 1000
@@ -129,7 +81,8 @@ mapf fs x = map ($ x) fs
 -}
 plot :: [Vector Double->Vector Double] -> (Double,Double) -> Int -> IO ()
 plot fs rx n = mplot (x: mapf fs x)
-    where x = linspace n rx  
+    where x = linspace n rx
+          mapf gs y = map ($ y) gs
 
 {- | Draws a parametric curve. For instance, to draw a spiral we can do something like:
 
@@ -165,6 +118,15 @@ imshow m = do
 
 ----------------------------------------------------
 
+gnuplotX :: String -> IO ()
+gnuplotX command = do { _ <- system cmdstr; return()} where
+    cmdstr = "echo \""++command++"\" | gnuplot -persist"
+
+datafollows = "\\\"-\\\""
+
+prep = (++"e\n\n") . unlines . map (unwords . (map show))
+
+
 gnuplotpdf :: String -> String -> [([[Double]], String)] -> IO ()
 gnuplotpdf title command ds = gnuplot (prelude ++ command ++" "++ draw) >> postproc where
     prelude = "set terminal epslatex color; set output '"++title++".tex';"
diff --git a/lib/Numeric/Container.hs b/lib/Numeric/Container.hs
index 1c542b8..6b73a4e 100644
--- a/lib/Numeric/Container.hs
+++ b/lib/Numeric/Container.hs
@@ -15,7 +15,13 @@
 -- Stability   :  provisional
 -- Portability :  portable
 --
--- Numeric classes for containers of numbers, including conversion routines
+-- Basic numeric operations on 'Vector' and 'Matrix', including conversion routines.
+--
+-- The 'Container' class is used to define optimized generic functions which work
+-- on 'Vector' and 'Matrix' with real or complex elements.
+--
+-- Some of these functions are also available in the instances of the standard
+-- numeric Haskell classes provided by "Numeric.Vector" and "Numeric.Matrix".
 --
 -----------------------------------------------------------------------------
 
diff --git a/lib/Numeric/LinearAlgebra/Algorithms.hs b/lib/Numeric/LinearAlgebra/Algorithms.hs
index 64deba2..c49bec7 100644
--- a/lib/Numeric/LinearAlgebra/Algorithms.hs
+++ b/lib/Numeric/LinearAlgebra/Algorithms.hs
@@ -82,7 +82,10 @@ import Data.Array
 import Numeric.Container hiding ((.*),(*/))
 import Numeric.MatrixBoot
 
--- | Auxiliary typeclass used to define generic computations for both real and complex matrices.
+{- | Auxiliary typeclass used to define generic linear algebra computations for both real and complex matrices. Only double precision is supported in this version (we can
+transform single precision objects using 'single' and 'double').
+
+-}
 class (Product t,
        Convert t,
        Container Vector t,