evolvable 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 833387bfa4abc039a65f181a9a31cf582075d8e90a7bef1f483ca4a9fa53c699
-  data.tar.gz: f2b32861840ae9c7fe89f5353ab535b2966da0592a1c619f01adecc2be1629e6
+  metadata.gz: 046213e8982bac4913f713e33942e9ef5ead7bd655871f995cbbe36797ce64f9
+  data.tar.gz: 2980cf144a9ed46e3abea9d0d395ee582a1207002fa2ab88bb2c967580f3bd6e
 SHA512:
-  metadata.gz: 667ab941471ab3b949ec631b2d94115667447d43736502862439c574e1c8e1d8231cd37c64aea2bc2900ea750054a17e3e58d7064c030250c5e0792c4019f9b5
-  data.tar.gz: a5c40439db48c8205bd12749ecf103e70266079ecde14eedbc45b180a10154b9c4e025a323411ff6c79b28603a744b4f59f9f5516785e90d0e3fccef9cc8ad05
+  metadata.gz: 934eb04d489153638b00c002a2315e35140867f36ebfd9ecd8b3eb30fc0b6f249991a7b5f7b8f83a848bc3de9c36d9e060a89e16e7492bdf7d59f18d63aff405
+  data.tar.gz: ed1cac7f1c24265c29488d2e58304fc81b57be1a2891b87ab4b229218da63f3961cc1ea9dfda926df7226b083db0f2262cbb343ec667f3aa603831887b70e0bd

data/README.md

@@ -1,24 +1,34 @@
 # Evolvable
 
-Genetic algorithms mimic biological processes such as natural selection, crossover, and mutation to model evolutionary behaviors in code. The "evolvable" gem can add evolutionary behavior to any Ruby object.
+Genetic algorithms mimic biological processes such as natural selection, crossover, and mutation to model evolutionary behaviors in code. This gem can add evolutionary behaviors to any Ruby object.
 
-If you're interested in seeing exactly how the "evolvable" gem evolves populations of Ruby objects, I suggest opening up the [Population](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/population.rb) class, specifically check out the following methods:
+## Demos
 
