dgoldhirsch-cs 0.0.0 → 0.0.1

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 dgoldhirsch
+Copyright (c) 2009 David C. Goldhirsch
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,7 +1,69 @@
 = cs
 
-Description goes here.
+Computer Science Module for Ruby
+
+This is an ambitious gem in which we hope to provide useful computer science algorithms.
+The first version is very small, offering two algorithms to compute Fibonacci numbers.
+We did this as an exercise in writing good Ruby code, as well as learning how to provide
+real, useful libraries as gems.
+
+Here are the two Fibonacci algorithms currently supported:
+
+[Matrix exponentiation]  This is the fastest way we have found to compute Fibonacci numbers.
+It makes use of the fact that if M = Matrix[[0, 1], [1, 1]], then the lower right element of
+M**k contains the (k + 1)'th Fibonacci number.  This is very fast if the Matrix.** operation
+is optimized to use successive squaring rather than individual multiplications.  Ruby's
+implementation of Matrix.** does exactly this, fortunately.
+
+[While loop]  This is a simple loop that computes F(n) by adding F(0) + F(1) + ... + F(n - 1).
+For n < 5000, this seems to perform about as well as the matrix exponentiation.  But, thereafter
+it is MUCH slower (at least, in the benchmarks we performed).
+
+= Using the library
+
+The algorithms are available in two forms.  The basic form is a module method:
+
+  require 'rubygems'
+  require 'cs'
+  y = CS::fibonacci(6) # returns F(6) which is 8 = 5 + 3, using default algorithm
+
+An optional parameter selects the algorithm to be used.  By default, the matrix
+exponentiation algorithm is used.  However, you can choose one or the other as follows:
+
+  y_more_slowly = CS::fibonacci(6, CS::FIBONACCI_WHILE_LOOP)
+
+As a convenience, the method is also available as an instance mixin for the class Integer:
+
+  require 'rubygems'
+  require 'cs_fibonacci'
+  y = 6.fibonacci # use default algorithm
+  y_slower = 6.fibonacci(CS::FIBONACCI_WHILE_LOOP)
+
+== Obtaining the gem from github
+
+gem sources -a http://gems.github.com
+gem install dgoldhirsch-cs
+
+== Extensions to Standard Library
+
+While coding these algorithms, we found it useful to code an extension to the
+standard Ruby Matrix class, to obtain the lower right element of a matrix.
+It may be that this is already available in one of the existing Ruby extension
+gems--but, for now, we included it in the CS module on the chance that
+someone else might want to make use of it:
+
+  require 'rubygems'
+  require 'cs'
+  y = CS::lower_right(Matrix[[1, 2], [3, 4]]) # y is 4
+
+== This is Still Half-Baked
+
+Obviously, this is a beginner's gem which is in an infant state.  Comments and
+suggestions are very welcome.  As a companion to the gem, we'll try to create
+a Web site that demonstrates the algorithms and which solicits additional algorithm
+contributions and suggestions.   We'll update this document when/if we are able
+to finish that.
 
 == Copyright
 
-Copyright (c) 2009 dgoldhirsch. See LICENSE for details.
+Copyright (c) 2009 David C. Goldhirsch. See LICENSE for details.

data/lib/cs.rb

@@ -1,74 +1,103 @@
 require 'rubygems'
+require 'matrix'
 
 # Title:: Computer Science Library for Ruby
 # Author:: David C. Goldhirsch
 # Copyright (c) 2009, David C. Goldhirsch
-class CS
-  # Fibonacci number generator.
-  # Return integer value of F(n) for any integer n >= 1,
-  # where F(n) is defined as F(n - 1) + F(n - 2) for n > 2, F(2) = 1
-  # and F(1) = 0.
-  #
-  # E.g., the sequence (F(1), ..., F(7)) is (0, 1, 1, 2, 3, 5, 8).
-  #
-  # Values of n less than 1 are equivalent to n = 1.
-  def self.fibonacci n
-    return 0 if n <= 1
-    return (FibonacciSecondOrHigher.advanced_by n - 2).result
-  end
+module CS
 
-  private
+  ########################################## Fibonacci Algorithms
 
-  # The class 'new' method is privatized, because users should not be
-  # instantiating this class.
-  def self.new
-    super.new
-  end
-end
-
-private
+  MATRIX = :matrix
+  ADDITION = :addition
+  Fibonacci_algorithms = [MATRIX, ADDITION]
 
