gene_genie 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ec1b4f9a01e789dfccd2c2ae244d88d024c2a1a1
-  data.tar.gz: 23d0def3b38095501ea43abf43eef535b5377cb0
+SHA256:
+  metadata.gz: ea71d46d33da67b5dff6976fbcf4aa6dfd73eecd0fd1c2a0fce2fe70ff02de52
+  data.tar.gz: 18034001ed08324f708e0395d1970aae79880f24949c1e954b453737333b04b5
 SHA512:
-  metadata.gz: 910757fa425a73ab14759642d5f28cbe0535390b0f8735439a38976941944c680de0cf7924164b19eb6f7dbea71c52f59394fe980b34c109ec89815165a1bc34
-  data.tar.gz: 727fe8801c9eaed03834693bc4d38601fb66b3ea9ec9bd39f423dddc7c99d39db7e5c3f0b35966020e6baf302bcf9601ea6aa23a9a9b23009676acd29fee316b
+  metadata.gz: 19139fef4bb51b4ca40d6f949f716bba442b5fc3490ccc26c0cd555fe0eb0db09ad4bdb8366a1562b63bdc9072a4425bd71989a3af0c4cb7fd22f9ddc247eb78
+  data.tar.gz: 1c7686c788280f0cf40f8abfdb2fee8f267e1b5cbfc087b913042553cde7245fc2f24ce9778c481bee6b19b03e99483add0f1f9d5484be4542f80ab5d318cd47

data/README.md

