-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A utility for computing distributions of material to review among reviewers.
--   
--   A utility for computing distributions of material to review among
--   reviewers. <tt>Referees</tt> takes into consideration the areas of
--   expertise of the referees, the number of items that they accept for
--   review, the languages they understand, and the minimum and maximum
--   number of copies we may want to distribute per each item to review.
@package Referees
@version 0.0.0


-- | Types and constructors for use in <a>Referees.Solver</a>.
module Referees.Solver.Types.Internal

-- | Represents the capacity of some bin.
type Capacity = Int

-- | Represents the number of copies to make of some item.
type Copies = Int

-- | Note that values of this type, when used to represent indices for a
--   <a>Matrix</a>, may not be directly usable with access functions from
--   <a>Data.Matrix</a>. This is due to the possibility of some conversion
--   between indices for <a>Matrix</a>s and <tt>[]</tt> having taken place
--   in their construction.
newtype Index a
Index :: Int -> Index a
_idx :: Index a -> Int
type Row = Index Row'
data Row'
type Col = Index Col'
data Col'
type Profit = Double
type ProfitMatrix = Matrix Profit
type ProfitFunction a b c = a -> b -> Maybe c -> Profit
data Bounds a
Bounds :: a -> a -> Bounds a
_lower :: Bounds a -> a
_upper :: Bounds a -> a

-- | This function creates a (<a>Maybe</a>) <a>Bounds</a> value, holding
--   both lower and upper bounds for an interval, after verifying that they
--   are consistent.
mkBounds :: (Num a, Ord a) => a -> a -> Maybe (Bounds a)
instance Show (Index a)
instance Read (Index a)
instance Eq (Index a)
instance Num (Index a)
instance Enum (Index a)
instance Eq a => Eq (Bounds a)
instance Show a => Show (Bounds a)


-- | This module contains the core functions used in solving the
--   Generalized Assignment Problem with the help of the GLPK toolkit.
module Referees.Solver.Internal

-- | <a>lpGAP</a> is based on Martello &amp; Toth 1990’s linear integer
--   programming formulation of the Generalized Assignment Problem (GAP).
--   This function, in addition, excludes all combinations whose profit is
--   <tt>0</tt>. <a>lpGAP</a> interfaces with the <a>GLPK</a> toolkit
--   through <tt>glpk-hs</tt>.
--   
--   In <a>lpGAP</a> <tt>profitM caps bounds</tt>, <tt>profitM</tt> is a
--   profit matrix (which can be computed by <a>mkProfitMatrix</a>, using a
--   <a>ProfitFunction</a>), <tt>caps</tt> stands for a list of items’
--   capacities (computable by <tt>toCap</tt>), and <tt>bounds</tt> encodes
--   in a <a>Bounds</a> <a>Copies</a> value (producible with
--   <tt>mkBounds</tt>) both the lower and upper bounds on the number of
--   copies to distribute per each item.
--   
--   <ul>
--   <li>Cf. Martello, S. and Toth, P.: <i>Knapsack Problems: Algorithms
--   and Computer</i> <i>Implementations</i>, ch. 7, John Wiley &amp; Sons,
--   1990.</li>
--   </ul>
lpGAP :: ProfitMatrix -> [Capacity] -> Bounds Copies -> LP String Double

-- | <tt><a>x</a> i j</tt>, for <tt>i = {1, …, m}</tt>, <tt>j = {1, …,
--   n}</tt>, where <tt>m</tt> stands for the number of items, and
--   <tt>n</tt> for the number of bins. These “variables” are to be used
--   only within the GAP formulation in <a>lpGAP</a>.
x :: Row -> Col -> String

-- | Objective function to maximize in <a>lpGAP</a>. It stands for the
--   overall profit accrued by a given distribution of items among bins.
--   
--   <ul>
--   <li>Cf. Martello, S. and Toth, P.: op. cit.</li>
--   </ul>
objFun :: ProfitMatrix -> LinFunc String Double

-- | Constraint function. It is used, in <a>lpGAP</a>, to specify the
--   capacity of each bin. Note that items are not divisible, and therefore
--   their cost, as detracted from a given bin’s capacity, is fixed at
--   <tt>1</tt>.
--   
--   <ul>
--   <li>Cf. Martello, S. and Toth, P.: op. cit.</li>
--   </ul>
subFunCap :: ProfitMatrix -> Col -> LinFunc String Double

-- | Constraint function. It is used, in <a>lpGAP</a>, to specify how many
--   copies of each item can be distributed.
--   
--   <ul>
--   <li>Cf. Martello, S. and Toth, P.: op. cit.</li>
--   </ul>
subFunMult :: ProfitMatrix -> Row -> LinFunc String Double

