chore: fix ci, haddocks, remove unused functions

Author: rasheedja

.github/workflows/haskell.yml

@@ -39,6 +39,9 @@ jobs:
       - name: Check cabal file
         run: nix develop --command make cabal-check
 
+      - name: Update cabal package index
+        run: nix develop --command make cabal-update
+
       - name: Configure the build
         run: nix develop --command make configure
 

.gitignore

@@ -4,3 +4,4 @@ dist-*/
 .vscode/*
 .direnv/*
 .envrc
+cabal.project.local

Makefile

@@ -14,6 +14,10 @@ format-check:
 cabal-check:
 	cabal check
 
+.PHONY: cabal-update
+cabal-update:
+	cabal update
+
 .PHONY: configure
 configure:
 	cabal configure --enable-tests --enable-benchmarks --disable-documentation
@@ -36,4 +40,4 @@ docs:
 	cabal haddock all --disable-documentation
 
 .PHONY: ci
-ci: format-check cabal-check configure deps build test docs
+ci: format-check cabal-check cabal-update configure deps build test docs

src/Linear/Simplex/Prettify.hs

@@ -18,7 +18,7 @@ import Data.Map qualified as M
 import Data.Ratio
 import Linear.Simplex.Types
 
--- | Convert a 'VarConstMap' into a human-readable 'String'
+-- | Convert a 'VarLitMapSum' into a human-readable 'String'
 prettyShowVarConstMap :: VarLitMapSum -> String
 prettyShowVarConstMap = aux . M.toList
   where

src/Linear/Simplex/Solver/TwoPhase.hs

@@ -10,7 +10,7 @@
 -- 'findFeasibleSolution' performs phase one of the two-phase simplex method.
 -- 'optimizeFeasibleSystem' performs phase two of the two-phase simplex method.
 -- 'twoPhaseSimplex' performs both phases of the two-phase simplex method.
--- 'twoPhaseSimplex'' performs both phases with variable domain support.
+-- 'twoPhaseSimplex' supports variable domains via its 'VarDomainMap' argument.
 module Linear.Simplex.Solver.TwoPhase
   ( findFeasibleSolution
   , optimizeFeasibleSystem
@@ -272,7 +272,7 @@ findFeasibleSolution unsimplifiedSystem = do
 
 -- | Optimize a feasible system by performing the second phase of the two-phase simplex method.
 --  We first pass an 'ObjectiveFunction'.
---  Then, the feasible system in 'DictionaryForm' as well as a list of slack variables, a list artificial variables, and the objective variable.
+--  Then, the feasible system in 'Dict' form as well as a list of slack variables, a list artificial variables, and the objective variable.
 --  Returns 'Optimal' with variable values if an optimal solution is found, or 'Unbounded' if the objective is unbounded.
 optimizeFeasibleSystem :: (MonadIO m, MonadLogger m) => ObjectiveFunction -> FeasibleSystem -> m OptimisationOutcome
 optimizeFeasibleSystem objFunction fsys@(FeasibleSystem {dict = phase1Dict, ..}) = do

src/Linear/Simplex/Types.hs

@@ -13,24 +13,14 @@ import Data.List (sort)
 import qualified Data.Map as M
 import GHC.Generics (Generic)
 
+-- | Variable identifier used in maps and constraints.
+-- Conventionally this maps to x1, x2, ... in examples.
 type Var = Int
 
+-- | Numeric type used throughout simplex computations.
 type SimplexNum = Rational
 
-type SystemRow = PolyConstraint
-
-type System = [SystemRow]
-
--- A 'Tableau' where the basic variable may be empty.
--- All non-empty basic vars are slack vars
-data SystemWithSlackVarRow = SystemInStandardFormRow
-  { mSlackVar :: Maybe Var
-  -- ^ This is Nothing iff the row does not have a slack variable
-  , row :: TableauRow
-  }
-
-type SystemWithSlackVars = [SystemWithSlackVarRow]
-
+-- | A feasible system produced by phase one, ready for phase two optimization.
 data FeasibleSystem = FeasibleSystem
   { dict :: Dict
   , slackVars :: [Var]
@@ -66,6 +56,7 @@ data SimplexResult = SimplexResult
   }
   deriving (Show, Read, Eq, Generic)
 
+-- | Mapping from variable id to its numeric value/coefficient.
 type VarLitMap = M.Map Var SimplexNum
 
 -- | List of variables with their 'SimplexNum' coefficients.
@@ -75,7 +66,7 @@ type VarLitMap = M.Map Var SimplexNum
 type VarLitMapSum = VarLitMap
 
 -- | For specifying constraints in a system.
---   The LHS is a 'Vars', and the RHS, is a 'SimplexNum' number.
+--   The LHS is a 'VarLitMapSum', and the RHS, is a 'SimplexNum' number.
 --   LEQ [(1, 2), (2, 1)] 3.5 is equivalent to 2x1 + x2 <= 3.5.
 --   Users must only provide positive integer variables.
 --
@@ -87,25 +78,18 @@ data PolyConstraint
   deriving (Show, Read, Eq, Generic)
 
 -- | Create an objective function.
---   We can either 'Max'imize or 'Min'imize a 'VarTermSum'.
+--   We can either 'Max'imize or 'Min'imize a 'VarLitMapSum'.
 data ObjectiveFunction = Max {objective :: VarLitMapSum} | Min {objective :: VarLitMapSum}
   deriving (Show, Read, Eq, Generic)
 
--- | TODO: Maybe we want this type
--- TODO: A better/alternative name
-data Equation = Equation
-  { lhs :: VarLitMapSum
-  , rhs :: SimplexNum
-  }
-
 -- | Value for 'Tableau'. lhs = rhs.
 data TableauRow = TableauRow
   { lhs :: VarLitMapSum
   , rhs :: SimplexNum
   }
   deriving (Show, Read, Eq, Generic)
 
--- | A simplex 'Tableu' of equations.
+-- | A simplex 'Tableau' of equations.
 --   Each entry in the map is a row.
 type Tableau = M.Map Var TableauRow
 
@@ -126,6 +110,9 @@ data DictValue = DictValue
 --   deriving (Show, Read, Eq, Generic)
 type Dict = M.Map Var DictValue
 
+-- | Objective row representation used during pivoting.
+-- 'variable' is the objective basic variable and 'function'/'constant' encode
+-- the objective in dictionary form.
 data PivotObjective = PivotObjective
   { variable :: Var
   , function :: VarLitMapSum

src/Linear/Simplex/Util.hs

@@ -30,7 +30,7 @@ isMax :: ObjectiveFunction -> Bool
 isMax (Max _) = True
 isMax (Min _) = False
 
--- | Simplifies a system of 'PolyConstraint's by first calling 'simplifyPolyConstraint',
+-- | Simplifies a system of 'PolyConstraint's,
 --  then reducing 'LEQ' and 'GEQ' with same LHS and RHS (and other similar situations) into 'EQ',
 --  and finally removing duplicate elements using 'nub'.
 simplifySystem :: [PolyConstraint] -> [PolyConstraint]
@@ -78,7 +78,7 @@ simplifySystem = nub . reduceSystem
             then EQ lhs rhs : reduceSystem pcs
             else EQ lhs rhs : reduceSystem (pcs \\ matchingConstraints)
 
--- | Converts a 'Dict' to a 'Tableau' using 'dictEntryToTableauEntry'.
+-- | Converts a 'Dict' to a 'Tableau'.
 --  FIXME: maybe remove this line. The basic variables will have a coefficient of 1 in the 'Tableau'.
 dictionaryFormToTableau :: Dict -> Tableau
 dictionaryFormToTableau =
@@ -130,17 +130,6 @@ combineVarLitMapSums =
     keepVal = const pure
     sumVals k v1 v2 = Just $ v1 + v2
 
-foldDictValue :: [DictValue] -> DictValue
-foldDictValue [] = error "Empty list of DictValues given to foldDictValue"
-foldDictValue [x] = x
-foldDictValue (DictValue {varMapSum = vm1, constant = c1} : DictValue {varMapSum = vm2, constant = c2} : dvs) =
-  let combinedDictValue =
-        DictValue
-          { varMapSum = foldVarLitMap [vm1, vm2]
-          , constant = c1 + c2
-          }
-  in  foldDictValue $ combinedDictValue : dvs
-
 foldVarLitMap :: [VarLitMap] -> VarLitMap
 foldVarLitMap [] = error "Empty list of VarLitMaps given to foldVarLitMap"
 foldVarLitMap [x] = x
@@ -158,7 +147,7 @@ foldVarLitMap (vm1 : vm2 : vms) =
                         (Just vm1VarVal, Just vm2VarVal) -> vm1VarVal + vm2VarVal
                         (Just vm1VarVal, Nothing) -> vm1VarVal
                         (Nothing, Just vm2VarVal) -> vm2VarVal
-                        (Nothing, Nothing) -> error "Reached unreachable branch in foldDictValue"
+                        (Nothing, Nothing) -> error "Reached unreachable branch in foldVarLitMap"
                     )
             )
             combinedVars
@@ -180,9 +169,3 @@ logMsg lvl msg = do
     LevelWarn -> $logWarn msgToLog
     LevelError -> $logError msgToLog
     LevelOther otherLvl -> error "logMsg: LevelOther is not implemented"
-
-extractTableauValues :: Tableau -> Map.Map Var SimplexNum
-extractTableauValues = Map.map (.rhs)
-
-extractDictValues :: Dict -> Map.Map Var SimplexNum
-extractDictValues = Map.map (.constant)