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


-- | Genetic algorithm library
--   
--   This package provides a framework for working with genetic algorithms.
--   A genetic algorithm is an evolutionary technique, inspired by
--   biological evolution, to evolve entities that perform as good as
--   possible in terms of a predefined criterion (the scoring function).
--   Note: lower scores are assumed to indicate better entities. The GA
--   module provides a type class for defining entities and the functions
--   that are required by the genetic algorithm. Checkpointing in between
--   generations is available, as is automatic restoring from the last
--   available checkpoint.
@package GA
@version 0.2


-- | GA, a Haskell library for working with genetic algoritms
--   
--   Aug. 2011 - Sept. 2011, by Kenneth Hoste
--   
--   version: 0.2
module GA

-- | Type class for entities that represent a candidate solution.
--   
--   Five parameters:
--   
--   <ul>
--   <li>data structure representing an entity (e)</li>
--   <li>score type (s), e.g. Double</li>
--   <li>data used to score an entity, e.g. a list of numbers (d)</li>
--   <li>some kind of pool used to generate random entities, e.g. a Hoogle
--   database (p)</li>
--   <li>monad to operate in (m)</li>
--   </ul>
--   
--   Minimal implementation includes genRandom, crossover, mutation, and
--   either score', score or scorePop.
class (Eq e, Read e, Show e, Ord s, Read s, Show s, Monad m) => Entity e s d p m | e -> s, e -> d, e -> p, e -> m
genRandom :: Entity e s d p m => p -> Int -> m e
crossover :: Entity e s d p m => p -> Float -> Int -> e -> e -> m (Maybe e)
mutation :: Entity e s d p m => p -> Float -> Int -> e -> m (Maybe e)
score' :: Entity e s d p m => d -> e -> (Maybe s)
score :: Entity e s d p m => d -> e -> m (Maybe s)
scorePop :: Entity e s d p m => d -> [e] -> [e] -> m (Maybe [Maybe s])
isPerfect :: Entity e s d p m => (e, s) -> Bool

-- | Configuration for genetic algorithm.
data GAConfig
GAConfig :: Int -> Int -> Int -> Float -> Float -> Float -> Float -> Bool -> Bool -> GAConfig

-- | population size
getPopSize :: GAConfig -> Int

-- | size of archive (best entities so far)
getArchiveSize :: GAConfig -> Int

-- | maximum number of generations to evolve
getMaxGenerations :: GAConfig -> Int

-- | fraction of entities generated by crossover (tip: &gt;= 0.80)
getCrossoverRate :: GAConfig -> Float

-- | fraction of entities generated by mutation (tip: &lt;= 0.20)
getMutationRate :: GAConfig -> Float

-- | parameter for crossover (semantics depend on crossover operator)
getCrossoverParam :: GAConfig -> Float

-- | parameter for mutation (semantics depend on mutation operator)
getMutationParam :: GAConfig -> Float

-- | enable/disable built-in checkpointing mechanism
getWithCheckpointing :: GAConfig -> Bool

-- | rescore archive in each generation?
getRescoreArchive :: GAConfig -> Bool

-- | Do the evolution!
evolve :: Entity e s d p m => StdGen -> GAConfig -> p -> d -> m [ScoredEntity e s]

-- | Do the evolution (supports checkpointing).
--   
--   Requires support for liftIO in monad used.
evolveVerbose :: (Entity e s d p m, MonadIO m) => StdGen -> GAConfig -> p -> d -> m [ScoredEntity e s]

-- | Random search.
--   
--   Useful to compare with results from genetic algorithm.
randomSearch :: Entity e s d p m => StdGen -> Int -> p -> d -> m [ScoredEntity e s]