evolvable 0.1.3 → 1.1.0

data/lib/evolvable/population.rb

@@ -1,119 +1,238 @@
 # frozen_string_literal: true
 
 module Evolvable
+  #
+  # @readme
+  #   Population objects are responsible for generating and evolving instances.
+  #   They orchestrate all the other Evolvable objects to do so.
+  #
+  #   Populations can be initialized and re-initialized with a number of useful
+  #   parameters.
+  #
+  # @example
+  #   # TODO: initialize a population with all supported parameters
   class Population
     extend Forwardable
 
-    def initialize(evolvable_class:,
-                   size: 20,
-                   selection_count: 2,
-                   crossover: Crossover.new,
-                   mutation: Mutation.new,
-                   generation_count: 0,
-                   log_progress: false,
-                   objects: [])
-      @evolvable_class = evolvable_class
+    def self.load(data)
+      dump_attrs = Serializer.load(data)
+      new(**dump_attrs)
+    end
+
+    # Initializes an Evolvable::Population.
+    # Keyword arguments:
+    # #### evolvable_class
+    # Required. Implicitly specified when using EvolvableClass.new_population.
+    # #### id, name
+    # Both default to `nil`. Not used by Evolvable, but convenient when working
+    # with multiple populations.
+    # #### size
+    # Defaults to `40`. Specifies the number of instances in the population.
+    # #### evolutions_count
+    # Defaults to `0`. Useful when re-initializing a saved population with instances.
+    # #### search_space
+    # Defaults to `evolvable_class.new_search_space` which uses the
+    # [EvolvableClass.search_space](#evolvableclasssearch_space) method
+    # #### evolution
+    # Defaults to `Evolvable::Evolution.new`. See [evolution](#evolution-1)
+    # #### evaluation
+    # Defaults to `Evolvable::Evaluation.new`, with a goal of maximizing
+    # towards Float::INFINITY. See [evaluation](#evaluation-1)
+    # #### instances
+    # Defaults to initializing a `size` number of `evolvable_class`
+    # instances using the `search_space` object. Any given instances
+    # are assigned, but if given less than `size`, more will be initialized.
+    #
+    def initialize(evolvable_type: nil,
+                   evolvable_class: nil, # Deprecated
+                   id: nil,
+                   name: nil,
+                   size: 40,
+                   evolutions_count: 0,
+                   gene_space: nil, # Deprecated
+                   search_space: nil,
+                   parent_evolvables: [],
+                   evaluation: Evaluation.new,
+                   evolution: Evolution.new,
+                   selection: nil,
+                   combination: nil,
+                   mutation: nil,
+                   evolvables: [])
+      @id = id
+      @evolvable_type = evolvable_type || evolvable_class
+      @name = name
       @size = size
-      @selection_count = selection_count
-      @crossover = crossover
-      @mutation = mutation
-      @generation_count = generation_count
-      @log_progress = log_progress
-      assign_objects(objects)
+      @evolutions_count = evolutions_count
+      @search_space = initialize_search_space(search_space || gene_space)
+      @parent_evolvables = parent_evolvables
+      self.evaluation = evaluation
+      @evolution = evolution
+      self.selection = selection if selection
+      self.combination = combination if combination
+      self.mutation = mutation if mutation
+      @evolvables = new_evolvables(count: @size - evolvables.count, evolvables: evolvables)
     end
 
-    attr_accessor :evolvable_class,
+    attr_accessor :id,
+                  :evolvable_type,
+                  :name,
                   :size,
