feldtruby 0.3.8 → 0.3.9

data/.gitignore

@@ -47,3 +47,5 @@ pkg
 
 # For rubinius:
 #*.rbc
+
+related/*

data/README.md

@@ -2,10 +2,18 @@ feldtruby
 =========
 Robert Feldt's Common Ruby Code lib. I will gradually collect the many generally useful Ruby tidbits I have laying around and clean them up into here. Don't want to rewrite these things again and again... So far this collects a number of generally useful additions to the standard Ruby classes/libs and then includes a simple optimization framework (FeldtRuby::Optimize).
 
+Note that good documentation is not really a focus here. As things mature in here I will move logically unique/separate sets of functionality into separate Ruby libs/gems of useful code. At that point there will be more focus on documentation.
+
 email: robert.feldt ((a)) gmail.com
 
 Contents
 --------
+
+### Statistics
+* Cluster linkage metrics
+* Access to R from Ruby (extends existing lib so that you can more easily transfer complex objects back to Ruby)
+* ...
+
 ### Time
 	Time.timestamp()    				# Get a timestamp string back with the current time
 
@@ -47,17 +55,7 @@ numerical optimization using DE:
 		(1 - x)**2 + 100*(y - x*x)**2
 	}
 
-Contributing to feldtruby
-------------------------- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
-* Fork the project.
-* Start a feature/bugfix branch.
-* Commit and push until you are happy with your contribution.
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
 Copyright
 ------------
-Copyright (c) 2012 Robert Feldt. See LICENSE.txt for
+Copyright (c) 2012-2013 Robert Feldt. See LICENSE.txt for
 further details.

data/Rakefile

@@ -7,14 +7,31 @@ def psys(str)
   system str
 end
 
-desc "Run all tests"
-task :test do
+def run_tests(testFiles)
   helper_files = Dir["test/**/*helper*.rb"]
-  test_files = Dir["test/**/test*.rb"]
-  require_files = (helper_files + test_files).map {|f| "require \"#{f}\""}.join('; ')
+  require_files = (helper_files + testFiles).map {|f| "require \"#{f}\""}.join('; ')
   psys "ruby -Ilib:. -e '#{require_files}' --"
 end
 
+desc "Run all tests"
+task :test do
+  run_tests Dir["test/**/test*.rb"]
+end
+
+def filter_latest_changed_files(filenames, numLatestChangedToInclude = 1)
+  filenames.sort_by{ |f| File.mtime(f) }[-numLatestChangedToInclude, numLatestChangedToInclude]
+end
+
+desc "Run only the latest changed test file"
+task :t do
+  run_tests filter_latest_changed_files(Dir["test/**/test*.rb"])
+end
+
+desc "Run only the latest two changed test file"
+task :t2 do
+  run_tests filter_latest_changed_files(Dir["test/**/test*.rb"], 2)
+end
+
 desc "Clean up intermediate/build files"
 task :clean do
   FileUtils.rm_rf "pkg"

data/lib/feldtruby/array.rb

@@ -1,6 +1,11 @@
 require 'feldtruby/array/basic_stats'
 
 class Array
+	def map_with_index(&block)
+		index = -1 # Start below zero since we pre-increment in the loop
+		self.map {|v| block.call(v,index+=1)}
+	end
+
 	# Calculate the distance between the elements.
 	def distance_between_elements
 		return nil if self.length == 0

data/lib/feldtruby/minitest_extensions.rb

@@ -10,8 +10,18 @@ module MiniTest::Assertions
     pvalue = FeldtRuby.chi_squared_test(values)
     assert(pvalue > expectedPValue, msg || "Proportions differ! p-value is #{pvalue} (<0.05), counts: #{values.counts.inspect}")
   end
+
+  def assert_falsey(value, msg = nil)
+    assert(value.!, msg || "#{value} is not falsey (it is #{value})")
+  end
+
+  def assert_truthy(value, msg = nil)
+    assert(value, msg || "#{value} is not truthy (it is #{value})")
+  end
 end
 
 module MiniTest::Expectations
   infect_an_assertion :assert_similar_proportions, :must_have_similar_proportions
+  infect_an_assertion :assert_falsey, :must_be_falsey
+  infect_an_assertion :assert_truthy, :must_be_truthy
 end

data/lib/feldtruby/optimize/objective.rb

@@ -1,124 +1,128 @@
-
 require 'feldtruby/optimize'
 require 'feldtruby/float'
+require 'feldtruby/optimize/sub_qualities_comparators'
+
+module FeldtRuby::Optimize
 
