evolvable 1.0.0 → 1.2.0

data/lib/evolvable/population.rb

@@ -1,38 +1,87 @@
 # 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(id: nil,
-                   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,
-                   evolution: Evolution.new,
+                   gene_space: nil, # Deprecated
+                   search_space: nil,
+                   parent_evolvables: [],
                    evaluation: Evaluation.new,
-                   instances: [])
+                   evolution: Evolution.new,
+                   selection: nil,
+                   combination: nil,
+                   mutation: nil,
+                   evolvables: [])
       @id = id
-      @evolvable_class = evolvable_class
+      @evolvable_type = evolvable_type || evolvable_class
       @name = name
       @size = size
       @evolutions_count = evolutions_count
-      @gene_space = initialize_gene_space(gene_space)
+      @search_space = initialize_search_space(search_space || gene_space)
+      @parent_evolvables = parent_evolvables
+      self.evaluation = evaluation
       @evolution = evolution
-      @evaluation = evaluation || Evaluation.new
-      initialize_instances(instances)
+      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 :id,
-                  :evolvable_class,
+                  :evolvable_type,
                   :name,
                   :size,
                   :evolutions_count,
-                  :gene_space,
+                  :search_space,
                   :evolution,
-                  :evaluation,
-                  :instances
+                  :parent_evolvables,
+                  :evolvables
 
     def_delegators :evolvable_class,
                    :before_evaluation,
@@ -42,18 +91,62 @@ module Evolvable
     def_delegators :evolution,
                    :selection,
                    :selection=,
-                   :crossover,
-                   :crossover=,
+                   :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..count).each do
+      1.upto(count) do
         before_evaluation(self)
         evaluation.call(self)
         before_evolution(self)
@@ -65,34 +158,81 @@ module Evolvable
       end
     end
 
-    def best_instance
-      evaluation.best_instance(self)
+    def best_evolvable
+      evaluation.best_evolvable(self)
     end
 
     def met_goal?
       evaluation.met_goal?(self)
     end
 
-    def new_instance(genes: [], population_index: nil)
-      evolvable_class.new_instance(population: self,
-                                   genes: genes,
-                                   population_index: population_index)
+    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 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 reset_evolvables
+      self.evolvables = []
+      new_evolvables(count: size)
+    end
+
+    def new_parent_genome_cycle
+      parent_evolvables.map(&:genome).shuffle!.combination(2).cycle
+    end
+
+    def evolvable_class
+      @evolvable_class ||= evolvable_type.is_a?(Class) ? evolvable_type : Object.const_get(evolvable_type)
+    end
+
+    def dump(only: nil, except: nil)
+      Serializer.dump(dump_attrs(only: only, except: except))
+    end
+
+    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 initialize_gene_space(gene_space)
-      return GeneSpace.build(gene_space) if gene_space
+    def initialize_search_space(search_space)
+      return SearchSpace.build(search_space, evolvable_class) if search_space
 
-      evolvable_class.new_gene_space
+      evolvable_class.new_search_space
     end
 
-    def initialize_instances(instances)
-      @instances = instances || []
-      (@size - instances.count).times do |n|
-        genes = gene_space.new_genes
-        @instances << new_instance(genes: genes, population_index: n)
-      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

@@ -1,9 +1,31 @@
 # 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
@@ -11,8 +33,13 @@ module Evolvable
     attr_accessor :size
 
     def call(population)
-      population.instances.slice!(0..-1 - @size)
+      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

@@ -1,21 +1,41 @@
 # 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.instances = initialize_offspring(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 initialize_offspring(population)
-      parent_genes = population.instances.map!(&:genes)
-      parent_gene_couples = parent_genes.combination(2).cycle
-      Array.new(population.size) do |index|
-        genes_1, genes_2 = parent_gene_couples.next
-        genes = genes_1.zip(genes_2).map!(&:sample)
-        population.new_instance(genes: genes, population_index: index)
+    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

data/lib/evolvable/version.rb

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