-- evolve!
-- evaluate_objects!
-- select_objects!
-- crossover_objects!
-- mutate_objects!
+- [Evolvable Sentence](https://github.com/mattruzicka/evolvable_sentence) - An interactive version of the evolvable sentence example in "Getting Started"
+- [Evolvable Equation](https://github.com/mattruzicka/evolvable_equation) - Evolves an equation of a specified length to evaluate to a given number
 
 ## Usage
 
-To introduce evolvable behavior to any Ruby object, do the following:
+- [Getting Started](#Getting-Started)
+- [The Gene Pool](#The-Gene-Pool)
+- [Fitness](#Fitness)
+- [Evolvable Population](#Evolvable-Population)
+- [Monitoring Progress](#Monitoring-Progress)
+- [Hooks](#Hooks)
+- [Mutation Objects](#Mutation-Objects)
+- [Crossover Objects](#Crossover-Objects)
+- [Helper Methods](#Helper-Methods)
+- [Configuration](#Configuration)
+
+### Getting Started
 
-1. Include the Evolvable module
-2. Define a class method named "evolvable_gene_pool"
-3. Define an instance method named "fitness"
+To build an object with evolvable behavior, do the following:
 
-For example, let's say we want to make a text-to-speech command evolve from saying random nonsense to saying whatever you desire.
+1. Add ```include Evolvable``` to your class
+2. Define ```.evolvable_gene_pool``` ([documentation](#The-Gene-Pool))
+3. Define ```#fitness``` ([documentation](#Fitness))
+
+As an example, let's make a text-to-speech command evolve from saying random nonsense to whatever you desire. We'll start by defining a Sentence class and doing the three steps above:
 
 ```Ruby
 require 'evolvable'
@@ -40,80 +50,295 @@ class Sentence
     end
     score
   end
-
-  def words
-    @genes.values.join
-  end
 end
 ```
 
 Now let's listen to our computer evolve its speech. The following code assumes your system has a text-to-speech command named "say" installed. Run this code in irb:
 
 ```ruby
+# To play with a more interactive version, check out https://github.com/mattruzicka/evolvable_sentence
+
 population = Sentence.evolvable_population
 object = population.strongest_object
 
 until object.fitness == Sentence::DESIRED_WORDS.length
-  puts object.words
-  system("say #{object.words}")
+  words = object.genes.values.join
+  puts words
+  system("say #{words}")
   population.evolve!(fitness_goal: Sentence::DESIRED_WORDS.length)
   object = population.strongest_object
 end
+
+```
+
+The ```Evolvable::Population#evolve!``` method evolves the population from one generation to the next. It accepts two optional keyword arguments:
+
+```ruby
+{ generations_count: 1, fitness_goal: nil }
 ```
 
-To play with a more interactive version, check out https://github.com/mattruzicka/evolvable_sentence
+Specifying the **fitness_goal** is useful when there's a known fitness you're trying to achieve. We use it in the evolvable sentence example above. If you want your population to keep evolving until it hits a particular fitness goal, set **generations_count** to a large number. The **generations_count** keyword argument tells ```#evolve!``` how many times to run.
+
+If you're interested in seeing exactly how ```Evolvable::Population#evolve!``` works, Open up the [Population](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/population.rb) class and check out the following methods:
+
+- ```evaluate_objects!```
+- ```select_objects!```
+- ```crossover_objects!```
+- ```mutate_objects!```
 
 ### The Gene Pool
 
-TODO: add descriptions and examples for following
+Currently, the gene pool needs to be an array of arrays. Each inner array contains a gene name and an array of possible values for the gene. Expect future releases to make defining the gene pool more straightforward. Check out [Development](#Development) below for details. Until then, here's an example of a simple ```.evolvable_gene_pool``` definition for evolvable dueling pianos:
+
+```ruby
+class DualingPianos
+  NOTES = ['C', 'C♯', 'D', 'D♯', 'E', 'F', 'F♯', 'G', 'G♯', 'A', 'A♯', 'B']
+
+  def self.evolvable_gene_pool
+    [[:piano_1, NOTES],
+     [:piano_2, NOTES]]
+  end
+end
+```
+
+The number of potential genes in the gene pool can be extremely large. For these cases, "Evolvable" makes it possible for objects to contain only a subset of genes with the ```.evolvable_genes_count``` method. Any gene defined in the ```.evolvable_gene_pool``` can still manifest during mutations. In this way, we can limit the gene size of particular objects without limiting the genes available to a population.
+
+```ruby
+require 'evolvable'
+
+class ComplexBot
+  include Evolvable
+
+  def self.evolvable_gene_pool
+    potential_gene_values = (1..10_000).to_a
+    Array.new(1_000_000) { |n| [n, potential_gene_values] }
+  end
+
+  def self.evolvable_genes_count
+    5_000
+  end
+end
 
-*.evolvable_gene_pool*
-*.evolvable_genes_count*
+ComplexBot.evolvable_gene_pool.size # => 1_000_000
+population = ComplexBot.evolvable_population
+complex_bot = population.objects.first
+complex_bot.genes.count # => 10_000
+```
 
 ### Fitness
 
-TODO: add description and example
+The ```#fitness``` method is responsible for measuring how well an object performs. It returns a value or "score" which influences whether an object will be selected to "breed" the next generation of objects. How fitness is defined depends on what you're trying to achieve. If you're trying to break a high score record in Tetris, for example, then the fitness function for your tetris bot might simply return its tetris score:
+
+```ruby
+class TetrisBot
+  alias fitness tetris_score
+end
+```
+
+If, however, your aim is to construct a bot that plays Tetris in an aesthetically pleasing way, maybe you'd define fitness by surveying your artist friends.
+
+```ruby
+class TetrisArtBot
+  def fitness
+    artist_friend_ratings.sum / artist_friend_ratings.count
+  end
+end
+```
+
+The result of ```#fitness``` can be any object that includes the ([Comparable](https://ruby-doc.org/core-2.6.1/Comparable.html)) mixin from Ruby and implements the ```<=>``` method. Many Ruby classes such as String and Integer have default implementations.
+
+You may want to evaluate a whole generation of objects at once. For example, maybe you want each of your bots to play a game against each other and base your fitness score off their win records. For this case, use ```.evolvable_evaluate!(objects)``` like so: 
+
+```ruby
+class GamerBot
+  def self.evolvable_evaluate!(objects)
+    objects.combination(2).each do |player_1, player_2|
+      winner = Game.play(player_1, player_2)
+      winner.win_count += 1
+    end
+  end
+
+  alias fitness win_count
+end
+```
+
+### Evolvable Population
+
+The Evolvable::Population class can be initialized in two ways
+
+1. ```EvolvableBot.evolvable_population```
+2. ```Evolvable::Population.new(evolvable_class: EvolvableBot)```
+
+
+Both ways accept the following keyword arguments as defined by ```Evolvable::Population#initialize```
+```ruby
+{ evolvable_class:, # Required. Inferred if you use the .evolvable_population method
+  size: 20, # The number of objects in each generation
+  selection_count: 2, # The number of objects to be selected as parents for crossover
+  crossover: Crossover.new, # Any object that implements #call
+  mutation: Mutation.new, # Any object that implements #call!
+  generation_count: 0, # Useful when you want to re-initialize a previously saved population of objects
+  objects: [], # Ditto
+  log_progress: false } # See the "Monitoring Progress" section for details
+```
+
+```.evolvable_population(args = {})``` merges any given args with with any keyword arguments defined in ```.evolvable_population_attrs``` Example:
+
+```ruby
+class Plant
+  include Evolvable
+
+  def self.evolvable_population_attrs
+  { size: 100,
+    selection_count: 5,
+    mutation: Evolvable::Mutation.new(rate: 0.3),
+    log_progress: false }
+  end
+
+  def self.evolvable_gene_pool
+    [[:leaf_count, (1..100).to_a],
+     [:root_type, ['fibrous', 'taproot']]]
+  end
+end
 
-### Custom Evolvable Class Methods
+population = Plant.evolvable_population(log_progress: true)
+population.size # => 100
+population.selection_count # => 5
+population.mutation.rate # => 0.3
+population.log_progress # => true
+```
+
+The ```.evolvable_initialize(genes, population, object_index)``` is used by Evolvable::Population to initialize new objects. You can override it to control how your objects are initialized. Make sure to assign the passed in **genes** to your initialized objects. Here's an example implementation for when you want your imaginary friends to have names:
 
-TODO: add descriptions and example implementations for the following
+```ruby
+class ImaginaryFriend
+  def self.evolvable_initialize(genes, population, object_index)
+    friend = new(name: BABY_NAMES.sample)
+    friend.genes = genes
+    friend.population = population
+    friend
+  end
+end
+```
 
-*.evolvable_evaluate!(objects)*
-*.evolvable_population(args = {})*
-*.evolvable_population_attrs*
-*.evolvable_initialize(genes, population, object_index)*
+The third argument to ```.evolvable_initialize``` is the index of the object in the population before being evaluated. It is useful when you what to give your objects more utilitarian names:
+
+```ruby
+friend.name == "#{name} #{population.generation_count}.#{object_index}" # => "ImaginaryFriend 0.11"
+```
+
+A time when you'd want to use Evolvable::Population initializer instead of ```EvolvableBot.evolvable_population``` is when you're re-initializing a population. For example, maybe you want to continue evolving a population of chat bots that you had previously saved to a database:
+
+```ruby
+population = load_chat_bot_population
+Evolvable::Population.new(evolvable_class: population.evolvable_class,
+                          size: population.size,
+                          selection_count: population.selection_count,
+                          crossover: population.crossover,
+                          mutation: population.mutation,
+                          generation_count: population.generation_count,
+                          objects: population.objects)
+```
+
+### Monitoring Progress
+
+```#evolvable_progress``` is used by ```Evolvable::Population#evolve!``` to log the progress of the "strongest object" in each generation. That is, the object with the best fitness score. It runs just after objects are evaluated and the ```Evolvable::Population#strongest_object``` can be determined. ```Evolvable::Population#log_progress``` must equal true in order for the result of the ```#evolvable_progress``` to be logged.
+
+In the [evolvable sentence demo](https://github.com/mattruzicka/evolvable_sentence), ```evolvable_progress``` is implemented in order to output the strongest object's generation count, fitness score, and words. In this example, we also use the "say" text-to-speech command to pronounce the words. 
+
+```Ruby
+  class Sentence
+    def evolvable_progress
+      words = @genes.values.join
+      puts "Generation: #{population.generation_count} | Fitness: #{fitness} | #{words}"
+      system("say #{words}") if say?
+    end
+  end
+  population.log_progress = true
+```
+
+Hooks can also be used to monitor progress.
 
 ### Hooks
 
-TODO: add description
+You can define any the following class method hooks on any Evolvable class. They run during the evolution of each generation in ```Evolvable::Population#evolve!```
+
+```.evolvable_before_evolution(population)```
 
-*.evolvable_before_evolution(population)*
-*.evolvable_after_select(population)*
-*.evolvable_after_evolution(population)*
+```.evolvable_after_select(population)```
 
-### Custom Mutations
+```.evolvable_after_evolution(population)```
 
-TODO: Show how to define and use a custom mutation object
+### Mutation Objects
 
-### Custom Crossover
+The [Evolvable::Mutation](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/mutation.rb) class defines the default mutation implementation with a default mutation rate of 0.03. It can be initialized with a custom mutation rate like so:
 
-TODO: Show how to define and use a custom crossover object
+```ruby
+mutation = Evolvable::Mutation.new(rate: 0.05)
+population = Evolvable::Population.new(mutation: mutation)
+population.evolve!
+```
+
+Any Ruby object that implements ```#call!(objects)``` can be used as a mutation object. The default implementation is specialized to work with evolvable objects that define a ```evolvable_genes_count``` that is less than ```evolvable_gene_pool.size```. For more information on this, see [The Gene Pool](#The-Gene-Pool)
+
+### Crossover Objects
+
+The [Evolvable::Crossover](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/crossover.rb) class defines the default crossover implementation.
+
+```ruby
+crossover = Evolvable::Crossover.new
+population = Evolvable::Population.new(crossover: crossover)
+population.evolve!
+```
+
+Any Ruby object that implements ```#call(parent_genes, offspring_count)``` can be used as a crossover object. The default implementation is specialized to work with evolvable objects that define a ```evolvable_genes_count``` that is less than ```evolvable_gene_pool.size```. For more information on this, see [The Gene Pool](#The-Gene-Pool)
 
 ### Helper Methods
 
-TODO: add description
+```Evolvable.combine_dimensions(dimensions)```
 
-*Evolvable.combine_dimensions(dimensions)*
+This is helpful when you want to create, for lack of a better word, "multidimensional genes". In the following example, we want our fortune cookie to evolve fortunes based on its eater's hair and eye color because fortune cookies understand things that we aren't capable of knowing.
 
-### Configuration
+```ruby
+class FortuneCookie
+  include Evolvable
 
-TODO: Make logger configurable and make it smarter about picking a default
+  HAIR_COLORS = ['black', 'blond', 'brown', 'gray', 'red', 'white']
+  EYE_COLORS = ['blue', 'brown', 'gray', 'green']
+ 
+  FORTUNES = ['You will prosper',
+              'You will endure hardship',
+              'You are about to eat a crisp and sugary cookie']
 
-## Demos
+  def self.evolvable_gene_pool
+    gene_names_array = Evolvable.combine_dimensions([HAIR_COLORS, EYE_COLORS])
+    gene_names_array.map! { |gene_name| [gene_name, FORTUNES] }
+  end
 
-- https://github.com/mattruzicka/evolvable_sentence - A more interactive version of the evolvable sentence code above.
-- https://github.com/mattruzicka/evolvable_equation - Evolves an equation of a specified length to evaluate to a given number.
-- More demos to come.
+  def fitness
+    hair_color = find_eater_hair_color
+    eye_color = find_eater_eye_color
+    fortune = @genes[[hair_color, eye_color]]
+    eater.give_fortune(fortune)
+    sleep 2.weeks
+    eater.how_true?(fortune)
+  end
+end
+```
+
+In this not-at-all-contrived example, ```Evolvable.combine_dimensions([HAIR_COLOR, EYE_COLORS])``` returns
+
+```ruby
+[["auburn", "blue"], ["auburn", "brown"], ["auburn", "gray"], ["auburn", "green"], ["black", "blue"], ["black", "brown"], ["black", "gray"], ["black", "green"], ["blond", "blue"], ["blond", "brown"], ["blond", "gray"], ["blond", "green"], ["brown", "blue"], ["brown", "brown"], ["brown", "gray"], ["brown", "green"], ["gray", "blue"], ["gray", "brown"], ["gray", "gray"], ["gray", "green"], ["red", "blue"], ["red", "brown"], ["red", "gray"], ["red", "green"], ["white", "blue"], ["white", "brown"], ["white", "gray"], ["white", "green"]]
+```
+
+which is useful for composing genes made up of various dimensions and accessing gene values by these dimensions in the ```#fitness``` and ```.evolvable_evaluate!(objects)``` methods.
+
+```Evolvable.combine_dimensions(dimensions)``` can take an array containing any number of arrays as an argument. One item from each given array will be in each output array and the item's index will be the same as the index of the argument array it belongs to. All combinations of items from the various arrays that follow this rule will be returned as arrays. The number of output arrays is equal to the product of multiplying the sizes of each given array. This method was difficult to write as was this description. I'd be really interested to see other people's implementations :)
+
+### Configuration
+
+TODO: Make logger configurable and make it smarter about picking a default
 
 ## Installation
 
@@ -141,6 +366,8 @@ I would also like to make more obvious how an evolvable object's genes can influ
 
 I have a general sense of how I want to move forward on these features, but feel free to message me with ideas or implementations.
 
+If you see a TODO in this README, feel free to do it :)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/evolvable.

data/bin/console

@@ -10,5 +10,41 @@ require 'evolvable'
 # require "pry"
 # Pry.start
 
+
+class BandMember
+  include Evolvable
+
+  SYNTHS = [:synth_1, :synth_2]
+
+  # SYNTH_OPTIONS = { synth_1: [[:cutoff, (1..100).to_a],
+                              # [:reverb: (1..5).to_a]],
+                    # synth_2: []}
+
+  SAMPLES = [:sample_1, :sample_2]
+
+  # SAMPLE_OPTIONS = { sample_1: [[:cutoff, (1..100).to_a],
+                                # [:reverb: (1..5).to_a]],
+                     # sample_2: []}
+
+  def self.evolvable_gene_pool
+    
+  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
+  end
+
+  def fitness
+    0
+  end
+end
+
+
+
 require 'irb'
 IRB.start(__FILE__)

data/lib/evolvable/mutation.rb

@@ -6,6 +6,8 @@ module Evolvable
       @rate = rate
     end
 
+    attr_accessor :rate
+
     def_delegators :@evolvable_class,
                    :evolvable_genes_count,
                    :evolvable_gene_pool_size,

data/lib/evolvable/population.rb

@@ -22,13 +22,14 @@ module Evolvable
       assign_objects(objects)
     end
 
-    attr_reader :evolvable_class,
-                :size,
-                :selection_count,
-                :crossover,
-                :mutation,
-                :generation_count,
-                :objects
+    attr_accessor :evolvable_class,
+                  :size,
+                  :selection_count,
+                  :crossover,
+                  :mutation,
+                  :generation_count,
+                  :log_progress,
+                  :objects
 
     def_delegators :@evolvable_class,
                    :evolvable_evaluate!,
@@ -44,7 +45,7 @@ module Evolvable
         @generation_count += 1
         evolvable_before_evolution(self)
         evaluate_objects!
-        log_progress if @log_progress
+        log_evolvable_progress if log_progress
         break if fitness_goal_met?
 
         select_objects!
@@ -68,7 +69,7 @@ module Evolvable
       end
     end
 
-    def log_progress
+    def log_evolvable_progress
       @objects.last.evolvable_progress
     end
 

data/lib/evolvable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Evolvable
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evolvable
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Matt Ruzicka
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-10 00:00:00.000000000 Z
+date: 2019-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler