biopsy 0.1.0.alpha

data/lib/biopsy/optimisers/tabu_search.rb

@@ -0,0 +1,437 @@
+require 'rubystats'
+require 'statsample'
+require 'set'
+require 'pp'
+require 'matrix'
+
+# TODO:
+# - make distributions draw elements from the range, not just from distribution (DONE)
+# - test on real SOAPdt data (in progress)
+# - make code to run 100 times for a particular dataset, capture the trajectory, and plot the progress over time along with a histogram of the data distribution
+# - plot SD and step-size over time
+# - capture data about convergence (done for toy data, need to repeat for other data)
+
+module Biopsy
+
+  # a Distribution represents the probability distribution from
+  # which the next value of a parameter is drawn. The set of all
+  # distributions acts as a probabilistic neighbourhood structure.
+  class Distribution
+
+    attr_reader :sd
+
+    # create a new Distribution
+    def initialize(mean, range, sd_increment_proportion, sd)
+      @mean = mean
+      @maxsd = range.size * 0.66
+      @minsd = 0.5
+      @sd = sd
+      self.limit_sd
+      @range = range
+      @sd_increment_proportion = sd_increment_proportion
+      self.generate_distribution
+    rescue
+        raise "generation of distribution with mean: #{@mean}, sd: #{@sd} failed."
+    end
+
+    # generate the distribution
+    def generate_distribution
+      @dist = Rubystats::NormalDistribution.new(@mean, @sd)
+    end
+
+    def limit_sd
+      @sd = @sd > @maxsd ? @maxsd : @sd
+      @sd = @sd < @minsd ? @minsd : @sd
+    end
+
+    # loosen the distribution by increasing the sd
+    # and renerating
+    def loosen(factor=1)
+      @sd += @sd_increment_proportion * factor * @range.size
+      self.limit_sd
+      self.generate_distribution
+    end
+
+    # tighten the distribution by reducing the sd
+    # and regenerating
+    def tighten(factor=1)
+      @sd -= @sd_increment_proportion * factor * @range.size unless (@sd <= 0.01)
+      self.limit_sd
+      self.generate_distribution
+    end
+
+    # set standard deviation to the minimum possible value
+    def set_sd_min
+      @sd = @minsd
+    end
+
+    # draw from the distribution
+    def draw
+      r = @dist.rng.to_i
+      raise "drawn number must be an integer" unless r.is_a? Integer
+      # keep the value inside the allowed range
+      r = 0 - r if r < 0
+      if r >= @range.size
+        diff = 1 + r - @range.size
+        r = @range.size - diff
+      end
+      @range[r]
+    end
+
+  end # Distribution
+
+  # a Hood represents the neighbourhood of a specific location
+  # in the parameter space being explored. It is generated using
+  # the set of Distributions, which together define the neighbourhood
+  # structure.
+  class Hood
+
+    attr_reader :best
+
+    def initialize(distributions, max_size, tabu)
+      # tabu
+      @tabu = tabu 
+      # neighbourhood
+      @max_size = max_size
+      @members = []
+      @best = {
+        :parameters => nil,
+        :score => 0.0
+      }
+      # probabilities
+      @distributions = distributions
+      self.populate
+    end
+
+    # generate a single neighbour
+    def generate_neighbour
+      n = 0
+      begin
+        if n >= 100
+          # taking too long to generate a neighbour, 
+          # loosen the neighbourhood structure so we explore further
+          # debug("loosening distributions")
+          @distributions.each do |param, dist|
+            dist.loosen
+          end
+        end
+        # preform the probabilistic step move for each parameter
+        neighbour = Hash[@distributions.map { |param, dist| [param, dist.draw] }]
+        n += 1
+      end while self.is_tabu?(neighbour)
+      @tabu << neighbour
+      @members << neighbour
+    end
+
+    # update best?
+    def update_best? current
+      @best = current.clone if current[:score] > @best[:score]
+    end
+
+    # true if location is tabu
+    def is_tabu? location
+      @tabu.member? location
+    end
+
+    # generate the population of neighbours
+    def populate
+      @max_size.times do |i|
+        self.generate_neighbour
+      end
+    end
+
+    # return the next neighbour from this Hood
+    def next
+      @members.pop
+    end
+
+    # returns true if the current neighbour is
+    # the last one in the Hood
+    def last?
+      @members.empty?
+    end
+
+  end # Hood
+
+  # A Tabu Search implementation with a domain-specific probabilistic
+  # learning heuristic for optimising over an unconstrained parameter
+  # space with costly objective evaluation.
+  class TabuSearch #< OptmisationAlgorithm
+
+    attr_reader :current, :best, :hood_no
+    attr_accessor :max_hood_size, :sd_increment_proportion, :starting_sd_divisor, :backtrack_cutoff
+    attr_accessor :jump_cutoff
+
+    Thread = Struct.new(:best, :tabu, :distributions, 
+                        :standard_deviations, :recent_scores, 
+                        :iterations_since_best, :backtracks,
+                        :current, :current_hood, :loaded)
+
+    def initialize(parameter_ranges, threads=8, limit=nil)
+
+      @ranges = parameter_ranges
+
+      # solution tracking
+      @best = nil
+
+      # tabu list
+      @tabu = Set.new
+      @tabu_limit = nil
+      @start_time = Time.now
+
+      # neighbourhoods
+      @max_hood_size = 5
+      @starting_sd_divisor = 5
+      @standard_deviations = {}
+      @sd_increment_proportion = 0.05
+      @hood_no = 1
+
+      # adjustment tracking
+      @recent_scores = []
+      @jump_cutoff = 10
+
+      # logging
+      @log_data = false
+      @logfiles = {}
+      self.log_setup
+
+      # backtracking
+      @iterations_since_best = 0
+      @backtrack_cutoff = 2
+      @backtracks = 1.0
+
+      # convergence
+      @num_threads = 2
+      @threads = []
+
+    end # initialize
+
+    def setup start_point
+      @current = {:parameters => start_point, :score => nil}
+      @best = @current
+      self.setup_threads
+    end
+
+    # given the score for a parameter set,
+    # return the next parameter set to be scored
+    def run_one_iteration(parameters, score)
+      @current = {:parameters => parameters, :score => score}
+      # update best score?
+      self.update_best?
+      # log any data
+      self.log
+      # cycle threads
+      self.load_next_thread
+      # get next parameter set to score
+      self.next_candidate
+      @current[:parameters]
+    end # run_one_iteration
+
+    def setup_threads
+      @num_threads.times do
+        @threads << Thread.new
+      end
+      @threads.each do |thread|
+        @current = {
+          :parameters => self.random_start_point,
+          :score => nil
+        }
+        @best = @current
+        @standard_deviations = {}
+        @recent_scores = []
+        @tabu = Set.new
+        self.define_neighbourhood_structure
+        @current_hood = Biopsy::Hood.new(@distributions, @max_hood_size, @tabu)
+        thread.members.each do |sym|
+          ivar = self.sym_to_ivar_sym sym
+          thread[sym] = self.instance_variable_get(ivar)
+        end
+        thread.loaded = false
+      end
+      @current_thread = @num_threads - 2
+    end
+
+    def load_next_thread
+      thread = @threads[@current_thread]
+      if thread.loaded
+        thread.members.each do |sym|
+          ivar = self.sym_to_ivar_sym sym
+          thread[sym] = self.instance_variable_get(ivar)
+        end
+      else
+        thread.loaded = true
+      end
+      @current_thread = (@current_thread + 1) % @num_threads
+      thread = @threads[@current_thread]
+      thread.members.each do |sym|
+        ivar = self.sym_to_ivar_sym sym
+        self.instance_variable_set(ivar, thread[sym])
+      end
+    end
+
+    def update_best?
+      @current_hood.update_best? @current
+      if @best[:score].nil? || @current[:score] > @best[:score]
+        @best = @current.clone
+      else
+        @iterations_since_best += 1
+      end
+    end
+
+    # use probability distributions to define the
+    # initial neighbourhood structure
+    def define_neighbourhood_structure
+      # probabilities
+      @distributions = {}
+      @current[:parameters].each_pair do |param, value|
+        self.update_distribution(param, value)
+      end
+    end
+
+    # update the neighbourhood structure by adjusting the probability
+    # distributions according to total performance of each parameter
+    def update_neighbourhood_structure
+      self.update_recent_scores
+      best = self.backtrack_or_continue
+      unless @distributions.empty?
+        @standard_deviations = Hash[@distributions.map { |k, d| [k, d.sd] }]
+      end
+      best[:parameters].each_pair do |param, value|
+        self.update_distribution(param, value)
+      end
+    end
+
+    # set the distribution for parameter +:param+ to a new one centered
+    # around the index of +value+
+    def update_distribution(param, value)
+      mean = @ranges[param].index(value)
+      range = @ranges[param]
+      sd = self.sd_for_param(param, range)
+      @distributions[param] = Biopsy::Distribution.new(mean, 
+                                                      range,
+                                                      @sd_increment_proportion,
+                                                      sd)
+    end
+
+    # return the standard deviation to use for +:param+
+    def sd_for_param(param, range)
+      @standard_deviations.empty? ? (range.size.to_f / @starting_sd_divisor) : @standard_deviations[param]
+    end
+
+    # return the correct 'best' location to form a new neighbourhood around
+    # deciding whether to continue progressing from the current location
+    # or to backtrack to a previous good location to explore further
+    def backtrack_or_continue
+      best = nil
+      if (@iterations_since_best / @backtracks) >= @backtrack_cutoff * @max_hood_size
+        self.backtrack
+        best = @best
+      else
+        best = @current_hood.best
+        self.adjust_distributions_using_gradient
+      end
+      if best[:parameters].nil?
+        # this should never happen!
+        best = @best        
+      end
+      best
+    end
+
+    def backtrack
+      @backtracks += 1.0
+      # debug('backtracked to best')
+      @distributions.each_pair { |k, d| d.tighten }
+    end
+
+    # update the array of recent scores
+    def update_recent_scores
+      @recent_scores.unshift @best[:score]
+      @recent_scores = @recent_scores.take @jump_cutoff
+    end
+
+    # use the gradient of recent best scores to update the distributions
+    def adjust_distributions_using_gradient
+      return if @recent_scores.length < 3
+      vx = (1..@recent_scores.length).to_a.to_scale
+      vy = @recent_scores.reverse.to_scale
+      r = Statsample::Regression::Simple.new_from_vectors(vx,vy)
+      slope = r.b
+      if slope > 0
+        @distributions.each_pair { |k, d| d.tighten slope }
+      elsif slope < 0
+        @distributions.each_pair { |k, d| d.loosen slope }
+      end
+    end
+
+    # shift to the next neighbourhood
+    def next_hood
+      @hood_no += 1
+      # debug("entering hood # #{@hood_no}")
+      self.update_neighbourhood_structure
+      @current_hood = Hood.new(@distributions, @max_hood_size, @tabu)
+    end
+
+    # get the next neighbour to explore from the current hood
+    def next_candidate
+      @current[:parameters] = @current_hood.next
+      @current[:score] = nil
+      # exhausted the neighbourhood?
+      if @current_hood.last?
+        # debug(@current_hood.best)
+        self.next_hood
+      end
+    end
+
+    # check termination conditions 
+    # and return true if met
+    def finished?
+      return false if @threads.first.recent_scores.size < @jump_cutoff
+      scores = @threads.map { |t| t.recent_scores }
+      scores.map { |s| s.mean }.uniq.length == 1
+    end
+
+    # True if this algorithm chooses its own starting point
+    def knows_starting_point?
+      true
+    end
+
+    def log_setup
+      if @log_data
+        require 'csv'
+        @logfiles[:standard_deviations] = CSV.open('standard_deviations.csv', 'w')
+        @logfiles[:best] = CSV.open('best.csv', 'w')
+        @logfiles[:score] = CSV.open('score.csv', 'w')
+        @logfiles[:params] = CSV.open('params.csv', 'w')
+      end
+    end
+
+    def log
+      if @log_data
+        @logfiles[:standard_deviations] << @distributions.map { |k, d| d.sd }
+        @logfiles[:best] << [@best[:score]]
+        @logfiles[:score] << [@current[:score]]
+        @logfiles[:params] << @current[:parameters].map { |k, v| v }
+      end
+    end
+
+    def log_teardown
+      @logfiles.each_pair do |k, f|
+        f.close
+      end
+    end
+
+    def sym_to_ivar_sym sym
+      "@#{sym.to_s}".to_sym
+    end
+
+    def select_starting_point
+      self.random_start_point
+    end
+
+    def random_start_point
+      Hash[@ranges.map { |p, r| [p, r.sample] }] 
+    end
+
+  end # TabuSearch
+
+end # Biopsy

