evolvable 1.0.2 → 1.1.0

data/lib/evolvable.rb

@@ -4,70 +4,230 @@ require 'forwardable'
 require 'evolvable/version'
 require 'evolvable/error/undefined_method'
 require 'evolvable/gene'
-require 'evolvable/gene_space'
+require 'evolvable/search_space'
+require 'evolvable/genome'
 require 'evolvable/goal'
-require 'evolvable/goal/equalize'
-require 'evolvable/goal/maximize'
-require 'evolvable/goal/minimize'
+require 'evolvable/equalize_goal'
+require 'evolvable/maximize_goal'
+require 'evolvable/minimize_goal'
 require 'evolvable/evaluation'
 require 'evolvable/evolution'
 require 'evolvable/selection'
-require 'evolvable/gene_crossover'
+require 'evolvable/gene_combination'
 require 'evolvable/point_crossover'
 require 'evolvable/uniform_crossover'
 require 'evolvable/mutation'
 require 'evolvable/population'
+require 'evolvable/count_gene'
+require 'evolvable/rigid_count_gene'
+require 'evolvable/serializer'
 
+#
+# @readme
+#   The `Evolvable` module makes it possible to implement evolutionary behaviors for
+#   any class by defining a `.search_space` class method and `#value` instance method.
+#   Then to evolve instances, initialize a population with `.new_population` and invoke
+#   the `#evolve` method on the resulting population object.
+#
+#   ### Implementation Steps
+#
+#   1. [Include the `Evolvable` module in the class you want to evolve.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable)
+#   2. [Define `.search_space` and any gene classes that you reference.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/SearchSpace)
+#   3. [Define `#value`.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evaluation)
+#   4. [Initialize a population with `.new_population` and use `#evolve`.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population)
+#
 module Evolvable
+  extend Forwardable
+
   def self.included(base)
-    def base.new_population(keyword_args = {})
-      keyword_args[:evolvable_class] = self
+    base.extend(ClassMethods)
+  end
+
+  def self.new_object(old_val, new_val, default_class)
+    new_val.is_a?(Hash) ? (old_val&.class || default_class).new(**new_val) : new_val
+  end
+
+  module ClassMethods
+    #
+    # @readme
+    #   Initializes a population using configurable defaults that can be configured and optimized.
+    #   Accepts the same named parameters as
+    #   [Population#initialize](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population#initialize).
+    #
+    def new_population(keyword_args = {})
+      keyword_args[:evolvable_type] = self
       Population.new(**keyword_args)
     end
 
-    def base.new_instance(population: nil, genes: [], population_index: nil)
-      evolvable = initialize_instance
+    #
+    # Initializes a new instance. Accepts a population object, an array of gene objects,
+    # and the instance's population index. This method is useful for re-initializing
+    # instances and populations that have been saved.
+    #
+    # _It is not recommended that you override this method_ as it is used by
+    # Evolvable internals. If you need to customize how your instances are
+    # initialized you can override either of the following two "initialize_instance"
+    # methods.
+    #
+    def new_evolvable(population: nil,
+                      genome: Genome.new,
+                      generation_index: nil)
+      evolvable = initialize_evolvable
       evolvable.population = population
-      evolvable.genes = genes
-      evolvable.population_index = population_index
-      evolvable.initialize_instance
+      evolvable.genome = genome
+      evolvable.generation_index = generation_index
+      evolvable.after_initialize
       evolvable
     end
 
-    def base.initialize_instance
+    def initialize_evolvable
       new
     end
 
-    def base.new_gene_space
-      GeneSpace.build(gene_space)
+    def new_search_space
+      space_config = search_space.empty? ? gene_space : search_space
+      search_space = SearchSpace.build(space_config, self)
+      search_spaces.each { |space| search_space.merge_search_space!(space) }
+      search_space
     end
 
