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


-- | Simple evolutionary algorithm framework.
--   
--   Simple framework for running an evolutionary algorithm by providing
--   selection, recombination, and mutation operators.
@package SimpleEA
@version 0.2


-- | A framework for simple evolutionary algorithms. Provided with a
--   function for evaluating a genome's fitness, a function for
--   probabilistic selection among a pool of genomes, and recombination and
--   mutation operators, <a>runEA</a> will run an EA that lazily produces
--   an infinite list of generations.
--   
--   <a>Utils</a> contains utilitify functions that makes it easier to
--   write the genetic operators.
module AI.SimpleEA

-- | Runs the evolutionary algorithm with the given start population. This
--   will produce an infinite list of generations and <a>take</a> or
--   <a>takeWhile</a> should be used to decide how many generations should
--   be computed. To run a specific number of generations, use <a>take</a>:
--   
--   <pre>
--   let generations = take 50 $ runEA myFF mySF myROp myMOp myStdGen
--   </pre>
--   
--   To run until a criterion is met, e.g. that an individual with a
--   fitness of at least 19 is found, <a>takeWhile</a> can be used:
--   
--   <pre>
--   let criterion   = any id . map (\i -&gt; snd i &gt;= 19.0)
--   let generations = takeWhile (not . criterion) $ runEA myFF mySF myROp myMOp myStdGen
--   </pre>
runEA :: [Genome a] -> FitnessFunc a -> SelectionFunction a -> RecombinationOp a -> MutationOp a -> PureMT -> [[(Genome a, Fitness)]]

-- | A fitness functions assigns a fitness score to a genome. The rest of
--   the individuals of that generation is also provided in case the
--   fitness is in proportion to its neighbours.
type FitnessFunc a = Genome a -> [Genome a] -> Fitness

-- | A selection function is responsible for selection. It takes pairs of
--   genomes and their fitness and is responsible for returning one or more
--   individuals.
type SelectionFunction a = [(Genome a, Fitness)] -> Rand PureMT [Genome a]

-- | A recombination operator takes two <i>parent</i> genomes and returns
--   two <i>children</i>.
type RecombinationOp a = (Genome a, Genome a) -> Rand PureMT (Genome a, Genome a)

-- | A mutation operator takes a genome and returns (a possibly altered)
--   copy of it.
type MutationOp a = Genome a -> Rand PureMT (Genome a)

-- | An individual's fitness is simply a number.
type Fitness = Double

-- | A genome is a list (e.g. a <a>String</a>).
type Genome a = [a]


-- | Utilitify functions that makes it easier to write the genetic
--   operators and functions for doing calculations on the EA data.
module AI.SimpleEA.Utils

-- | Returns the average fitnesses for a list of generations.
avgFitnesses :: [[(Genome a, Fitness)]] -> [Fitness]

-- | Returns the maximum fitness per generation for a list of generations.
maxFitnesses :: [[(Genome a, Fitness)]] -> [Fitness]

-- | Returns the minimum fitness per generation for a list of generations.
minFitnesses :: [[(Genome a, Fitness)]] -> [Fitness]

-- | Returns the standard deviation of the fitness values per generation
--   fot a list of generations.
stdDeviations :: [[(Genome a, Fitness)]] -> [Double]

-- | Returns a list of <tt>len</tt> random genomes who has length
--   <tt>genomeLen</tt> made of elements in the range <tt>[from,to]</tt>.
randomGenomes :: (RandomGen g, Random a, Enum a) => Int -> Int -> a -> a -> Rand g [Genome a]

-- | Fitness-proportionate selection: select a random item from a list of
--   (item, score) where each item's chance of being selected is
--   proportional to its score
fitPropSelect :: RandomGen g => [(a, Fitness)] -> Rand g a

-- | Performs tournament selection amoing <tt>size</tt> individuals and
--   returns the winner
tournamentSelect :: [(a, Fitness)] -> Int -> Rand PureMT a

-- | Applies sigma scaling to a list of fitness values. In sigma scaling,
--   the standard deviation of the population fitness is used to scale the
--   fitness scores.
sigmaScale :: [Fitness] -> [Fitness]

-- | Takes a list of fitness values and returns rank scaled values. For a
--   list of <i>n</i> values, this means that the best fitness is scaled to
--   <i>n</i>, the second best to <i>n-1</i>, and so on.
rankScale :: [Fitness] -> [Fitness]

-- | takes a list of (genome,fitness) pairs and returns a list of genomes
--   sorted by fitness (descending)
elite :: [(a, Fitness)] -> [a]

-- | takes a list of generations and returns a string intended for plotting
--   with gnuplot.
getPlottingData :: [[(Genome a, Fitness)]] -> String