evolvable 1.0.2 → 1.1.0

data/lib/evolvable/evolution.rb

@@ -1,24 +1,56 @@
 # frozen_string_literal: true
 
 module Evolvable
+  #
+  # @readme
+  #   After a population's instances are evaluated, they undergo evolution.
+  #   The default evolution object is composed of selection,
+  #   crossover, and mutation objects and applies them as operations to
+  #   a population's evolvables in that order.
+  #
   class Evolution
     extend Forwardable
 
+    #
+    #  Initializes a new evolution object.
+    #
+    # Keyword arguments:
+    #
+    # #### selection
+    # The default is `Selection.new`
+    # #### crossover - deprecated
+    # The default is `GeneCrossover.new`
+    # #### mutation
+    # The default is `Mutation.new`
+    #
     def initialize(selection: Selection.new,
-                   crossover: GeneCrossover.new,
+                   combination: GeneCombination.new,
+                   crossover: nil, # deprecated
                    mutation: Mutation.new)
       @selection = selection
-      @crossover = crossover
+      @combination = crossover || combination
       @mutation = mutation
     end
 
-    attr_accessor :selection,
-                  :crossover,
-                  :mutation
+    attr_reader :selection,
+                :combination,
+                :mutation
+
+    def selection=(val)
+      @selection = Evolvable.new_object(@selection, val, Selection)
+    end
+
+    def combination=(val)
+      @combination = Evolvable.new_object(@combination, val, GeneCombination)
+    end
+
+    def mutation=(val)
+      @mutation = Evolvable.new_object(@mutation, val, Mutation)
+    end
 
     def call(population)
       selection.call(population)
-      crossover.call(population)
+      combination.call(population)
       mutation.call(population)
       population
     end

data/lib/evolvable/gene.rb

@@ -1,22 +1,64 @@
 # frozen_string_literal: true
 
 module Evolvable
+  #
+  # @readme
+  #   For evolution to be effective, an evolvable's genes must be able to influence
+  #   its behavior. Evolvables are composed of genes that can be used to run simple
+  #   functions or orchestrate complex interactions. The level of abstraction is up
+  #   to you.
+  #
+  #   Defining gene classes requires encapsulating some "sample space" and returning
+  #   a sample outcome when a gene attribute is accessed. For evolution to proceed
+  #   in a non-random way, the same sample outcome should be returned every time
+  #   a particular gene is accessed with a particular set of parameters.
+  #   Memoization is a useful technique for doing just this. The
+  #   [memo_wise](https://github.com/panorama-ed/memo_wise) gem may be useful for
+  #   more complex memoizations.
+  #
+  # @example
+  #   # This gene generates a random hexidecimal color code for use by evolvables.
+  #
+  #   require 'securerandom'
+  #
+  #   class ColorGene
+  #     include Evolvable::Gene
+  #
+  #     def hex_code
+  #       @hex_code ||= SecureRandom.hex(3)
+  #     end
+  #   end
+  #
+
   module Gene
     def self.included(base)
-      def base.key=(val)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def key=(val)
         @key = val
       end
 
-      def base.key
+      def key
         @key
       end
 
-      def base.crossover(gene_a, gene_b)
-        [gene_a, gene_b].sample
+      def combine(gene_a, gene_b)
+        genes = [gene_a, gene_b]
+        genes.compact!
+        genes.sample
       end
+
+      #
+      # @deprecated
+      #   Will be removed in 2.0
+      #   Use {#combine}
+      #
+      alias crossover combine
     end
 
-    attr_accessor :instance
+    attr_accessor :evolvable
 
     def key
       self.class.key