-# An Objective captures one or more objectives into a single object
+# An Objective captures one or more (sub-)objectives into a single object
 # and supports a large number of ways to utilize basic objective
 # functions in a single framework. You subclass and add instance
 # methods named as 
 #   objective_min_qualityAspectName (for an objective/aspect to be minimized), or 
 #   objective_max_qualityAspectName (for an objective/aspect to be minimized).
+#
 # There can be multiple aspects (sub-objectives) for a single objective.
+#
+# An objective keeps track of the min and max value that has been seen so far
+# for each sub-objective.
+
 # This base class uses mean-weighted-global-ratios (MWGR) as the default mechanism
-# for handling multi-objectives i.e. with more than one sub-objective. 
-# An objective has version numbers to indicate the number of times the scale 
-# for the calculation of the ratios has been changed.
-class FeldtRuby::Optimize::Objective
-	attr_accessor :current_version, :logger
+# for handling multi-objectives i.e. with more than one sub-objective.
+#
+# An objective has version numbers to indicate the number of times a new min or max
+# value has been identified for a sub-objective.
+class Objective
+	# Current version of this objective. Is updated when the min or max values for a sub-objective
+	# has been updated.
+	attr_accessor :current_version
+
+	# For logging changes to the objective.
+	attr_accessor :logger
 
 	def initialize
 		@logger = nil # To avoid getting warnings that logger has not been initialized
 		@current_version = 0
-		@pareto_front = Array.new(num_aspects)
+		@pareto_front = Array.new(num_aspects) # The pareto front is misguided since it only has one best value per sub-objective, not the whole front!
 	end
 
-	def reset_quality_scale(candidate, aspectIndex, typeOfReset)
-		if (typeOfReset == :min && is_min_aspect?(aspectIndex)) || 
-		   (typeOfReset == :max && !is_min_aspect?(aspectIndex))
-			@pareto_front[aspectIndex] = candidate
-		end
+	# Return the number of aspects/sub-objectives of this objective.
+	def num_aspects
+		@num_aspects ||= aspect_methods.length
+	end
 
-		# Reset the best object since we have a new scale
-		@best_candidate = nil
-		@best_qv = nil
+	def num_sub_objectives
+		num_aspects
+	end
 
-		inc_version_number
+	def aspect_methods
+		@aspect_methods ||= self.methods.select {|m| is_aspect_method?(m)}
 	end
 
-	def update_best_candidate(candidate)
-		@best_candidate = candidate
-		@best_qv = candidate._quality_value
+	def is_min_aspect?(aspectIndex)
+		(@is_min_aspect ||= (aspect_methods.map {|m| is_min_aspect_method?(m)}))[aspectIndex]
 	end
 
-	def inc_version_number
-		@current_version += 1
+	def is_aspect_method?(methodNameAsSymbolOrString)
+		methodNameAsSymbolOrString.to_s =~ /^objective_(min|max)_([\w_]+)$/
 	end
 
-	# Return the number of aspects/sub-objectives of this objective.
-	def num_aspects
-		@num_aspects ||= aspect_methods.length
+	def is_min_aspect_method?(methodNameAsSymbolOrString)
+		methodNameAsSymbolOrString.to_s =~ /^objective_min_([\w_]+)$/
 	end
 
-	# Class for representing multi-objective qualitites...
-	class QualityValue
-		attr_reader :qv, :sub_qvs
+	# The vectors can be mapped to a more complex candidate object before we call
+	# the sub objectives to calc their quality values. Default is no mapping but subclasses
+	# can override this for more complex evaluation schemes.
+	def map_candidate_vector_to_candidate_to_be_evaluated(vector)
+		vector
+	end
 
-		def initialize(qv, subQvs, objective)
-			@qv, @sub_qvs, @objective = qv, subQvs, objective
-			@version = objective.current_version
-		end
+	# Return a vector of the "raw" sub-quality values, i.e. the fitness value for each sub-objective.
+	# The candidate vector is assumed to be a vector of values.
+	def sub_qualities_of(candidateVector)
+		candidate = map_candidate_vector_to_candidate_to_be_evaluated(candidateVector)
+		aspect_methods.map {|omethod| self.send(omethod, candidate)}
+	end
 
