large_binomials 1.0.0

data/README.md

@@ -0,0 +1,82 @@
+large_binomials
+===============
+
+This gem mixes in some general methods to calculate binomials to `Integer`. In
+addition, it also mixes in some methods to calculate large binomials, with
+“large” being defined as having a result greater than `Float.MAX`. The main
+`Integer#binomial(k)` method is then adjusted such that when the result is less
+than or equal to `Float.MAX`, an `Integer` is returned, and a
+`LargeBinomials::LargeFloat` otherwise. Continuing to use `Integer` makes the
+calculation of binomials more and more expensive as the result becomes larger
+and larger.
+
+Installation
+------------
+
+Do the following to install this gem:
+
+1. Make a clone of the repository
+2. Build the gem: `gem build large_binomials.gemspec`
+3. Install the gem: `gem install ./large_binomials-0.9.gem`
+
+Usage
+-----
+
+The following code (also included in the project as
+`bin/test_performance_binomial.rb`) shows how to use the library:
+
+	# encoding: utf-8
+	#
+	# Test the performance of the calculation of a binomial
+	#
+
+	require 'benchmark'
+	require 'large_binomials'
+
+	puts "Going to test the performance of the calculation of a binomial."
+
+	Samples = (1 .. 3).collect{ |i| 10 ** i}.collect{ |i| [1, 2, 3, 5].collect{ |j| j * i}}.flatten
+
+	Samples.each{ |n|
+		[1, n/100, n/10, n/2].each { |k|
+			puts "#{n} C #{k}"
+			c = 0
+			time = Benchmark.realtime { c = n.binomial(k) }
+			puts "  binomial: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.float_binomial_by_product_of_divisions(k) }
+			puts "  Π(/), float: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.float_binomial_by_division_of_products(k) }
+			puts "  Π/Π, float: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.large_float_binomial_by_product_of_divisions(k) }
+			puts "  Π(/), LargeFloat: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.large_float_binomial_by_division_of_products(k) }
+			puts "  Π/Π, LargeFloat: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.binomial_by_division_of_parallel_products(k) }
+			puts "  ∥Π/∥Π, integer: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.binomial_by_division_of_products(k) }
+			puts "  Π/Π, integer: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.binomial_by_product_of_divisions(k) }
+			puts "  Π(/), integer: #{time}s (#{c})"
+			time = Benchmark.realtime { c = n.binomial_by_pascals_triangle(k) }
+			puts "  ∑, integer: #{time}s (#{c})"
+		}
+	}
+
+License
+-------
+
+Library to calculate large binomials  
+Copyright (C) 2013  Filip van Laenen <f.a.vanlaenen@ieee.org>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,45 @@
+# Ruby Library to Calculate Large Binomials
+# Copyright © 2013 Filip van Laenen <f.a.vanlaenen@ieee.org>
+#
+# This file is part of the Ruby Library to Calculate Large Binomials.
+#
+# The Ruby Library to Calculate Large Binomials is free software: you can
+# redistribute it and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# The Ruby Library to Calculate Large Binomials is distributed in the hope that
+# it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You can find a copy of the GNU General Public License in /LICENSE
+#
+
+require 'rspec/core/rake_task'
+ 
+desc 'Default: run specs.'
+task :default => :spec
+ 
+desc 'Run specs'
+RSpec::Core::RakeTask.new do |t|
+	t.pattern = "./spec/**/*_spec.rb"
+end
+
+def find_integer_methods
+	require_relative 'lib/core_ext/integer'
+	integer_methods = Integer.instance_methods(false)
+	integer_methods.select!{ | m | 1.method(m).source_location != nil }
+	integer_methods.select!{ | m | 1.method(m).source_location[0].include? 'large_binomials'}
+	integer_methods.collect{ | m | "::Integer##{m}"}
+end
+
+desc 'Run Mutant'
+task :mutant do
+	require 'mutant'
+	find_integer_methods
+	status = Mutant::CLI.run(['::LargeBinomials*', find_integer_methods, '--rspec-unit'].flatten)
+	if status.nonzero?
+		abort 'Mutant task is not successful'
+	end
+end

data/bin/test_performance_binomial.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/ruby
+# encoding: utf-8
+#
+# Test the performance of the calculation of a binomial
+#
+
+require 'benchmark'
+require 'large_binomials'
+
+puts "Going to test the performance of the calculation of a binomial."
+
+Samples = (1 .. 3).collect{ |i| 10 ** i}.collect{ |i| [1, 2, 3, 5].collect{ |j| j * i}}.flatten
+
+Samples.each{ |n|
+	[1, n/100, n/10, n/2].each { |k|
+		puts "#{n} C #{k}"
+		c = 0
+		time = Benchmark.realtime { c = n.binomial(k) }
+		puts "  binomial: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.float_binomial_by_product_of_divisions(k) }
+		puts "  Π(/), float: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.float_binomial_by_division_of_products(k) }
+		puts "  Π/Π, float: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.large_float_binomial_by_product_of_divisions(k) }
+		puts "  Π(/), LargeFloat: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.large_float_binomial_by_division_of_products(k) }
+		puts "  Π/Π, LargeFloat: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.binomial_by_division_of_parallel_products(k) }
+		puts "  ∥Π/∥Π, integer: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.binomial_by_division_of_products(k) }
+		puts "  Π/Π, integer: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.binomial_by_product_of_divisions(k) }
+		puts "  Π(/), integer: #{time}s (#{c})"
+		time = Benchmark.realtime { c = n.binomial_by_pascals_triangle(k) }
+		puts "  ∑, integer: #{time}s (#{c})"
+	}
+}

