evolvable 0.1.3 → 1.1.0

data/lib/evolvable.rb

@@ -1,86 +1,233 @@
 # frozen_string_literal: true
 
 require 'forwardable'
-require 'logger'
-
 require 'evolvable/version'
-require 'evolvable/population'
-require 'evolvable/crossover'
+require 'evolvable/error/undefined_method'
+require 'evolvable/gene'
+require 'evolvable/search_space'
+require 'evolvable/genome'
+require 'evolvable/goal'
+require 'evolvable/equalize_goal'
+require 'evolvable/maximize_goal'
+require 'evolvable/minimize_goal'
+require 'evolvable/evaluation'
+require 'evolvable/evolution'
+require 'evolvable/selection'
+require 'evolvable/gene_combination'
+require 'evolvable/point_crossover'
+require 'evolvable/uniform_crossover'
 require 'evolvable/mutation'
-require 'evolvable/helper_methods'
-require 'evolvable/hooks'
-require 'evolvable/errors/not_implemented'
-
+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 HelperMethods
+  extend Forwardable
 
   def self.included(base)
-    base.extend Hooks
-
-    def base.evolvable_gene_pool
-      raise Errors::NotImplemented, __method__
-    end
-
-    def base.evolvable_genes_count
-      evolvable_gene_pool_size
-    end
-
-    def base.evolvable_evaluate!(_objects); end
+    base.extend(ClassMethods)
+  end
 
-    def base.evolvable_population_attrs
-      {}
-    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
 
-    def base.evolvable_population(args = {})
-      clear_evolvable_gene_pool_caches
-      args = evolvable_population_attrs.merge!(args)
-      args[:evolvable_class] = self
-      Population.new(args)
+  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.evolvable_initialize(genes, population, _object_index)
-      evolvable = new
-      evolvable.genes = genes
+    #
+    # 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.genome = genome
+      evolvable.generation_index = generation_index
+      evolvable.after_initialize
       evolvable
     end
 
-    def base.evolvable_gene_pool_cache
-      @evolvable_gene_pool_cache ||= evolvable_gene_pool
+    def initialize_evolvable
+      new
     end
 
-    def base.evolvable_gene_pool_size
-      @evolvable_gene_pool_size ||= evolvable_gene_pool_cache.size
+    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.clear_evolvable_gene_pool_caches
-      @evolvable_gene_pool_cache = nil
-      @evolvable_gene_pool_size = nil
+    #
+    # @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.evolvable_random_genes(count = nil)
-      gene_pool = evolvable_gene_pool_cache
-      count ||= evolvable_genes_count
-      gene_pool = gene_pool.sample(count) if count < gene_pool.size
-      genes = {}
-      gene_pool.each { |name, potentials| genes[name] = potentials.sample }
-      genes
+    #
+    # @abstract Override this method to define multiple search spaces
+    #
+    # @return [Array]
+    #
+    # @see https://github.com/mattruzicka/evolvable#search_space
+    #
+    def search_spaces
+      []
     end
-  end
 
-  def self.logger
-    @logger ||= Logger.new(STDOUT)
-  end
+    # @deprecated
+    #   Will be removed in version 2.0.
+    #   Use {#search_space} instead.
+    def gene_space
+      {}
+    end
 
-  attr_accessor :genes,
-                :population
 
-  def fitness
-    raise Errors::NotImplemented, __method__
+    #
+    # @readme
+    #   Runs before evaluation.
+    #
+    def before_evaluation(population); end
+
+    #
+    # @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
+
+    #
+    # @readme
+    #   Runs after evolution.
+    #
+    def after_evolution(population); end
   end
 
-  def evolvable_progress(info = nil)
-    info ||= "Generation: #{population.generation_count} | Fitness: #{fitness}"
-    Evolvable.logger.info(info)
+  # 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
+
+  #
+  # @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: 0.1.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Matt Ruzicka
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2019-03-11 00:00:00.000000000 Z
+date: 2021-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -25,55 +25,77 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: byebug
+  name: readme_yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.64.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.64.0
-description: 
-email: 
-executables: []
+        version: '0'
+description:
+email:
+executables:
+- hello
 extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
+- README_YARD.md
 - bin/console
 - bin/setup
 - evolvable.gemspec
