evolvable 0.1.3 → 1.1.0

data/lib/evolvable/evaluation.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # @readme
+  #   For selection to be effective in the context of evolution, there needs to be
+  #   a way to compare evolvables. In the genetic algorithm, this is often
+  #   referred to as the "fitness function".
+  #
+  #   The `Evolvable::Evaluation` object expects evolvable instances to define a `#value` method that
+  #   returns some numeric value. Values are used to evaluate instances relative to each
+  #   other and with regards to some goal. Out of the box, the goal can be set
+  #   to maximize, minimize, or equalize numeric values.
+  #
+  # @example
+  #   # TODO: Show how to add/change population's evaluation object
+  #
+  #   # The goal value can also be assigned via as argument to `Evolvable::Population#evolve`
+  #   population.evolve(goal_value: 1000)
+  #
+  class Evaluation
+    GOALS = { maximize: Evolvable::Goal::Maximize.new,
+              minimize: Evolvable::Goal::Minimize.new,
+              equalize: Evolvable::Goal::Equalize.new }.freeze
+
+    DEFAULT_GOAL_TYPE = :maximize
+
+    def initialize(goal = DEFAULT_GOAL_TYPE)
+      @goal = normalize_goal(goal)
+    end
+
+    attr_accessor :goal
+
+    def call(population)
+      population.evolvables.sort_by! { |evolvable| goal.evaluate(evolvable) }
+    end
+
+    def best_evolvable(population)
+      population.evolvables.max_by { |evolvable| goal.evaluate(evolvable) }
+    end
+
+    def met_goal?(population)
+      goal.met?(population.evolvables.last)
+    end
+
+    private
+
+    def normalize_goal(goal_arg)
+      case goal_arg
+      when Symbol
+        goal_from_symbol(goal_arg)
+      when Hash
+        goal_from_hash(goal_arg)
+      else
+        goal_arg || default_goal
+      end
+    end
+
+    def default_goal
+      GOALS[DEFAULT_GOAL_TYPE]
+    end
+
+    def goal_from_symbol(goal_arg)
+      GOALS[goal_arg]
+    end
+
+    def goal_from_hash(goal_arg)
+      goal_type, value = goal_arg.first
+      goal = GOALS[goal_type]
+      goal.value = value
+      goal
+    end
+  end
+end

data/lib/evolvable/evolution.rb

@@ -0,0 +1,58 @@
+# 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,
+                   combination: GeneCombination.new,
+                   crossover: nil, # deprecated
+                   mutation: Mutation.new)
+      @selection = selection
+      @combination = crossover || combination
+      @mutation = mutation
+    end
+
+    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)
+      combination.call(population)
+      mutation.call(population)
+      population
+    end
+  end
+end

data/lib/evolvable/gene.rb

@@ -0,0 +1,67 @@
+# 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)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def key=(val)
+        @key = val
+      end
+
+      def key
+        @key
+      end
+
+      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 :evolvable
+
+    def key
+      self.class.key
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Evolvable
+
+  #
+  # 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(_evolvable)
+      raise Errors::UndefinedMethod, "#{self.class.name}##{__method__}"
+    end
+
+    def met?(_evolvable)
+      raise Errors::UndefinedMethod, "#{self.class.name}##{__method__}"
+    end
+  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,64 +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
 
-    def initialize(rate: 0.03)
+    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 : DEFAULT_PROBABILITY)
       @rate = rate
     end
 
-    attr_accessor :rate
-
-    def_delegators :@evolvable_class,
-                   :evolvable_genes_count,
-                   :evolvable_gene_pool_size,
-                   :evolvable_random_genes
-
-    def call!(objects)
-      @evolvable_class = objects.first.class
-      mutations_count = find_mutations_count(objects)
-      return if mutations_count.zero?
-
-      mutant_genes = generate_mutant_genes(mutations_count)
-      object_mutations_count = mutations_count / objects.count
-      object_mutations_count = 1 if object_mutations_count.zero?
+    attr_accessor :probability,
+                  :rate
 
-      mutant_genes.each_slice(object_mutations_count).with_index do |m_genes, index|
-        object = objects[index] || objects.sample
-        genes = object.genes
-        genes.merge!(m_genes.to_h)
-        rm_genes_count = genes.count - evolvable_genes_count
-        genes.keys.sample(rm_genes_count).each { |key| genes.delete(key) }
-      end
+    def call(population)
+      mutate_evolvables(population.evolvables) unless probability.zero?
+      population
     end
 
-    def inspect
-      "#<#{self.class.name} #{as_json.map { |a| a.join(': ') }.join(', ')} >"
-    end
+    def mutate_evolvables(evolvables)
+      evolvables.each do |evolvable|
+        next unless rand <= probability
 
-    def as_json
-      { type: self.class.name,
-        rate: @rate }
+        evolvable.genome.each { |_key, config| mutate_genes(config[:genes]) }
+      end
     end
 
     private
 
-    def find_mutations_count(objects)
-      return 0 if @rate.zero?
+    def mutate_genes(genes)
+      genes_count = genes.count
+      return if genes_count.zero?
 
-      count = (objects.count * evolvable_genes_count * @rate)
-      return count.to_i if count >= 1
+      return mutate_gene_by_index(genes, rand(genes_count)) unless rate
 
-      rand <= count ? 1 : 0
+      genes_count.times { |index| mutate_gene_by_index(genes, index) if rand <= rate }
     end
 
-    def generate_mutant_genes(mutations_count)
-      gene_pool_size = evolvable_gene_pool_size
-      mutant_genes = []
-      while mutant_genes.count < mutations_count
-        genes_count = [gene_pool_size, mutations_count - mutant_genes.count].min
-        mutant_genes.concat evolvable_random_genes(genes_count).to_a
-      end
-      mutant_genes
+    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

@@ -0,0 +1,71 @@
+# 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
+    end
+
+    attr_accessor :points_count
+
+    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
+      evolvables = []
+      loop do
+        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
+
+    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|
+        genes_2_range_values = genes_2[range]
+        genes_2[range] = genes_1[range]
+        genes_1[range] = genes_2_range_values
+      end
+    end
+
+    def generate_ranges(genes_count)
+      current_point = rand(genes_count)
+      range_slices = [0...current_point]
+      (points_count - 1).times do
+        new_point = rand(current_point...genes_count)
+        break if new_point.nil?
+
+        range_slices << (current_point...new_point)
+        current_point = new_point
+      end
+      range_slices << (current_point..-1)
+      range_slices
+    end
+  end
+end