revac 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d7c4ca351b69ea97d4e61ce1a0e2a615204c22b4
+  data.tar.gz: fa2f20c8a5f837c9ebe29db0e95fdffb0f9733c0
+SHA512:
+  metadata.gz: e78e574cde74e8822b3dbf17b4766e208cb63c87ad6c3cd5b6e64cbe506c5bfc87fc4d8635a60431189770246526a26552280e23e7510f156762ae2438ddf26b
+  data.tar.gz: a05be6bc722d77ddf0006e18f75eac50d906a5be3d468f7b84ac4b96274a2d0fa834caefe04a823a9f64ad5b820c52b856eb788690db205eefd4eab1383a1137

data/Gemfile

@@ -0,0 +1,10 @@
+# encoding: utf-8
+
+source 'http://rubygems.org'
+
+group :development do
+	gem 'jeweler'
+  gem 'rake'
+  gem 'rdoc'
+  gem 'bundler'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Chris Timperley
+
+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/README.md

@@ -0,0 +1,4 @@
+RubyREVAC
+=========
+
+A Ruby-based implementation of the REVAC meta-heuristic tuner (Relevance Estimation and Value Calibration of Evolutionary Algorithm Parameters).

data/Rakefile

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+# Load all dependencies.
+require 'rubygems'
+require 'bundler'
+require 'rake'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'jeweler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+# Gem Specification.
+Jeweler::Tasks.new do |gem|
+  gem.name = "revac"
+  gem.homepage = "http://github.com/ChrisTimperley/RubyREVAC"
+  gem.license = "MIT"
+  gem.summary = "Implementation of REVAC tuner for meta-heuristics (Relevance Estimation and Value Calibration
+of Evolutionary Algorithm Parameters)."
+  gem.description = <<-EOF
+    An implementation of the REVAC tuner (Relevance Estimation and Value Calibration
+of Evolutionary Algorithm Parameters) proposed by V. Nannen and  A.E. Eiben, extended to work with arbitrary meta-heuristics
+implemented on arbitrary platforms.
+  EOF
+  gem.email = "christimperley@gmail.com"
+  gem.author = "Chris Timperley"
+end
+
+# Gem Management.
+Jeweler::RubygemsDotOrgTasks.new
+
+# Unit Testing.
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+# Documentation.
+task :default => :test
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "revac #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/revac.rb

