evolvable 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0c306e82d21ec726d59896acd642596cc3eb16afc7f9b4e6139cdfd518a4575
-  data.tar.gz: e39f962084249d83e96b0900f2b6851c29f56f1c7656f9a4556278de534b0b5c
+  metadata.gz: 833387bfa4abc039a65f181a9a31cf582075d8e90a7bef1f483ca4a9fa53c699
+  data.tar.gz: f2b32861840ae9c7fe89f5353ab535b2966da0592a1c619f01adecc2be1629e6
 SHA512:
-  metadata.gz: ac75175b693ff6733208b1e5c118ccc577dfebae13c498b613ab440a38136255299914ce6017bce64dcb4b065e5acd59b71c1e3047bb2210daa93ea1770745dd
-  data.tar.gz: 2f1c0e5df3868e255db1ebea18160fdd246604d9a54c1834279421d494a6701c9f9803cb2aacf7273fcbd0cf2141d8013813b8381427de330c078dac617e2415
+  metadata.gz: 667ab941471ab3b949ec631b2d94115667447d43736502862439c574e1c8e1d8231cd37c64aea2bc2900ea750054a17e3e58d7064c030250c5e0792c4019f9b5
+  data.tar.gz: a5c40439db48c8205bd12749ecf103e70266079ecde14eedbc45b180a10154b9c4e025a323411ff6c79b28603a744b4f59f9f5516785e90d0e3fccef9cc8ad05

data/README.md