-- | Given a <a>ProfitFunction</a>, <a>mkProfitMatrix</a> computes a profit
--   matrix between <tt>bins</tt> and <tt>items</tt>, optionally taking a
--   <tt>quality</tt> as being by default shared between them. The values
--   in a <a>ProfitMatrix</a> serve to distribute items among bins
--   according to the capacities of the latter and the values of the
--   former.
mkProfitMatrix :: ProfitFunction a b c -> [a] -> [b] -> Maybe c -> ProfitMatrix

-- | Wrapper to use <a>matrix</a> with extra type safety.
safeMatrix :: Row -> Col -> ((Row, Col) -> Double) -> ProfitMatrix

-- | Wrapper to use <a>getElem</a> with extra type safety.
safeGetElem :: ProfitMatrix -> (Row, Col) -> Double

-- | Simple helper function to run the <tt>glpk-hs</tt> interface to GLPK,
--   as constructed with <a>lpGAP</a>. Takes the same arguments as
--   <a>lpGAP</a>.
run_lpGAP :: ProfitMatrix -> [Capacity] -> Bounds Copies -> IO (ReturnCode, Maybe (Double, Map String Double))

-- | <a>fromGLPKtoList</a> turns the (unIOd) output of <a>run_lpGAP</a>
--   into a more usable format.
fromGLPKtoList :: (ReturnCode, Maybe (Double, Map String Double)) -> Maybe [(Col, Row)]


-- | This module reexports some types and functions from
--   <a>Referees.Solver.Types.Internal</a>.
module Referees.Solver.Types

-- | Note that values of this type, when used to represent indices for a
--   <a>Matrix</a>, may not be directly usable with access functions from
--   <a>Data.Matrix</a>. This is due to the possibility of some conversion
--   between indices for <a>Matrix</a>s and <tt>[]</tt> having taken place
--   in their construction.
newtype Index a
Index :: Int -> Index a
_idx :: Index a -> Int
type Row = Index Row'
type Col = Index Col'
type ProfitFunction a b c = a -> b -> Maybe c -> Profit
type ProfitMatrix = Matrix Profit
data Bounds a

-- | This function creates a (<a>Maybe</a>) <a>Bounds</a> value, holding
--   both lower and upper bounds for an interval, after verifying that they
--   are consistent.
mkBounds :: (Num a, Ord a) => a -> a -> Maybe (Bounds a)

-- | Represents the capacity of some bin.
type Capacity = Int

-- | Represents the number of copies to make of some item.
type Copies = Int


-- | Types and constructors for use in <a>Referees</a>.
module Referees.Types.Internal
type Name = String
type Language = String
type Area = String
type Subarea = String
data Entry subtype
Entry :: Name -> Maybe Capacity -> [Language] -> [(Area, [Subarea])] -> Entry subtype
_name :: Entry subtype -> Name
_capacity :: Entry subtype -> Maybe Capacity
_languages :: Entry subtype -> [Language]
_areas :: Entry subtype -> [(Area, [Subarea])]
data Referee
Referee :: Referee
data Proposal
Proposal :: Proposal
type Match = (Entry Referee, [Entry Proposal])

-- | For warning about issues that may take place during parsing.
data CSV_Warning
DifferingCapacities :: Name -> CSV_Warning
newtype StringListParse sep
StrLstP :: [String] -> StringListParse sep
_strLstP :: StringListParse sep -> [String]
data Semicolon
Semicolon :: Semicolon
newtype MaybeCapacityParse
MaybeCapP :: Maybe Capacity -> MaybeCapacityParse
_maybeCapP :: MaybeCapacityParse -> Maybe Capacity

-- | This type and its <a>FromField</a> instance declarations are used to
--   describe the parsing rules for reconstruction of <a>Entry</a> values
--   from CSV files.
--   
--   The two <a>FromField</a> instance declarations here (vid. source)
--   enable silent conditional parsing of the second field in a CSV file
--   with 4 fields. In this scenario, if the second field is parseable as
--   <a>Int</a>, it is parsed as <a>MaybeCapacityParse</a> (a wrapper for
--   <a>Maybe</a> <a>Capacity</a>); otherwise, as <a>StringListParse</a>
--   <a>Semicolon</a> (a wrapper for <tt>[<a>String</a>]</tt>).
data CSVentry
CSVentry :: !Name -> !MaybeCapacityParse -> !(StringListParse Semicolon) -> !Area -> !(StringListParse Semicolon) -> CSVentry
_nameCSV :: CSVentry -> !Name
_capacityCSV :: CSVentry -> !MaybeCapacityParse
_languagesCSV :: CSVentry -> !(StringListParse Semicolon)
_areaCSV :: CSVentry -> !Area
_subareasCSV :: CSVentry -> !(StringListParse Semicolon)
instance Eq (Entry subtype)
instance Show (Entry subtype)
instance Eq (StringListParse sep)
instance Show (StringListParse sep)
instance Eq MaybeCapacityParse
instance Show MaybeCapacityParse
instance FromRecord CSVentry
instance FromField MaybeCapacityParse
instance FromField (StringListParse Semicolon)


