charlie 0.5.0

data/History.txt

@@ -0,0 +1,3 @@
+== 0.5.0 / 2007-12-19
+* First release.
+

data/Manifest.txt

@@ -0,0 +1,53 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+TODO.txt
+data/BENCHMARK
+data/CROSSOVER
+data/GENOTYPE
+data/MUTATION
+data/SELECTION
+data/template.html
+examples/bit.rb
+examples/function_opt_2peak.rb
+examples/function_opt_sombero.rb
+examples/gladiatorial_simple.rb
+examples/gladiatorial_sunburn.rb
+examples/gridwalk.rb
+examples/output/flattened_sombero.html
+examples/output/flattened_sombero2_.html
+examples/output/fopt1_dblopt.html
+examples/output/hill10.html
+examples/output/hill2.csv
+examples/output/hill2.html
+examples/output/royalroad1_report.html
+examples/output/royalroad2_report.html
+examples/output/royalroadquick_report.html
+examples/output/tsp.html
+examples/output/weasel1_report.html
+examples/output/weasel2_report.html
+examples/royalroad.rb
+examples/royalroad2.rb
+examples/simple_climb_hill2.rb
+examples/tsp.rb
+examples/weasel.rb
+lib/charlie.rb
+lib/charlie/crossover.rb
+lib/charlie/etc/minireport.rb
+lib/charlie/etc/monkey.rb
+lib/charlie/genotype.rb
+lib/charlie/list/list_crossover.rb
+lib/charlie/list/list_genotype.rb
+lib/charlie/list/list_mutate.rb
+lib/charlie/mutate.rb
+lib/charlie/permutation/permutation.rb
+lib/charlie/population.rb
+lib/charlie/selection.rb
+test/t_common.rb
+test/test_basic.rb
+test/test_benchmark.rb
+test/test_cross.rb
+test/test_mutator.rb
+test/test_permutation.rb
+test/test_sel.rb

data/README.txt

@@ -0,0 +1,90 @@
+Charlie
+
+* http://rubyforge.org/projects/charlie/
+* http://charlie.rubyforge.org
+* mailto:sander.land+ruby@gmail.com
+
+== DESCRIPTION:
+Charlie is a library for genetic algorithms. It allows you to easily create
+and run genetic algorithms. You can choose selection, crossover or mutation 
+strategies from either built-in options or simply write your own.
+It also includes methods that can be used to compare several of these 
+strategies, generating reports with statistics that can be used to determine 
+which one to use in future problems.
+
+== EXAMPLES:
+This example finds the binary representation of the number 512.
+ require 'rubygems'
+ require 'charlie'
+ class Find512 < BitStringGenotype(10) # choose a genotype, in this case a list of 10 bits represents a solution
+   # Define a fitness function. This one returns minus the offset to the best solution, so a higher number is better.
+   # Usually, you won't know the best solution, and will define this as some value that needs to be maximized.
+   def fitness  
+     # Use the 'genes' function to retrieve the array of bits representing this solution.
+     -(genes.map(&:to_s).join.to_i(2) - 512).abs
+   end
+ end
+ # Finally, create an instance of a population (with the default size of 20) and let it run for the default number of 100 generations.
+ Population.new(Find512).evolve_on_console
+
+This example solves RubyQuiz #142.
+
+ require 'rubygems'
+ require 'charlie'
+ N=5
+ CITIES = (0...N).map{|i| (0...N).map{|j| [i,j] } }.inject{|a,b|a+b}
+
+ class TSP < PermutationGenotype(CITIES.size)
+   def fitness
+     d=0
+     (genes + [genes[0]]).each_cons(2){|a,b| 
+        a,b=CITIES[a],CITIES[b]
+        d += Math.sqrt( (a[0]-b[0])**2 + (a[1]-b[1])**2 ) 
+      }
+     -d # lower distance -> higher fitness.
+   end
+ end
+ pop = Population.new(TSP,20).evolve_on_console(50)
+
+== INSTALL:
+
+* sudo gem install charlie
+
+== Documentation
+Because of the high amount of metaprogramming used in the package, the rdoc documentation is incomplete and also contains some non-existent functions.
+
+The following pages contain overviews of the most important parts, including pointers to the appropriate pages of the documentation.
+* Genotypes[link:files/data/GENOTYPE.html]
+* Selection[link:files/data/SELECTION.html]
+* Crossover[link:files/data/CROSSOVER.html]
+* Mutation[link:files/data/MUTATION.html]
+* Benchmarking[link:files/data/BENCHMARK.html]
+
+Also see the 'examples' directory for several examples, where most of the functionality is used.
+
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007 Sander Land
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,43 @@
+
+require 'rubygems'
+require 'hoe'
+
+$LOAD_PATH.unshift './lib'
+
+require 'charlie'
+
+Hoe.new('charlie', Charlie::VERSION) do |p|
+  p.rubyforge_name = 'charlie'
+  p.url = 'http://charlie.rubyforge.org'
+
+  p.author = 'Sander Land'
+  p.email = 'sander.land+ruby@gmail.com'
+
+  p.summary = 'A genetic algorithms library for Ruby.'
+  p.description =  p.paragraphs_of('README.txt', 2..3).join("\n\n")
+  
+
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+
+  #p.test_globs ['test/test_all.rb']  # removed test_all, because rake now does that anyway
+  p.clean_globs = ['test/output/*','./**/*~'] # Remove this on "rake clean" : test output and kate backups
+
+  p.rdoc_pattern = /^lib|\.txt$|^data\/[A-Z]+$/
+  p.remote_rdoc_dir = '' # Release to root
+end
+
+task :build_manifest do |t|
+  require 'find'
+  paths = []
+  Find.find(".") do |path|
+    next if File.directory?(path)
+    next if path =~ /\.svn/ # no svn
+    next if path =~ /~$/    # no kate backups
+    paths << path.sub(%r{^\./}, '') 
+  end
+  File.open("Manifest.txt", "w") do |f|
+    f.puts paths.sort.join("\n")
+  end
+end
+
+