data/lib/evolvable/gene_combination.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # @readme
+  #   Combination generates new evolvable instances by combining the genes of selected instances.
+  #   You can think of it as a mixing of parent genes from one generation to
+  #   produce the next generation.
+  #
+  #   You may choose from a selection of combination objects or implement your own.
+  #   The default combination object is `Evolvable::GeneCombination`.
+  #
+  # Custom crossover objects must implement the `#call` method which accepts
+  # the population as the first object.
+  # Enables gene types to define combination behaviors.
+  #
+  # Each gene class can implement a unique behavior for
+  # combination by overriding the following default implementation
+  # which mirrors the behavior of `Evolvable::UniformCrossover`
+  #
+  class GeneCombination
+    def call(population)
+      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|
+        gene_config_2 = genome_2.config[gene_key]
+        count_gene = combine_count_genes(gene_config_1, gene_config_2)
+        genes = combine_genes(count_gene.count, gene_config_1, gene_config_2)
+        new_config[gene_key] = { count_gene: count_gene, genes: genes }
+      end
+      Genome.new(config: new_config)
+    end
+
+    def combine_count_genes(gene_config_1, gene_config_2)
+      count_gene_1 = gene_config_1[:count_gene]
+      count_gene_2 = gene_config_2[:count_gene]
+      count_gene_1.class.combine(count_gene_1, count_gene_2)
+    end
+
+    def combine_genes(count, gene_config_1, gene_config_2)
+      genes_1 = gene_config_1[:genes]
+      genes_2 = gene_config_2[:genes]
+      first_gene = genes_1.first || genes_2.first
+      return [] unless first_gene
+
+      gene_class = first_gene.class
+      Array.new(count) do |index|
+        gene_a = genes_1[index]
+        gene_b = genes_2[index]
+        gene_class.combine(gene_a, gene_b) || gene_class.new
+      end
+    end
+  end
+end

data/lib/evolvable/genome.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # @readme
+  #   TODO...
+  #
+  class Genome
+    extend Forwardable
+
+    def self.load(data)
+      new(config: Serializer.load(data))
+    end
+
+    def initialize(config: {})
+      @config = config
+    end
+
+    attr_reader :config
+
+    #
+    # Returns the first gene with the given key. In the Melody example above, the instrument gene has the key `:instrument` so we might write something like: `instrument_gene = melody.find_gene(instrument)`
+    #
+    # @param [<Type>] key <description>
+    #
+    # @return [<Type>] <description>
+    #
+    def find_gene(key)
+      @config.dig(key, :genes, 0)
+    end
+
+    #
+    # Returns an array of genes that have the given key. Gene keys are defined in the [EvolvableClass.search_space](#evolvableclasssearch_space) method. In the Melody example above, the key for the note genes would be `:notes`. The following would return an array of them: `note_genes = melody.find_genes(:notes)`
+    #
+    # @param [<Type>] *keys <description>
+    #
+    # @return [<Type>] <description>
+    #
+    def find_genes(*keys)
+      keys.flatten!
+      return @config.dig(keys.first, :genes) if keys.count <= 1
+
+      @config.values_at(*keys).flat_map { _1&.fetch(:genes, []) || [] }
+    end
+
+    #
+    # <Description>
+    #
+    # @param [<Type>] key <description>
+    #
+    # @return [<Type>] <description>
+    #
+    def find_genes_count(key)
+      find_count_gene(key).count
+    end
+
+    #
+    # <Description>
+    #
+    # @param [<Type>] key <description>
+    #
+    # @return [<Type>] <description>
+    #
+    def find_count_gene(key)
+      @config.dig(key, :count_gene)
+    end
+
+    def_delegators :config, :each
+
+    def gene_keys
+      @config.keys
+    end
+
+    def genes
+      @config.flat_map { |_gene_key, gene_config| gene_config[:genes] }
+    end
+
+    def inspect
+      self.class.name
+    end
+
+    def dump
+      Serializer.dump @config
+    end
+  end
+end

data/lib/evolvable/goal.rb

@@ -1,18 +1,51 @@
 # frozen_string_literal: true
 
 module Evolvable
-  module Goal
+
+  #
+  # The goal for a population can be specified via assignment - `population.goal = Evolvable::Goal::Equalize.new` - or by passing an evaluation object when [initializing a population](#evolvablepopulationnew).
+  #
+  # You can intialize the `Evolvable::Evaluation` object with any goal object like this:
+  #
+  # You can implement custom goal object like so:
+  #
+  # @example
+  #   goal_object = SomeGoal.new(value: 100)
+  #   Evolvable::Evaluation.new(goal_object)
+  #
+  # or more succinctly like this:
+  #
+  # @example
+  #   Evolvable::Evaluation.new(:maximize) # Uses default goal value of   Float::INFINITY
+  #   Evolvable::Evaluation.new(maximize: 50) # Sets goal value to 50
+  #   Evolvable::Evaluation.new(:minimize) # Uses default goal value of   -Float::INFINITY
+  #   Evolvable::Evaluation.new(minimize: 100) # Sets goal value to 100
+  #   Evolvable::Evaluation.new(:equalize) # Uses default goal value of 0
+  #   Evolvable::Evaluation.new(equalize: 1000) # Sets goal value to 1000
+  #
+  # @example
+  #   class CustomGoal < Evolvable::Goal
+  #     def evaluate(instance)
+  #       # Required by Evolvable::Evaluation in order to sort instances in preparation for selection.
+  #     end
+  #
+  #     def met?(instance)
+  #       # Used by Evolvable::Population#evolve to stop evolving when the goal value has been reached.
+  #     end
+  #   end
+  #
+  class Goal
     def initialize(value: nil)
       @value = value if value
     end
 
     attr_accessor :value
 
