genetic_algorithms 0.0.2 → 0.0.3

data/README.md

@@ -6,31 +6,105 @@ This project contains my work in progress on Genetic Algorithms. The basic premi
 
 A chromosome is a solution to a problem, and represented as a bit string. It is intentionally general in order to lend itself to multiple domains. The only thing linking it to a particular problem set is the fitness function. A fitness function evaluates a chromosome, that is, the effectiveness of a proposed solution.
 
-## Usage
+## The Engine
 
-In the GeneticAlgorithms module, the Engine class encapsulates the entire evolution process. You can quickly use it with default values like this:
+In the GeneticAlgorithms module, the Engine class encapsulates the entire evolution process. When you construct one, by default it gives you a population of size 10, a chromosome length of 10, and 5 generations of evolution. You'll notice that modifying these values can have a tremendous effect on the algorithm itself, and that is one of the interesting characteristics of Genetic Algorithms. In the future I will be opening up more parameters as well; currently many of them are tightly coupled to their respective classes.
+
+## Knapsack, An Example Use Case
+
+I stumbled on an interesting use case and decided to implement it for demonstrational purposes. Let's say we have a knapsack, and furthermore, let's say it can only hold a finite number of items. Assuming we know how much space each item takes, and how much total space the knapsack has, then how can we most efficiently utilize the knapsack? That is, we want to put as many items in it as possible with the least amount of free space left over. Enter genetic algorithms.
+
+### Encoding
+
+First of all, we need a way to express solutions to this problem as a chromosome. Since genetic_algorithms uses binary encoding, that's how we're going to approach it. Let's decide that there are only 4 items that we're considering for this exclusive knapsack. The items are a hammer, coin, pen, and wallet. The chromosome will then have 4 bits. An "ON" bit indicates that the item is in the knapsack, and an "OFF" means it is not. So, if we see something like "1010" that means a hammer(left one) and pen(right one) are in the knapsack, but the coin(left zero) and wallet(right zero) are not.
+
+### The Fitness Function
+
+From a high level perspective, the fitness function should return how efficient the knapsack is being utilized. The implementation is covered below.
+
+Currently, genetic_algorithms is expecting better solutions to return greater numbers than worse solutions. This implies that the highest number returned from a fitness function is the best solution.
+
+### Finally...some code!
+
+Here is the Knapsack class:
 
 ```ruby
-GeneticAlgorithms::Engine.new.start "AllOffSample"
+class Knapsack
+  CAPACITY, BEST_SCORE = 24, 1000
+
+  def initialize chromosome
+    @contents = decode chromosome
+  end
+
+  def utilization
+    space_used = @contents.inject(0) do |accum, item|
+      accum += item.space_needed
+    end
+    
+    (space_used.to_f / CAPACITY * 1000).round
+  end
+
+  private
+
+  def decode chromosome
+    all_items = Item.create_items({ hammer: 17, coin: 4, pen: 9, wallet: 11 })
+    index = -1
+
+    filtered_items = all_items.select do |item|
+      index += 1
+      chromosome[index] == "1"
+    end
+  end
+end
 ```
-And you'll see something like:
+
+And the Item class:
 
 ```ruby
-{"1000000000"=>9}
+class Item
+  def self.create_items item_hash
+    item_hash.inject(Array.new) do |items, (name, space_needed)|
+      items << Item.new(name, space_needed)
+    end
+  end
+
+  def initialize name, space_needed
+    @name = name
+    @space_needed = space_needed
+  end
+
+  attr_reader :name, :space_needed
+end
 ```
 
-This is a Hash containing the best chromosome found, and its score based on the fitness function. The argument to the start method is the name of a fitness function module. I have included a few with this project as a basic reference for creating your own. Here is an example fitness function where the best solution is where all bits are off:
+### Enter genetic_algorithms
 
 ```ruby
-lambda do |chromosome|
-  chromosome.each_char.inject(0) do |accum, char|
-    accum += 1 if char == Chromosome::OFF
-    accum
-  end
+require 'genetic_algorithms'
+include GeneticAlgorithms
+
+Engine.new(10,4).start(Knapsack::BEST_SCORE) do |chromosome|
+  score = Knapsack.new(chromosome).utilization
+  score = Knapsack::BEST_SCORE - score if score > Knapsack::BEST_SCORE
+  score
 end
 ```
 
-The engine has three optional parameters that can be utilized during construction. The population size, chromosome length, and number of generations to evolve (in that order). You'll notice that modifying these values can have a tremendous effect on the algorithm itself, and that is one of the interesting characteristics of genetic algorithms. In the future I will be opening up more parameters as well; currently many of them are tightly coupled to their respective classes.
+Take note of the line checking whether the score is greater than the best score. It is necessary because we don't want genetic_algorithms to think that the over-utilized knapsacks are better solutions. A knapsack with too much stuff in it would otherwise have a higher score.
+
+The result of this run will be something like:
+
+```ruby
+{"1100"=>875}
+```
+
+We see here that the best solution found is a hammer and a coin, totalling 21 out of 24 (0.875) in terms of knapsack capacity.
+
+### Um, that's not the best solution...
+
+You are correct! That's why I chose to show it. The best solution is actually "0111", but given the parameters that we used for the engine, it wasn't able to discover it. This illustrates an important point. Genetic Algorithms may not find the best solution, in fact, some people refer to them as "good enough" algorithms. 
+
+You will get the best solution if you run it a few times as shown, but if you tweak the engine parameters a bit, the ideal solution will be found every time.
 
 ## Logging
 