-		def <=>(other)
-			@qv <=> other.qv
-		end
+	# Return a single quality value for the whole objective for a given candidate. 
+	# By default this uses a variant of Bentley and Wakefield's sum-of-weighted-global-ratios (SWGR)
+	# called mean-of-weighted-global-ratios (MWGR) which always returns a fitness value
+	# in the range (0.0, 1.0) with 1.0 signaling the best fitness seen so far. The scale is adaptive
+	# though so that the best candidate so far always has a fitness value of 1.0.
+	def quality_of(candidate, weights = self.default_weights)
+		return candidate._quality_value_without_check if quality_value_is_up_to_date?(candidate)
+		num_aspects == 1 ? qv_single(candidate) : qv_mwgr(candidate, weights)
+	end
 
-		# Two quality values are the same if they have the same qv, regardless of their
-		# sub qualities.
-		def ==(other)
-			other = other.qv if QualityValue === other
-			@qv == other
-		end
+	# Set the default weights to use when calculating a single quality values from
+	# the vector of sub-qualities.
+	def default_weights=(weights)
+		raise "Must be same number of weights as there are sub-objectives (#{num_aspects}), but is #{weights.length}" unless weights.length == num_aspects
+		@default_weights = weights
+	end
 
-		def improvement_in_relation_to(other)
-			if QualityValue === other
-				pdiff = @qv.ratio_diff_vs(other.qv)
-				subpdiffs = @sub_qvs.zip(other.sub_qvs).map {|s, os| s.ratio_diff_vs(os)}
-				qinspect(pdiff, subpdiffs, "Difference", "SubQ. differences", true) + ", #{report_on_num_differences(subpdiffs)}"
-			else
-				@qv.improvement_in_relation_to(other)
-			end
-		end
+	# Current default weights among the sub-objectives (nil if none have been set)
+	attr_reader :default_weights
 
-		def report_on_num_differences(subQvRatioDiffs)
-			num_inc = subQvRatioDiffs.select {|v| v > 0}.length
-			num_dec = subQvRatioDiffs.select {|v| v < 0}.length
-			num_same = subQvRatioDiffs.length - num_inc - num_dec
-			"#{num_inc} increased, #{num_dec} decreased, #{num_same} same"
-		end
+	# Return the fitness of a candidate. It is the same as the quality value above.
+	def fitness_for(candidate, weights = nil)
+		quality_of(candidate, weights)
+	end
 
-		def qinspect(qv, subQvs, qvDesc = "Quality", subQvDesc = "SubQualities", subQvsAreRatios = false, qvIsRatio = true)
-			subQvs = subQvs.map {|v| v*100.0} if subQvsAreRatios
-			sqs = subQvs.map do |sqv| 
-				s = (Float === sqv ? sqv.round_to_decimals(4) : sqv).inspect
-				s += "%" if subQvsAreRatios
-				s
-			end.join(", ")
-			if qvIsRatio
-				qstr = ("%.4f" % (100.0 * qv)) + "%"
-			else
-				qstr = "%.4f" % qv
-			end
-			"#{qvDesc}: #{qstr}, #{subQvDesc}: [#{sqs}]"
-		end
+  #############################
+  # Sane above here!
+  #############################
 
-		def inspect
-			qinspect(@qv, @sub_qvs) + ", Obj. version: #{@version}"
+	def reset_quality_scale(candidate, aspectIndex, typeOfReset)
+		if (typeOfReset == :min && is_min_aspect?(aspectIndex)) || 
+		   (typeOfReset == :max && !is_min_aspect?(aspectIndex))
+			@pareto_front[aspectIndex] = candidate
 		end
 
-		# Refer all other methods to the main quality value
-		def method_missing(meth, *args, &block)
-			@qv.send(meth, *args, &block)
-      	end
+		# Reset the best object since we have a new scale
+		@best_candidate = nil
+		@best_qv = nil
+
+		inc_version_number
 	end
 
-	# Return a single quality value for the whole objective for a given candidate. 
-	# By default this uses a variant of Bentley and Wakefield's sum-of-weighted-global-ratios (SWGR)
-	# called mean-of-weighted-global-ratios (MWGR) which always returns a fitness value
-	# in the range (0.0, 1.0) with 1.0 signaling the best fitness seen so far. The scale is adaptive
-	# though so that the best candidate so far always has a fitness value of 1.0.
-	def quality_value(candidate, weights = nil)
-		return candidate._quality_value_without_check if quality_value_is_up_to_date?(candidate)
-		num_aspects == 1 ? qv_single(candidate) : qv_mwgr(candidate, weights)
+	def update_best_candidate(candidate)
+		@best_candidate = candidate
+		@best_qv = candidate._quality_value
+	end
+
+	def inc_version_number
+		@current_version += 1
 	end
 
 	def quality_value_is_up_to_date?(candidate)