-- | This module reexports some functions from
--   <a>Referees.Solver.Internal</a>.
module Referees.Solver

-- | Given a <a>ProfitFunction</a>, <a>mkProfitMatrix</a> computes a profit
--   matrix between <tt>bins</tt> and <tt>items</tt>, optionally taking a
--   <tt>quality</tt> as being by default shared between them. The values
--   in a <a>ProfitMatrix</a> serve to distribute items among bins
--   according to the capacities of the latter and the values of the
--   former.
mkProfitMatrix :: ProfitFunction a b c -> [a] -> [b] -> Maybe c -> ProfitMatrix

-- | Simple helper function to run the <tt>glpk-hs</tt> interface to GLPK,
--   as constructed with <a>lpGAP</a>. Takes the same arguments as
--   <a>lpGAP</a>.
run_lpGAP :: ProfitMatrix -> [Capacity] -> Bounds Copies -> IO (ReturnCode, Maybe (Double, Map String Double))

-- | <a>fromGLPKtoList</a> turns the (unIOd) output of <a>run_lpGAP</a>
--   into a more usable format.
fromGLPKtoList :: (ReturnCode, Maybe (Double, Map String Double)) -> Maybe [(Col, Row)]


-- | This module defines the functions needed to specialize
--   <a>Referees.Solver</a> to the problem of assigning proposals among
--   referees.
module Referees.Internal

-- | Parses from a CSV file into <a>Entry</a> <a>Referee</a> values.
fromCSVtoReferees :: FilePath -> IO [Entry Referee]

-- | Parses from a CSV file into <a>Entry</a> <a>Proposal</a> values.
fromCSVtoProposals :: FilePath -> IO [Entry Proposal]

-- | Taking the path to some CSV file in the appropriate format, parses it
--   into values of type <a>Entry</a> <tt>a</tt>. This function is intended
--   to be used with wrappers that specialize <tt>a</tt> to some concrete
--   type.
fromCSVtoEntry :: FilePath -> IO [Entry a]

-- | Parses CSV files into <a>CSVentry</a>s, according to the format
--   described in <a>Referees</a>.
--   
--   The parser is defined at the <tt>FromField</tt> instance declarations
--   in <a>Referees.Types.Internal</a>.
readCSVentries :: FilePath -> IO [CSVentry]

-- | <a>distributeWith</a> computes a distribution of proposals among
--   referees, according to the given parameters.
distributeWith :: ProfitFunction (Entry Proposal) (Entry Referee) Language -> [Entry Referee] -> Capacity -> Bounds Copies -> Maybe Language -> [Entry Proposal] -> IO (Maybe [Match])

-- | Computes the profit for an assignment between the given <a>Entry</a>
--   <a>Proposal</a> and <a>Entry</a> <a>Referee</a>. The scale is
--   continuous in [0,2]. Takes understood languages into account.
profitRefProp :: ProfitFunction (Entry Proposal) (Entry Referee) Language

-- | This list is used to bias the profit associated with <tt>Area</tt>s
--   and <tt>Subarea</tt>s matches according to their order in the
--   corresponding <a>Entry</a>s.
logBias :: [Double]

-- | <a>toCap</a> <tt>rs def</tt> builds a list of capacities matching the
--   <a>Referee</a>s in <tt>rs</tt>, while assigning default capacity
--   <tt>def</tt> to those <a>Referee</a>s that don’t have one defined.
toCap :: [Entry Referee] -> Capacity -> [Capacity]

-- | Provides a list of all <a>Referee</a>s suited for a <a>Proposal</a>,
--   regardless of any distribution.
whichRefereesForProposal :: Entry Proposal -> [Entry Referee] -> Maybe Language -> [Entry Referee]

-- | Provides a list of all <a>Proposal</a>s suited for a <a>Referee</a>,
--   regardless of any distribution.
whichProposalsForReferee :: Entry Referee -> [Entry Proposal] -> Maybe Language -> [Entry Proposal]

-- | Concise printing of assignments. Ignores <a>Entry</a> <a>Referee</a>s
--   for which there are no assigned <a>Entry</a> <a>Proposal</a>s.
ppDistribution :: Maybe [Match] -> String
ppReferee :: Entry Referee -> String
ppProposal :: Entry Proposal -> String
ppEntry :: Entry a -> String

-- | Pretty prints the given matrix, converting its values to 2-digit
--   precision. This is currently used only in debug.
ppMatrix :: Matrix Double -> String
ppCSV_Warning :: CSV_Warning -> String
ppNames :: [Name] -> String