-                  :selection_count,
-                  :crossover,
-                  :mutation,
-                  :generation_count,
-                  :log_progress,
-                  :objects
-
-    def_delegators :@evolvable_class,
-                   :evolvable_evaluate!,
-                   :evolvable_initialize,
-                   :evolvable_random_genes,
-                   :evolvable_before_evolution,
-                   :evolvable_after_select,
-                   :evolvable_after_evolution
-
-    def evolve!(generations_count: 1, fitness_goal: nil)
-      @fitness_goal = fitness_goal
-      generations_count.times do
-        @generation_count += 1
-        evolvable_before_evolution(self)
-        evaluate_objects!
-        log_evolvable_progress if log_progress
-        break if fitness_goal_met?
-
-        select_objects!
-        evolvable_after_select(self)
-        crossover_objects!
-        mutate_objects!
-        evolvable_after_evolution(self)
+                  :evolutions_count,
+                  :search_space,
+                  :evolution,
+                  :parent_evolvables,
+                  :evolvables
+
+    def_delegators :evolvable_class,
+                   :before_evaluation,
+                   :before_evolution,
+                   :after_evolution
+
+    def_delegators :evolution,
+                   :selection,
+                   :selection=,
+                   :combination,
+                   :combination=,
+                   :mutation,
+                   :mutation=
+
+    def_delegator :selection, :size, :selection_size
+    def_delegator :selection, :size=, :selection_size=
+
+    def_delegator :mutation, :rate, :mutation_rate
+    def_delegator :mutation, :rate=, :mutation_rate=
+    def_delegator :mutation, :probability, :mutation_probability
+    def_delegator :mutation, :probability=, :mutation_probability=
+
+    attr_reader :evaluation
+
+    def evaluation=(val)
+      @evaluation = Evolvable.new_object(@evaluation, val, Evaluation)
+    end
+
+    def_delegators :evaluation,
+                   :goal,
+                   :goal=
+
+    #
+    #  Keyword arguments:
+    #
+    #  #### count
+    #  The number of evolutions to run. Expects a positive integer
+    #  and Defaults to Float::INFINITY and will therefore run indefinitely
+    #  unless a `goal_value` is specified.
+    #  #### goal_value
+    #  Assigns the goal object's value. Will continue running until any
+    #  instance's value reaches it. See [evaluation](#evaluation-1)
+    #
+    #  ### Evolvable::Population#best_instance
+    #  Returns an instance with the value that is nearest to the goal value.
+    #
+    #  ### Evolvable::Population#met_goal?
+    #  Returns true if any instance's value matches the goal value, otherwise false.
+    #
+    #  ### Evolvable::Population#new_instance
+    #  Initializes an instance for the population. Note that this method does not
+    #  add the new instance to its array of instances.
+    #
+    #  Keyword arguments:
+    #
+    #  #### genes
+    #  An array of initialized gene objects. Defaults to `[]`
+    #  #### population_index
+    #  Defaults to `nil` and expects an integer.
+    #
+    # See (EvolvableClass#population_index)[#evolvableclasspopulation_index-population_index]
+    #
+    def evolve(count: Float::INFINITY, goal_value: nil)
+      goal.value = goal_value if goal_value
+      1.upto(count) do
+        before_evaluation(self)
+        evaluation.call(self)
+        before_evolution(self)
+        break if met_goal?
+
+        evolution.call(self)
+        self.evolutions_count += 1
+        after_evolution(self)
       end
     end
 
-    def strongest_object
-      objects.max_by(&:fitness)
+    def best_evolvable
+      evaluation.best_evolvable(self)
     end
 
-    def evaluate_objects!
-      evolvable_evaluate!(@objects)
-      if @fitness_goal
-        @objects.sort_by! { |i| -(i.fitness - @fitness_goal).abs }
-      else
-        @objects.sort_by!(&:fitness)
-      end
+    def met_goal?
+      evaluation.met_goal?(self)
     end
 
-    def log_evolvable_progress
-      @objects.last.evolvable_progress
+    def new_evolvable(genome: nil)
+      return generate_evolvables(1).first unless genome || parent_evolvables.empty?
+
+      evolvable = evolvable_class.new_evolvable(population: self,
+                                                genome: genome || search_space.new_genome,
+                                                generation_index: @evolvables.count)
+      @evolvables << evolvable
+      evolvable
     end
 
-    def fitness_goal_met?
-      @fitness_goal && @objects.last.fitness >= @fitness_goal
+    def new_evolvables(count:, evolvables: nil)
+      evolvables ||= @evolvables || []
+      @evolvables = evolvables
+
+      if parent_evolvables.empty?
+        Array.new(count) { new_evolvable(genome: search_space.new_genome) }
+      else
+        @evolvables = generate_evolvables(count)
+      end
     end
 
-    def select_objects!
-      @objects.slice!(0..-1 - @selection_count)
+    def reset_evolvables
+      self.evolvables = []
+      new_evolvables(count: size)
     end
 
-    def crossover_objects!
-      parent_genes = @objects.map(&:genes)
-      offspring_genes = @crossover.call(parent_genes, @size)
-      @objects = offspring_genes.map.with_index do |genes, i|
-        evolvable_initialize(genes, self, i)
-      end
+    def new_parent_genome_cycle
+      parent_evolvables.map(&:genome).shuffle!.combination(2).cycle
     end
 
-    def mutate_objects!
-      @mutation.call!(@objects)
+    def evolvable_class
+      @evolvable_class ||= evolvable_type.is_a?(Class) ? evolvable_type : Object.const_get(evolvable_type)
     end
 
-    def inspect
-      "#<#{self.class.name} #{as_json} >"
+    def dump(only: nil, except: nil)
+      Serializer.dump(dump_attrs(only: only, except: except))
     end
 