data/lib/genetic_algorithms/engine.rb

@@ -10,9 +10,7 @@ module GeneticAlgorithms
       @population  = Population.new @chromosomes
     end 
 
-    def start(fitness_function_type)
-      extend GeneticAlgorithms::FitnessFunctions.const_get(fitness_function_type)
-
+    def start(best_possible_score, &fitness_function)
       highest_score, best_gen = 0, nil
       
       (0...@num_generations).inject(@population) do |newest_population, i|
@@ -20,7 +18,7 @@ module GeneticAlgorithms
 
         if newest_population.highest_score > highest_score
           highest_score, best_gen = newest_population.highest_score, newest_population
-          break if highest_score == self.best_possible_score
+          break if highest_score == best_possible_score
         end
 
         next_gen

data/lib/genetic_algorithms/version.rb

@@ -1,3 +1,3 @@
 module GeneticAlgorithms
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/lib/genetic_algorithms.rb

@@ -14,11 +14,5 @@ module GeneticAlgorithms
   require 'genetic_algorithms/exceptions'
   require 'genetic_algorithms/roulette_wheel'
   require 'genetic_algorithms/population'
-
-  ff_path = File.join(File.expand_path("..", __FILE__), "genetic_algorithms/fitness_functions")
-  Dir[File.join ff_path, "**/*.rb"].each do |f|
-    require f
-  end
-
   require 'genetic_algorithms/engine'
 end

data/spec/engine_spec.rb

@@ -2,35 +2,55 @@ require 'spec_helper'
 include GeneticAlgorithms
 
 describe Engine do
-  subject { Engine.new }
-
+  
   # TODO: DRY out this code
   describe "#start" do
     context "AllOffSample fitness function" do
+
+      subject do 
+        Engine.new(10,10,10).start(10) do |chromosome|
+          chromosome.each_char.inject(0) do |accum, char|         
+            accum += 1 if char == Chromosome::OFF                 
+            accum                                                 
+          end
+        end
+      end                                                     
+
       it "returns a hash" do
-        subject.start("AllOffSample").is_a?(Hash).should == true
+        subject.is_a?(Hash).should == true
       end
 
       it "returns the best solution as a Chromosome" do
-        subject.start("AllOffSample").keys.first.is_a?(Chromosome).should == true
+        subject.keys.first.is_a?(Chromosome).should == true
       end
 
       it "returns the best score as a Fixnum" do
-        subject.start("AllOffSample").values.first.is_a?(Fixnum).should == true
+        subject.values.first.is_a?(Fixnum).should == true
       end
     end
 
     context "AlternatingOnOffSample fitness function" do
+
+      subject do 
+        Engine.new(10,10,10).start(10) do |chromosome|
+          (0...chromosome.length).inject(0) do |accum, index|                      
+            accum += 1 if index % 2 == 0 and chromosome[index] == Chromosome::ON   
+            accum += 1 if index % 2 == 1 and chromosome[index] == Chromosome::OFF  
+            accum                                                                  
+          end                                                                      
+        end
+      end                                                     
+
       it "returns a hash" do
-        subject.start("AlternatingOnOffSample").is_a?(Hash).should == true
+        subject.is_a?(Hash).should == true
       end
 
       it "returns the best solution as a Chromosome" do
-        subject.start("AlternatingOnOffSample").keys.first.is_a?(Chromosome).should == true
+        subject.keys.first.is_a?(Chromosome).should == true
       end
 
       it "returns the best score as a Fixnum" do
-        subject.start("AlternatingOnOffSample").values.first.is_a?(Fixnum).should == true
+        subject.values.first.is_a?(Fixnum).should == true
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: genetic_algorithms
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-11 00:00:00.000000000 Z
+date: 2012-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logging
@@ -76,8 +76,6 @@ files:
 - lib/genetic_algorithms/chromosome.rb
 - lib/genetic_algorithms/engine.rb
 - lib/genetic_algorithms/exceptions.rb
-- lib/genetic_algorithms/fitness_functions/all_off_sample.rb
-- lib/genetic_algorithms/fitness_functions/alternating_on_off_sample.rb
 - lib/genetic_algorithms/natural_hash.rb
 - lib/genetic_algorithms/population.rb
 - lib/genetic_algorithms/roulette_wheel.rb

data/lib/genetic_algorithms/fitness_functions/all_off_sample.rb

@@ -1,19 +0,0 @@
-module GeneticAlgorithms
-  module FitnessFunctions
-    module AllOffSample
-
-      def best_possible_score
-        @chromosome_length
-      end
-  
-      def fitness_function
-        lambda do |chromosome|
-          chromosome.each_char.inject(0) do |accum, char|
-            accum += 1 if char == Chromosome::OFF
-            accum
-          end
-        end
-      end
-    end
-  end
-end

data/lib/genetic_algorithms/fitness_functions/alternating_on_off_sample.rb

@@ -1,20 +0,0 @@
-module GeneticAlgorithms
-  module FitnessFunctions
-    module AlternatingOnOffSample
-
-      def best_possible_score
-        @chromosome_length
-      end
-  
-      def fitness_function
-        lambda do |chromosome|
-          (0...chromosome.length).inject(0) do |accum, index|
-            accum += 1 if index % 2 == 0 and chromosome[index] == Chromosome::ON
-            accum += 1 if index % 2 == 1 and chromosome[index] == Chromosome::OFF
-            accum
-          end
-        end
-      end
-    end
-  end
-end