-# Fibonacci generating class, each of whose instances represents F(2 + k)
-# for some given k. To obtain the integer value of F(w), use the 'result' method, e.g.:
-# - f = FibonacciSecondOrHigher.new
-# - f.result # the integer 1 = F(2)
-# - f.advance
-# - f.result # the integer 2 = F(3)
-# - etc.
-class FibonacciSecondOrHigher
-  attr_accessor :result
-  attr_accessor :previous
-  attr_accessor :second_previous  # non-nil only for F(3) and higher
-
-  # This is the proper way to create an instance
-  # representing F(2 + k).  Please use this instead of 'new'.
-  # Return an instance representing F(2 + k) for given k.
-  # E.g., if k is 0, the result is F(2);  if k is 1, the
-  # result is F(3);  if k is 4 the result is F(6)
-  def self.advanced_by k
-    return (1..k).inject(FibonacciSecondOrHigher.new) do |f, i|
-      f.advance
-    end
+  # Generalized Fibonacci generator.
+  # Return the integer value of F(n) for any integer n, where
+  # F(0) = 0
+  # F(1) = 1
+  # F(k > 1) = F(k - 1) + F(k - 2)
+  # Starting with F(0), the first few Fibonacci values are 0, 1, 1, 2, 3, 5, 8, ...
+  #
+  # Usage:   CS::fibonacci(anInteger, aSymbol = CS::MATRIX)
+  # in which anInteger is any integer (but anything less than 0 will be
+  # interpreted as 0), and aSymbol optionally specifies the algorithm to be
+  # used.  See this module's Fibonacc_algorithms constant for the possible
+  # algorithm names.  By default, the fastest known algorithm will be used.
+  def self.fibonacci(n, algorithm = MATRIX)
+    # The following seems to be the fastest algorithm, perhaps because
+    # Ruby's Matrix.** operation is smart enough to use squares of squares
+    # to minimize the number of multiplications.
+    return matrix_fibonacci(n) if algorithm == MATRIX
+    return additive_fibonacci(n) if algorithm == ADDITION
   end
 
-  # Change internal state such that if the receiver currently
-  # represents F(k) it will be advanced to represent F(k + 1).
-  def advance
-    self.second_previous = self.previous
-    self.previous = self.result
-    self.result += self.second_previous # i.e., second_previous + previous
-    return self
+  # Matrix utility to return
+  # the lower, right-hand element of a given matrix.
+  def self.lower_right matrix
+    return nil if matrix.row_size == 0
+    return matrix[matrix.row_size - 1, matrix.column_size - 1]
+  end
+  
+  # Matrix exponentiation algorithm to compute Fibonacci numbers.
+  # Let M be Matrix [[0, 1], [1, 1]].  Then, the lower right element of M**k is
+  # F(k + 1).  In other words, the lower right element of M is F(2) which is 1, and the
+  # lower right element of M**2 is F(3) which is 2, and the lower right element
+  # of M**3 is F(4) which is 3, etc.
+  #
+  # This is a good way to compute F(n) because the Ruby implementation of Matrix.**
+  # uses an O(log n) optimized algorithm (*).  Computing M**(n-1) is actually
+  # faster (**) than using a simple while/for loop to compute F(0) + F(1) + ... + F(n-1).
+  #
+  # We found this algorithm in <I>Introduction To Algorithms
+  # (Second Edition)</I>, by Cormen, Leiserson, Rivest, and Stein, MIT Press
+  # (http://mitpress.mit.edu), in exercise 3-31 on pages 902, 903.
+  #
+  # (*) Ruby's Matrix.**(k) works by computing partial = ((m**2)**2)... as far as possible,
+  # and then multiplying partial by M**(the remaining number of times).  E.g., to compute
+  # M**19, compute partial = ((M**2)**2) = M**16, and then compute partial*(M**3) = M**19.
+  # That's only 3 matrix multiplications of M to compute M*19.
+  #
+  # (**) "Faster" means on the workstations we tried, the matrix algorithm takes less total time
+  # (see Ruby's Benchmark::bmbm) than a simple, additive loop.  But the space complexity
+  # may well be larger for the matrix algorithm, which in turn may affect the likelihood
+  # of garbage collection in large cases.  Therefore, as with almost everything else,
+  # a different algorithm may be better suited to any particular environment or situation.
+  # This is why we provide the optional, alternative algorithms.
+  # 
+  def self.matrix_fibonacci(n)
+    return 0 if n <= 0 # F(0)
+    return 1 if n == 1 # F(1)
+    # To get F(n >= 2), compute M**(n - 1) and extract the lower right element.
+    return CS::lower_right(M**(n - 1))
   end
 
