wallace 0.0.0

data/lib/core/evaluator.rb

@@ -0,0 +1,52 @@
+# The evaluator is responsible for determining the fitness of given individuals within the
+# population. An evaluation function is provided to each evaluator which produces a fitness
+# measure object for a given individual.
+class Wallace::Evaluator
+
+  attr_reader :threads
+
+  # Constructs a new evaluator.
+  # Attach the given fitness calculation method to the evaluate method of this
+  # evaluator.
+  #
+  # *Parameters:*
+  # * opts, a hash of keyword options for this evaluator.
+  #   -> threads, the number of threads that evaluation should be split across.
+  # * f, function to calculate and return the fitness of a given individual.
+  def initialize(opts = {}, &f)
+    @threads = opts[:threads] || 1
+    define_singleton_method(:evaluate, &f)
+  end
+
+  # Evaluates all given individuals within a population.
+  # If multi-threading is enabled then individuals are split into equal (as possible)
+  # chunks. For now concurrency has not been implemented, and will be thought about
+  # in more detail in a future version.
+  #
+  # *Parameters:*
+  # * rng, random number generator to use during evaluation.
+  # * population, the population of individuals to evaluate.
+  def process!(rng, population)
+    population.subpopulations.each do |s|
+      if @threads > 1
+        s.contents.peach(@threads) { |i| i.fitness = evaluate(rng, i) }
+      else
+        s.contents.each { |i| i.fitness = evaluate(rng, i) }
+      end
+    end
+
+    # Should we find the best and worst individuals in each sub-population?
+
+  end
+
+  # Evaluates a given individual and returns their fitness score.
+  # Should not modify the providied individual.
+  #
+  # *Parameters:*
+  # * rng, random number generator to use during evaluation.
+  # * individual, the individual whose fitness should be calculated.
+  def evaluate(rng, individual)
+    raise NotImplementedError, 'No evaluation function was provided to this evaluator.'
+  end
+
+end

data/lib/core/evolver.rb

@@ -0,0 +1,47 @@
+# Steady-state vs. Generational
+class Wallace::Evolver
+
+  # Constructs a new evolver.
+  #
+  # *Parameters:*
+  # * rng, the random number generator to use for stochastic processes.
+  # * population, the population to evolve.
+  # * evaluator, the evaluator to use to determine the fitness of individuals. 
+  # * breeder, the breeder to use to create individuals for successive generations.
+  # * migrator, the migrator to use to exchange individuals between sub-populations.
+  # * termination, the termination criteria for the evolution.
+  def initialize(rng, population, evaluator, termination)
+    @rng = rng
+    @population = population
+    @evaluator = evaluator
+    @termination = termination
+    @evaluator = evaluator
+    @state = nil
+  end
+
+  # Conducts the described evolutionary algorithm until the termination criteria is met.
+  # Upon meeting the termination criteria, the best individual found from the entire run
+  # is returned.
+  def evolve
+
+    # Initialise and evaluate the population.
+    @population.fresh!(@rng)
+    @evaluator.process!(@rng, @population)
+    @state = Wallace::State.new(@population)
+
+    # Continue the evolution unless the termination condition has been met.
+    until @termination.finished?(@state)
+      @migrator.migrate!(@rng, @population) unless @migrator.nil?
+      @population.breed!(@rng)
+      @evaluator.process!(@rng, @population)
+      @state.next!
+      #puts "#{@state.best.to_s} = #{@state.best.fitness.value}"
+      puts "#{@state.generations}: #{@state.best.fitness.value} (#{@state.best.data.length})"
+    end
+
+    # Return the best individual from the run.
+    return @state.best
+
+  end
+
+end

data/lib/core/exceptions.rb

@@ -0,0 +1,6 @@
+module Wallace::Errors
+
+  # Thrown when all genetic material has been used.
+  class GenotypeExhaustedError < StandardError; end
+
+end

data/lib/core/experiment.rb

@@ -0,0 +1,22 @@
+# Experiment instances are used to
+class Wallace::Experiment
+
+  # Constructs a new experiment.
+  #
+  # *Parameters:*
+  # * opts, a hash of keyword options for this constructor.
+  #   -> parameters, the set of parameters to feed to the configurator.
+  #   -> repeats, the number of times to repeat the experiment.
+  # * configurator, a lambda function used to setup the experiment run according to
+  #   some given parameters.
+  def initialize(opts, configurator)
+    @parameters = opts[:parameters]
+    @repeats = opts[:repeats] || 1
+  end
+
+  # Performs the experiment described by this objects attributes.
+  def experiment
+
+  end
+
+end

data/lib/core/fitness.rb

@@ -0,0 +1,8 @@
+# The base fitness measure class. Fitness objects are responsible for storing
+# fitness details for a given individual and should implement ordering
+# functionality such that they can be compared and sorted.
+class Wallace::Fitness
+
+  include Comparable
+
+end

data/lib/core/fraction.rb