-    def base.gene_space
+    #
+    # @abstract
+    #
+    # This method is responsible for configuring the available gene types
+    # of evolvable instances. In effect, it provides the
+    # blueprint for constructing a hyperdimensional genetic space that's capable
+    # of being used and searched by evolvable objects.
+    #
+    # Override this method with a search space config for initializing
+    # SearchSpace objects. The config can be a hash, array of arrays,
+    # or single array when there's only one type of gene.
+    #
+    # The below example definitions could conceivably be used to generate evolvable music.
+    #
+    # @todo
+    #   Define gene config attributes - name, type, count
+    #
+    # @example Hash config
+    #   def search_space
+    #     { instrument: { type: InstrumentGene, count: 1..4 },
+    #       notes: { type: NoteGene, count: 16 } }
+    #   end
+    # @example Array of arrays config
+    #   # With explicit gene names
+    #   def search_space
+    #     [[:instrument, InstrumentGene, 1..4],
+    #      [:notes, NoteGene, 16]]
+    #   end
+    #
+    #   # Without explicit gene names
+    #   def search_space
+    #     [[SynthGene, 0..4], [RhythmGene, 0..8]]
+    #   end
+    # @example Array config
+    #   # Available when when just one type of gene
+    #   def search_space
+    #     [NoteGene, 1..100]
+    #   end
+    #
+    #   # With explicit gene type name.
+    #   def search_space
+    #     ['notes', 'NoteGene', 1..100]
+    #   end
+    #
+    # @return [Hash, Array]
+    #
+    # @see https://github.com/mattruzicka/evolvable#search_space
+    #
+    def search_space
       {}
     end
 
-    def base.before_evaluation(population); end
+    #
+    # @abstract Override this method to define multiple search spaces
+    #
+    # @return [Array]
+    #
+    # @see https://github.com/mattruzicka/evolvable#search_space
+    #
+    def search_spaces
+      []
+    end
 
-    def base.before_evolution(population); end
+    # @deprecated
+    #   Will be removed in version 2.0.
+    #   Use {#search_space} instead.
+    def gene_space
+      {}
+    end
 
-    def base.after_evolution(population); end
-  end
 
-  def initialize_instance; end
+    #
+    # @readme
+    #   Runs before evaluation.
+    #
+    def before_evaluation(population); end
 
-  attr_accessor :population,
-                :genes,
-                :population_index
+    #
+    # @readme
+    #   Runs after evaluation and before evolution.
+    #
+    # @example
+    #   class Melody
+    #     include Evolvable
+    #
+    #     # Play the best melody from each generation
+    #     def self.before_evolution(population)
+    #       population.best_evolvable.play
+    #     end
+    #
+    #     # ...
+    #   end
+    #
+    def before_evolution(population); end
 
-  def value
-    raise Errors::UndefinedMethod, "#{self.class.name}##{__method__}"
+    #
+    # @readme
+    #   Runs after evolution.
+    #
+    def after_evolution(population); end
   end
 
-  def find_gene(key)
-    @genes.detect { |g| g.key == key }
-  end
+  # Runs an evolvable is initialized. Ueful for implementing custom initialization logic.
+  def after_initialize; end
+
+  #
+  # @!method value
+  #   Implementing this method is required for evaluation and selection.
+  #
+  attr_accessor :id,
+                :population,
+                :genome,
+                :generation_index,
+                :value
 
-  def find_genes(key)
-    @genes.select { |g| g.key == key }
+  #
+  # @deprecated
+  #   Will be removed in version 2.0.
+  #   Use {#generation_index} instead.
+  #
+  def population_index
+    generation_index
   end
+
+  #
+  # @!method find_gene
+  #   @see Genome#find_gene
+  # @!method find_genes
+  #   @see Genome#find_genes
+  # @!method find_genes_count
+  #   @see Genome#find_genes_count
+  # @!method genes
+  #   @see Genome#genes
+  #
+  def_delegators :genome,
+                 :find_gene,
+                 :find_genes,
+                 :find_genes_count,
+                 :genes
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evolvable
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Matt Ruzicka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-04-04 00:00:00.000000000 Z
+date: 2021-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,38 +24,77 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: readme_yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
-executables: []
+executables:
+- hello
 extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
 - README.md
+- README_YARD.md
 - bin/console
 - bin/setup
 - evolvable.gemspec
-- examples/evolvable_string.rb
-- examples/evolvable_string/char_gene.rb
+- examples/ascii_art.rb
+- examples/ascii_gene.rb
+- examples/hello_world.rb
+- examples/images/diagram.png
+- examples/stickman.rb
+- exe/hello
 - lib/evolvable.rb
+- lib/evolvable/count_gene.rb
+- lib/evolvable/equalize_goal.rb
 - lib/evolvable/error/undefined_method.rb
 - lib/evolvable/evaluation.rb
 - lib/evolvable/evolution.rb
 - lib/evolvable/gene.rb