data/TODO.txt

@@ -0,0 +1,28 @@
+This is my todo list. Contributions and suggestions don't have to be restricted to these things in any way.
+
+=== Small stuff
+* fix the initialize call in Genotype#from_genes
+* clean up PCross, PMutate
+* n-point crossover for lists
+
+=== Bigger stuff
+* Better crossover and/or mutation operators for permutations. Especially something useful for TSP.  (http://en.wikipedia.org/wiki/Edge_recombination_operator ?)
+* More builtin genotypes:
+   1. Tree-based, extending into genetic programming.
+   2. Graphs / adjacency matrix.
+   3. Neural networks.
+   4. selection algorithms.
+* Extend benchmarking options:
+   1. Compare several generation/population size settings. Especially both of them together while keeping the number of fitness evaluations roughly constant.
+   2. Detailed stats for use in comparing a small number of strategies? Including population stats for every generation and run, graphs?
+
+
+
+
+
+
+
+
+
+
+

data/data/BENCHMARK

@@ -0,0 +1,53 @@
+== Benchmark documentation
+Population#benchmark can compare several selection, crossover and mutation methods and give a report comparing their
+performance, both for convergence and speed.
+
+The call to the function is:
+
+ Population.benchmark(genotype_class,html_output_file,csv_output_file=nil) {
+   selection RandomSelection, TournamentSelection(3)
+   crossover SinglePointCrossover
+   mutator   ListMutator(
+ }
+
+* +genotype_class+ is simply your genotype class.
+* +html_output_file+ is an output file where a large report with several tables of statistics will be written. Pass nil for no output file of this type.
+* +csv_output_file+ is an output file where the raw data (the maximum fitness value for each run) will be written. Pass nil or omit parameter for no output file of this type.
+
+
+
+In the block you can call several functions to specify the parameters of the benchmark.
+This is sometimes refered to as a DSL. As inaccurate as that term may be, I'll still use it here.
+
+
+=== Benchmark DSL documentation  (also see StrategiesDSL)
+In the block you must call the following functions:
+
+==== selection(*s_args)
+Will cause each of the selection modules in +s_args+ to be tested.
+==== crossover(*c_args)
+Will cause each of the crossover modules in +c_args+ to be tested.
+==== mutator(*m_args)
+Will cause each of the mutation modules in +m_args+ to be tested.
+
+
+If you want to test the module that is already included without repeating it, just pass Module.new as one of the arguments (or Module.new{self.name='default'} for something more descriptive).
+
+
+You can also call the following functions to change some other settings:
+
+==== self.generations     =  g
+Changes the number of generations in each test to +g+. Default is 50.
+
+==== self.population_size =  s
+Changes the population size in each test to +g+. Default is 20.
+
+==== self.repeat          =  r
+Changes the number of times each test will be repeated to +r+. Default is 10, a higher number here will take longer to 
+complete, but will improve the accuracy of the results.
+
+
+
+
+
+

data/data/CROSSOVER

@@ -0,0 +1,49 @@
+== Crossover documentation
+A crossover operator combines two parents to generate one or (usually) two children.
+
+The crossover operator should be defined as a +cross+ method in the metaclass of your genotype class.
+   class Example < Genotype
+     ...
+     class << self
+       def cross(parent1,parent2)
+         # generate children. 
+       end
+     end
+     use NullCrossover # or include some builtin operator
+   end
+Also see the Genotype#from_genes function, which can be useful for generating children after extracting and recombining the parents' genes.
+
+The builtin crossover operators are implemented as modules which should be included in the metaclass. 
+Using the Class#use keyword does this automatically. 
+
+== General Crossovers
+=== NullCrossover
+Just returns copies of the two parents, i.e. performs no crossover at all.
+
+== List-based Crossovers
+These crossovers can be used for all list- and string-based genotypes.
+
+=== SinglePointCrossover
+Standard single point crossover. Returns two children.
+
+=== UniformCrossover
+Standard uniform crossover.Returns two children.
+
+
+== Specialized Crossovers
+=== For PermutationGenotype
+PermutationCrossover is a partial preservation crossover for permutations.
+It is fairly destructive, which can lead to poor performance.
+
+
+== Meta-crossovers
+These functions take one or more crossover modules and generate a new crossover module.
+
+=== SingleChild(crossover)  (#SingleChild)
+Applies an arbitrary crossover and returns a random child.
+ 
+=== PCross(p,crossover,othercrossover=NullCrossover)
+Applies an arbitrary crossover with probability p, and another crossover with probability 1-p.
+
+
+ 

data/data/GENOTYPE

@@ -0,0 +1,49 @@
+== Genotype documentation
+The genotype, aka genome, aka chromosomes is a simple representation of a solution to your problem.
+This is usually an array of numbers or bits.
+
+=== Creating your own.
+If you are creating your own genotype, just inherit from the base Genotype class.
+You should initialize an instance in the +initialize+ method, and make sure the +genes+ and +genes=+ functions work properly.
+
+The base class includes NullCrossover, NullMutator and Elitism(ScaledRouletteSelection(),1) by default.
+
+All of the other genotypes described here inherit the base class, and its associated selection/crossover/mutation operators, unless
+otherwise indicated.
+
+=== List-based genotypes  (file)[link:files/lib/charlie/list/list_genotype_rb.html]
+All of these genotypes are based on arrays and can use the list-based crossover and mutation operators.
+They are all generated dynamically by functions, and should be used like:
+
+ class MyGenotype < FloatListGenotype(5)
+   def fitness
+     ...
+   end
+ end
+
+
+====   FloatListGenotype(n,range=0..1)   
+Genotype of +n+ floats in the range +range+.
+
+Includes <tt>ListMutator()</tt> (with default parameters :expected_n[3], :uniform[ 0.25 ]) and <tt>SinglePointCrossover</tt> by default.
+
+====  BitStringGenotype(n)
+Genotype of +n+ bits. +genes+ returns an array of 0/1, +to_s+ returns a string.
+
+Includes <tt>ListMutator(:expected_n[3],:flip), SinglePointCrossover</tt> by default.
+
+==== StringGenotype(n,elements)
+Genotype of +n+ elements (not necessarily chars).
+
+Includes <tt>ListMutator(:expected_n[2],:replace[*elements]), SinglePointCrossover</tt> by default.
+
+=== Specialized genotypes
+These genotypes have their own crossover and mutation operators.
+
+==== PermutationGenotype(n,elements=0...n)  (file)[link:files/lib/charlie/permutation/permutation_rb.html]
+Genotype for permutations. Includes PermutationMutator and PermutationCrossover by default.
+
+
+
+
+

data/data/MUTATION

@@ -0,0 +1,43 @@
+== Mutation documentation
+A mutation operator mutates a single instance in place.
+
+
+
+The mutation operator should be defined as a +mutate!+ method in your genotype class.
+   class Example < Genotype
+     def mutate!
+       # apply mutation here.
+     end
+     use NullMutator # or include some builtin operator
+   end
+
+The non-destructive counterpart +mutate+ is defined automatically by Genotype#mutate.
+
+== General Mutators
+=== NullMutator
+Just returns self
+
+== List-based Mutators
+These crossovers can be used for all list- and string-based genotypes.
+
+=== ListMutator(strategy=:expected_n ,point_mutator=:uniform)
+Generates a wide variety of mutators for lists, strings and bitstrings.
+
+* strategy can be a proc or one of the MutationStrategies : single point, multi-point and probabilistic.
+* point_mutator can be a proc or one of the PointMutators : bit flipping, replacing elements, or adding some offset.
+See the documentation of list_mutate.rb[link:files/lib/charlie/list/list_mutate_rb.html] for more info on these.
+
+Both of these parameters use Symbol#[] in the examples. <tt>:replace['a','b']</tt> is simply equivalent to <tt>[:replace,'a','b']</tt>
+
+== Specialized Mutators
+=== For PermutationGenotype
+PermutationMutator is a transposition mutator for permutations.
+
+== Meta-mutators
+These functions take one or more mutator modules and generate a new mutator module.
+
+=== PMutate(p,mutator,othermutator=NullMutator)
+Applies an arbitrary mutator with probability p, and another mutator with probability 1-p.
+
+
+ 

data/data/SELECTION

@@ -0,0 +1,48 @@
+== Selection documentation
+A selection operator generates the new generation from the old.
+
+
+
+The selection strategy should be defined as a +next_generation+ method in the metaclass of your genotype class.
+   class Example < Genotype
+     ...
+     class << self
+       def next_generation(population)
+         # select parents and yield(parent1,parent2) them to the crossover and mutation operator. Create an array from several of these calls to get the next generation.
+       end
+     end
+     use RouletteSelection # or include some builtin operator
+   end
+
+
+== Fitness-based selection strategies
+These strategies work with genotype classes which define a +fitness+ function. The +fitness+ function should return a number, higher fitness means better and more likely to be selected. All except RouletteSelection can handle negative fitness values.
+
+*   RandomSelection
+*   TruncationSelection(best=0.3)
+*   BestOnlySelection
+*   RouletteSelection
+*   ScaledRouletteSelection(&block)
+*   TournamentSelection(group_size=4,n_times=nil)   
+
+The documentation for selection_rb[link:files/lib/charlie/selection_rb.html] contains explanations for most of these.
+
+=== Meta-selection
+==== Elitism(selection,n=1)
+Generates a module which applies elitism to some selection strategy. This:
+* saves the best +n+ solutions
+* applies the selection
+* replaces the last +n+ individuals in the new population with the best +n+ of the old population (unless the newer individual has higher fitness).
+This ensures the maximum fitness can never decrease.
+
+
+
+== Co-evolutionary selection strategies
+These strategies work with genotype classes which define a <tt>fight(other)</tt> function. 
+This function should return true if the instance defeats +other+ in a 'fight'.
+
+*  GladiatorialSelection
+
+Because there is no way to determine who is the actual best individual, using Population#benchmark 
+for comparing strategies for convergence speed, etc.
+is not possible. Defining a fitness function as some statistic you want to track and then using benchmark should be possible, but is untested.