@@ -143,7 +147,7 @@ class FeldtRuby::Optimize::Objective
 	# Rand candidates from best to worst. NOTE! We do the steps of MWGR separately since we must
 	# update the global mins and maxs before calculating the SWG ratios.
 	def mwgr_rank_candidates(candidates, weights = nil)
-		sub_qvss = candidates.map {|c| sub_objective_values(c)}
+		sub_qvss = candidates.map {|c| sub_qualities_of(c)}
 		sub_qvss.zip(candidates).each {|sub_qvs, c| update_global_mins_and_maxs(sub_qvs, c)}
 		sub_qvss.each_with_index.map do |sub_qvs, i|
 			qv = mwgr_ratios(sub_qvs).weighted_mean(weights)
@@ -191,18 +195,6 @@ class FeldtRuby::Optimize::Objective
 		numerator.to_f.protected_division_with(max - min)
 	end
 
-	# The vectors can be mapped to a more complex candidate object before we call
-	# the sub objectives to calc their quality values. Default is no mapping but subclasses
-	# can override this.
-	def map_candidate_vector_to_candidate_to_be_evaluated(vector)
-		vector
-	end
-
-	def sub_objective_values(candidateVector)
-		candidate = map_candidate_vector_to_candidate_to_be_evaluated(candidateVector)
-		aspect_methods.map {|omethod| self.send(omethod, candidate)}
-	end
-
 	def update_global_mins_and_maxs(aspectValues, candidate = nil)
 		aspectValues.each_with_index {|v, i| update_global_min_and_max(i, v, candidate)}
 	end
@@ -222,6 +214,68 @@ class FeldtRuby::Optimize::Objective
 		end
 	end
 