@@ -0,0 +1,7 @@
+# Instances of the fraction class are used to disambiguate if a given float
+# should be treated as an absolute value or rather a fraction of some other
+# (implicit) value.
+#
+# If the Fraction class is not used, it is assumed that a given number is an
+# absolute number (in a context-sensitive environment).
+Wallace::Fraction = Struct.new(:value)

data/lib/core/individual.rb

@@ -0,0 +1,65 @@
+# This class is the base class used to represent individuals within the population.
+# The data (e.g. list, tree, string) for an individual is held within its data attribute.
+class Wallace::Individual
+
+  include Comparable
+
+  # Neither the species nor the data of the individual may be modified
+  # once the individual has been created.
+  attr_accessor :species,
+                :data
+
+  # Allow the fitness of the individual to be both read and written to.
+  attr_accessor :fitness
+
+  # Constructs a new individual.
+  #
+  # *Parameters:*
+  # * species, the species of the individual.
+  # * data, the data for this individual.
+  # * opts, keyword arguments for this constructor.
+  # * -> fitness, the fitness object for this individual (keyword).
+  def initialize(species, data, opts = {})
+    @species = species
+    @fitness = nil
+    @data = data
+    @fitness = opts[:fitness]
+  end
+
+  # Checks whether this individual has been evaluated.
+  # Returns true if it has, false if otherwise.
+  def evaluated?
+    return (not @fitness.nil?)
+  end
+
+  # Post-processes this individual.
+  # Returns the post-processed individual.
+  def finish!
+    @species.finish!(self)
+  end
+
+  # Compares the fitness of this individual against that of another.
+  #
+  # *Parameters:*
+  # * other, the individual to compare against.
+  def <=>(other)
+    @fitness <=> other.fitness
+  end
+
+  # Creates a clone of this individual.
+  #
+  # *Parameters:*
+  # * opts, keyword arguments for this method.
+  # * -> copy_fitness, flag indicating whether fitness information should be copied across
+  #   to the cloned individual.
+  def clone(opts = {})
+    copy_fitness = opts[:copy_fitness]
+    return Wallace::Individual.new(species, data.clone, fitness: copy_fitness ? fitness : nil)
+  end
+
+  # Produces a string representation of this individual.
+  def to_s
+    return @data.to_s
+  end
+
+end

data/lib/core/logger.rb

@@ -0,0 +1,5 @@
+# 
+class Wallace::Logger < Wallace::Analyser
+
+
+end

data/lib/core/migrator.rb

@@ -0,0 +1,6 @@
+# The migrator is responsible for migrating (exchanging) individuals between
+# connected sub-populations.
+class Wallace::Migrator
+
+
+end

data/lib/core/operator.rb

@@ -0,0 +1,54 @@
+# Operators are used to produce individuals for the next generation using
+# members of the current population as their inputs.
+#
+# TODO: Feed state data into the operator (size of population, fitness, generations, etc).
+class Wallace::Operator
+
+  # Using meta-methods to give the operator a name/tag that
+  # can be used to refer to it within the DSL or command line.
+  class << self
+    attr_accessor :name
+  end
+
+  # Constructs an instance of an Operator.
+  #
+  # *Parameters:*
+  # * opts, a hash of keyword options for this method.
+  #   -> id, the unique identifier for this operator.
+  def initialize(opts = {})
+    @id = opts[:id]
+  end
+
+  # Produces an arbitrary number of individuals according to the rules of this operator
+  # using 
+  #
+  # *Parameters:*
+  # * rng, random number generator to use within the operation.
+  # * inputs, input individuals to the operation.
+  #
+  # *Returns:*
+  # An array of the offspring individuals produced by this operation.
+  def produce(rng, inputs)
+    operate(rng, inputs.map { |i| i.data }).each_with_index do |data, i|
+      inputs[i].data = data
+    end
+    return inputs
+  end
+
+  # Performs this genetic operation on the genetic data of a given number of individuals
+  # to return the genetic data for their offspring.
+  #
+  # Unlike 'produce', this method operates only on the genetic data (we refrain from the
+  # term chromosome since an individual may have multiple chromosomes).
+  #
+  # *Parameters:*
+  # * rng, the RNG to use within this operation.
+  # * inputs, input individuals to the operation.
+  #
+  # *Returns:*
+  # An array containing the genetic data for each produced offspring.
+  def operate(rng, inputs)
+    raise NotImplementedError, "No 'operate' function was implemented by this operator."
+  end
+
+end

data/lib/core/population.rb

