documentation, thanks

linearSolve examples, install, changelog

5 files changed, 69 insertions, 7 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 00a9838..157036e 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -12,6 +12,9 @@ Ubuntu/Debian:
 
 Other distributions may require additional libraries. They can be given in a **--configure-option**.
 
+Adrian Victor Crisciu has developed an [installation method](http://comments.gmane.org/gmane.comp.lang.haskell.glasgow.user/24976) for systems
+which don't provide shared lapack libraries.
+
 ## Mac OS/X ###############################################
 
 GSL must be installed via Homebrew or MacPorts.
diff --git a/packages/base/CHANGELOG b/packages/base/CHANGELOG
index 35ccdbc..95982ac 100644
--- a/packages/base/CHANGELOG
+++ b/packages/base/CHANGELOG
@@ -11,9 +11,11 @@
         Numeric.LinearAlgebra.Data
         Numeric.LinearAlgebra.Devel
 
-      The documentation is now hidden for Data.Packed.*, Numeric.Container, and
+      For normal usage we only need to import Numeric.LinearAlgebra.HMatrix.
+
+      (The documentation is now hidden for Data.Packed.*, Numeric.Container, and
       the other Numeric.LinearAlgebra.* modules, but they continue to be exposed
-      for backwards compatibility.
+      for backwards compatibility.)
 
     * Added support for empty arrays, extending automatic conformability
       (very useful for construction of block matrices).
diff --git a/packages/base/THANKS.md b/packages/base/THANKS.md
index 805a19e..571f370 100644
--- a/packages/base/THANKS.md
+++ b/packages/base/THANKS.md
@@ -139,7 +139,8 @@ module reorganization, monadic mapVectorM, and many other improvements.
 
 - Clemens Lang updated the MacPort installation instructions.
 
-- Henning Thielemann reported the pinv inefficient implementation.
+- Henning Thielemann reported the pinv inefficient implementation and the need of
+  pkgconfig-depends.
 
 - bdoering reported the problem of zero absolute tolerance in the integration functions.
 
@@ -157,9 +158,13 @@ module reorganization, monadic mapVectorM, and many other improvements.
 
 - Denis Laxalde separated the gsl tests from the base ones.
 
-- "idontgetoutmuch" reported a bug in the static diagonal creation functions.
+- Dominic Steinitz (idontgetoutmuch) reported a bug in the static diagonal creation functions.
 
-- Dylan Thurston reported an error in the glpk documentation.
+- Dylan Thurston reported an error in the glpk documentation and ambiguity in
+  the description of linearSolve.
+
+- Adrian Victor Crisciu developed an installation method for platforms which
+  don't provide shared lapack libraries.
 
 - Ian Ross reported the max/minIndex bug.
 
diff --git a/packages/base/src/Data/Packed/Numeric.hs b/packages/base/src/Data/Packed/Numeric.hs
index 7aa53f1..6027f43 100644
--- a/packages/base/src/Data/Packed/Numeric.hs
+++ b/packages/base/src/Data/Packed/Numeric.hs
@@ -160,7 +160,29 @@ instance Mul Vector Matrix Vector where
 
 --------------------------------------------------------------------------------
 
--- | least squares solution of a linear system, similar to the \\ operator of Matlab\/Octave (based on linearSolveSVD)
+{- | Least squares solution of a linear system, similar to the \\ operator of Matlab\/Octave (based on linearSolveSVD)
+
+@
+a = (3><2)
+ [ 1.0,  2.0
+ , 2.0,  4.0
+ , 2.0, -1.0 ]
+@
+
+@
+v = vector [13.0,27.0,1.0]
+@
+
+>>> let x = a <\> v
+>>> x
+fromList [3.0799999999999996,5.159999999999999]
+
+>>> a #> x
+fromList [13.399999999999999,26.799999999999997,1.0]
+
+It also admits multiple right-hand sides stored as columns in a matrix.
+
+-}
 infixl 7 <\>
 (<\>) :: (LSDiv c, Field t) => Matrix t -> c t -> c t
 (<\>) = linSolve
diff --git a/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs b/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs
index d2cae6c..c0cc622 100644
--- a/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs
+++ b/packages/base/src/Numeric/LinearAlgebra/HMatrix.hs
@@ -194,7 +194,37 @@ mul :: Numeric t => Matrix t -> Matrix t -> Matrix t
 mul = mXm
 
 
--- | 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'. 
+{- | 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'.
+
+@
+a = (2><2)
+ [ 1.0, 2.0
+ , 3.0, 5.0 ]
+@
+
+@
+b = (2><3)
+ [  6.0, 1.0, 10.0
+ , 15.0, 3.0, 26.0 ]
+@
+
+>>> linearSolve a b
+Just (2><3)
+ [ -1.4802973661668753e-15,     0.9999999999999997, 1.999999999999997
+ ,       3.000000000000001, 1.6653345369377348e-16, 4.000000000000002 ]
+
+>>> let Just x = it
+>>> disp 5 x
+2x3
+-0.00000  1.00000  2.00000
+ 3.00000  0.00000  4.00000
+
+>>> a <> x
+(2><3)
+ [  6.0, 1.0, 10.0
+ , 15.0, 3.0, 26.0 ]
+
+-}
 linearSolve m b = A.mbLinearSolve m b
 
 -- | return an orthonormal basis of the null space of a matrix. See also 'nullspaceSVD'.