@@ -1,8 +1,119 @@
 # Evolvable
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/evolvable`. To experiment with that code, run `bin/console` for an interactive prompt.
+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.
 
-TODO: Delete this and the text above, and describe your gem
+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:
+
+- evolve!
+- evaluate_objects!
+- select_objects!
+- crossover_objects!
+- mutate_objects!
+
+## Usage
+
+To introduce evolvable behavior to any Ruby object, do the following:
+
+1. Include the Evolvable module
+2. Define a class method named "evolvable_gene_pool"
+3. Define an instance method named "fitness"
+
+For example, let's say we want to make a text-to-speech command evolve from saying random nonsense to saying whatever you desire.
+
+```Ruby
+require 'evolvable'
+
+class Sentence
+  include Evolvable
+
+  DICTIONARY = ('a'..'z').to_a << ' '
+  DESIRED_WORDS = 'colorless green ideas sleep furiously'
+
+  def self.evolvable_gene_pool
+    Array.new(DESIRED_WORDS.length) { |index| [index, DICTIONARY] }
+  end
+
+  def fitness
+    score = 0
+    @genes.values.each_with_index do |value, index|
+      score += 1 if value == DESIRED_WORDS[index]
+    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
+population = Sentence.evolvable_population
+object = population.strongest_object
+
+until object.fitness == Sentence::DESIRED_WORDS.length
+  puts object.words
+  system("say #{object.words}")
+  population.evolve!(fitness_goal: Sentence::DESIRED_WORDS.length)
+  object = population.strongest_object
+end
+```
+
+To play with a more interactive version, check out https://github.com/mattruzicka/evolvable_sentence
+
+### The Gene Pool
+
+TODO: add descriptions and examples for following
+
+*.evolvable_gene_pool*
+*.evolvable_genes_count*
+
+### Fitness
+
+TODO: add description and example
+
+### Custom Evolvable Class Methods
+
+TODO: add descriptions and example implementations for the following
+
+*.evolvable_evaluate!(objects)*
+*.evolvable_population(args = {})*
+*.evolvable_population_attrs*
+*.evolvable_initialize(genes, population, object_index)*
+
+### Hooks
+
+TODO: add description
+
+*.evolvable_before_evolution(population)*
+*.evolvable_after_select(population)*
+*.evolvable_after_evolution(population)*
+
+### Custom Mutations
+
+TODO: Show how to define and use a custom mutation object
+
+### Custom Crossover
+
+TODO: Show how to define and use a custom crossover object
+
+### Helper Methods
+
+TODO: add description
+
+*Evolvable.combine_dimensions(dimensions)*
+
+### Configuration
+
+TODO: Make logger configurable and make it smarter about picking a default
+
+## Demos
+
+- 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.
 
 ## Installation
 
@@ -20,15 +131,15 @@ Or install it yourself as:
 
     $ gem install evolvable
 
-## Usage
+## Development
 
-TODO: Write usage instructions here
+After checking out the repo, run `bundle install` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-## Development
+I am looking to both simplify how genes are defined as well as support more complex gene types by way of a new Gene class. Currently, genes are represented as an array of arrays or hashes depending on the context. This will likely change.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+I would also like to make more obvious how an evolvable object's genes can influence its behavior/fitness with well-defined pattern for gene expression, probably via an instance method on a gene called "express".
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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.
 
 ## Contributing
 

data/evolvable.gemspec

@@ -7,8 +7,7 @@ Gem::Specification.new do |spec|
   spec.version = Evolvable::VERSION
   spec.authors = ['Matt Ruzicka']
 
-  spec.summary = 'A framework for writing genetic algorithms'
-  spec.summary = 'Make Ruby objects evolvable with genetic algorithms'
+  spec.summary = 'Add evolutionary behavior to any Ruby object'
   spec.homepage = 'https://github.com/mattruzicka/evolvable'
   spec.license = 'MIT'
 

data/lib/evolvable/{callbacks.rb → hooks.rb}

@@ -1,5 +1,5 @@
 module Evolvable
-  module Callbacks
+  module Hooks
     def evolvable_before_evolution(population); end
 
     def evolvable_after_select(population); end

data/lib/evolvable/mutation.rb

@@ -11,18 +11,18 @@ module Evolvable
                    :evolvable_gene_pool_size,
                    :evolvable_random_genes
 
-    def call!(individuals)
-      @evolvable_class = individuals.first.class
-      mutations_count = find_mutations_count(individuals)
+    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)
-      individual_mutations_count = mutations_count / individuals.count
-      individual_mutations_count = 1 if individual_mutations_count.zero?
+      object_mutations_count = mutations_count / objects.count
+      object_mutations_count = 1 if object_mutations_count.zero?
 
-      mutant_genes.each_slice(individual_mutations_count).with_index do |m_genes, index|
-        individual = individuals[index] || individuals.sample
-        genes = individual.genes
+      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) }
@@ -40,10 +40,10 @@ module Evolvable
 
     private
 
-    def find_mutations_count(individuals)
+    def find_mutations_count(objects)
       return 0 if @rate.zero?
 
-      count = (individuals.count * evolvable_genes_count * @rate)
+      count = (objects.count * evolvable_genes_count * @rate)
       return count.to_i if count >= 1
 
       rand <= count ? 1 : 0

data/lib/evolvable/population.rb

@@ -11,7 +11,7 @@ module Evolvable
                    mutation: Mutation.new,
                    generation_count: 0,
                    log_progress: false,
-                   individuals: [])
+                   objects: [])
       @evolvable_class = evolvable_class
       @size = size
       @selection_count = selection_count
@@ -19,7 +19,7 @@ module Evolvable
       @mutation = mutation
       @generation_count = generation_count
       @log_progress = log_progress
-      assign_individuals(individuals)
+      assign_objects(objects)
     end
 
     attr_reader :evolvable_class,
@@ -28,7 +28,7 @@ module Evolvable
                 :crossover,
                 :mutation,
                 :generation_count,
-                :individuals
+                :objects
 
     def_delegators :@evolvable_class,
                    :evolvable_evaluate!,
@@ -43,49 +43,53 @@ module Evolvable
       generations_count.times do
         @generation_count += 1
         evolvable_before_evolution(self)
-        evaluate_individuals!
+        evaluate_objects!
         log_progress if @log_progress
         break if fitness_goal_met?
 
-        select_individuals!
+        select_objects!
         evolvable_after_select(self)
-        reproduce_individuals!
-        mutate_individuals!
+        crossover_objects!
+        mutate_objects!
         evolvable_after_evolution(self)
       end
     end
 
-    def evaluate_individuals!
-      evolvable_evaluate!(@individuals)
+    def strongest_object
+      objects.max_by(&:fitness)
+    end
+
+    def evaluate_objects!
+      evolvable_evaluate!(@objects)
       if @fitness_goal
-        @individuals.sort_by! { |i| -(i.fitness - @fitness_goal).abs }
+        @objects.sort_by! { |i| -(i.fitness - @fitness_goal).abs }
       else
-        @individuals.sort_by!(&:fitness)
+        @objects.sort_by!(&:fitness)
       end
     end
 
     def log_progress
-      @individuals.last.evolvable_progress
+      @objects.last.evolvable_progress
     end
 
     def fitness_goal_met?
-      @fitness_goal && @individuals.last.fitness >= @fitness_goal
+      @fitness_goal && @objects.last.fitness >= @fitness_goal
     end
 
-    def select_individuals!
-      @individuals.slice!(0..-1 - @selection_count)
+    def select_objects!
+      @objects.slice!(0..-1 - @selection_count)
     end
 
-    def reproduce_individuals!
-      parent_genes = @individuals.map(&:genes)
+    def crossover_objects!
+      parent_genes = @objects.map(&:genes)
       offspring_genes = @crossover.call(parent_genes, @size)
-      @individuals = offspring_genes.map.with_index do |genes, i|
+      @objects = offspring_genes.map.with_index do |genes, i|
         evolvable_initialize(genes, self, i)
       end
     end
 
-    def mutate_individuals!
-      @mutation.call!(@individuals)
+    def mutate_objects!
+      @mutation.call!(@objects)
     end
 
     def inspect
@@ -103,11 +107,11 @@ module Evolvable
 
     private
 
-    def assign_individuals(individuals)
-      @individuals = individuals || []
-      (@size - individuals.count).times do |n|
+    def assign_objects(objects)
+      @objects = objects || []
+      (@size - objects.count).times do |n|
         genes = evolvable_random_genes
-        @individuals << evolvable_initialize(genes, self, n)
+        @objects << evolvable_initialize(genes, self, n)
       end
     end
   end

data/lib/evolvable/version.rb

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

data/lib/evolvable.rb

@@ -8,14 +8,14 @@ require 'evolvable/population'
 require 'evolvable/crossover'
 require 'evolvable/mutation'
 require 'evolvable/helper_methods'
-require 'evolvable/callbacks'
+require 'evolvable/hooks'
 require 'evolvable/errors/not_implemented'
 
 module Evolvable
   extend HelperMethods
 
   def self.included(base)
-    base.extend Callbacks
+    base.extend Hooks
 
     def base.evolvable_gene_pool
       raise Errors::NotImplemented, __method__
@@ -25,14 +25,7 @@ module Evolvable
       evolvable_gene_pool_size
     end
 
-    def base.evolvable_evaluate!(_individuals); end
-
-    def base.evolvable_initialize(genes, population, _individual_index)
-      evolvable = new
-      evolvable.genes = genes
-      evolvable.population = population
-      evolvable
-    end
+    def base.evolvable_evaluate!(_objects); end
 
     def base.evolvable_population_attrs
       {}
@@ -45,6 +38,13 @@ module Evolvable
       Population.new(args)
     end
 
+    def base.evolvable_initialize(genes, population, _object_index)
+      evolvable = new
+      evolvable.genes = genes
+      evolvable.population = population
+      evolvable
+    end
+
     def base.evolvable_gene_pool_cache
       @evolvable_gene_pool_cache ||= evolvable_gene_pool
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evolvable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Matt Ruzicka
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-09 00:00:00.000000000 Z
+date: 2019-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -68,10 +68,10 @@ files:
 - bin/setup
 - evolvable.gemspec
 - lib/evolvable.rb
-- lib/evolvable/callbacks.rb
 - lib/evolvable/crossover.rb
 - lib/evolvable/errors/not_implemented.rb
 - lib/evolvable/helper_methods.rb
+- lib/evolvable/hooks.rb
 - lib/evolvable/mutation.rb
 - lib/evolvable/population.rb
 - lib/evolvable/version.rb
@@ -100,5 +100,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Make Ruby objects evolvable with genetic algorithms
+summary: Add evolutionary behavior to any Ruby object
 test_files: []