documentation

10 files changed, 51 insertions, 25 deletions

diff --git a/packages/base/CHANGELOG b/packages/base/CHANGELOG
index c3e118c..0336a28 100644
--- a/packages/base/CHANGELOG
+++ b/packages/base/CHANGELOG
@@ -1,21 +1,25 @@
 0.17.0.0
 --------
 
-    * improved matrix extraction using vectors of indexes (??)
+    * improved matrix extraction (??) and rectangular matrix slices without data copy
 
     * basic support of Int32 and Int64 elements
     
-    * remap, more general cond
+    * remap, more general cond, sortIndex
 
     * experimental support of type safe modular arithmetic, including linear
       systems and lu factorization
     
-    * elementary row operations in ST monad
+    * elementary row operations and inplace matrix slice products in the ST monad
 
-    * old compatibility modules removed
+    * Improved development tools.
+
+    * old compatibility modules removed, simpler organization of internal modules
 
     * unitary, pairwiseD2, tr'
 
+    * ldlPacked, ldlSolve
+
 0.16.1.0
 --------
 
diff --git a/packages/base/hmatrix.cabal b/packages/base/hmatrix.cabal
index f725341..7b25349 100644
--- a/packages/base/hmatrix.cabal
+++ b/packages/base/hmatrix.cabal
@@ -7,7 +7,11 @@ Maintainer:         Alberto Ruiz
 Stability:          provisional
 Homepage:           https://github.com/albertoruiz/hmatrix
 Synopsis:           Numeric Linear Algebra
-Description:        Linear algebra based on BLAS and LAPACK.
+Description:        Linear systems, matrix decompositions, and other numerical computations based on BLAS and LAPACK.
+                    .
+                    The standard interface is provided by the module "Numeric.LinearAlgebra".
+                    .
+                    A safer interface with statically checked dimensions is provided by "Numeric.LinearAlgebra.Static".
                     .
                     Code examples: <http://dis.um.es/~alberto/hmatrix/hmatrix.html>
 