data/lib/biopsy/settings.rb

@@ -0,0 +1,110 @@
+# Optimisation Framework: Settings
+#
+# == Description
+#
+# The Settings singleton object maintains general settings (as opposed to
+# those specific to the experiment, which are contained in the Experiment
+# object).
+#
+# Key settings include the location(s) of config file(s), the Domain that
+# is currently active, and the directories to search for objective functions.
+#
+# Methods are provided for loading, listing, accessing and saving the settings
+#
+module Biopsy
+
+  require 'singleton'
+  require 'yaml'
+  require 'pp'
+
+  class SettingsError < StandardError
+  end
+
+  class Settings
+    include Singleton
+
+    attr_accessor :base_dir
+    attr_accessor :target_dir
+    attr_accessor :domain_dir
+    attr_accessor :domain
+    attr_accessor :objectives_dir
+    attr_accessor :objectives_subset
+    attr_accessor :sweep_cutoff
+
+    def initialize
+      self.set_defaults
+    end
+
+    def set_defaults
+      # defaults
+      @config_file = '~/.biopsyrc'
+      @base_dir = ['.']
+      @target_dir = ['targets']
+      @domain_dir = ['domains']
+      @domain = 'test_domain'
+      @objectives_dir = ['objectives']
+      @objectives_subset = nil
+      @sweep_cutoff = 100
+    end
+
+    # Loads settings from a YAML config file. If no file is
+    # specified, the default location ('~/.biopsyrc') is used.
+    # Settings loaded from the file are merged into any
+    # previously loaded settings.
+    def load(config_file=@config_file)
+      newsets = YAML::load_file(config_file)
+      raise 'Config file was not valid YAML' if newsets == false
+      newsets.deep_symbolize.each_pair do |key, value|
+        varname = "@#{key.to_s}".to_sym
+        unless self.instance_variables.include? varname
+          raise SettingsError.new "Key #{key.to_s} in settings file is not valid"
+        end
+        self.instance_variable_set(varname, value)
+      end
+    end
+
+    # Saves the settings to a YAML config file. If no file is
+    # specified, the default location ('~/.biopsyrc') is used.
+    def save(config_file=@config_file)
+      File.open(config_file, 'w') do |f|
+        f.puts self.to_s
+      end
+    end
+
+    # Returns a hash of the settings
+    def all_settings
+      settings = {}
+      instance_variables.each do |var|
+        key = var[1..-1]
+        settings[key] = self.instance_variable_get(var)
+      end
+      settings
+    end
+
+    # Returns a YAML string representation of the settings
+    def to_s
+      all_settings.to_yaml
+    end
+
+    # Locate the first YAML config file whose name
+    # excluding extension matches +:name+ (case insensitive)
+    # in dirs listed by the +:dir_key+ setting.
+    def locate_config(dir_key, name)
+      dir_key = "@#{dir_key.to_s}".to_sym
+      unless self.instance_variables.include? dir_key
+        raise SettingsError.new "no setting found for compulsory key #{dir_key}"
+      end
+      self.instance_variable_get(dir_key).each do |dir|
+        Dir.chdir ::File.expand_path(dir) do
+          Dir[name + '.yml'].each do |file|
+            return ::File.expand_path(file) if ::File.basename(file, '.yml').downcase == name.downcase
+          end
+        end
+      end
+
+      nil
+    end
+
+  end # Settings
+
+end # Biopsy