-- | This function creates a (<a>Maybe</a>) <a>Bounds</a> value, holding
--   both lower and upper bounds for an interval, after verifying that they
--   are consistent.
mkBounds :: (Num a, Ord a) => a -> a -> Maybe (Bounds a)


-- | This module reexports some types and functions from
--   <a>Referees.Types.Internal</a>.
module Referees.Types
type Name = String
type Language = String
type Area = String
type Subarea = String
data Entry subtype
Entry :: Name -> Maybe Capacity -> [Language] -> [(Area, [Subarea])] -> Entry subtype
_name :: Entry subtype -> Name
_capacity :: Entry subtype -> Maybe Capacity
_languages :: Entry subtype -> [Language]
_areas :: Entry subtype -> [(Area, [Subarea])]
data Referee
data Proposal
type Match = (Entry Referee, [Entry Proposal])


-- | Utility for computing distributions of material to review among
--   reviewers.
--   
--   Example of use:
--   
--   <ul>
--   <li>First, load the CSV files representing referees and
--   proposals:</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; referees &lt;- fromCSVtoReferees "referees.csv"
--   
--   &gt;&gt;&gt; proposals &lt;- fromCSVtoProposals "proposals.csv"
--   </pre>
--   
--   Each line in these files obeys the following format:
--   
--   <pre>
--   <a>Name</a>,<tt>Capacity</tt>,<a>Language</a>;…;<a>Language</a>,<a>Area</a>,<a>Subarea</a>;…;<a>Subarea</a>
--   </pre>
--   
--   <a>Area</a> and <a>Subarea</a> fields can be empty but they must be
--   present. <tt>Capacity</tt> and <a>Language</a> fields are optional. If
--   only one of them is included, the parser will detect which one on the
--   basis of whether it contains digits.
--   
--   If there are many areas (and corresponding subareas) for some
--   <a>Name</a>, these go in different lines, as in the following example:
--   
--   <pre>
--   RefereeA,3,Spanish,Metaphysics,Identity
--   RefereeA,Greek,Aesthetics
--   RefereeB,1,PoliticalPhilosophy,State;Justice
--   RefereeC,Catalan,PhilosophyOfMind,Perception
--   </pre>
--   
--   <ul>
--   <li>Then, use the <a>distributeWith</a> function; the
--   <tt>ProfitFunction</tt> used in the example is provided by the
--   library:</li>
--   </ul>
--   
--   <pre>
--   &gt;&gt;&gt; let Just bnds = mkBounds 1 3
--   
--   &gt;&gt;&gt; match &lt;- distributeWith profitRefProp referees 3 bnds (Just "Greek") proposals
--   </pre>
--   
--   Now you can pretty print the outcome:
--   
--   <pre>
--   &gt;&gt;&gt; putStr $ ppDistribution match
--   </pre>
module Referees

-- | Parses from a CSV file into <a>Entry</a> <a>Referee</a> values.
fromCSVtoReferees :: FilePath -> IO [Entry Referee]

-- | Parses from a CSV file into <a>Entry</a> <a>Proposal</a> values.
fromCSVtoProposals :: FilePath -> IO [Entry Proposal]

-- | <a>distributeWith</a> computes a distribution of proposals among
--   referees, according to the given parameters.
distributeWith :: ProfitFunction (Entry Proposal) (Entry Referee) Language -> [Entry Referee] -> Capacity -> Bounds Copies -> Maybe Language -> [Entry Proposal] -> IO (Maybe [Match])

-- | Computes the profit for an assignment between the given <a>Entry</a>
--   <a>Proposal</a> and <a>Entry</a> <a>Referee</a>. The scale is
--   continuous in [0,2]. Takes understood languages into account.
profitRefProp :: ProfitFunction (Entry Proposal) (Entry Referee) Language

-- | This function creates a (<a>Maybe</a>) <a>Bounds</a> value, holding
--   both lower and upper bounds for an interval, after verifying that they
--   are consistent.
mkBounds :: (Num a, Ord a) => a -> a -> Maybe (Bounds a)

-- | Provides a list of all <a>Referee</a>s suited for a <a>Proposal</a>,
--   regardless of any distribution.
whichRefereesForProposal :: Entry Proposal -> [Entry Referee] -> Maybe Language -> [Entry Referee]

-- | Provides a list of all <a>Proposal</a>s suited for a <a>Referee</a>,
--   regardless of any distribution.
whichProposalsForReferee :: Entry Referee -> [Entry Proposal] -> Maybe Language -> [Entry Proposal]

-- | Concise printing of assignments. Ignores <a>Entry</a> <a>Referee</a>s
--   for which there are no assigned <a>Entry</a> <a>Proposal</a>s.
ppDistribution :: Maybe [Match] -> String