-    def as_json
-      { evolvable_class: @evolvable_class.name,
-        size: @size,
-        selection_count: @selection_count,
-        crossover: @crossover.as_json,
-        mutation: @mutation.as_json,
-        generation_count: @generation_count }
+    DUMP_METHODS = %i[evolvable_type
+                      id
+                      name
+                      size
+                      evolutions_count
+                      search_space
+                      evolution
+                      evaluation].freeze
+
+    def dump_attrs(only: nil, except: nil)
+      attrs = {}
+      dump_methods = only || DUMP_METHODS
+      dump_methods -= except if except
+      dump_methods.each { |m| attrs[m] = send(m) }
+      attrs
     end
 
     private
 
-    def assign_objects(objects)
-      @objects = objects || []
-      (@size - objects.count).times do |n|
-        genes = evolvable_random_genes
-        @objects << evolvable_initialize(genes, self, n)
-      end
+    def initialize_search_space(search_space)
+      return SearchSpace.build(search_space, evolvable_class) if search_space
+
+      evolvable_class.new_search_space
+    end
+
+    def generate_evolvables(count)
+      evolvables = combination.new_evolvables(self, count)
+      mutation.mutate_evolvables(evolvables)
+      evolvables
     end
   end
 end

data/lib/evolvable/rigid_count_gene.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Evolvable
+  class RigidCountGene
+    include Gene
+
+    def self.combine(gene_a, _gene_b)
+      gene_a
+    end
+
+    def initialize(count)
+      @count = count
+    end
+
+    attr_reader :count
+  end
+end

data/lib/evolvable/search_space.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # @readme
+  #   The search space encapsulates the range of possible genes
+  #   for a particular evolvable. You can think of it as the boundaries of
+  #   genetic variation. It is configured via the
+  #   [.search_space](#evolvableclasssearch_space) method that you define
+  #   on your evolvable class. It's used by populations to initialize
+  #   new evolvables.
+  #
+  #   Evolvable provides flexibility in how you define your search space.
+  #   The below example implementations for `.search_space` produce the
+  #   exact same search space for the
+  #   [Hello World](https://github.com/mattruzicka/evolvable#hello-world)
+  #   demo program. The different styles arguably vary in suitability for
+  #   different contexts, perhaps depending on how programs are loaded and
+  #   the number of different gene types.
+  #
+  # @example
+  #   # All 9 of these example definitions are equivalent
+  #
+  #   # Hash syntax
+  #   { chars: { type: 'CharGene', max_count: 100 } }
+  #   { chars: { type: 'CharGene', min_count: 1, max_count: 100 } }
+  #   { chars: { type: 'CharGene', count: 1..100 } }
+  #
+  #   # Array of arrays syntax
+  #   [[:chars, 'CharGene', 1..100]]
+  #   [['chars', 'CharGene',  1..100]]
+  #   [['CharGene', 1..100]]
+  #
+  #   # A single array works when there's only one type of gene
+  #   ['CharGene', 1..100]
+  #   [:chars, 'CharGene', 1..100]
+  #   ['chars', 'CharGene', 1..100]
+  #
+  #
+
+  class SearchSpace
+    class << self
+      def build(config, evolvable_class = nil)
+        if config.is_a?(SearchSpace)
+          config.evolvable_class = evolvable_class if evolvable_class
+          config
+        else
+          new(config: config, evolvable_class: evolvable_class)
+        end
+      end
+    end
+
+    def initialize(config: {}, evolvable_class: nil)
+      @evolvable_class = evolvable_class
+      @config = normalize_config(config)
+    end
+
+    attr_accessor :evolvable_class, :config
+
+    def new_genome
+      Genome.new(config: new_genome_config)
+    end
+
+    def merge_search_space(val)
+      val = val.config if val.is_a?(self.class)
+      @config.merge normalize_config(val)
+    end
+
+    def merge_search_space!(val)
+      val = val.config if val.is_a?(self.class)
+      @config.merge! normalize_config(val)
+    end
+
+    private
+
+    def normalize_config(config)
+      case config
+      when Hash
+        normalize_hash_config(config)
+      when Array
+        if config.first.is_a?(Array)
+          build_config_from_2d_array(config)
+        else
+          merge_config_with_array({}, config)
+        end
+      end
+    end
+
+    def normalize_hash_config(config)
+      config.each do |gene_key, gene_config|
+        next unless gene_config[:type]
+
+        gene_class = lookup_gene_class(gene_config[:type])
+        gene_class.key = gene_key
+        gene_config[:class] = gene_class
+      end
+    end
+
+    def build_config_from_2d_array(array_config)
+      config = {}
+      array_config.each { |array| merge_config_with_array(config, array) }
+      config
+    end
+
+    def merge_config_with_array(config, gene_array)
+      gene_key, gene_class, count = extract_array_configs(gene_array)
+      gene_class.key = gene_key
+      config[gene_key] = { class: gene_class, count: count }
+      config
+    end
+
+    def extract_array_configs(gene_array)
+      first_item = gene_array.first
+      return extract_array_with_key_configs(gene_array) if first_item.is_a?(Symbol)
+
+      gene_class = lookup_gene_class(first_item)
+      _type, count = gene_array
+      [gene_class, gene_class, count]
+    rescue NameError
+      extract_array_with_key_configs(gene_array)
+    end
+
+    def extract_array_with_key_configs(gene_array)
+      gene_key, type, count = gene_array
+      gene_class = lookup_gene_class(type)
+      [gene_key, gene_class, count]
+    end
+
+    def lookup_gene_class(class_name)
+      return class_name if class_name.is_a?(Class)
+
+      (@evolvable_class || Object).const_get(class_name)
+    end
+
+    def new_genome_config
+      genome_config = {}
+      config.each do |gene_key, gene_config|
+        genome_config[gene_key] = new_gene_config(gene_config)
+      end
+      genome_config
+    end
+
+    def new_gene_config(gene_config)
+      count_gene = init_count_gene(gene_config)
+      gene_class = gene_config[:class]
+      genes = Array.new(count_gene.count) { gene_class.new }
+      { count_gene: count_gene, genes: genes }
+    end
+
+    def init_count_gene(gene_config)
+      min = gene_config[:min_count]
+      max = gene_config[:max_count]
+      return init_min_max_count_gene(min, max) if min || max
+
+      count = gene_config[:count] || 1
+      case count
+      when Numeric
+        RigidCountGene.new(count)
+      when Range
+        CountGene.new(range: count)
+      when String
+        Kernel.const_get(gene_config[:count]).new
+      when Class
+        gene_config[:count].new
+      end
+    end
+
+    def init_min_max_count_gene(min, max)
+      min ||= 1
+      max ||= min * 10
+      CountGene.new(range: min..max)
+    end
+  end
+
+  #
+  # @deprecated
+  #   Will be removed in 2.0
+  #   use {SearchSpace} instead
+  #
+  class GeneSpace < SearchSpace; end
+end

