documentation for simplex

5 files changed, 74 insertions, 15 deletions

diff --git a/packages/glpk/examples/simplex1.hs b/packages/glpk/examples/simplex1.hs
index 4609524..9639f37 100644
--- a/packages/glpk/examples/simplex1.hs
+++ b/packages/glpk/examples/simplex1.hs
@@ -5,8 +5,8 @@ import Numeric.LinearProgramming
 objFun = Maximize [10, 6, 4]
 
 constr = Dense [ [1,1,1]  :<: 100
-              , [10,4,5] :<: 600 
-              , [2,2,6]  :<: 300 ]
+               , [10,4,5] :<: 600 
+               , [2,2,6]  :<: 300 ]
 
 -- default bounds
 bnds = [ 1 :>: 0
diff --git a/packages/glpk/examples/simplex2.hs b/packages/glpk/examples/simplex2.hs
index 76a53df..40e4bbd 100644
--- a/packages/glpk/examples/simplex2.hs
+++ b/packages/glpk/examples/simplex2.hs
@@ -1,6 +1,6 @@
 import Numeric.LinearProgramming
 
-prob = Maximize [1,2,3,4]
+prob = Maximize [4, 3, -2, 7]
 
 constr1 = Sparse [ [1#1, 1#2] :<: 10
                  , [1#3, 1#4] :<: 10 
@@ -12,5 +12,6 @@ constr2 = Dense [ [1,1,0,0] :<: 10
 
 main = do
     print $ simplex prob constr1 []
-    print $ simplex prob constr2 []
+    print $ simplex prob constr2 [ 2 :>: 1, 4 :&: (2,7)]
+    print $ simplex prob constr2 [ Free 3 ]
 
diff --git a/packages/glpk/examples/simplex3.hs b/packages/glpk/examples/simplex3.hs
index 0f787cb..3a7e8e8 100644
--- a/packages/glpk/examples/simplex3.hs
+++ b/packages/glpk/examples/simplex3.hs
@@ -1,7 +1,8 @@
-import Numeric.LinearProgramming
-
+-- compare with
 -- $ glpsol --cpxlp  /usr/share/doc/glpk-utils/examples/plan.lp  -o result.txt
 
+import Numeric.LinearProgramming
+
 prob = Minimize [0.03, 0.08, 0.17, 0.12, 0.15, 0.21, 0.38]
 
 constr = Dense
diff --git a/packages/glpk/examples/simplex4.hs b/packages/glpk/examples/simplex4.hs
index 3b9c060..8496f6d 100644
--- a/packages/glpk/examples/simplex4.hs
+++ b/packages/glpk/examples/simplex4.hs
@@ -1,7 +1,8 @@
-import Numeric.LinearProgramming
-
+-- compare with
 -- $ glpsol --cpxlp  /usr/share/doc/glpk-utils/examples/plan.lp  -o result.txt
 
+import Numeric.LinearProgramming
+
 prob = Minimize [0.03, 0.08, 0.17, 0.12, 0.15, 0.21, 0.38]
 
 constr = Sparse
diff --git a/packages/glpk/lib/Numeric/LinearProgramming.hs b/packages/glpk/lib/Numeric/LinearProgramming.hs
index 1b14080..fff304f 100644
--- a/packages/glpk/lib/Numeric/LinearProgramming.hs
+++ b/packages/glpk/lib/Numeric/LinearProgramming.hs
@@ -1,12 +1,66 @@
 {-# LANGUAGE ForeignFunctionInterface #-}
 
+{- |
+Module      :  Numeric.LinearProgramming
+Copyright   :  (c) Alberto Ruiz 2010
+License     :  GPL
+
+Maintainer  :  Alberto Ruiz (aruiz at um dot es)
+Stability   :  provisional
+
+This module provides an interface to the standard simplex algorithm.
+
+For example, the following linear programming problem
+
+@maximize 4 x_1 + 3 x_2 - 2 x_3 + 7 x_4
+subject to
+
+x_1 + x_2 <= 10
+x_3 + x_4 <= 10
+
+and
+
+x_i >= 0@
+
+can be solved as follows:
+
+@import Numeric.LinearProgramming
+
+prob = Maximize [4, 3, -2, 7]
+
+constr1 = Sparse [ [1\#1, 1\#2] :<: 10
+                 , [1\#3, 1\#4] :<: 10 
+                 ]
+                 
+
+\> simplex prob constr1 []
+Optimal (110.0,[10.0,0.0,0.0,10.0])@
+
+The coefficients of the constraint matrix can also be given in dense format:
+
+@constr2 = Dense [ [1,1,0,0] :<: 10
+                , [0,0,1,1] :<: 10 
+                ]@
+
+By default all variables are bounded as @x_i <= 0@, but this can be
+changed:
+
+@\> simplex prob constr2 [2 :>: 1, 4 :&: (2,7)]
+Optimal (88.0,[9.0,1.0,0.0,7.0])
+
+\> simplex prob constr2 [Free 3]
+Unbounded@
+
+-}
+
 module Numeric.LinearProgramming(
+    simplex,
     Optimization(..),
+    Constraints(..),
+    Bounds,
     Bound(..),
     (#),
-    Coeffs(..),
-    Solution(..),
-    simplex,
+    Solution(..)
 ) where
 
 import Numeric.LinearAlgebra
@@ -21,7 +75,7 @@ import Data.Function(on)
 
 -----------------------------------------------------
 
--- | Coefficient of a variable
+-- | Coefficient of a variable for a sparse representation of constraints.
 (#) :: Double -> Int -> (Double,Int)
 infixl 5 #
 (#) = (,)
@@ -41,13 +95,15 @@ data Solution = Undefined
               | Unbounded
               deriving Show
             
-data Coeffs = Dense  [ Bound [Double] ]
-            | Sparse [ Bound [(Double,Int)] ]
+data Constraints = Dense  [ Bound [Double] ]
+                 | Sparse [ Bound [(Double,Int)] ]
 
 data Optimization = Maximize [Double]
                   | Minimize [Double]
 
-simplex :: Optimization -> Coeffs -> [Bound Int] -> Solution
+type Bounds = [Bound Int]
+
+simplex :: Optimization -> Constraints -> Bounds -> Solution
 
 simplex opt (Dense constr) bnds = extract sg sol where
     sol = simplexDense (mkConstrD objfun constr) (mkBoundsD constr bnds)