-    def evaluate(_instance)
+    def evaluate(_evolvable)
       raise Errors::UndefinedMethod, "#{self.class.name}##{__method__}"
     end
 
-    def met?(_instance)
+    def met?(_evolvable)
       raise Errors::UndefinedMethod, "#{self.class.name}##{__method__}"
     end
   end

data/lib/evolvable/maximize_goal.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # Prioritizes instances with greater values. This is the default.
+  #
+  # The default goal value is `Float::INFINITY`, but it can be reassigned
+  # to any numeric value.
+  #
+  class MaximizeGoal < Goal
+    def value
+      @value ||= Float::INFINITY
+    end
+
+    def evaluate(evolvable)
+      evolvable.value
+    end
+
+    def met?(evolvable)
+      evolvable.value >= value
+    end
+  end
+
+  #
+  # @deprecated
+  #   Will be removed in 2.0.
+  #   Use {MaximizeGoal} instead
+  #
+  class Goal::Maximize < MaximizeGoal; end
+end

data/lib/evolvable/minimize_goal.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Evolvable
+  # Prioritizes instances with lesser values.
+  #
+  # The default goal value is `-Float::INFINITY`, but it can be reassigned
+  # to any numeric value
+  #
+  class MinimizeGoal < Goal
+    def value
+      @value ||= -Float::INFINITY
+    end
+
+    def evaluate(evolvable)
+      -evolvable.value
+    end
+
+    def met?(evolvable)
+      evolvable.value <= value
+    end
+  end
+
+  #
+  # @deprecated
+  #   Will be removed in 2.0.
+  #   Use {MinimizeGoal} instead
+  #
+  class Goal::Minimize < MinimizeGoal; end
+end

data/lib/evolvable/mutation.rb

@@ -1,41 +1,93 @@
 # frozen_string_literal: true
 
 module Evolvable
+  #
+  # @readme
+  #   Mutation serves the role of increasing genetic variation. When an evolvable
+  #   undergoes a mutation, one or more of its genes are replaced by newly
+  #   initialized ones. In effect, a gene mutation invokes a new random outcome
+  #   from the genetic search space.
+  #
+  #   Mutation frequency is configurable using the `probability` and `rate`
+  #   parameters.
+  #
+  # @example
+  #   # Show how to initialize/assign population with a specific mutation object
+  #
   class Mutation
     extend Forwardable
 
+    DEFAULT_PROBABILITY = 0.03
+
+    #
+    # Initializes a new mutation object.
+    #
+    # Keyword arguments:
+    #
+    # #### probability
+    # The probability that a particular instance undergoes a mutation.
+    # By default, the probability is 0.03 which translates to 3%.
+    # If initialized with a `rate`, the probability will be 1 which
+    # means all genes _can_ undergo mutation, but actual gene mutations
+    # will be subject to the given mutation rate.
+    # #### rate
+    # the rate at which individual genes mutate. The default rate is 0 which,
+    # when combined with a non-zero `probability` (the default), means that
+    # one gene for each instance that undergoes mutation will change.
+    # If a rate is given, but no `probability` is given, then the `probability`
+    # will bet set to 1 which always defers to the mutation rate.
+    #
+    # To summarize, the `probability` represents the chance of mutation on
+    # the instance level and the `rate` represents the chance on the gene level.
+    # The `probability` and `rate` can be any number from 0 to 1. When the
+    # `probability` is 0, no mutation will ever happen. When the `probability`
+    # is not 0 but the rate is 0, then any instance that undergoes mutation
+    # will only receive one mutant gene. If the rate is not 0, then if an
+    # instance has been chosen to undergo mutation, each of its genes will
+    # mutate with a probability as defined by the `rate`.
+    #
+    # @example Example Initializations:
+    #   Evolvable::Mutation.new # Approximately #{DEFAULT_PROBABILITY} of instances will receive one mutant gene
+    #   Evolvable::Mutation.new(probability: 0.5) # Approximately 50% of instances will receive one mutant gene
+    #   Evolvable::Mutation.new(rate: 0.03) # Approximately  3% of all genes in the population will mutate.
+    #   Evolvable::Mutation.new(probability: 0.3, rate: 0.03) # Approximately 30% of instances will have approximately 3% of their genes mutated.
+    #
+    # Custom mutation objects must implement the `#call` method which accepts the population as the first object.
+    #
     def initialize(probability: nil, rate: nil)
