jinni 0.3.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1519546cd3391ee816b4549b277f97927fe38bcf
-  data.tar.gz: 0d87d66bde2789bb322944cd475b32455c084130
+  metadata.gz: 265cce6a9225304fcb2cf8aaff35746e70b21a9c
+  data.tar.gz: 1aafa6ab1f8c8a24532acc308dfaea9f9dcfbdc6
 SHA512:
-  metadata.gz: fd99d43d5632c90f9d4ad08afb65e645bfb5b13fd9106d7c2fdc565e29cc9a126ef5636190b242c25de4c73038147d2ab5ac30a6f938dff53a698a113227c808
-  data.tar.gz: d9f480dc6a9e3985b2f5ef0eb75eabc50ee338997ded126a20f6e087762bcedfad1511766d308a14554e77ff2678e908fe60054b4be31c4b07ec816ddce27d5d
+  metadata.gz: fac38fa29e93ea40c5f3ad75b7307e938dfbf6ecac0fdd5053acedbbdcc096e49075abd078d912b82073d0a377cdcb53cd3d454964bee437e7704546e2785679
+  data.tar.gz: e520b7da0664015a5a815d3ec49b5779cf556dc054398d2294690de2f9e12bc8ccb63d6479f14f777ac5aae94390f774a33820817dc7c55d998c73ce86474ce5

data/README.md

@@ -59,51 +59,7 @@ Or install it yourself as:
 
 ## API
 
