evolvable 1.0.0 → 1.2.0

data/README_YARD.md

@@ -0,0 +1,237 @@
+# Evolvable 🦎
+
+[![Gem Version](https://badge.fury.io/rb/evolvable.svg)](https://badge.fury.io/rb/evolvable) [![Maintainability](https://api.codeclimate.com/v1/badges/7faf84a6d467718b33c0/maintainability)](https://codeclimate.com/github/mattruzicka/evolvable/maintainability)
+
+An evolutionary framework for writing programs that use operations such as selection, crossover, and mutation. Explore ideas generatively in any domain, discover novel solutions to complex problems, and build intuitions about intelligence, complexity, and the natural world.
+
+Subscribe to the [Evolvable Newsletter](https://www.evolvable.site/newsletter) to slowly learn more, or keep reading this contextualization of the [full documentation](https://rubydoc.info/github/mattruzicka/evolvable).
+
+
+## Table of Contents
+* [Installation](#installation)
+* [Getting Started](#getting-started)
+* [Concepts](#concepts)
+* [Genes](#genes)
+* [Populations](#populations)
+* [Evaluation](#evaluation)
+* [Evolution](#evolution)
+* [Selection](#selection)
+* [Combination](#combination)
+* [Mutation](#mutation)
+* [Search Space](#search-space)
+
+
+## Installation
+
+Add [gem "evolvable"](https://rubygems.org/gems/evolvable) to your Gemfile and run `bundle install` or install it yourself with: `gem install evolvable`
+
+## Getting Started
+
+{@readme Evolvable}
+
+To demonstrate these steps, we'll look at the [Hello World](#) example program.
+
+### Hello World
+
+Let's build the evolvable hello world program using the above steps. It'll evolve a population of arbitrary strings to be more like a given target string. After installing this gem, run `evolvable hello` at the command line to see it in action.
+
+Below is example output from evolving a population of randomly initialized string objects to match "Hello World!", then "Hello Evolvable World".
+
+```
+❯ Enter a string to evolve: Hello World!
+
+pp`W^jXG'_N`%              Generation 0
+H-OQXZ\a~{H*               Generation 1 ...
+HRv9X WorlNi               Generation 50 ...
+HRl6W World#               Generation 100 ...
+Hello World!               Generation 165
+
+❯ Enter a string to evolve: Hello Evolvable World
+
+Helgo World!b+=1}3         Generation 165
+Helgo Worlv!}:c(SoV        Generation 166
+Helgo WorlvsC`X(Joqs       Generation 167
+Helgo WorlvsC`X(So1RE      Generation 168 ...
+Hello Evolv#"l{ Wor*5      Generation 300 ...
+Hello Evolvable World      Generation 388
+```
+
+### Step 1
+
+Let's begin by defining a `HelloWorld` class and have it **include the `Evolvable` module**.
+
+```ruby
+class HelloWorld
+  include Evolvable
+end
+```
+
+### Step 2
+
+Now we can **define the `.search_space`** class method with the types of [genes](#genes) that we want our our evolvable "hello world" instances to be able to have. We'll use `CharGene` instances to represent single characters within strings. So an instance with the string value of "Hello" would be composed of five `CharGene` instances.
+
+```ruby
+class HelloWorld
+  include Evolvable
+
+  def self.search_space
+    ["CharGene", 1..40]
+  end
+end
+```
+
+The [Search Space](#search-space) can be defined in a variety of ways. The above is shorthand that's useful for when there's only one type of gene. This method can also return an array of arrays or hash.
+
+The `1..40` specifies the range of possible genes for a particular HelloWorld instance. Evolvable translates this range or integer value into a `Evolvable::CountGene` object.
+
+By specifying a range, an `Evolvable::CountGene` instance can change the number of genes that are present in an evovlable instance. Count genes undergo evolutionary operations like any other gene. Their effects can be seen in the letter changes from Generation 165 to 168 in the above example output.
+
+To finish step 2, we'll **define the gene class** that we referenced in the above `.search_space` method. Gene classes should include the `Evolvable::Gene` module.
+
+```ruby
+class CharGene
+  include Evolvable::Gene
+
+  def self.chars
+    @chars ||= 32.upto(126).map(&:chr)
+  end
+
+  def to_s
+    @to_s ||= self.class.chars.sample
+  end
+end
+```
+
+It's important that, once accessed, the data for a particular gene never change. When the `#to_s` method first runs, Ruby's `||=` operator memoizes the result of randomly picking a char, enabling this method to sample a char only once per gene.
+
+After defining the search space, we can now initialize `HelloWorld` instances with random genes, but to actually evolve them, we need to **define the `#value` instance method**. It provides the basis for comparing different evolvable instances.
+
+### Step 3
+
+In the next step, we'll set the goal value to 0, so that evolution favors evolvable HelloWorld instances with `#value` methods that return numbers closer to 0. That means we want instances that more closely match their targets to return scores nearer to 0. As an example, if our target is "hello world", an instance that returns "jello world" would have a value of 1 and "hello world" would have a value of 0.
+
+For a working implementation, see the `#value` method in [examples/hello_world.rb](https://github.com/mattruzicka/evolvable/blob/main/examples/hello_world.rb)
+
+### Step 4
+
+Now it's time to **initialize a population with `.new_population`**. By default, evolvable populations seek to maximize numeric values. In this program, we always know the best possible value, so setting the goal to a concrete number makes sense. This is done by passing the evaluation params with equalize set to 0.
+
+We'll also specify the number of instances in a population using the population's `size` parameter and change the mutation porbability from 0.03 (3%) to 0.6 (60%).
+
+Experimentation has suggested that a large mutation probability tends to decrease the time it takes to evolve matches with short strings and has the opposite effect for long strings. This is demonstrated in the example output above by how many generations it took to go from "Hello World!" to "Hello Evolvable World". As an optimization, we could dynamically change the mutation probability using a population hook detailed below, but doing so will be left as an exercise for the reader. [Pull requests are welcome.](#contributing)
+
+```ruby
+population = HelloWorld.new_population(size: 100,
+                                       evaluation: { equalize: 0 },
+                                       mutation: { probability: 0.6 }
+```
+
+
+At this point, everything should work when we run `population.evolve`, but it'll look like nothing is happening. The next section will allow us to gain instight by hooking into the evolutionary process.
+
+### Evolvable Population Hooks
+
+The following class methods can be implemented on your Evolvable class, e.g. HelloWorld, to hook into the Population#evolve lifecycle. This is useful for logging evolutionary progress, optimizing parameters, and creating interactions with and between evolvable instances.
+
+1. `.before_evaluation(population)` - {@readme Evolvable::ClassMethods#before_evaluation}
+2. `.before_evolution(population)`- {@readme Evolvable::ClassMethods#before_evolution}
+3. `.after_evolution(population)` - {@readme Evolvable::ClassMethods#after_evolution}
+
+Let's define `.before_evolution` to print the best value for each generation. We'll also define `HelloWorld#to_s`, which implicitly delegates to `CharGene#to_s` during the string interpolation that happens.
+
+```ruby
+class HelloWorld
+  include Evolvable
+
+  def self.before_evolution(population)
+    best_evolvable = population.best_evolvable
+    evolutions_count = population.evolutions_count
+    puts "#{best_evolvable} - Generation #{evolutions_count}"
+  end
+
+  # ...
+
+  def to_s
+    @to_s ||= genes.join
+  end
+
+  # ...
+end
+```
+
+Finally we can **evolve the population with the `Evolvable::Population#evolve` instance method**.
+
+```ruby
+population.evolve
+```
+
+**You now know the fundamental steps to building evolvable programs of endless complexity in any domain!** 🐸 The exact implementation for the command line demo can be found in [exe/hello](https://github.com/mattruzicka/evolvable/blob/main/exe/hello) and [examples/hello_world.rb](https://github.com/mattruzicka/evolvable/blob/main/examples/hello_world.rb).
+
+## Concepts
+
+[Populations](#populations) are composed of evolvables which are composed of genes. Evolvables orchestrate behaviors by delegating to gene objects. Collections of genes are organized into genomes and constitute the [search space](#search-space). [Evaluation](#evaluation) and [evolution](#evolution) objects are used to evolve populations. By default, evolution is composed of [selection](#selection), [combination](#combination), and [mutation](#mutation).
+
+The following concept map depicts how genes flow through populations.
+
+![Concept Map](https://github.com/mattruzicka/evolvable/raw/main/examples/images/diagram.png)
+
+Evolvable is designed with extensibility in mind. Evolvable objects such as [evaluation](#evaluation), [evolution](#evolution), [selection](#selection), [combination](#combination), and [mutation](#mutation) can be extended and swapped, potentially in ways that alter the above graph.
+
+## Genes
+{@readme Evolvable::Gene}
+
+{@example Evolvable::Gene}
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Gene)
+
+## Populations
+{@readme Evolvable::Population}
+
+{@example Evolvable::Population}
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population)
+
+## Evaluation
+{@readme Evolvable::Evaluation}
+
+{@example Evolvable::Evaluation}
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evaluation)
+
+## Evolution
+{@readme Evolvable::Evolution}
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evolution)
+
+## Selection
+{@readme Evolvable::Selection}
+
+{@example Evolvable::Selection}
+
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Selection)
+
+## Combination
+{@readme Evolvable::GeneCombination}
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Combination)
+
+## Mutation
+{@readme Evolvable::Mutation}
+
+{@example Evolvable::Mutation}
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Mutation)
+
+## Search Space
+{@readme Evolvable::SearchSpace}
+
+{@example Evolvable::SearchSpace}
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/SearchSpace)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/evolvable.
+
+If you're interested in contributing, but don't know where to get started, message me on twitter at [@mattruzicka](https://twitter.com/mattruzicka).

data/bin/console

@@ -2,13 +2,26 @@
 
 require 'bundler/setup'
 require 'evolvable'
+require 'byebug'
 
-require './examples/evolvable_string'
+Dir['./examples/*.rb'].each { |f| require f }
 
-puts "To get started, try this:\n\n" \
-     " population = EvolvableString.new_population\n" \
-     " population.mutation.probability = 0.8\n" \
-     " population.evolve(goal_value: EvolvableString::TARGET_STRING.length)\n\n"
+## HelloWorld
+# population = HelloWorld.new_population(size: 100,
+#                                        evaluation: { equalize: 0 },
+#                                        mutation: { probability: 0.6 })
+# population.evolve
+# HelloWorld.start_loop(population)
+
+## Stickman
+# population = Stickman.new_population(size: 5,
+#                                      mutation: { probability: 0.3 })
+# population.evolve
+
+## AsciiArt
+# ascii_art = AsciiArt.new_population(size: 8,
+#                                     mutation: { probability: 0.3, rate: 0.02 })
+# ascii_art.evolve
 
 require 'irb'
 IRB.start(__FILE__)

data/evolvable.gemspec

@@ -26,6 +26,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'byebug', '~> 11.0'
-  spec.add_development_dependency 'rubocop', '~> 0.64.0'
+  spec.add_development_dependency 'readme_yard'
+  spec.add_development_dependency 'yard'
 end

data/examples/ascii_art.rb

@@ -0,0 +1,62 @@
+require './examples/ascii_gene'
+
+class AsciiArt
+  include Evolvable
+
+  class << self
+    def search_space
+      { chars: { type: 'AsciiGene', count: 136 } }
+    end
+
+    def before_evaluation(population)
+      population.best_evolvable.to_terminal
+    end
+  end
+
+  CLEAR_SEQUENCE = ("\e[1A\r\033[2K" * 14).freeze
+
+  def to_terminal
+    print(CLEAR_SEQUENCE) unless population.evolutions_count.zero?
+    lines = genes.each_slice(17).flat_map(&:join)
+    lines[0] = "\n    #{lines[0]}     #{green_text('Minimalism Score:')} #{value}"
+    lines[1] << "     #{green_text('Generation:')} #{population.evolutions_count}"
+    print "\n\n#{lines.join("\n    ")}\n\n\n\n   #{green_text('Use Ctrl-C to stop')} "
+  end
+
+  def minimalism_score
+    @minimalism_score ||= essence_score + spacial_score - clutter_score
+  end
+
+  alias value minimalism_score
+
+  private
+
+  def chars
+    @chars ||= genes.map(&:to_s)
+  end
+
+  def essence_score
+    chars.each_slice(16).each_cons(3).sum do |top, middle, bottom|
+      top_cons = top.each_cons(3).to_a
+      bottom_cons = bottom.each_cons(3).to_a
+      middle.each_cons(3).with_index.sum do |middle_chars, index|
+        mid_center_char = middle_chars.delete_at(1)
+        count = middle_chars.count(mid_center_char)
+        count += top_cons[index].count(mid_center_char)
+        count + (bottom_cons[index]&.count(mid_center_char) || 0)
+      end
+    end
+  end
+
+  def spacial_score
+    chars.count { |c| c == ' ' }
+  end
+
+  def clutter_score
+    chars.uniq.count
+  end
+
+  def green_text(text)
+    "\e[32m#{text}\e[0m"
+  end
+end

data/examples/ascii_gene.rb

@@ -0,0 +1,9 @@
+class AsciiGene
+  include Evolvable::Gene
+
+  ASCII_RANGE = 32..126
+
+  def to_s
+    @to_s ||= rand(ASCII_RANGE).chr
+  end
+end

data/examples/hello_world.rb

@@ -0,0 +1,91 @@
+class HelloWorld
+  include Evolvable
+
+  class CharGene
+    include Evolvable::Gene
+
+    def self.chars
+      @chars ||= 32.upto(126).map(&:chr)
+    end
+
+    def self.ensure_chars(string)
+      @chars.concat(string.chars - chars)
+    end
+
+    def to_s
+      @to_s ||= self.class.chars.sample
+    end
+  end
+
+  MAX_STRING_LENGTH = 40
+
+  def self.search_space
+    { char_genes: { type: 'CharGene', count: 1..MAX_STRING_LENGTH } }
+  end
+
+  def self.start_loop(population)
+    loop do
+      HelloWorld.seek_target
+      prepare_to_exit_loop && break if exit_loop?
+
+      population.reset_evolvables
+      population.evolve
+    end
+  end
+
+  def self.exit_loop?
+    ['"exit"', 'exit'].include?(target)
+  end
+
+  def self.prepare_to_exit_loop
+    print "\n\n\n\n\n #{green_text('Goodbye!')}\n\n\n"
+    true
+  end
+
+  def self.seek_target
+    print "\n\n\n\n\n #{green_text('Use "exit" to stop')} \e[1A\e[1A\e[1A\r" \
+    " #{green_text('Enter a string to evolve: ')}"
+    self.target = gets.strip!
+  end
+
+  def self.target=(val)
+    @target = if val.empty?
+                'I chose this string :)'
+              else
+                CharGene.ensure_chars(val)
+                val.slice(0...MAX_STRING_LENGTH)
+              end
+  end
+
+  def self.target
+    @target ||= 'Hello World!'
+  end
+
+  def self.before_evolution(population)
+    best_evolvable = population.best_evolvable
+    spacing = ' ' * (2 + MAX_STRING_LENGTH - best_evolvable.to_s.length)
+    puts " #{best_evolvable}#{spacing}#{green_text("Generation #{population.evolutions_count}")}"
+  end
+
+  def self.green_text(text)
+    "\e[32m#{text}\e[0m"
+  end
+
+  def to_s
+    @to_s ||= genes.join
+  end
+
+  def value
+    @value ||= compute_value
+  end
+
+  private
+
+  def compute_value
+    string = to_s
+    target = self.class.target
+    target_length = target.length
+    char_matches = target.each_char.with_index.count { |chr, i| chr == string[i] }
+    (target_length - char_matches) + (target_length - string.length).abs
+  end
+end

data/examples/stickman.rb

@@ -0,0 +1,77 @@
+require './examples/ascii_gene'
+
+class Stickman
+  include Evolvable
+
+  class HeadGene
+    include Evolvable::Gene
+
+    def to_s
+      @to_s ||= %w[0 4 9 A C D O P Q R b c d g o p q].sample
+    end
+  end
+
+  class AppendageGene
+    include Evolvable::Gene
+
+    OPTIONS = %w[` ^ - _ = \ | /] << ' '
+
+    def to_s
+      @to_s ||= OPTIONS.sample
+    end
+  end
+
+  class << self
+    def search_space
+      { head: { type: 'HeadGene', count: 1 },
+        body: { type: 'AsciiGene', count: 1 },
+        appendages: { type: 'AppendageGene', count: 4 } }
+    end
+
+    CLEAR_SEQUENCE = ("\e[1A\r\033[2K" * 8).freeze
+
+    def before_evaluation(population)
+      population.evolvables.each do |evolvable|
+        puts "\n\n#{evolvable.draw}\n\n"
+        print green_text(" Rate Stickman #{population.evolutions_count}.#{evolvable.generation_index + 1}: ")
+        evolvable.value = gets.to_i
+        print CLEAR_SEQUENCE
+      end
+
+      (@best_evolvables ||= []) << population.best_evolvable
+      animate_best_evolvables if @best_evolvables.count > 1
+      print "\n\n\n\n\n\n\n #{green_text('Evolve next generation?');} Yes!" \
+            "  #{green_text('...Use Ctrl-C to stop')}#{"\b" * 23}"
+      gets
+      print CLEAR_SEQUENCE
+    end
+
+    def animate_best_evolvables
+      @best_evolvables.each_with_index do |evolvable, index|
+        puts "\n\n#{green_text(evolvable.draw)}\n\n"
+        print green_text(" Generation: #{index}\r\n ")
+        sleep 0.12
+        print "#{CLEAR_SEQUENCE}"
+      end
+    end
+
+    def green_text(text)
+      "\e[32m#{text}\e[0m"
+    end
+  end
+
+  def draw
+    canvas.sub!('o', find_gene(:head).to_s)
+    canvas.sub!('0', find_gene(:body).to_s)
+    find_genes(:appendages).each { |a| canvas.sub!('-', a.to_s) }
+    canvas
+  end
+
+  private
+
+  def canvas
+    @canvas ||= "    o    \n" \
+                "   -0-   \n" \
+                "   - -   \n" \
+  end
+end

data/exe/hello

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'evolvable'
+require 'byebug'
+
+Dir['./examples/*.rb'].each { |f| require f }
+
+population = HelloWorld.new_population(size: 100,
+                                       evaluation: { equalize: 0 },
+                                       mutation: { probability: 0.6 })
+population.evolve
+HelloWorld.start_loop(population)
+
+require 'irb'
+IRB.start(__FILE__)

data/lib/evolvable/count_gene.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Evolvable
+  class CountGene
+    include Gene
+
+    class << self
+      def combine(gene_a, gene_b)
+        min = gene_a.min_count
+        max = gene_a.max_count
+        count = combination.call(gene_a, gene_b).clamp(min, max)
+        new(range: gene_a.range, count: count)
+      end
+
+      LAMBDAS = [->(a, b) { [a, b].sample.count + rand(-1..1) },
+                 ->(a, b) { a.count + b.count / 2 }].freeze
+
+      def combination
+        LAMBDAS.sample
+      end
+    end
+
+    def initialize(range:, count: nil)
+      @range = range
+      @count = count
+    end
+
+    attr_reader :range
+
+    def count
+      @count ||= rand(@range)
+    end
+
+    def min_count
+      @range.min
+    end
+
+    def max_count
+      @range.max
+    end
+  end
+end

data/lib/evolvable/equalize_goal.rb

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

data/lib/evolvable/evaluation.rb

@@ -1,27 +1,46 @@
 # 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
 
-    def initialize(goal = :maximize)
+    DEFAULT_GOAL_TYPE = :maximize
+
+    def initialize(goal = DEFAULT_GOAL_TYPE)
       @goal = normalize_goal(goal)
     end
 
     attr_accessor :goal
 
     def call(population)
-      population.instances.sort_by! { |instance| goal.evaluate(instance) }
+      population.evolvables.sort_by! { |evolvable| goal.evaluate(evolvable) }
     end
 
-    def best_instance(population)
-      population.instances.max_by { |instance| goal.evaluate(instance) }
+    def best_evolvable(population)
+      population.evolvables.max_by { |evolvable| goal.evaluate(evolvable) }
     end
 
     def met_goal?(population)
-      goal.met?(population.instances.last)
+      goal.met?(population.evolvables.last)
     end
 
     private
@@ -33,10 +52,14 @@ module Evolvable
       when Hash
         goal_from_hash(goal_arg)
       else
-        goal
+        goal_arg || default_goal
       end
     end
 
+    def default_goal
+      GOALS[DEFAULT_GOAL_TYPE]
+    end
+
     def goal_from_symbol(goal_arg)
       GOALS[goal_arg]
     end