data/lib/biopsy/target.rb

@@ -0,0 +1,113 @@
+module Biopsy
+
+  class TargetLoadError < Exception
+  end
+
+  class Target
+    require 'yaml'
+    require 'ostruct'
+
+    # array of input files expected by the target constructor
+    attr_accessor :input_files
+    # array of output files to keep for submission to objective
+    # functions during optimisation
+    attr_accessor :output_files
+    # hash mapping parameters to the ranges of values they can take
+    attr_reader :parameter_ranges
+    # path to the constructor code
+    attr_reader :constructor_path
+    attr_reader :domain
+
+    # create a new Target instance.
+    # arguments:
+    # +:domain+ the domain to which this target belongs (see Domain documentation)
+    def initialize domain
+      @domain = domain
+    end
+
+    # load target with +name+.
+    def load_by_name name
+      path = self.locate_definition name
+      raise TargetLoadError.new("Target definition file does not exist for #{name}") if path.nil?
+      config = YAML::load_file(path)
+      raise TargetLoadError.new("Target definition file #{path} is not valid YAML") if config.nil?
+      missing = self.check_config config.deep_symbolize
+      if missing
+        msg = "Target definition file #{path} is missing required fields: #{missing}"
+        raise TargetLoadError.new(msg)
+      end
+      errors = self.validate_config config
+      unless errors.empty?
+        raise TargetLoadError.new("Target definition file #{path} contains the following errors:\n - #{errors.join("\n - ")}")
+      end
+      self.store_config config
+      self.check_constructor
+      self.load_constructor
+    end
+
+    # given the name of a target, return the path
+    # to the definition YAML file. All +:target_dir+s defined in Settings are
+    # searched and the first matching YAML file is loaded. 
+    def locate_definition name
+      Settings.instance.locate_config(:target_dir, name)
+    end
+
+    # verify that +:config+ contains values for all essential target settings
+    # returning false if no keys are missing, or an array of the missing keys
+    # if any cannot be found
+    def check_config config
+      required = %w(input_files output_files parameter_ranges constructor_path)
+      missing = false
+      required.each do |key|
+        unless config.has_key? key.to_sym
+          missing ||= []
+          missing << key
+        end
+      end
+      missing
+    end
+
+    # validate the config against the domain definition. Return an array
+    # whose length will be the number of errors found. Thus an array of
+    # length 0 indicates that the config is valid according to the domain
+    # specification.
+    def validate_config config
+      @domain.target_valid? config
+    end
+
+    # Store the values in +:config+
+    def store_config config
+      config.each_pair do |key, value|
+        self.instance_variable_set('@' + key.to_s, value)
+      end
+    end
+
+    # Validate the constructor. True if valid, false otherwise.
+    def check_constructor
+      raise "constructor path is not defined for this target" if @constructor_path.nil?
+      self.valid_ruby? @constructor_path
+    end
+
+    # Load constructor
+    def load_constructor
+      require File.join(Settings.instance.target_dir, @constructor_path)
+      file_name = File.basename(@constructor_path, '.rb')
+      constructor_name = file_name.camelize
+      @constructor = Module.const_get(constructor_name).new
+    end
+
+    # Run the constructor for the parameter set +:params+
+    def run params
+      @constructor.run params
+    end
+
+    # true if file is valid ruby
+    def valid_ruby? file
+      return false unless ::File.exists? file
+      result = `ruby -c #{file} &> /dev/null`
+      !result.size.zero?
+    end
+
+  end # end of class Domain
+
+end # end of module Biopsy

data/lib/biopsy/version.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+
+module Biopsy
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    BUILD = 'alpha'
+
+    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
+  end
+end # Biopsy

data/lib/biopsy.rb

@@ -0,0 +1,13 @@
+require "biopsy/version"
+require "biopsy/base_extensions"
+require "biopsy/settings"
+require "biopsy/domain"
+require "biopsy/experiment"
+require "biopsy/target"
+require "biopsy/objective_handler"
+require "biopsy/objective_function"
+require "biopsy/opt_algorithm"
+require "biopsy/optimisers/genetic_algorithm"
+require "biopsy/optimisers/tabu_search"
+require "biopsy/optimisers/parameter_sweeper"
+require "biopsy/objectives/fastest_optimum"