-### creatures : instance
-
-Jinni adds the following public instance methods to your creatures:
-
-#### fitness()
-you should override this function with something sensible for your class. It returns `0.0` by default, but any float will do.
-#### genes()
-genes is a getter method that returns the genetic attributes available to your instance.
-#### mutate(rate = 0.01)
-mutate returns a slightly mutated object. Each bit in the original dna has a `rate` chance of flipping.
-#### <<(object) / cross(object)
-<< is the basic method used to cross two objects. It splits the dna strands of the input objects into random chunks, and then they randomly swap.
-#### to_binary()
-to_binary returns the binary dna strand that represents the object.
-
-### creatures : class
-
-Jinni adds the following public class methods to your creature class:
-
-#### attr_genetic(:name, min, max)
-use this method in your class to declare your genetic attributes.
-#### random_new()
-random_new initializes an object with attributes randomly assigned from within your declared range.
-#### new_from_binary()
-use this method to initialize an object from an arbitrary binary string.
-
-### numeric
-
-Jinni also monkeypatches the following methods into Numeric:
-
-#### to_binary()
-utility method to convert a numeric into a binary string.
-#### bits()
-utility method to return the number of bits that the binary representation of the number requires
-
-### genepool
-
-Jinni creates a class, Genepool which inherits from Array. Genepool has the following instance methods:
-
-#### generate(n, mutationRate = 0.01, quality = :fitness)
-use this method to create a new generation of `n` creatures based on a genepool. it uses weighted roulette wheel selection to simulate the effects of genetic fitness, then crosses the selected objects together.
-#### roulette(n, quality = :fitness)
-this utility method uses weighted roulette wheel selection to choose `n` objects from your gene pool influenced by fitness. It does not cross them.
-#### average(quality = :fitness)
-this method returns the mean of one quality through a collection of objects. It's very useful for watching your generations increase in fitness.
+See the API documentation over on [rubydoc](http://www.rubydoc.info/gems/jinni/)
 
 ## Contributing
 

data/lib/jinni/creature.rb

@@ -7,17 +7,21 @@ module Jinni
     # move this into the specific creature class, not the generic Creature
     # @@genes = Hash.new
 
-    # redefine this method in your class
+    # you should override this function with something sensible for your class.
+    # It returns `0.0` by default, but any float will do.
     def fitness
       0.0
     end
 
-    # getter for list of genes
+    # genes is a getter method that returns a hash with the genetic attributes
+    # available to your instance as keys, and the size of their range of values
+    # as values
     def genes
       @@genes
     end
 
-    # method to return a possibly mutated version of a given object
+    # mutate returns a slightly mutated object. Each bit in the original dna has
+    # a `rate` chance of flipping.
     def mutate(rate = 0.01)
       binary = self.to_binary
       newBinaryArray = binary.chars.map do |bit|
@@ -30,7 +34,8 @@ module Jinni
       return self.class.new_from_binary newBinary
     end
 
-    # method to cross two creatures. returns a child
+    # << is the basic method used to cross two objects. It splits the dna strands
+    # of the input objects into random chunks, and then they randomly swap.
     # usage:
     # child = bill << ted
     def cross(object)
@@ -50,7 +55,7 @@ module Jinni
     end
     alias :<< :cross
 
-    # serialize object into binary, according to schema laid out in eigenclass
+    # to_binary returns the binary dna strand that represents the given object.
     def to_binary
       self.class.genes.collect {|gene, range|
         output = String.new

data/lib/jinni/eigenclass.rb

@@ -15,14 +15,17 @@ module Jinni
       #   @@schema_total = total
       # end
 
-      # to be used like `Klass.new()`
-      def random_new(*args, &block)
+      # random_new initializes an object with attributes randomly
+      # assigned from within your declared range.
+      def new_randomly(*args, &block)
         obj = allocate
         obj.send(:initialize_randomly, *args, &block)
         obj
       end
+      alias :random_new :new_randomly
 
-      # to be used by `cross`, `Klass.new_from_binary(binary_string)`
+      # use this method to initialize an object from an arbitrary binary string.
+      # it's used internally by the cross method.
       def new_from_binary(*args, &block)
         obj = allocate
         obj.send(:initialize_from_binary, *args, &block)
@@ -39,13 +42,14 @@ module Jinni
         class_variable_set "@@genes", genes
       end
 
-      # the required length of a binary string to generate a creature of this class
+      # returns required length of a binary string to generate a creature of this class
       def genetic_bits
         genes.values.map {|range| range.bits}.reduce(:+)
       end
 
 
-      # use like attr_accessor
+      # use this method in your class to declare your genetic attributes.
+      # use it how you would attr_accessor
       def attr_genetic( gene, min, max )
         range = max - min + 1
 

data/lib/jinni/genepool.rb

@@ -1,4 +1,8 @@
 class Jinni::Genepool < Array
+
+  # this utility method uses weighted roulette wheel selection to
+  # choose `n` objects from your gene pool influenced by fitness.
+  # It does not cross them.
   def roulette(n, quality = :fitness)
     scratch = self.clone
 
@@ -21,6 +25,10 @@ class Jinni::Genepool < Array
     return selected
   end
 
+  # use this method to create a new generation of `n` creatures based
+  # on a genepool. it uses weighted roulette wheel selection to simulate
+  # the effects of genetic fitness, then crosses the selected objects
+  # together.
   def generate(n, mutationRate = 0.01, quality = :fitness)
     scratch = self.clone
 
@@ -37,6 +45,8 @@ class Jinni::Genepool < Array
     return generation
   end
 
+  # this method returns the mean of one quality through a collection of objects.
+  # It's very useful for watching your generations increase in fitness.
   def average(quality = :fitness)
     self.map {|f| f.send(quality)}.inject{ |sum, n| sum + n }.to_f / self.length
   end

data/lib/jinni/numeric.rb

@@ -1,8 +1,11 @@
 class Numeric
+  # utility method to convert a numeric into a binary string.
   def to_binary
     to_s(2)
   end
 
+  # utility method to return the number of bits that the
+  # binary representation of the number requires
   def bits
     to_binary.length()
   end

data/lib/jinni/version.rb

@@ -1,3 +1,3 @@
 module Jinni
-  VERSION = "0.3.4"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jinni
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Andrew Monks