data/lib/evolvable/selection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # @readme
+  #   The selection object assumes that a population's evolvables have already
+  #   been sorted by the evaluation object. It selects "parent" evolvables to
+  #   undergo combination and thereby produce the next generation of evolvables.
+  #
+  #   Only two evolvables are selected as parents for each generation by default.
+  #   The selection size is configurable.
+  #
+  # @example
+  #  # TODO: Show how to add/change population's selection object
+  #
+  class Selection
+    extend Forwardable
+
+    #
+    # Initializes a new selection object.
+    #
+    # Keyword arguments:
+    #
+    # #### size
+    # The number of instances to select from each generation from which to
+    # perform crossover and generate or "breed" the next generation. The
+    # number of parents The default is 2.
+    #
+    def initialize(size: 2)
+      @size = size
+    end
+
+    attr_accessor :size
+
+    def call(population)
+      population.parent_evolvables = select_evolvables(population.evolvables)
+      population.evolvables = []
+      population
+    end
+
+    def select_evolvables(evolvables)
+      evolvables.last(@size)
+    end
+  end
+end

data/lib/evolvable/serializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Evolvable
+  class Serializer
+    class << self
+      def dump(data)
+        klass.dump(data)
+      end
+
+      def load(data)
+        klass.load(data)
+      end
+
+      private
+
+      def klass
+        @klass ||= Marshal
+      end
+    end
+  end
+end

data/lib/evolvable/uniform_crossover.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # Randomly chooses a gene from one of the parents for each gene position.
+  #
+  class UniformCrossover
+    def call(population)
+      population.evolvables = new_evolvables(population, population.size)
+      population
+    end
+
+    def new_evolvables(population, count)
+      parent_genome_cycle = population.new_parent_genome_cycle
+      Array.new(count) do
+        genome = build_genome(parent_genome_cycle.next)
+        population.new_evolvable(genome: genome)
+      end
+    end
+
+    private
+
+    def build_genome(genome_pair)
+      new_config = {}
+      genome_1, genome_2 = genome_pair.shuffle!
+      genome_1.each do |gene_key, gene_config_1|
+        count_gene = gene_config_1[:count_gene]
+        genes = crossover_genes(count_gene.count, gene_config_1, genome_2.config[gene_key])
+        new_config[gene_key] = { count_gene: count_gene, genes: genes }
+      end
+      Genome.new(config: new_config)
+    end
+
+    def crossover_genes(count, gene_config_1, gene_config_2)
+      gene_arrays = [gene_config_1[:genes], gene_config_2[:genes]]
+      Array.new(count) do |index|
+        genes = gene_arrays.sample
+        genes[index] || gene_arrays.detect { |a| a != genes }[index]
+      end
+    end
+  end
+end

data/lib/evolvable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Evolvable
-  VERSION = '0.1.3'
+  VERSION = '1.1.0'
 end