@@ -0,0 +1,56 @@
+# In this current version of Wallace each population may only hold individuals of a single
+# species. For future versions supporting co-operative and competitive evolution it should
+# be able to adapt the population model to fit.
+class Wallace::Population
+
+  attr_reader :subpopulations
+
+  # Constructs a new population.
+  #
+  # *Parameters:*
+  # * breeder, the breeder used to generate individuals for successive generations.
+  # * subpopulations, a list of subpopulations contained within this population.
+  def initialize(breeder, subpopulations)
+    @breeder = breeder
+    @subpopulations = subpopulations
+  end
+
+  # Clears the contents of each sub-population within this population and resets all
+  # attached components.
+  def clear!
+    @subpopulations.each { |s| s.clear }
+  end
+
+  # Initialises a fresh population of individuals.
+  #
+  # *Parameters:*
+  # * rng, the random number generator to use.
+  def fresh!(rng)
+    @subpopulations.each { |s| s.fresh!(rng) }
+  end
+
+  # Breeds the next generation of individuals for this population.
+  #
+  # *Parameters:*
+  # * rng, random number generator to use during breeding.
+  def breed!(rng)
+    @subpopulations.each { |s| @breeder.breed!(rng, s) }
+  end
+
+  # Selects the best individual from the current population.
+  def best
+    @subpopulations.map { |s| s.best }.min
+  end
+
+  # Selects the worst individual from the current population.
+  def worst
+    @subpopulations.map { |s| s.worst }.max
+  end
+
+  # Calculates the combined size (number of individuals) of this population.
+  def size
+    @subpopulations.reduce(0) { |sum, sp| sum += sp.length }
+  end
+  alias_method :length, :size
+
+end

data/lib/core/selector.rb

@@ -0,0 +1,43 @@
+# Selectors are used to select individuals from a set of candidates (usually, but not exclusively
+# the sub-population) as participants in the breeding process.
+#
+# Different selector classes are used to implement different types of selection rules.
+# 
+# A "prepare" method is provided to allow the list of candidates to be pre-processed, saving time
+# for selection methods such as roulette selection.
+class Wallace::Selector
+
+  class << self
+    attr_accessor :name
+  end
+
+  # Prepares a list of candidates for use with this selector.
+  # Pre-processing can be performed on this list to improve performance.
+  # The list of candidates is not stored by the selector, instead it is stored
+  # by an associated input node.
+  #
+  # *Parameters:*
+  # * candidates, the list of candidates to select from.
+  # * opts, a hash of keyword options for this method.
+  #   -> random, random number generator to use in pre-processing of candidates.
+  #
+  # *Returns:*
+  # A prepared list of candidates for use with this selector.
+  def prepare(candidates, opts = {})
+    candidates
+  end
+
+  # Selects a single individual from the list of prepared candidates according
+  # to the rules of this selection method.
+  #
+  # *Parameters:*
+  # * rng, the RNG to use to inform the choice of candidate.
+  # * candidates, the candidate individuals for selection.
+  #
+  # *Returns:*
+  # A selected individual from the list of candidates.
+  def produce(rng, candidates)
+    raise NotImplementedError, 'No produce function was implemented by this selector.'
+  end
+
+end

data/lib/core/species.rb

@@ -0,0 +1,52 @@
+# Each individual in the population must belong to a single species.
+class Wallace::Species
+
+  attr_reader :id
+
+  class << self
+    attr_accessor :name
+  end
+
+  # Creates a new Species.
+  #
+  # *Parameters:*
+  # * opts, hash of keyword options used by this method.
+  #   -> id, the unique identifier for this species.
+  def initialize(opts)
+    @id = opts[:id]
+  end
+
+  # Determines whether a given individual is a valid member of this species.
+  # Validity may be determined by more than just membership. For example,
+  # there may be certain size constraints on individuals.
+  #
+  # *Parameters:*
+  # * individual, the individual to check for validity.
+  #
+  # *Returns:*
+  # true if a valid member of this species, false if invalid or not a member.
+  def valid?(individual)
+    individual.species === self
+  end
+
+  # Spawns a new member of this species at random.
+  #
+  # *Parameters:*
+  # * rng, the random number generator to use.
+  def spawn(rng)
+    raise NotImplementedError, 'Spawn method not implemented by this species.'
+  end
+
+  # Used to post-process individuals belonging to this species after they have
+  # been created. By default this method is a stub.
+  #
+  # *Parameters:*
+  # * individual, the individual to post-process.
+  #
+  # *Returns:*
+  # * the post-processed individual.
+  def finish!(individual)
+    individual
+  end
+
+end

data/lib/core/state.rb

@@ -0,0 +1,29 @@
+# This class is used to record information about the state of the evolution.
+class Wallace::State
+
+  # Allow all information to be read, but not changed.
+  attr_reader :population,
+              :generations,
+              :stagnation,
+              :best
+
+  # Constructs a new state object.
+  #
+  # *Parameters*
+  # * population, the population of the state.
+  def initialize(population)
+    @population = population
+    @generations = 0
+    @stagnation = 0
+    @best = population.best
+  end
+
+  # Updates the state object with the current state of the evolver.
+  def next!
+    @generations += 1
+    @stagnation += 1
+    pbest = population.best
+    @best = pbest if pbest < @best
+  end
+
+end