+	# Class for representing multi-objective qualitites...
+	class QualityValue
+		attr_reader :qv, :sub_qvs, :objective
+
+		def initialize(qv, subQvs, objective)
+			@qv, @sub_qvs, @objective = qv, subQvs, objective
+			@version = objective.current_version
+		end
+
+		def <=>(other)
+			@qv <=> other.qv
+		end
+
+		# Two quality values are the same if they have the same qv, regardless of their
+		# sub qualities.
+		def ==(other)
+			other = other.qv if QualityValue === other
+			@qv == other
+		end
+
+		def improvement_in_relation_to(other)
+			if QualityValue === other
+				pdiff = @qv.ratio_diff_vs(other.qv)
+				subpdiffs = @sub_qvs.zip(other.sub_qvs).map {|s, os| s.ratio_diff_vs(os)}
+				qinspect(pdiff, subpdiffs, "Difference", "SubQ. differences", true) + ", #{report_on_num_differences(subpdiffs)}"
+			else
+				@qv.improvement_in_relation_to(other)
+			end
+		end
+
+		def report_on_num_differences(subQvRatioDiffs)
+			num_inc = subQvRatioDiffs.select {|v| v > 0}.length
+			num_dec = subQvRatioDiffs.select {|v| v < 0}.length
+			num_same = subQvRatioDiffs.length - num_inc - num_dec
+			"#{num_inc} increased, #{num_dec} decreased, #{num_same} same"
+		end
+
+		def qinspect(qv, subQvs, qvDesc = "Quality", subQvDesc = "SubQualities", subQvsAreRatios = false, qvIsRatio = true)
+			subQvs = subQvs.map {|v| v*100.0} if subQvsAreRatios
+			sqs = subQvs.map do |sqv| 
+				s = (Float === sqv ? sqv.round_to_decimals(4) : sqv).inspect
+				s += "%" if subQvsAreRatios
+				s
+			end.join(", ")
+			if qvIsRatio
+				qstr = ("%.4f" % (100.0 * qv)) + "%"
+			else
+				qstr = "%.4f" % qv
+			end
+			"#{qvDesc}: #{qstr}, #{subQvDesc}: [#{sqs}]"
+		end
+
+		def inspect
+			qinspect(@qv, @sub_qvs) + ", Obj. version: #{@version}"
+		end
+
+		# Refer all other methods to the main quality value
+		def method_missing(meth, *args, &block)
+			@qv.send(meth, *args, &block)
+    end
+	end
+
 	def log_new_min_max(index, newValue, oldValue, description)
 		log("New global #{description} for sub-objective #{aspect_methods[index]}",
 			("a %.3f" % (100.0 * (newValue - oldValue).protected_division_with(oldValue))) + "% difference",
@@ -247,38 +301,15 @@ class FeldtRuby::Optimize::Objective
 	def global_max_values_per_aspect
 		@global_max_values_per_aspect ||= Array.new(num_aspects).map {-Float::INFINITY}
 	end
-
-	private
-
-	def aspect_methods
-		@aspect_methods ||= self.methods.select {|m| is_aspect_method?(m)}
-	end
-
-	def is_min_aspect?(aspectIndex)
-		(@is_min_aspect ||= (aspect_methods.map {|m| is_min_aspect_method?(m)}))[aspectIndex]
-	end
-
-	def is_aspect_method?(methodNameAsSymbolOrString)
-		methodNameAsSymbolOrString.to_s =~ /^objective_(min|max)_([\w_]+)$/
-	end
-
-	def is_min_aspect_method?(methodNameAsSymbolOrString)
-		methodNameAsSymbolOrString.to_s =~ /^objective_min_([\w_]+)$/
-	end
 end
 
-# We add strangely named accessor methods so we can attach the quality values to objects.
-# We use strange names to minimize risk of method name conflicts.
-class Object
-	attr_accessor :_quality_value_without_check, :_objective, :_objective_version
-	def _quality_value
-		@_objective.ensure_updated_quality_value(self) if defined?(@_objective) && @_objective
-		@_quality_value_without_check ||= nil # To avoid warning if unset
-	end
+# The MWGR is a simple way to weigh the fitness values of multiple sub-objectives into a single
+# fitness value.
+module MeanWeigthedGlobalRatios
 end
 
 # Short hand for when the objective function is given as a block that should be minimized.
-class FeldtRuby::Optimize::ObjectiveMinimizeBlock < FeldtRuby::Optimize::Objective
+class ObjectiveMinimizeBlock < Objective
 	def initialize(&objFunc)
 		super()
 		@objective_function = objFunc
@@ -290,7 +321,7 @@ class FeldtRuby::Optimize::ObjectiveMinimizeBlock < FeldtRuby::Optimize::Objecti
 end
 
 # Short hand for when the objective function is given as a block that should be minimized.
-class FeldtRuby::Optimize::ObjectiveMaximizeBlock < FeldtRuby::Optimize::Objective
+class ObjectiveMaximizeBlock < Objective
 	def initialize(&objFunc)
 		super()
 		@objective_function = objFunc
@@ -299,4 +330,16 @@ class FeldtRuby::Optimize::ObjectiveMaximizeBlock < FeldtRuby::Optimize::Objecti
 	def objective_max_cost_function(candidate)
 		@objective_function.call(*candidate.to_a)
 	end
+end
+
+end
+
+# We add strangely named accessor methods so we can attach the quality values to objects.
+# We use strange names to minimize risk of method name conflicts.
+class Object
+	attr_accessor :_quality_value_without_check, :_objective, :_objective_version
+	def _quality_value
+		@_objective.ensure_updated_quality_value(self) if defined?(@_objective) && @_objective
+		@_quality_value_without_check ||= nil # To avoid warning if unset
+	end
 end

data/lib/feldtruby/optimize/search_space.rb

@@ -1,14 +1,18 @@
 require 'feldtruby/optimize'
 
+module FeldtRuby::Optimize
+
 # A search space is a set of constraints that limits which values
 # are searched for. The search space can generate valid candidate
 # solutions that are inside the space. It can also check if a
 # given candidate is in the space. The default search space has min
 # and max values for each element of a continuous vector.
-class FeldtRuby::Optimize::SearchSpace
-	attr_reader :min_values, :max_values
+class SearchSpace
+	attr_reader :min_values, :max_values, :deltas
 
-	def initialize(minValues, maxValues)
+	def initialize(minValues, maxValues, sampler = LatinHypercubeSampler.new)
+		sampler.search_space = self
+		@sampler = sampler
 		# Check that we have valid min and max values
 		raise "Not same num of min values (#{minValues.length}) as there are max values (#{maxValues.length})" if minValues.length != maxValues.length
 		raise "A search space must have >= 1 variable to be searched, here you specified min values: #{minValues.inspect}" if minValues.length < 1
@@ -19,6 +23,15 @@ class FeldtRuby::Optimize::SearchSpace
 		@deltas = @min_values.zip(@max_values).map {|min,max| max-min}
 	end
 
+	# Generate a new candidate.
+	def gen_candidate
+		@sampler.sample_candidate
+	end
+
+	def gen_value_for_position(index)
+		@sampler.sample_value_for_dimension(index)
+	end
+
 	# Bound candidate using the min and max values. We randomly generate a new value inside the space
 	# for each element that is outside.
 	def bound(candidate)
@@ -48,13 +61,94 @@ class FeldtRuby::Optimize::SearchSpace
 		@min_values.length
 	end
 
-	def gen_candidate
-		(0...num_variables).map {|i| gen_value_for_position(i)}
+	# A sampler generates a new candidate (or set of candidates) that is (are) within a search space. 
+	# This default sampler does uniform random sampling over the whole search space.
+	class Sampler
+		attr_accessor :search_space
+
+		def initialize(searchSpace = nil)
+			self.search_space = searchSpace
+		end
+
+		# Random uniform sampling of a valid value for a given dimension _index_ in the search space.
+		def sample_value_for_dimension(index)
+			min, delta = search_space.min_values[index], search_space.deltas[index]
+			min + delta * rand()
+		end
+
+		# Sample one candidate within the space. Default is to do random uniform sampling.
+		def sample_candidate
+			num_vars = search_space.num_variables
+			(0...num_vars).map {|i| sample_value_for_dimension(i)}
+		end
+
+		# Sample multiple candidates from the search space. The default is just to call the method sampling one
+		# candidate mutliple times. But subclasses can implement more sophisticated schemes.
+		def sample_candidates(numCandidates)
+			Array.new(numCandidates) { sample_candidate() }
+		end
+	end
+
+	# Set samplers sample many candidates in one go, often to create a better "spread" of genotypes within
+	# the search space. This is an abstract base class so sub-classes ust override the sample_candidates method.
+	class SetSampler < Sampler
+		# The chunk size is the number of candidates that are generated in one go and from which the individual
+		# candidates are then taken. Default is 200 to get a nice initial spread.
+		def initialize(chunkSize = 200)
+			@chunk_size = chunkSize
+			@chunk = []
+		end
+
+		# Sample a set of candidates.
+		def sample_candidates(numCandidates)
+			raise NotImplementedError # Subclasses must implement this
+		end
+
+		def sample_candidate
+			sample_new_chunk() if chunk_empty?
+			pop_candidate_from_chunk()
+		end
+
+		def sample_new_chunk
+			@chunk = sample_candidates(@chunk_size)
+		end
+
+		def chunk_empty?
+			@chunk.nil? || @chunk.length < 1
+		end
+
+		def pop_candidate_from_chunk
+			@chunk.pop
+		end
 	end
 
-	def gen_value_for_position(i)
-		min, delta = @min_values[i], @deltas[i]
-		min + delta * rand()
+	# LatinHypercube sampling is a stratified random sampling in bins over the search space. It is a simple
+	# way to ensure a more even spread over the search space when sampling. It has shown to be generally 
+	# useful for seeding initial populations in population based search without requiring any fitness
+	# evaluations. For example used in Deb's OmniOptimizer and in Tiwari's AMGA2 etc.
+	class LatinHypercubeSampler < SetSampler
+		# Sample the latin hypercube evenly for each dimension in the search space and then
+		# use Knuth unbiased shuffling to create individuals from the evenly spread out samples.
+		def sample_candidates(numCandidates)
+			set = Array.new(numCandidates).map {Array.new}
+			(0...(search_space.num_variables)).each do |dimension|
+				samples = latin_samples_for_dimension(dimension, numCandidates)
+				pi = (0...numCandidates).to_a.shuffle  # Ruby has Knuth shuffle built in so no need to implement
+				(0...numCandidates).each {|i| set[i] << samples[pi[i]]}
+			end
+			set
+		end
+
+		# Evenly spread _numSamples_ random samples over the search space dimension with _index_.
+		def latin_samples_for_dimension(index, numSamples)
+			low, delta = search_space.min_values[index], search_space.deltas[index]
+			interval_size = delta / numSamples.to_f
+			i = 0
+			Array.new(numSamples).map do
+				i += 1
+				(low + (i-1) * interval_size) + (interval_size * rand())
+			end
+		end
 	end
 
 	def is_candidate?(c)
@@ -66,4 +160,6 @@ class FeldtRuby::Optimize::SearchSpace
 	end
 end
 
-FeldtRuby::Optimize::DefaultSearchSpace = FeldtRuby::Optimize::SearchSpace.new_symmetric(2, 1)
+DefaultSearchSpace = SearchSpace.new_symmetric(2, 1)
+
+end