-  def to_s
-    return second_previous.to_s + "," + previous.to_s + "," + "=>" + result.to_s
+  # This is a simple, additive loop to compute F(n) by computing
+  # F(0) + F(1) + ... + F(n-1).  Our spotty benchmark/profiling suggests that
+  # this is always worse in CPU time and general response time than
+  # the linear_matrix_fibonacci algorithm.  (And, surprisingly, this seems to be true even
+  # for very low values of n.)  We provide it for purposes of information, and as
+  # a point of comparison for performance.
+  def self.additive_fibonacci(n)
+    return 0 if n <= 0
+    b = 0 # F(0)
+    result = 1 # F(1)
+    (n - 1).times do
+      a = b
+      b = result
+      result += a # i.e., result = a + b
+    end
+    return result
   end
 
   private
 
-  # Instances represent F(2), unless/until they are advanced
-  def initialize
-    self.previous = 0 # F(<= 1)
-    self.result = 1 # F(2)
-  end
+  # To understand why this matrix is useful for Fibonacci numbers, remember
+  # that the definition of Matrix.** for any Matrix[[a, b], [c, d]] is
+  # is [[a*a + b*c, a*b + b*d], [c*a + d*b, c*b + d*d]].  In other words, the
+  # lower right element is computing F(k - 2) + F(k - 1) every time M is multiplied
+  # by itself (it is perhaps easier to understand this by computing M**2, 3, etc, and
+  # watching the result march up the sequence of Fibonacci numbers).
+  M = Matrix[[0, 1], [1,1]]
+
 end

data/lib/cs_fibonacci.rb

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'cs.rb'
+
+# Integer mixin providing Integer.fibonacci() instance method
+# that delegates to CS::fibonacci.  Type the following:
+#
+# <code>
+# require 'cs' # get the gem
+# require 'cs_fibonacci.rb' # get the Integer mixin
+# </code>
+#
+# And now you can do this:
+#
+# <code>
+#    puts 7.fibonacci() # prints 8
+# </code>
+class Integer
+  def fibonacci algorithm = CS::MATRIX
+    return CS::fibonacci(self, algorithm)
+  end
+end

data/lib/cs_matrix.rb

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'cs.rb'
+require 'matrix' 
+
+# Useful Class Matrix mixins.
+#
+# <code>
+# require 'cs' # get the CS gem
+# require 'cs_matrix.rb' # get the CS Matrix mixin
+# </code>
+#
+# And now you can do this:
+#
+# <code>
+#    puts 7.fibonacci() # prints 8
+# </code>
+class Matrix
+  # Useful for dealing with matrices.
+  # Return the lower, right-hand element of a given matrix.
+  def lower_right
+    return CS::lower_right(self)
+  end
+end

data/test/cs_benchmark_test.rb

@@ -0,0 +1,22 @@
+require "test_helper"
+require File.join(File.dirname(__FILE__), '..', 'lib', 'cs.rb')
+require "benchmark"
+require "ruby-prof"
+
+class CS_benchmark < Test::Unit::TestCase
+
+  N = 50000  # large enough to show a difference
+  
+  # This isn't a test per se, but rather a very simple performance profiler.
+  def test_performance
+    y = Benchmark.bmbm do |x|
+      x.report("matrix_fibonacci") { CS::matrix_fibonacci(N) }
+      x.report("additive_fibonacci") { CS::additive_fibonacci(N) }
+    end
+  end
+  
+  def test_rubyprof
+    RubyProf::GraphPrinter.new(RubyProf.profile {CS::matrix_fibonacci(N)}).print(STDOUT, 0)
+    RubyProf::GraphPrinter.new(RubyProf.profile {CS::additive_fibonacci(N)}).print(STDOUT, 0)
+  end
+end

data/test/cs_mixin_test.rb

@@ -0,0 +1,24 @@
+require "test_helper"
+require File.join(File.dirname(__FILE__), '..', 'lib', 'cs_fibonacci.rb')
+require File.join(File.dirname(__FILE__), '..', 'lib', 'cs_matrix.rb')
+
+
+# Test mixin wrappers for the CS library.  This is just
+# for the mixin wrappers--the hard core tests for the
+# CS library itself should be written against the CS module
+# directly.
+class CsMixinTest  < Test::Unit::TestCase
+
+  def test_fibonacci_mixin
+    assert_equal 13, 7.fibonacci # ensure works with Fixnum
+    assert_equal 13, 7.fibonacci(CS::ADDITION) # ensure optional algorithm works
+    # Use reflection to ensure that the method has been mixed
+    # into Bignum as well as Fixnum.
+    y = 0xfffffffffe # Bignum on any 32-bit system
+    assert y.method(:fibonacci)
+  end
+
+  def test_matrix_mixin
+    assert_equal 6, Matrix[[1,2,3], [4,5,6]].lower_right
+  end
+end

data/test/cs_test.rb