data/large_binomials.gemspec

@@ -0,0 +1,37 @@
+# -*- encoding: utf-8 -*-
+#
+# Ruby Library to Calculate Large Binomials
+# Copyright © 2013 Filip van Laenen <f.a.vanlaenen@ieee.org>
+#
+# This file is part of the Ruby Library to Calculate Large Binomials.
+#
+# The Ruby Library to Calculate Large Binomials is free software: you can
+# redistribute it and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# The Ruby Library to Calculate Large Binomials is distributed in the hope that
+# it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You can find a copy of the GNU General Public License in /LICENSE
+#
+
+Gem::Specification.new do |gem|
+	gem.name = 'large_binomials'
+	gem.version = '1.0.0'
+	gem.authors = [ 'Filip van Laenen' ]
+	gem.email = [ 'f.a.vanlaenen@ieee.org' ]
+
+	gem.description = 'Large binomials'
+	gem.summary = 'Library to calculate large binomials'
+	gem.homepage = 'https://github.com/filipvanlaenen/large_binomials'
+	gem.license = 'GPL'
+
+	gem.require_paths = [ 'lib' ]
+	gem.files = `git ls-files`.split("\n")
+	gem.test_files = `git ls-files -- spec`.split("\n")
+	gem.extra_rdoc_files = %w[LICENSE README.md]
+
+end

data/lib/core_ext/integer.rb

@@ -0,0 +1,127 @@
+# encoding: utf-8
+#
+# Ruby Library to Calculate Large Binomials
+# Copyright © 2013 Filip van Laenen <f.a.vanlaenen@ieee.org>
+#
+# This file is part of the Ruby Library to Calculate Large Binomials.
+#
+# The Ruby Library to Calculate Large Binomials is free software: you can
+# redistribute it and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# The Ruby Library to Calculate Large Binomials is distributed in the hope that
+# it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You can find a copy of the GNU General Public License in /LICENSE
+#
+
+class Integer
+
+	def to_lf
+		LargeBinomials::LargeFloat.new(self)
+	end
+
+	def binomial(k)
+		binomial = breaking_binomial_by_product_of_divisions(k)
+		if binomial == nil
+			large_float_binomial_by_product_of_divisions(k)
+		else
+			binomial
+		end
+	end
+
+	# Copied from http://rosettacode.org/wiki/Evaluate_binomial_coefficients#Ruby (on 7 June 2013)
+	def binomial_by_product_of_divisions(k)
+		(0...k).inject(1) do |m,i|
+			(m * (self - i)) / (i + 1)
+		end
+	end
+
+	# Breaking version of binomial_by_product_of_divisions
+	def breaking_binomial_by_product_of_divisions(k)
+		(0...k).inject(1) do |m,i|
+			if m > Float::MAX
+				return nil
+			end
+			(m * (self - i)) / (i + 1)
+		end
+	end
+
+	# LargeFloat version of binomial_by_product_of_divisions
+	def large_float_binomial_by_product_of_divisions(k)
+		(0...k).inject(1.to_lf) do |m,i|
+			(m * (self - i)) / (i + 1)
+		end
+	end
+
+	# Float version of binomial_by_product_of_divisions
+	def float_binomial_by_product_of_divisions(k)
+		(0...k).inject(1.to_f) do |m,i|
+			(m * (self - i)) / (i + 1)
+		end
+	end
+
+	# From http://rosettacode.org/wiki/Evaluate_binomial_coefficients#Ruby (on 7 June 2013)
+	def binomial_by_division_of_products(k)
+		# n!/(n-k)!
+		pTop = (self-k+1 .. self).inject(1, &:*) 
+		# k!
+		pBottom = (2 .. k).inject(1, &:*)
+		pTop / pBottom
+	end
+
+	# Parallel version of binomial_by_division_of_products
+	# Note that threads in Ruby 1.9 don't spread over multiple processors, so
+	# due to context switching this parallel version will often be a bit slower
+	# than the sequential one.
+	def binomial_by_division_of_parallel_products(k)
+		# n!/(n-k)!
+		top_thread = Thread.new do
+			Thread.current[:output] = (self-k+1 .. self).inject(1, &:*) 
+		end
+		# k!
+		bottom_thread = Thread.new do
+			Thread.current[:output] = (2 .. k).inject(1, &:*)
+		end
+		top_thread.join
+		bottom_thread.join
+		top_thread[:output] / bottom_thread[:output]
+	end
+
+	# LargeFloat version of binomial_by_division_of_products
+	def large_float_binomial_by_division_of_products(k)
+		# n!/(n-k)!
+		pTop = (self-k+1 .. self).inject(1.to_lf, &:*) 
+		# k!
+		pBottom = (2 .. k).inject(1.to_lf, &:*)
+		pTop / pBottom
+	end
+
+	# Float version of binomial_by_division_of_products
+	def float_binomial_by_division_of_products(k)
+		# n!/(n-k)!
+		pTop = (self-k+1 .. self).inject(1.to_f, &:*) 
+		# k!
+		pBottom = (2 .. k).inject(1.to_f, &:*)
+		pTop / pBottom
+	end
+
+	# Copied from http://www.brpreiss.com/books/opus8/html/page459.html (on 7 June 2013)
+	def binomial_by_pascals_triangle(k)
+		b = []
+		b[0] = 1
+		for i in 1 .. self
+			b[i] = 1
+			j = i - 1
+			while j > 0
+				b[j] += b[j - 1]
+				j -= 1
+			end
+		end
+		b[k]
+	end
+
+end