-- lib/evolvable/gene_crossover.rb
-- lib/evolvable/gene_space.rb
+- lib/evolvable/gene_combination.rb
+- lib/evolvable/genome.rb
 - lib/evolvable/goal.rb
-- lib/evolvable/goal/equalize.rb
-- lib/evolvable/goal/maximize.rb
-- lib/evolvable/goal/minimize.rb
+- lib/evolvable/maximize_goal.rb
+- lib/evolvable/minimize_goal.rb
 - lib/evolvable/mutation.rb
 - lib/evolvable/point_crossover.rb
 - lib/evolvable/population.rb
+- lib/evolvable/rigid_count_gene.rb
+- lib/evolvable/search_space.rb
 - lib/evolvable/selection.rb
+- lib/evolvable/serializer.rb
 - lib/evolvable/uniform_crossover.rb
 - lib/evolvable/version.rb
 homepage: https://github.com/mattruzicka/evolvable

data/examples/evolvable_string/char_gene.rb

@@ -1,9 +0,0 @@
-class CharGene
-  include Evolvable::Gene
-
-  CHARS = ('a'..'z').to_a
-
-  def to_s
-    @to_s ||= CHARS.sample
-  end
-end

data/examples/evolvable_string.rb

@@ -1,32 +0,0 @@
-require './examples/evolvable_string/char_gene'
-
-class EvolvableString
-  include Evolvable
-
-  TARGET_STRING = 'supercalifragilisticexpialidocious'
-
-  def self.gene_space
-    { char_genes: { type: 'CharGene', count: TARGET_STRING.length } }
-  end
-
-  def self.before_evolution(population)
-    best_instance = population.best_instance
-    puts "#{best_instance} | #{best_instance.value} matches | Generation #{population.evolutions_count}"
-  end
-
-  def to_s
-    find_genes(:char_genes).join
-  end
-
-  def value
-    @value ||= compute_value
-  end
-
-  def compute_value
-    value = 0
-    find_genes(:char_genes).each_with_index do |gene, index|
-      value += 1 if gene.to_s == TARGET_STRING[index]
-    end
-    value
-  end
-end

data/lib/evolvable/gene_crossover.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Evolvable
-  class GeneCrossover
-    def call(population)
-      population.instances = initialize_offspring(population)
-      population
-    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 = crossover_genes(genes_1, genes_2)
-        population.new_instance(genes: genes, population_index: index)
-      end
-    end
-
-    def crossover_genes(genes_1, genes_2)
-      genes_1.zip(genes_2).map! do |gene_a, gene_b|
-        gene_a.class.crossover(gene_a, gene_b)
-      end
-    end
-  end
-end

data/lib/evolvable/gene_space.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-module Evolvable
-  class GeneSpace
-    def self.build(config)
-      return config if config.respond_to?(:new_genes)
-
-      new(config: config)
-    end
-
-    def initialize(config: {})
-      @config = normalize_config(config)
-    end
-
-    attr_reader :config
-
-    def new_genes
-      genes = []
-      config.each do |_gene_key, gene_config|
-        (gene_config[:count] || 1).times do
-          gene = gene_config[:class].new
-          genes << gene
-        end
-      end
-      genes
-    end
-
-    private
-
-    def normalize_config(config)
-      config.each do |gene_key, gene_config|
-        next unless gene_config[:type]
-
-        gene_class = Kernel.const_get(gene_config[:type])
-        gene_class.key = gene_key
-        gene_config[:class] = gene_class
-      end
-    end
-  end
-end

data/lib/evolvable/goal/equalize.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Evolvable::Goal
-  class Equalize
-    include Evolvable::Goal
-
-    def value
-      @value ||= 0
-    end
-
-    def evaluate(instance)
-      -(instance.value - value).abs
-    end
-
-    def met?(instance)
-      instance.value == value
-    end
-  end
-end

data/lib/evolvable/goal/maximize.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Evolvable::Goal
-  class Maximize
-    include Evolvable::Goal
-
-    def value
-      @value ||= Float::INFINITY
-    end
-
-    def evaluate(instance)
-      instance.value
-    end
-
-    def met?(instance)
-      instance.value >= value
-    end
-  end
-end

data/lib/evolvable/goal/minimize.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Evolvable::Goal
-  class Minimize
-    include Evolvable::Goal
-
-    def value
-      @value ||= -Float::INFINITY
-    end
-
-    def evaluate(instance)
-      -instance.value
-    end
-
-    def met?(instance)
-      instance.value <= value
-    end
-  end
-end