@@ -1,27 +1,49 @@
 require "test_helper"
+require "matrix"
+require "timeout"
 
-class FibonacciTest  < Test::Unit::TestCase
-
-  # Basic test of CS::fibonacci.  Verify correctness of F(1, ...)
-  # as (0, 1, 1, 2, 3, 5, 8...).
-  def test_basic
-    assert_equal 0, CS::fibonacci(1)
-    assert_equal 1, CS::fibonacci(2)
-    assert_equal 1, CS::fibonacci(3)
-    assert_equal 2, CS::fibonacci(4)
-    assert_equal 3, CS::fibonacci(5)
-    assert_equal 5, CS::fibonacci(6)
-    assert_equal 8, CS::fibonacci(7)
+class CsFibonacciTest  < Test::Unit::TestCase
+
+  def test_matrix
+    (0..F.size - 1).each { | i | assert_equal F[i], CS::matrix_fibonacci(i)}
+  end
+  
+  def test_addititive
+    (0..F.size - 1).each { | i | assert_equal F[i], CS::additive_fibonacci(i)}
   end
 
-  # The assertion in this test is meaningless.  The point of running this test
-  # is to be sure that Fibonacci numbers up to some large number can be computed
-  # within a reasonable CPU/memory footprint.  For example, if a recursive rather
-  # than a linear algorithm were used, this test case would require 2**10,000 recursive
-  # calls, and the test would probably run out of memory.
+  def test_algorithm_parameter
+    assert_equal 8, CS::fibonacci(6, CS::MATRIX)
+    assert_equal 8, CS::fibonacci(6, CS::ADDITION)
+    assert_nil CS::fibonacci(3, :foobar)
+  end
+  
+  # Test for gross performance problems, using a time-out thread.
+  # It's possible--at least theoretically--for this test
+  # to fail because of system issues rather than the fibonacci
+  # generator.  So, if it fails, try it again and/or take its
+  # failure with a grain of salt.
   def test_raw_performance
-    x = CS::fibonacci(10000);
-    assert x > 0
+    assert_nothing_raised do
+      # 20 seconds would seem to be far more than is necessary for this...
+      Timeout::timeout(20) {CS::matrix_fibonacci(10000)}
+    end
+  end
+
+  # Test our understanding of the Ruby matrix module
+  def test_matrix
+    m = Matrix[[0, 1],[1, 1]]
+    m2 = m*m
+    m3 = m2*m
+    m4 = m3*m
+    m2squared = m2**2
+    assert_equal 1, CS::lower_right(m)
+    assert_equal 2, CS::lower_right(m2)
+    assert_equal 3, CS::lower_right(m3)
+    assert_equal 5, CS::lower_right(m4)
+    assert_equal m4, m2squared
+    e = Matrix[]
+    assert_nil CS::lower_right(e)
   end
 
   #The following function will take a massive amount of CPU time and an impossible amount of memory,
@@ -41,15 +63,18 @@ class FibonacciTest  < Test::Unit::TestCase
   end
 
   private
-  
-  # Seemingly innocent, recursive algorithm that computes the nth Fibonacci number.
+
+  # Fhe first few Fibonacci numbers, starting with F(0), for assertion comparisons
+  F = [0, 1, 1, 2, 3, 5, 8]
+
+    # Seemingly innocent, recursive algorithm that computes the nth Fibonacci number.
   # Requires 2**n recursive calls, requiring an obscene amount of memory and CPU time.
   # Try it for n = 1000, and then twiddle your thumbs while waiting for the "out of memory"
   # exception... 
   def recursive_fibonacci(n)
-    if(n == 1)
+    if (n == 1)
       return 0
-    elsif(n == 2 || n == 3)
+    elsif (n == 2 || n == 3)
       return 1
     end
     return recursive_fibonacci(n - 2) + recursive_fibonacci(n - 1)

data/test/test_helper.rb

@@ -3,7 +3,6 @@ require 'test/unit'
 
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'cs'
 
 class Test::Unit::TestCase
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dgoldhirsch-cs
 version: !ruby/object:Gem::Version 
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors: 
 - dgoldhirsch
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-06 00:00:00 -07:00
+date: 2009-07-09 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -24,6 +24,8 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - lib/cs.rb
+- lib/cs_fibonacci.rb
+- lib/cs_matrix.rb
 - LICENSE
 - README.rdoc
 has_rdoc: true
@@ -53,5 +55,7 @@ signing_key:
 specification_version: 2
 summary: Computer Science Library for Ruby
 test_files: 
+- test/cs_benchmark_test.rb
+- test/cs_mixin_test.rb
 - test/cs_test.rb
 - test/test_helper.rb