@@ -0,0 +1,207 @@
+# encoding: utf-8
+require 'CSV' unless defined?(CSV)
+
+# Implements the REVAC tuning method (Relevance Estimation and Value
+# Calibration of Evolutionary Algorithm Parameters), proposed by Nannen and
+# Eiben, which provides a fast and rational approach to parameter tuning for
+# meta-heuristics.
+#
+# Although originally designed for finding the optimal parameter setup for
+# evolutionary algorithms, this REVAC implementation may also be used to
+# tune other meta-heuristics, such as Ant Colony Optimisation or Particle
+# Swarm Optimisation.
+module REVAC
+
+  # Used to hold the name and range of legal values for a search parameter.
+  Parameter = Struct.new(:name, :range)
+
+  # Logs a parameter vector and its associated utility function value using
+  # a given CSV file.
+  #
+  # ==== Parameters
+  # [+path+]        The path to the output CSV file.
+  # [+evaluation+]  The current evaluation.
+  # [+vector+]      The parameter vector table.
+  # [+utility+]     The utility of the given vector.
+  def self.log(path, evaluation, vector, utility)
+    CSV.open(path, 'ab') do |f|
+      f << [evaluation] + vector + [utility]
+    end
+  end
+
+  # Computes the utility (response) of a given parameter vector.
+  #
+  # ==== Parameters
+  # [+vector+]      The parameter vector to evaluate.
+  # [+parameters+]  The list of tunable parameters.
+  # [+algorithm+]   A function which takes the a hash of parameter
+  #                 values as input, performs a given algorithm and
+  #                 returns the best fitness value found.
+  # [+runs+]        The number of runs to use for each parameter
+  #                 vector.
+  def self.evaluate_vector(vector, parameters, algorithm, runs)
+
+    # Transform the vector into a hash of parameter names and
+    # settings and compute the mean best fitness using this
+    # parameter vector across a given number of runs.
+    vector = Hash[vector.to_a.each_with_index.map { |v, i|
+      [parameters[i].name, v]
+    }]
+    Array.new(runs) { algorithm[vector] }.inject(:+).to_f / runs
+
+  end
+
+  # Performs REVAC mutation on an individual at a given index within the vector
+  # table to produce a new mutated vector.
+  #
+  # ==== Parameters
+  # [+random+]  The random number generator.
+  # [+table+]   The vector table.
+  # [+index+]   The index of the individual to mutate.
+  # [+h+]       The radius of the partial marginal density function.
+  #
+  # ==== Returns
+  # The resulting vector.
+  def self.mutate(random, table, index, h)
+
+    # Sort the values of this parameter for all vectors into ascending order
+    # before calculating the upper and lower bounds of the mutation distribution
+    # and drawing a new parameter value at uniform random.
+    return Array.new(table[0].length) do |i|
+      window = (0...table.length).sort { |x, y| table[x][i] <=> table[y][i] }
+      position = window.find_index(index)
+      window = [
+        window[[position - h, 0].max],
+        window[[position + h, table.length - 1].min]
+      ]
+      window = table[window[0]][i] .. table[window[1]][i]
+      random.rand(window)
+    end
+    
+  end
+
+  # Performs a multi-parent crossover on a list of parent chromosomes to produce
+  # a new chromosome.
+  #
+  # ==== Parameters
+  # [+random+]  The random number generator.
+  # [+parents+] The parents of the child chromosome.
+  #
+  # ==== Returns
+  # The proto-child vector of the provided parent vectors.
+  def self.crossover(random, parents)
+    Array.new(parents[0].length) { |i| parents[random.rand(parents.length)][i] }
+  end
+
+  # Tunes a given algorithm using REVAC.
+  #
+  # ==== Parameters
+  # [+parameters+]  A list of parameters to optimise. Each entry in the
+  #                 list contains the name of the parameter and the range
+  #                 of values that it can take.
+  # [+opts+]        A hash of keyword options to this method.
+  # [+&algorithm+]  A lambda function which takes a hash of named parameters
+  #                 as its input, uses them to perform a given algorithm,
+  #                 and returns the fitness of the best individual found.
+  #
+  # ==== Options
+  # [+evaluations+] The maximum number of evaluations to perform.
+  # [+parents+]     The number of parents to use when creating each child.
+  # [+runs+]        The number of runs to perform for each vector.
+  # [+vectors+]     The number of parameter vectors in the population.
+  # [+h+]           The radius of the partial marginal density function.
+  # [+log+]         The path to the output CSV file.
+  # [+debug+]       Used to enable / disable evaluation logging to the console.
+  #
+  # ==== Returns
+  # A hash containing the `optimal' parameter values for the given problem. 
+  def self.tune(parameters, opts = {}, &algorithm)
+
+    # Load the default values for any omitted parameters.
+    opts[:vectors] ||= 80
+    opts[:parents] ||= 40
+    opts[:h] ||= 5
+    opts[:runs] ||= 5
+    opts[:evaluations] ||= 5000
+    opts[:debug] ||= false
+
+    # The RNG to use during optimisation.
+    random = Random.new
+
+    # Convert the list of parameter name/range pairs into a list of parameter
+    # objects.
+    parameters = parameters.map { |n, r| Parameter.new(n, r) }
+
+    # Initialise evolution statistics.
+    oldest = 0
+    iterations = 0
+    evaluations = 0
+
+    # Initialise the output CSV file (if one has been given).
+    CSV.open(opts[:log], 'wb') do |f|
+      f << ['Evaluation'] + parameters.map { |p| p.name } + ['Utility']
+    end if opts[:log]
+
+    # Draw an initial set of parameter vectors at uniform random from
+    # their initial distributions.
+    table = Array.new(opts[:vectors]) do
+      parameters.map { |p| random.rand(p.range) }
+    end
+
+    # Compute the utility of each parameter vector, before finding and recording
+    # the best parameter vector.
+    utility = table.map do |v|
+      u = evaluate_vector(v, parameters, algorithm, opts[:runs])
+      log(opts[:output], evaluations, v, u) if opts[:log]
+      puts "Evaluation #{evaluations}: #{u}" if opts[:debug]
+      evaluations += 1
+      u
+    end
+    best_utility, best_vector = utility.each_with_index.min
+    best_vector = table[best_vector]
+
+    # Keep optimising until the termination condition is met.
+    until evaluations == opts[:evaluations]
+      
+      # Select the N-best vectors from the table as the parents
+      # of the next parameter vector.
+      parents = (0...opts[:vectors]).sort { |x, y|
+        utility[x] <=> utility[y]
+      }.take(opts[:parents]).map { |i| 
+        table[i]
+      }
+
+      # Perform multi-parent crossover on the N parents to create
+      # a proto-child vector.
+      child = crossover(random, parents)
+
+      # Replace the oldest vector from the population with this
+      # proto-child vector, before mutating it and computing its
+      # utility.
+      table[oldest] = child
+      table[oldest] = mutate(random, table, oldest, opts[:h])
+      utility[oldest] = evaluate_vector(child, parameters, algorithm, opts[:runs])
+
+      # Update the best vector if the child vector is an improvement.
+      if utility[oldest] < best_utility
+        best_vector = table[oldest]
+        best_utility = utility[oldest]
+      end
+
+      # Update evolution statistics and perform logging.
+      iterations += 1
+      evaluations += 1
+      log(opts[:output], evaluations, child, utility[oldest]) if opts[:log]
+      puts "Evaluation #{evaluations}: #{utility[oldest]}" if opts[:debug]
+      oldest = (oldest + 1) % opts[:vectors]
+
+    end
+
+    # Return the optimal parameter vector as a hash.
+    return Hash[parameters.zip(0...parameters.length).map { |param, index|
+      [param.name, best_vector[index]]
+    }]
+
+  end
+
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: revac
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Timperley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      An implementation of the REVAC tuner (Relevance Estimation and Value Calibration
+  of Evolutionary Algorithm Parameters) proposed by V. Nannen and  A.E. Eiben, extended to work with arbitrary meta-heuristics
+  implemented on arbitrary platforms.
+email: christimperley@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- lib/revac.rb
+- test/.gitkeep
+homepage: http://github.com/ChrisTimperley/RubyREVAC
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: Implementation of REVAC tuner for meta-heuristics (Relevance Estimation and
+  Value Calibration of Evolutionary Algorithm Parameters).
+test_files: []