+- 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/crossover.rb
-- lib/evolvable/errors/not_implemented.rb
-- lib/evolvable/helper_methods.rb
-- lib/evolvable/hooks.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_combination.rb
+- lib/evolvable/genome.rb
+- lib/evolvable/goal.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
 licenses:
@@ -82,7 +104,7 @@ metadata:
   homepage_uri: https://github.com/mattruzicka/evolvable
   source_code_uri: https://github.com/mattruzicka/evolvable
   changelog_uri: https://github.com/mattruzicka/evolvable/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -97,8 +119,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: Add evolutionary behavior to any Ruby object
 test_files: []

data/.rubocop.yml

@@ -1,20 +0,0 @@
-AllCops:
-  TargetRubyVersion: 2.6.1
-
-Style/Documentation:
-  Enabled: false
-
-Style/SymbolArray:
-  Enabled: false
-
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Naming/VariableNumber:
-  EnforcedStyle: 'snake_case'
-
-Metrics/LineLength:
-  Max: 90

data/lib/evolvable/crossover.rb

@@ -1,35 +0,0 @@
-class Crossover
-  def call(parent_genes, offspring_count)
-    parent_gene_couples = parent_genes.combination(2).cycle
-    Array.new(offspring_count) do
-      p1_genes, p2_genes = parent_gene_couples.next
-      p1_genes.merge(p2_genes) { |_k, p1_val, p2_val| [p1_val, p2_val].sample }
-      offspring_genes = merge_parent_genes(p1_genes, p2_genes)
-      trim_offspring_genes!(offspring_genes, p1_genes.count)
-      offspring_genes
-    end
-  end
-
-  def inspect
-    "#<#{self.class.name} #{as_json.map { |a| a.join(': ') }.join(', ')} >"
-  end
-
-  def as_json
-    { type: self.class.name }
-  end
-
-  private
-
-  def merge_parent_genes(p1_genes, p2_genes)
-    p1_genes.merge(p2_genes) { |_k, p1_val, p2_val| [p1_val, p2_val].sample }
-  end
-
-  def trim_offspring_genes!(offspring_genes, parent_genes_count)
-    trim_genes_count = offspring_genes.count - parent_genes_count
-    return if trim_genes_count.zero?
-
-    offspring_genes.keys.sample(trim_genes_count).each do |name|
-      offspring_genes.delete(name)
-    end
-  end
-end

data/lib/evolvable/errors/not_implemented.rb

@@ -1,5 +0,0 @@
-module Evolvable
-  module Errors
-    class NotImplemented < StandardError; end
-  end
-end

data/lib/evolvable/helper_methods.rb

@@ -1,45 +0,0 @@
-module Evolvable
-  module HelperMethods
-    def combine_dimensions(dimensions)
-      dimension_lengths = dimensions.map(&:length)
-      genes_count = dimension_lengths.inject(1) { |product, c| product * c }
-
-      genes = Array.new(genes_count) { [] }
-      element_repeat_counts = compute_element_repeat_counts(dimension_lengths)
-      sequence_counts = compute_sequence_counts(dimension_lengths)
-
-      dimensions.each_with_index do |dimension, dim_index|
-        element_count = element_repeat_counts[dim_index]
-        sequence = dimension.flat_map { |e| [e] * element_count }
-        dimension_sequence = sequence * sequence_counts[dim_index]
-        dimension_sequence.each_with_index do |element, gene_index|
-          genes[gene_index][dim_index] = element
-        end
-      end
-
-      genes
-    end
-
-    private
-
-    def compute_element_repeat_counts(dimension_lengths)
-      repeat_counts = Array.new(dimension_lengths.count - 1) do |n|
-        right_side_counts = dimension_lengths[(n + 1)..-1]
-        right_side_counts.inject(1) { |product, a| product * a }
-      end
-      repeat_counts << 1
-      repeat_counts
-    end
-
-    def compute_sequence_counts(dimension_lengths)
-      Array.new(dimension_lengths.count) do |n|
-        if n.zero?
-          1
-        else
-          right_side_counts = dimension_lengths[0...n]
-          right_side_counts.inject(1) { |product, a| product * a }
-        end
-      end
-    end
-  end
-end

data/lib/evolvable/hooks.rb

@@ -1,9 +0,0 @@
-module Evolvable
-  module Hooks
-    def evolvable_before_evolution(population); end
-
-    def evolvable_after_select(population); end
-
-    def evolvable_after_evolution(population); end
-  end
-end