-      @probability = probability || (rate ? 1 : 0.03)
-      @rate = rate || 0
+      @probability = probability || (rate ? 1 : DEFAULT_PROBABILITY)
+      @rate = rate
     end
 
     attr_accessor :probability,
                   :rate
 
     def call(population)
-      return population if probability.zero?
+      mutate_evolvables(population.evolvables) unless probability.zero?
+      population
+    end
 
-      population.instances.each do |instance|
-        mutate_instance(instance) if rand <= probability
+    def mutate_evolvables(evolvables)
+      evolvables.each do |evolvable|
+        next unless rand <= probability
+
+        evolvable.genome.each { |_key, config| mutate_genes(config[:genes]) }
       end
-      population
     end
 
     private
 
-    def mutate_instance(instance)
-      genes_count = instance.genes.count
+    def mutate_genes(genes)
+      genes_count = genes.count
       return if genes_count.zero?
 
-      return mutate_gene(instance, rand(genes_count)) if rate.zero?
+      return mutate_gene_by_index(genes, rand(genes_count)) unless rate
 
-      genes_count.times { |index| mutate_gene(instance, index) if rand <= rate }
+      genes_count.times { |index| mutate_gene_by_index(genes, index) if rand <= rate }
     end
 
-    def mutate_gene(instance, gene_index)
-      gene = instance.genes[gene_index]
-      mutant_gene = gene.class.new
-      instance.genes[gene_index] = mutant_gene
+    def mutate_gene_by_index(genes, gene_index)
+      genes[gene_index] = genes[gene_index].class.new
     end
   end
 end

data/lib/evolvable/point_crossover.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 module Evolvable
+  #
+  # Supports single and multi-point crossover. The default is single-point
+  # crossover via a `points_count` of 1 which can be changed on an existing population
+  # (`population.crossover.points_count = 5`) or during initialization
+  # (`Evolvable::PointCrossover.new(5)`)
+  #
   class PointCrossover
     def initialize(points_count: 1)
       @points_count = points_count
@@ -9,35 +15,43 @@ module Evolvable
     attr_accessor :points_count
 
     def call(population)
-      population.instances = initialize_offspring(population)
+      population.evolvables = new_evolvables(population, population.size)
       population
     end
 
-    private
-
-    def initialize_offspring(population)
-      parent_genes = population.instances.map!(&:genes)
-      parent_gene_couples = parent_genes.combination(2).cycle
-      offspring = []
-      population_index = 0
+    def new_evolvables(population, count)
+      parent_genome_cycle = population.new_parent_genome_cycle
+      evolvables = []
       loop do
-        genes_1, genes_2 = parent_gene_couples.next
-        crossover_genes(genes_1, genes_2).each do |genes|
-          offspring << population.new_instance(genes: genes, population_index: population_index)
-          population_index += 1
-          return offspring if population_index == population.size
+        genome_1, genome_2 = parent_genome_cycle.next
+        crossover_genomes(genome_1, genome_2).each do |genome|
+          evolvable = population.new_evolvable(genome: genome)
+          evolvables << evolvable
+          return evolvables if evolvable.generation_index == count
         end
       end
     end
 
-    def crossover_genes(genes_1, genes_2)
-      offspring_genes = [[], []]
+    private
+
+    def crossover_genomes(genome_1, genome_2)
+      genome_1 = genome_1.dup
+      genome_2 = genome_2.dup
+      genome_1.each do |gene_key, gene_config_1|
+        gene_config_2 = genome_2.config[gene_key]
+        genes_1 = gene_config_1[:genes]
+        genes_2 = gene_config_2[:genes]
+        crossover_genes!(genes_1, genes_2)
+      end
+      [genome_1, genome_2]
+    end
+
+    def crossover_genes!(genes_1, genes_2)
       generate_ranges(genes_1.length).each do |range|
-        offspring_genes.reverse!
-        offspring_genes[0][range] = genes_1[range]
-        offspring_genes[1][range] = genes_2[range]
+        genes_2_range_values = genes_2[range]
+        genes_2[range] = genes_1[range]
+        genes_1[range] = genes_2_range_values
       end
-      offspring_genes
     end
 
     def generate_ranges(genes_count)