@@ -1,4 +1,3 @@
-[![Build Status](https://travis-ci.org/MEHColeman/gene_genie.svg?branch=master)](https://travis-ci.org/MEHColeman/gene_genie)
 [![Gem Version](https://badge.fury.io/rb/gene_genie.svg)](http://badge.fury.io/rb/gene_genie)
 [![Code Climate](https://codeclimate.com/github/MEHColeman/gene_genie.png)](https://codeclimate.com/github/MEHColeman/gene_genie)
 
@@ -24,34 +23,102 @@ Or install it yourself as:
     $ gem install gene_genie
 
 ## Usage
-Basic usage is designed to be as simple as possible. You provide two things: a template and an evaluator.
-A template is a list of variables along with their possible range of values.
+Basic usage is designed to be as simple as possible. You provide two things: a
+template and an evaluator.
+
+A template is an array of hashes, representing a list of variables along with
+their possible range of values that you wish to optimise.
+
 An evaluator implements a fitness method that returns a numeric value.
-The genetic algorithm will then search for the set of values that maximises the fitness.
 
-```ruby
+The genetic algorithm will then search for the set of values that maximises the
+fitness.
+
+~~~ruby
 require 'gene_genie'
 
-template = {
+template = [{
   range_of_ints: 1..10,
+  more_ints: 3..100
+}]
+~~~
+
 <!---
   range_of_floats: 1.0..4.5,
-set_of_items: [:apple, :banana, :orange],
+  set_of_items: [:apple, :banana, :orange],
   ordered_set_of_items: [:one, :two, :three],
   circular_ordered_set: [:early_morning, :morning, :noon, :afternoon,
                          :evening, :midnight]
 -->
-}
-```
-
-If you use the simple genie interface, the genetic algorithm will come up with a reasonable best-guesses for various algorthm parameters, but you can dive under the covers to give yourself more flexibility.
+Typically, your fitness function will create a model represented by the values
+specified in the template, evaluate the performance of that model, and return a
+fitness score. But, it can be as complicated or simple as you need.
+
+A fitness function should return a float or integer
+~~~ruby
+class Summer
+  def fitness(params)
+    params.inject(0) {|acc, values| acc + values.each_value.inject(&:+)}
+  end
+end
+~~~
+Then, simply create a Genie, and optimise:
+~~~ruby
+genie = GeneGenie::Genie.new(template, Summer.new)
+genie.optimise
+
+puts genie.best.inspect
+~~~
+If you want to monitor progress of the optimisation algorithm, you can register
+a listener:
+~~~ruby
+genie.register_listener(Proc.new do |g|
+  puts "Best score: '#{g.best.to_hashes.to_s}', Score: #{g.best_fitness}"
+end)
+~~~
+See the examples directory for more details.
+
+If you use the simple `genie` interface, the genetic algorithm will come up with
+reasonable best-guesses for various algorithm parameters, but you can dive under
+the covers to give yourself more flexibility.
 * Population size
 * Gene pools
 * Initialization
 * Optimisation Criteria
 
-Custom objects for crossover, gene selection, etc.
 
+## Advanced Use
+
+If you want more control over your algorithm, you can skip the `Genie`, and use
+`GenePool` directly.
+
+This allows you to create objects that are used to control the methods used for
+mutation, crossover, gene selection, gene pool parameters like population size
+and convergence criteria.
+~~~ruby
+  gene_mutator = CustomMutator.new(gm_args)
+  gene_factory = CustomGeneFactory.new(gf_args)
+
+  template_evaluator = CustomTemplateEvaluator.new(template)
+  size = template_evaluator.recommended_size
+
+  GenePool.new(template: template,
+               fitness_evaluator: fitness_evaluator,
+               gene_factory: gene_factory,
+               size: size,
+               mutator: gene_mutator)
+~~~
+The `mutator` operates on a `Gene` to alter it slightly, mimicking natural gene
+mutations.
+
+The `gene_factory` creates a population of genes of a given size. Genes are
+typically generated randomly across the parameter space, but this allows you to
+have more control over how genes are distributed across this space.
+
+The `template_evaluator` is used to provide other configuration options to the
+GenePool, such as recommended size.
+
+---
 Note:
 Due to the non-deterministic nature of the algorithm, some of the tests don't
 pass every time at the moment! This is a known issue.

data/lib/gene_genie/combiner/one_point_combiner.rb

@@ -0,0 +1,34 @@
+module GeneGenie
+  module Combiner
+    # Picks alleles from each Gene randomly
+    class OnePointCombiner
+      def call(gene_a, gene_b)
+        if rand >= 0.5
+          first_gene = gene_a
+          second_gene = gene_b
+        else
+          first_gene = gene_b
+          second_gene = gene_a
+        end
+        first_gene_hashes = first_gene.to_hashes
+        second_gene_hashes = second_gene.to_hashes
+
+        total_length = first_gene_hashes.map(&:size).reduce(:+)
+        crossover_point = rand(0..(total_length - 1))
+
+        count = 0
+        new_information = first_gene_hashes.map.with_index do |part, index|
+          new_hash = {}
+          part.each do |k, v|
+            new_hash[k] = (count >= crossover_point) ? second_gene_hashes[index][k] : v
+            count += 1
+          end
+          new_hash
+        end
+        Gene.new(information: new_information,
+                 fitness_evaluator: first_gene.fitness_evaluator,
+                 gene_combiner: self)
+      end
+    end
+  end
+end

data/lib/gene_genie/combiner/uniform_combiner.rb

@@ -0,0 +1,21 @@
+module GeneGenie
+  module Combiner
+    # Picks alleles from each Gene randomly
+    class UniformCombiner
+      def call(first_gene, second_gene)
+        first_gene_hashes = first_gene.to_hashes
+        second_gene_hashes = second_gene.to_hashes
+        new_information = first_gene_hashes.map.with_index do |part, index|
+          new_hash = {}
+          part.each do |k, v|
+            new_hash[k] = (rand > 0.5) ? v : second_gene_hashes[index][k]
+          end
+          new_hash
+        end
+        Gene.new(information: new_information,
+                 fitness_evaluator: first_gene.fitness_evaluator,
+                 gene_combiner: self)
+      end
+    end
+  end
+end

data/lib/gene_genie/combiner/weighted_average_combiner.rb

@@ -0,0 +1,26 @@
+module GeneGenie
+  module Combiner
+    # Creates new allele value by creating a (random) weighted
+    # average of the two parent genes. Good for genes that represent numeric
+    # scalar values, but not for genes representing discrete info.
+    class WeightedAverageCombiner
+      def call(first_gene, second_gene)
+        first_gene_hashes = first_gene.to_hashes
+        second_gene_hashes = second_gene.to_hashes
+        new_information = first_gene_hashes.map.with_index do |part, index|
+          new_hash = {}
+          part.each do |k, v|
+            p_first = rand(0.0..100.0)
+            p_second = 100 - p_first
+            new_hash[k] = (((p_first * v) +
+                            (p_second * second_gene_hashes[index][k]))/100).round
+          end
+          new_hash
+        end
+        Gene.new(information: new_information,
+                 fitness_evaluator: first_gene.fitness_evaluator,
+                 gene_combiner: self)
+      end
+    end
+  end
+end

data/lib/gene_genie/gene.rb

@@ -1,15 +1,20 @@
+require_relative 'combiner/one_point_combiner'
+
 module GeneGenie
   # A Gene is the basic unit of the genetic algorithm. Genes hold the
   # information used to evaluate their fitness.
   # They are combined into new Genes during the optimisation process.
   # @since 0.0.1
   class Gene
-    def initialize(information, fitness_evaluator)
+    def initialize(information:,
+                   fitness_evaluator:,
+                   gene_combiner: GeneGenie::Combiner::OnePointCombiner.new)
       fail ArgumentError, 'information must be Array' unless information.kind_of? Array
       fail ArgumentError, 'information must be Array of Hashes' unless information[0].kind_of? Hash
 
       @information = information
       @fitness_evaluator = fitness_evaluator
+      @combiner = gene_combiner
     end
 
     def to_hashes
@@ -20,22 +25,23 @@ module GeneGenie
       @fitness ||= @fitness_evaluator.fitness(@information)
     end
 
+    def fitness_evaluator
+      @fitness_evaluator
+    end
+
+    def normalised_fitness(minimum)
+      @normalised_fitness ||= fitness - minimum
+    end
+
     def mutate(mutator)
       @information = mutator.call @information
       @fitness = nil
+      @normalised_fitness = nil
       self
     end
 
     def combine(other_gene)
-      other_gene_hash = other_gene.to_hashes
-      new_information = @information.map.with_index do |part, index|
-        new_hash = {}
-        part.each do |k, v|
-          new_hash[k] = (rand > 0.5) ? v : other_gene_hash[index][k]
-        end
-        new_hash
-      end
-      Gene.new(new_information, @fitness_evaluator)
+      @combiner.call(self, other_gene)
     end
 
     def <=>(other)

data/lib/gene_genie/gene_factory.rb

@@ -1,4 +1,5 @@
 require_relative 'gene'
+require_relative 'combiner/weighted_average_combiner'
 
 module GeneGenie
   # GeneFactory
@@ -7,9 +8,10 @@ module GeneGenie
   # The default implementation will produce random genes, but other approaches
   # could be taken.
   class GeneFactory
-    def initialize(template, fitness_evaluator)
+    def initialize(template, fitness_evaluator, gene_combiner=nil)
       @template = template
       @fitness_evaluator = fitness_evaluator
+      @combiner = gene_combiner || GeneGenie::Combiner::WeightedAverageCombiner.new
     end
 
     def create(size = 1)
@@ -26,7 +28,9 @@ module GeneGenie
       gene_array = @template.map do |part|
         create_hash_from_template_part(part)
       end
-      Gene.new(gene_array, @fitness_evaluator)
+      Gene.new(information: gene_array,
+               fitness_evaluator: @fitness_evaluator,
+               gene_combiner: @combiner)
     end
 
     def create_hash_from_template_part(part)

data/lib/gene_genie/gene_pool.rb

@@ -1,5 +1,5 @@
 require_relative 'gene_factory'
-require_relative 'mutator/simple_gene_mutator'
+require_relative 'mutator/nudge_mutator'
 require_relative 'mutator/null_mutator'
 require_relative 'selector/proportional_selector'
 require_relative 'template_evaluator'
@@ -34,7 +34,7 @@ module GeneGenie
       unless (template.instance_of? Array) && (template[0].instance_of? Hash)
         fail ArgumentError, 'template must be an array of hashes of ranges'
       end
-      gene_mutator = SimpleGeneMutator.new(template)
+      gene_mutator = NudgeMutator.new(template, 0.01)
       gene_factory = GeneFactory.new(template, fitness_evaluator)
 
       template_evaluator = TemplateEvaluator.new(template)
@@ -55,13 +55,21 @@ module GeneGenie
     end
 
     def best
-      @pool.max_by(&:fitness)
+      @best ||= @pool.max_by(&:fitness)
     end
 
     def best_fitness
       best.fitness
     end
 
+    def worst
+      @worst ||= @pool.min_by(&:fitness)
+    end
+
+    def worst_fitness
+      worst.fitness
+    end
+
     def best_ever
       @best_ever ||= best
     end
@@ -73,7 +81,7 @@ module GeneGenie
         new_pool << select_genes_combine_and_mutate
       end
       @pool = new_pool
-      check_best_ever
+      update_stats
       @generation += 1
 
       @listeners.each { |l| l.call(self) }
@@ -86,28 +94,30 @@ module GeneGenie
     end
 
     def average_fitness
-      total_fitness / @pool.size
+      @average_fitness ||= total_fitness / @pool.size
     end
 
     def total_fitness
-      fitness_values.reduce(:+)
+      @total_fitness ||= fitness_values.reduce(:+)
     end
 
-    def genes
-      @pool
+    def total_normalised_fitness
+      @total_normalised_fitness ||= normalised_fitness_values.reduce(:+)
     end
 
-    def worst
-      @pool.min_by(&:fitness)
-    end
-
-    def worst_fitness
-      worst.fitness
+    def genes
+      @pool
     end
 
     private
 
-    def check_best_ever
+    def update_stats
+      @best = nil
+      @worst = nil
+      @total_fitness = nil
+      @total_normalised_fitness = nil
+      @average_fitness = nil
+
       @best_ever = best if best.fitness > best_ever.fitness
     end
 
@@ -115,17 +125,17 @@ module GeneGenie
       @selector.call(self)
     end
 
-    def combine_genes(first, second)
-      first.combine(second)
-    end
-
     def fitness_values
       @pool.map(&:fitness)
     end
 
+    def normalised_fitness_values
+      @pool.map{ |gene| gene.normalised_fitness(worst_fitness) }
+    end
+
     def select_genes_combine_and_mutate
       first_gene, second_gene = select_genes
-      new_gene = combine_genes(first_gene, second_gene)
+      new_gene = first_gene.combine(second_gene)
       new_gene.mutate(@mutator)
     end
   end

data/lib/gene_genie/genie.rb

@@ -1,4 +1,5 @@
 require_relative 'gene_pool'
+require_relative 'listener/logging_listener'
 
 # Namespace for GeneGenie genetic algorithm optimisation gem
 # @since 0.0.1
@@ -6,6 +7,9 @@ module GeneGenie
   # Top level, basic interface for GA optimisation.
   # Genie will attempt to optimise based on best-guess defaults if none are
   # provided
+  # Genie is basically a wrapper around GenePool that lets you get going as
+  # quickly as possible by providing a reasonable set of defaults.
+  # For more control and customisation, go straight to using GenePoo
   # @since 0.0.1
   class Genie
     DEFAULT_NO_OF_GENERATIONS = 50
@@ -35,6 +39,10 @@ module GeneGenie
     end
     alias_method :optimize, :optimise
 
+    def register_listener(listener)
+      @gene_pool.register_listener(listener)
+    end
+
     def best
       @gene_pool.best_ever.to_hashes
     end
@@ -56,8 +64,8 @@ module GeneGenie
       DEFAULT_NO_OF_GENERATIONS.times do
         current_fitness = best_fitness
         @gene_pool.evolve
-        break if best_fitness < current_fitness *
-          (1 + (IMPROVEMENT_THRESHOLD / 100))
+        break if (best_fitness < current_fitness *
+          (1 + (IMPROVEMENT_THRESHOLD / 100)) && best_fitness > 0)
       end
     end
   end

data/lib/gene_genie/mutator/nudge_mutator.rb

@@ -0,0 +1,29 @@
+module GeneGenie
+  # A NudgeMutator is very similar to a simple nutator, except that it will
+  # only change a value by a small amount, rather than to any valid amount.
+  # So, an allele with a rather specified in the template of 1..100, with a
+  # current value of 50 might change in the range 45..55 instead of 1..100.
+  # @since 0.2.0
+  class NudgeMutator
+    def initialize(template, mutation_rate = 0.04)
+      @template = template
+      @mutation_rate = mutation_rate * 1
+    end
+
+    def call(genes)
+      genes.each_with_index do |hash, index|
+        hash.each do |k, v|
+          if rand < @mutation_rate
+            nudge_max = (@template[index][k].size * 0.05).ceil
+            hash[k] = rand(
+              [@template[index][k].min, (v - nudge_max).floor].max..
+              [@template[index][k].max, (v + nudge_max).ceil].min
+            )
+          end
+        end
+      end
+      genes
+    end
+  end
+end
+

data/lib/gene_genie/selector/proportional_selector.rb

@@ -9,21 +9,12 @@ module GeneGenie
     private
 
     def pick_one(pool)
-      proportional_index = rand(total_normalised_fitness(pool))
+      proportional_index = rand(pool.total_normalised_fitness)
       total = 0
       pool.genes.each_with_index do |gene, index|
-        total += normalised_fitness(gene,pool)
+        total += gene.normalised_fitness(pool.worst_fitness)
         return gene if total >= proportional_index || index == (pool.size - 1)
       end
     end
-
-    def total_normalised_fitness(pool)
-      pool.genes.map { |gene| normalised_fitness(gene,pool) }.reduce(:+)
-    end
-
-    def normalised_fitness(gene,pool)
-      gene.fitness -
-        pool.worst_fitness + 1
-    end
   end
 end

data/lib/gene_genie/template_evaluator.rb

@@ -1,6 +1,7 @@
 module GeneGenie
   # A Template Evaluator provides certain analysis and useful information
-  # about templates
+  # about templates.
+  # A template is always treated internally as an Array of Hashes.
   # @since 0.0.2
   class TemplateEvaluator
     def initialize(template)
@@ -13,15 +14,34 @@ module GeneGenie
       }.reduce(:*)
     end
 
-    # returns a minimum of 10 unless the total number of permutations
-    # is below that
-    # otherwise, returns 1/1000th of the number of permutations up to a
-    # maximum of 1000
+    # Suggests a recommended GenePool size.
+    # returns a minimum of 6 unless the total number of permutations
+    # is below that.
+    # Otherwise, returns 1/1000th of the number of permutations up to a
+    # maximum of 20000
     def recommended_size
       [
-        [(permutations / 100_000), 5000].min,
-        [10, permutations].min,
+        [((Math.log(permutations))**2).ceil, 20000].min,
+        [6, permutations].min,
+        3
       ].max
     end
+
+    # Verifies that the given hash conforms to the constraints specified in the
+    # hash template
+    def hash_valid?(hash_under_test)
+      begin
+        @template.each_with_index do |h, index|
+          h.each do |k, v|
+            return false unless hash_under_test[index][k]
+            return false unless hash_under_test[index][k] >= v.min
+            return false unless hash_under_test[index][k] <= v.max
+          end
+        end
+      rescue
+        return false
+      end
+      return true
+    end
   end
 end

data/lib/gene_genie/version.rb

@@ -1,3 +1,3 @@
 module GeneGenie
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,31 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: gene_genie
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Mark Coleman
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2016-08-01 00:00:00.000000000 Z
+date: 2022-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-- !ruby/object:Gem::Dependency
-  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -39,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest-spec
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -75,11 +61,15 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/gene_genie.rb
+- lib/gene_genie/combiner/one_point_combiner.rb
+- lib/gene_genie/combiner/uniform_combiner.rb
+- lib/gene_genie/combiner/weighted_average_combiner.rb
 - lib/gene_genie/gene.rb
 - lib/gene_genie/gene_factory.rb
 - lib/gene_genie/gene_pool.rb
 - lib/gene_genie/genie.rb
 - lib/gene_genie/listener/logging_listener.rb
+- lib/gene_genie/mutator/nudge_mutator.rb
 - lib/gene_genie/mutator/null_mutator.rb
 - lib/gene_genie/mutator/simple_gene_mutator.rb
 - lib/gene_genie/selector/coin_flip_selector.rb
@@ -90,7 +80,7 @@ homepage: https://github.com/MEHColeman/gene_genie
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -105,9 +95,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: Genetic algorithm optimisation gem
 test_files: []