documentation

4 files changed, 115 insertions, 82 deletions

diff --git a/packages/base/src/Data/Packed/Numeric.hs b/packages/base/src/Data/Packed/Numeric.hs
index e90c612..d2a20be 100644
--- a/packages/base/src/Data/Packed/Numeric.hs
+++ b/packages/base/src/Data/Packed/Numeric.hs
@@ -1,4 +1,3 @@
-{-# LANGUAGE TypeFamilies #-}
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE MultiParamTypeClasses #-}
@@ -95,67 +94,46 @@ linspace 1 (a,b) = fromList[(a+b)/2]
 linspace n (a,b) = addConstant a $ scale s $ fromList $ map fromIntegral [0 .. n-1]
     where s = (b-a)/fromIntegral (n-1)
 
---------------------------------------------------------
-
-{- Matrix product, matrix - vector product, and dot product (equivalent to 'contraction')
-
-(This operator can also be written using the unicode symbol ◇ (25c7).)
-
-Examples:
-
->>> let a = (3><4)   [1..]      :: Matrix Double
->>> let v = fromList [1,0,2,-1] :: Vector Double
->>> let u = fromList [1,2,3]    :: Vector Double
-
->>> a
-(3><4)
- [ 1.0,  2.0,  3.0,  4.0
- , 5.0,  6.0,  7.0,  8.0
- , 9.0, 10.0, 11.0, 12.0 ]
-
-matrix × matrix:
+--------------------------------------------------------------------------------
 
->>> disp 2 (a <.> trans a)
-3x3
- 30   70  110
- 70  174  278
-110  278  446
+infixl 7 <.>
+-- | An infix synonym for 'dot'
+(<.>) :: Numeric t => Vector t -> Vector t -> t
+(<.>) = dot
 
-matrix × vector:
 
->>> a <.> v
-fromList [3.0,11.0,19.0]
+infixr 8 <·>, #>
 
-dot product:
+{- | dot product
 
->>> u <.> fromList[3,2,1::Double]
-10
+>>> vect [1,2,3,4] <·> vect [-2,0,1,1]
+5.0
 
-For complex vectors the first argument is conjugated:
+>>> let 𝑖 = 0:+1 :: ℂ
+>>> fromList [1+𝑖,1] <·> fromList [1,1+𝑖]
+2.0 :+ 0.0
 
->>> fromList [1,i] <.> fromList[2*i+1,3]
-1.0 :+ (-1.0)
+(the dot symbol "·" is obtained by Alt-Gr .)
 
->>> fromList [1,i,1-i] <.> complex a
-fromList [10.0 :+ 4.0,12.0 :+ 4.0,14.0 :+ 4.0,16.0 :+ 4.0]
 -}
+(<·>) :: Numeric t => Vector t -> Vector t -> t
+(<·>) = dot
 
 
---------------------------------------------------------------------------------
-
-infixl 7 <.>
--- | An infix synonym for 'dot'
-(<.>) :: Numeric t => Vector t -> Vector t -> t
-(<.>) = dot
+{- | dense matrix-vector product
 
+>>> let m = (2><3) [1..]
+>>> m
+(2><3)
+ [ 1.0, 2.0, 3.0
+ , 4.0, 5.0, 6.0 ]
 
-infixr 8 <·>, #>
--- | dot product
-(<·>) :: Numeric t => Vector t -> Vector t -> t
-(<·>) = dot
+>>> let v = vect [10,20,30]
 
+>>> m #> v
+fromList [140.0,320.0]
 
--- | matrix-vector product
+-}
 (#>) :: Numeric t => Matrix t -> Vector t -> Vector t
 (#>) = mXv
 
@@ -291,4 +269,4 @@ instance Numeric (Complex Double)
 instance Numeric Float
 instance Numeric (Complex Float)
 
---------------------------------------------------------------------------------
+
diff --git a/packages/base/src/Numeric/HMatrix.hs b/packages/base/src/Numeric/HMatrix.hs
index 9d34658..ec96bfc 100644
--- a/packages/base/src/Numeric/HMatrix.hs
+++ b/packages/base/src/Numeric/HMatrix.hs
@@ -17,10 +17,10 @@ module Numeric.HMatrix (
     -- |
     -- The standard numeric classes are defined elementwise:
     --
-    -- >>> fromList [1,2,3] * fromList [3,0,-2 :: Double]
+    -- >>>  vect [1,2,3] * vect [3,0,-2]
     -- fromList [3.0,0.0,-6.0]
     --
-    -- >>> (3><3) [1..9] * ident 3 :: Matrix Double
+    -- >>> mat 3 [1..9] * ident 3
     -- (3><3)
     --  [ 1.0, 0.0, 0.0
     --  , 0.0, 5.0, 0.0
@@ -36,6 +36,12 @@ module Numeric.HMatrix (
     --  , 5.0, 7.0, 5.0
     --  , 5.0, 5.0, 7.0 ]
     --
+    -- >>> mat 3 [1..9] + mat 1 [10,20,30]
+    -- (3><3)
+    --  [ 11.0, 12.0, 13.0
+    --  , 24.0, 25.0, 26.0
+    --  , 37.0, 38.0, 39.0 ]
+    --
 
     -- * Products
     -- ** dot
@@ -48,11 +54,12 @@ module Numeric.HMatrix (
     -- single-element matrices (created from numeric literals or using 'scalar')
     -- are used for scaling.
     --
-    -- >>> let m = (2><3)[1..] :: Matrix Double
-    -- >>> m <> 2 <> diagl[0.5,1,0]
+    -- >>> import Data.Monoid as M
+    -- >>>  let m = mat 3 [1..6]
+    -- >>> m M.<> 2 M.<> diagl[0.5,1,0]
     -- (2><3)
-    -- [ 1.0,  4.0, 0.0
-    -- , 4.0, 10.0, 0.0 ]
+    --  [ 1.0,  4.0, 0.0
+    --  , 4.0, 10.0, 0.0 ]
     --
     -- 'mconcat' uses 'optimiseMult' to get the optimal association order.
 
@@ -76,10 +83,18 @@ module Numeric.HMatrix (
     inv, pinv, pinvTol,
 
     -- * Determinant and rank
-    rcond, rank, ranksv,
+    rcond, rank,
     det, invlndet,
 
-    -- * Singular value decomposition
+    -- * Norms
+    Normed(..),
+    norm_Frob, norm_nuclear,
+
+    -- * Nullspace and range
+    orth,
+    nullspace, null1, null1sym,
+
+    -- * SVD
     svd,
     fullSVD,
     thinSVD,
@@ -112,18 +127,6 @@ module Numeric.HMatrix (
     sqrtm,
     matFunc,
 
-    -- * Nullspace
-    nullspacePrec,
-    nullVector,
-    nullspaceSVD,
-    null1, null1sym,
-
-    orth,
-
-    -- * Norms
-    Normed(..),
-    norm_Frob, norm_nuclear,
-
     -- * Correlation and convolution
     corr, conv, corrMin, corr2, conv2,
 
@@ -132,7 +135,8 @@ module Numeric.HMatrix (
     Seed, RandDist(..), randomVector, rand, randn, gaussianSample, uniformSample,
 
     -- * Misc
-    meanCov, peps, relativeError, haussholder, optimiseMult, udot,
+    meanCov, peps, relativeError, haussholder, optimiseMult, udot, nullspaceSVD, orthSVD, ranksv,
+    ℝ,ℂ,iC,
     -- * Auxiliary classes
     Element, Container, Product, Numeric, LSDiv,
     Complexable, RealElement,
@@ -142,8 +146,7 @@ module Numeric.HMatrix (
 --    Normed,
     Transposable,
     CGState(..),
-    Testable(..),
-    ℕ,ℤ,ℝ,ℂ, i_C
+    Testable(..)
 ) where
 
 import Numeric.LinearAlgebra.Data
@@ -151,14 +154,38 @@ import Numeric.LinearAlgebra.Data
 import Numeric.Matrix()
 import Numeric.Vector()
 import Data.Packed.Numeric hiding ((<>))
-import Numeric.LinearAlgebra.Algorithms hiding (linearSolve,Normed)
+import Numeric.LinearAlgebra.Algorithms hiding (linearSolve,Normed,orth)
 import qualified Numeric.LinearAlgebra.Algorithms as A
 import Numeric.LinearAlgebra.Util
 import Numeric.LinearAlgebra.Random
 import Numeric.Sparse((!#>))
 import Numeric.LinearAlgebra.Util.CG
 
--- | matrix product
+{- | dense matrix product
+
+>>> let a = (3><5) [1..]
+>>> a
+(3><5)
+ [  1.0,  2.0,  3.0,  4.0,  5.0
+ ,  6.0,  7.0,  8.0,  9.0, 10.0
+ , 11.0, 12.0, 13.0, 14.0, 15.0 ]
+
+>>> let b = (5><2) [1,3, 0,2, -1,5, 7,7, 6,0]
+>>> b
+(5><2)
+ [  1.0, 3.0
+ ,  0.0, 2.0
+ , -1.0, 5.0
+ ,  7.0, 7.0
+ ,  6.0, 0.0 ]
+
+>>> a <> b
+(3><2)
+ [  56.0,  50.0
+ , 121.0, 135.0
+ , 186.0, 220.0 ]
+
+-}
 (<>) :: Numeric t => Matrix t -> Matrix t -> Matrix t
 (<>) = mXm
 infixr 8 <>
@@ -166,3 +193,9 @@ infixr 8 <>
 -- | Solve a linear system (for square coefficient matrix and several right-hand sides) using the LU decomposition, returning Nothing for a singular system. For underconstrained or overconstrained systems use 'linearSolveLS' or 'linearSolveSVD'. 
 linearSolve m b = A.mbLinearSolve m b
 
+-- | return an orthonormal basis of the null space of a matrix. See also 'nullspaceSVD'.
+nullspace m = nullspaceSVD (Left (1*eps)) m (rightSV m)
+
+-- | return an orthonormal basis of the range space of a matrix. See also 'orthSVD'.
+orth m = orthSVD (Left (1*eps)) m (leftSV m)
+
diff --git a/packages/base/src/Numeric/LinearAlgebra/Util.hs b/packages/base/src/Numeric/LinearAlgebra/Util.hs
index 324fb44..4824af4 100644
--- a/packages/base/src/Numeric/LinearAlgebra/Util.hs
+++ b/packages/base/src/Numeric/LinearAlgebra/Util.hs
@@ -32,7 +32,7 @@ module Numeric.LinearAlgebra.Util(
     rand, randn,
     cross,
     norm,
-    ℕ,ℤ,ℝ,ℂ,𝑖,i_C, --ℍ
+    ℕ,ℤ,ℝ,ℂ,iC,
     Normed(..), norm_Frob, norm_nuclear,
     unitary,
     mt,
@@ -72,13 +72,10 @@ type ℝ = Double
 type ℕ = Int
 type ℤ = Int
 type ℂ = Complex Double
---type ℝn = Vector ℝ
---type ℂn = Vector ℂ
---newtype ℍ m = H m
 
-i_C, 𝑖 :: ℂ
-𝑖 = 0:+1
-i_C = 𝑖
+-- | imaginary unit
+iC :: ℂ
+iC = 0:+1
 
 {- | create a real vector
 
diff --git a/packages/base/src/Numeric/Sparse.hs b/packages/base/src/Numeric/Sparse.hs
index 1b8a7b3..f495e3a 100644
--- a/packages/base/src/Numeric/Sparse.hs
+++ b/packages/base/src/Numeric/Sparse.hs
@@ -62,7 +62,26 @@ mkCSR sm' = CSR{..}
     csrNRows = dim csrRows - 1
     csrNCols = fromIntegral (V.maximum csrCols)
 
-
+{- | General matrix with specialized internal representations for
+     dense, sparse, diagonal, banded, and constant elements.
+
+>>> let m = mkSparse [((0,999),1.0),((1,1999),2.0)]
+>>> m
+SparseR {gmCSR = CSR {csrVals = fromList [1.0,2.0],
+                      csrCols = fromList [1000,2000],
+                      csrRows = fromList [1,2,3],
+                      csrNRows = 2,
+                      csrNCols = 2000},
+                      nRows = 2,
+                      nCols = 2000}
+
+>>> let m = mkDense (mat 2 [1..4])
+>>> m
+Dense {gmDense = (2><2)
+ [ 1.0, 2.0
+ , 3.0, 4.0 ], nRows = 2, nCols = 2}
+
+-}
 data GMatrix
     = SparseR
         { gmCSR   :: CSR
@@ -146,7 +165,13 @@ gmXv Dense{..} v
                                  nRows nCols (dim v)
 
 
--- | general matrix - vector product
+{- | general matrix - vector product
+
+>>> let m = mkSparse [((0,999),1.0),((1,1999),2.0)]
+>>> m !#> vect[1..2000]
+fromList [1000.0,4000.0]
+
+-}
 infixr 8 !#>
 (!#>) :: GMatrix -> Vector Double -> Vector Double
 (!#>) = gmXv