data/lib/large_binomials.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+#
+# Ruby Library to Calculate Large Binomials
+# Copyright © 2013 Filip van Laenen <f.a.vanlaenen@ieee.org>
+#
+# This file is part of the Ruby Library to Calculate Large Binomials.
+#
+# The Ruby Library to Calculate Large Binomials is free software: you can
+# redistribute it and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# The Ruby Library to Calculate Large Binomials is distributed in the hope that
+# it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You can find a copy of the GNU General Public License in /LICENSE
+#
+
+# Library namespace
+module LargeBinomials
+end
+
+require 'core_ext/integer'
+require 'large_binomials/large_float'

data/lib/large_binomials/large_float.rb

@@ -0,0 +1,129 @@
+# encoding: utf-8
+#
+# Ruby Library to Calculate Large Binomials
+# Copyright © 2013 Filip van Laenen <f.a.vanlaenen@ieee.org>
+#
+# This file is part of the Ruby Library to Calculate Large Binomials.
+#
+# The Ruby Library to Calculate Large Binomials is free software: you can
+# redistribute it and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# The Ruby Library to Calculate Large Binomials is distributed in the hope that
+# it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You can find a copy of the GNU General Public License in /LICENSE
+#
+
+module LargeBinomials
+	class LargeFloat
+		include Comparable
+
+		attr_accessor :exponent, :mantissa
+
+		def initialize(m, e = 0)
+			@mantissa = m.to_f
+			@exponent = e
+		end
+
+		def clone
+			LargeFloat.new(@mantissa, @exponent)
+		end
+
+		def normalize
+			unless @mantissa == 0
+				normalization = Math.log10(@mantissa).floor
+				@mantissa /= 10 ** normalization
+				@exponent += normalization
+			end
+		end
+
+		def *(x)
+			if (x.instance_of? LargeFloat)
+				multiply_with_large_float(x)
+			else
+				multiply_with_numeric(x)
+			end
+		end
+
+		def multiply_with_large_float(lf)
+			product = self * lf.mantissa
+			product.exponent += lf.exponent
+			product
+		end
+
+		def multiply_with_numeric(i)
+			product = clone
+			new_mantissa = product.mantissa * i
+			if new_mantissa == Float::INFINITY
+				product.normalize
+			end
+			product.mantissa *= i
+			product
+		end
+
+		def /(x)
+			if (x.instance_of? LargeFloat)
+				divide_by_large_float(x)
+			else
+				divide_by_numeric(x)
+			end
+		end
+
+		def divide_by_large_float(lf)
+			quotient = self / lf.mantissa
+			quotient.exponent -= lf.exponent
+			quotient
+		end
+
+		def divide_by_numeric(n)
+			quotient = clone
+			quotient.mantissa /= n
+			quotient
+		end
+
+		def new_mantissa_for_addition(lf)
+			@mantissa + lf.mantissa * 10 ** (lf.exponent - @exponent)
+		end
+
+		def +(lf)
+			if self < lf
+				lf + self
+			else
+				LargeFloat.new(new_mantissa_for_addition(lf), @exponent)
+			end
+		end
+
+		def superscript(i)
+			s = i.to_s
+			s = s.gsub(/1/, '¹')
+			s = s.gsub(/2/, '²')
+			s = s.gsub(/3/, '³')
+			s = s.gsub(/4/, '⁴')
+			s = s.gsub(/5/, '⁵')
+			s = s.gsub(/6/, '⁶')
+			s = s.gsub(/7/, '⁷')
+			s = s.gsub(/8/, '⁸')
+			s = s.gsub(/9/, '⁹')
+			s.gsub(/0/, '⁰')
+		end
+
+		def to_s
+			normalize
+			"#{@mantissa}×10#{superscript(@exponent)}"
+		end
+
+		def <=>(lf)
+			normalize
+			lf.normalize
+			if @exponent == lf.exponent
+				@mantissa - lf.mantissa
+			else
+				@exponent - lf.exponent
+			end
+		end
+	end
+end