diff --git a/packages/base/src/Internal/Algorithms.hs b/packages/base/src/Internal/Algorithms.hs
index c8b2d3e..99c90aa 100644
--- a/packages/base/src/Internal/Algorithms.hs
+++ b/packages/base/src/Internal/Algorithms.hs
@@ -470,14 +470,14 @@ rq m =  {-# SCC "rq" #-} (r,q) where
 
 -- | Hessenberg factorization.
 --
--- If @(p,h) = hess m@ then @m == p \<> h \<> ctrans p@, where p is unitary
+-- If @(p,h) = hess m@ then @m == p \<> h \<> tr p@, where p is unitary
 -- and h is in upper Hessenberg form (it has zero entries below the first subdiagonal).
 hess        :: Field t => Matrix t -> (Matrix t, Matrix t)
 hess = hess'
 
 -- | Schur factorization.
 --
--- If @(u,s) = schur m@ then @m == u \<> s \<> ctrans u@, where u is unitary
+-- If @(u,s) = schur m@ then @m == u \<> s \<> tr u@, where u is unitary
 -- and s is a Shur matrix. A complex Schur matrix is upper triangular. A real Schur matrix is
 -- upper triangular in 2x2 blocks.
 --
@@ -497,7 +497,7 @@ cholSH = {-# SCC "cholSH" #-} cholSH'
 
 -- | Cholesky factorization of a positive definite hermitian or symmetric matrix.
 --
--- If @c = chol m@ then @c@ is upper triangular and @m == ctrans c \<> c@.
+-- If @c = chol m@ then @c@ is upper triangular and @m == tr c \<> c@.
 chol :: Field t => Matrix t ->  Matrix t
 chol m | exactHermitian m = cholSH m
        | otherwise = error "chol requires positive definite complex hermitian or real symmetric matrix"
diff --git a/packages/base/src/Internal/Container.hs b/packages/base/src/Internal/Container.hs
index 8926fac..307c6a8 100644
--- a/packages/base/src/Internal/Container.hs
+++ b/packages/base/src/Internal/Container.hs
@@ -72,7 +72,7 @@ infixr 8 <.>
 
 
 
-{- | infix synonym for 'app'
+{- | dense matrix-vector product
 
 >>> let m = (2><3) [1..]
 >>> m
diff --git a/packages/base/src/Internal/Element.hs b/packages/base/src/Internal/Element.hs
index 6d86f3d..a459678 100644
--- a/packages/base/src/Internal/Element.hs
+++ b/packages/base/src/Internal/Element.hs
@@ -325,9 +325,9 @@ takeDiag m = fromList [flatten m @> (k*cols m+k) | k <- [0 .. min (rows m) (cols
 
 ------------------------------------------------------------
 
-{- | create a general matrix
+{- | Create a matrix from a list of elements
 
->>> (2><3) [2, 4, 7+2*𝑖,   -3, 11, 0]
+>>> (2><3) [2, 4, 7+2*iC,   -3, 11, 0]
 (2><3)
  [       2.0 :+ 0.0,  4.0 :+ 0.0, 7.0 :+ 2.0
  , (-3.0) :+ (-0.0), 11.0 :+ 0.0, 0.0 :+ 0.0 ]
diff --git a/packages/base/src/Internal/Vector.hs b/packages/base/src/Internal/Vector.hs
index 29b6797..de4e670 100644
--- a/packages/base/src/Internal/Vector.hs
+++ b/packages/base/src/Internal/Vector.hs
@@ -127,7 +127,7 @@ n |> l
     l' = take n l
 
 
--- | Create a vector of indexes, useful for matrix extraction using '??'
+-- | Create a vector of indexes, useful for matrix extraction using '(??)'
 idxs :: [Int] -> Vector I
 idxs js = fromList (map fromIntegral js) :: Vector I
 
diff --git a/packages/base/src/Numeric/LinearAlgebra.hs b/packages/base/src/Numeric/LinearAlgebra.hs
index dd4cc67..9cab635 100644
--- a/packages/base/src/Numeric/LinearAlgebra.hs
+++ b/packages/base/src/Numeric/LinearAlgebra.hs
@@ -8,11 +8,16 @@ License     :  BSD3
 Maintainer  :  Alberto Ruiz
 Stability   :  provisional
 
+
 -}
 -----------------------------------------------------------------------------
 module Numeric.LinearAlgebra (
 
-    -- * Basic types and data processing
+    -- * Basic Types and data manipulation
+    -- | This package works with 2D ('Matrix') and 1D ('Vector')
+    -- arrays of real ('R') or complex ('C') double precision numbers.
+    -- Single precision and machine integers are also supported for
+    -- basic arithmetic and data manipulation.
     module Numeric.LinearAlgebra.Data,
 
     -- * Numeric classes
@@ -51,9 +56,9 @@ module Numeric.LinearAlgebra (
     -- ** dot
     dot, (<.>),
     -- ** matrix-vector
-    app, (#>), (<#), (!#>),
+    (#>), (<#), (!#>),
     -- ** matrix-matrix
-    mul, (<>),
+    (<>),
     -- | The matrix product is also implemented in the "Data.Monoid" instance, where
     -- single-element matrices (created from numeric literals or using 'scalar')
     -- are used for scaling.
@@ -172,7 +177,7 @@ import Internal.Sparse((!#>))
 import Internal.CG
 import Internal.Conversion
 
-{- | infix synonym of 'mul'
+{- | dense matrix product
 
 >>> let a = (3><5) [1..]
 >>> a
diff --git a/packages/base/src/Numeric/LinearAlgebra/Data.hs b/packages/base/src/Numeric/LinearAlgebra/Data.hs
index d2843c2..a389aac 100644
--- a/packages/base/src/Numeric/LinearAlgebra/Data.hs
+++ b/packages/base/src/Numeric/LinearAlgebra/Data.hs
@@ -8,21 +8,29 @@ License     :  BSD3
 Maintainer  :  Alberto Ruiz
 Stability   :  provisional
 
-Basic data processing.
+This module provides functions for creation and manipulation of vectors and matrices, IO, and other utilities.
 
 -}
 --------------------------------------------------------------------------------
 
 module Numeric.LinearAlgebra.Data(
 
+    -- * Elements
+    R,C,I,Z,type(./.),
+
     -- * Vector
-    -- | 1D arrays are storable vectors from the vector package. There is no distinction
-    --   between row and column vectors.
+    {- | 1D arrays are storable vectors directly reexported from the vector package.
+    -}
 
     fromList, toList, (|>), vector, range, idxs,
 
     -- * Matrix
 
+    {- | The main data type of hmatrix is a 2D dense array defined on top of
+         a storable vector. The internal representation is suitable for direct
+         interface with standard numeric libraries.
+    -}
+
     (><), matrix, tr, tr',
 
     -- * Dimensions
@@ -56,8 +64,9 @@ module Numeric.LinearAlgebra.Data(
     -- * Matrix extraction
     Extractor(..), (??),
 
-    takeRows, dropRows, takeColumns, dropColumns,
-    subMatrix, (?), (¿), fliprl, flipud,
+    (?), (¿), fliprl, flipud,
+
+    subMatrix, takeRows, dropRows, takeColumns, dropColumns,
 
     remap,
 
@@ -92,7 +101,7 @@ module Numeric.LinearAlgebra.Data(
     separable,
     fromArray2D,
     module Data.Complex,
-    R,C,I,Z,Mod, type(./.),
+    Mod,
     Vector, Matrix, GMatrix, nRows, nCols
 
 ) where
diff --git a/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs b/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs
index 8adaaaf..bac1c0c 100644
--- a/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs
+++ b/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs
@@ -13,7 +13,7 @@ compatibility with previous version, to be removed
 
 module Numeric.LinearAlgebra.HMatrix (
     module Numeric.LinearAlgebra,
-    (¦),(——),ℝ,ℂ,(<·>)
+    (¦),(——),ℝ,ℂ,(<·>),app,mul
 ) where
 
 import Numeric.LinearAlgebra
@@ -23,3 +23,7 @@ infixr 8 <·>
 (<·>) :: Numeric t => Vector t -> Vector t -> t
 (<·>) = dot
 
+app m v = m #> v
+
+mul a b = a <> b
+
diff --git a/packages/base/src/Numeric/LinearAlgebra/Static.hs b/packages/base/src/Numeric/LinearAlgebra/Static.hs
index d0a790d..0dab0e6 100644
--- a/packages/base/src/Numeric/LinearAlgebra/Static.hs
+++ b/packages/base/src/Numeric/LinearAlgebra/Static.hs
@@ -22,7 +22,7 @@ Stability   :  experimental
 
 Experimental interface with statically checked dimensions.
 
-This module is under active development and the interface is subject to changes.
+See code examples at http://dis.um.es/~alberto/hmatrix/static.html.
 
 -}
 
@@ -65,7 +65,7 @@ import Numeric.LinearAlgebra hiding (
     row,col,vector,matrix,linspace,toRows,toColumns,
     (<\>),fromList,takeDiag,svd,eig,eigSH,eigSH',
     eigenvalues,eigenvaluesSH,eigenvaluesSH',build,
-    qr,size,app,mul,dot,chol,range,R,C)
+    qr,size,dot,chol,range,R,C)
 import qualified Numeric.LinearAlgebra as LA
 import Data.Proxy(Proxy)
 import Internal.Static