fibonacci_rng 0.4.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24192194041fbb6a8a907907c3d80c793a25eb1a
-  data.tar.gz: afc6ce49588ec4aaeb8de9b1ead78bbec947f3ed
+  metadata.gz: 92d9ec37d3384e39e3e122ed13281ba8001c8f2a
+  data.tar.gz: df41080f4dc1a92a75028a4f8cce4f94f5c969ed
 SHA512:
-  metadata.gz: b8c839b0aad4e0defdc304bdb6bbdbf40a3db783711c2961345468e7e76d119bc78db0a147a763a283b42495c228e7b0017ee6b05a1d84e75d1cfa024472206a
-  data.tar.gz: e331373058f17ef81d5b43808f48c62e29a752de076620a2bdb9b1ad3cfcd75bdf20acae5ee032250aee3c69de302ded79a406ca560adafbb148ba9a9278c1f0
+  metadata.gz: 7885893e8155ca7b2c59ffd7688dd319a9935288b1796113d7185d263e4caad9c718aabbee84e1c7ca7e6c24bf8a79bbfd68634709c21467b02cb9ba22bb77de
+  data.tar.gz: 3e5cb32a061f12aa8a6218984318509788aea414a69ea4d2149733fd783bcd834bd0a86b7c7e522756cf08bda9fffea7177310c6cb870763c33ad9e437156331

data/README.md

@@ -1,8 +1,9 @@
 # FibonacciRng
 
 This gem implements a random number generator inspired by the famous Fibonacci
-number sequence. So far, this generator has performed quite well when compared
-to the built-in Ruby random number generator when tested with:
+number sequence. To be specific, it is a normalized, cyclic Fibonacci pseudo
+random number generator. So far, this generator has performed quite well when
+compared to the built-in Ruby random number generator when tested with:
 
 * A chi-squared test
 * An auto-correlation test
@@ -170,9 +171,83 @@ generator = FibonacciRng.new
 random_bytes = Array.new(len) { generator.byte }
 ```
 
+## Theory of Operation
+
+The random number generator used in this gem is based on a modified, cyclic
+Fibonacci generator. This ring buffer design modifies the simple sequence so
+that it feeds back onto itself, which in turn gives the appearance of chaos.
+There is one further required modification however. Since the Fibonacci sequence
+uses additions, a mechanism for preventing zeros from "swamping" the data, is
+needed. This is accomplished by rotating one of the arguments to the right by
+one bit. The basic outline of the generational cycle operation, with depth of
+N is shown below:
+![The Cycle Operation](docs/cycle.png)
+<br>Notes:
+* The last two elements are copies of the first two elements before
+the array was transformed.
+* Not shown above for brevity, the result of each addition is masked with the
+value 0x1FFFFFFF before being stored. This masks off any data beyond the low
+29 bits.
+
+#### 29 bit Integers?
+
+The random number generator masks the data in the ring buffer to 29 bit,
+unsigned values. To understand this, it is first necessary to under why
+masking is needed at all, and secondly, why this was done at 29 bits.
+
+Masking at some level is required because it is needed to simulate the numeric
+overflow of more primitive systems of arithmetic. In most systems, when the
+limit of an integer is reached, overflow occurs with no error indication. Ruby
+does not permit this to occur. To avoid overflow, Ruby transparently converts
+from a simple integer (FIXNUM class) to a multiple-precision number
+(BIGNUM class). The random number generator *requires* the computations to
+overflow, so masking the results forces the computation to act as if they had.
+
+So why 29 bits? Why not 32? or 64? The issue here is performance. Arithmetic
+with BIGNUM values is much slower than with FIXNUM values. Further, the
+conversion between FIXNUM and BIGNUM is also slow. The 29 bit size was
+chosen to ensure that all computations remain with FIXNUM values without
+ever reaching the threshold for the switch to BIGNUM values. In 32 bit Ruby
+systems, 29 bits is the largest value that meets this requirement.
+
+#### Code
+
+Enough with all these words and pictures. The best way to gain insight into
+ruby code is to study ruby code! What follows is the critical snippet of code
+that makes this random number generator spin:
+
+```ruby
+private
+
+#Cycle through the PRNG once.
+def do_spin
+  @buffer[-2] = @buffer[0]
+  @buffer[-1] = @buffer[1]
+
+  (0...@depth).each do |idx|
+    tmp = @buffer[idx+2]
+    @buffer[idx] = (@buffer[idx+1] + ((tmp >> 1)|(tmp.odd? ? TOP : 0))) & CHOP
+  end
+end
+
+```
+The above is found in the spinner.rb file. For completeness of understanding,
+the following constants are defined in the fibonacci_rng.rb file:
+
+```ruby
+CHOP = 0x1FFFFFFF
+TOP  = 0x10000000
+
+```
 
 ## Contributing
 
+Creating a good pseudo random number generator is quite an undertaking. For
+this reason, any input is most welcomed. There are two basic plans by which
+this can be accomplished.
+
+#### Plan A
+
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
@@ -182,7 +257,4 @@ random_bytes = Array.new(len) { generator.byte }
 #### Plan B
 
 Go to the GitHub repository and raise an issue calling attention to some
-aspect that could use some TLC or a suggestion or an idea. Apply labels
-to the issue that match the point you are trying to make. Then follow
-your issue and keep up-to-date as it is worked on. All input are greatly
-appreciated.
+aspect that could use some TLC or a suggestion or an idea.

data/fibonacci_rng.gemspec

@@ -9,8 +9,10 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Peter Camilleri"]
   spec.email         = ["peter.c.camilleri@gmail.com"]
   spec.homepage      = "http://teuthida-technologies.com/"
-  spec.description   = "A Fibonacci inspired pseudo random number generator. Suitable for light duties."
-  spec.summary       = "A Fibonacci inspired pseudo random number generator."
+  spec.description   = "A Fibonacci inspired pseudo random number generator. " +
+                       "[Updated] The algorithm is changed to use bit rotate " +
+                       "instead of bit shift."
+  spec.summary       = "[Updated] A Fibonacci inspired pseudo random number generator."
   spec.license       = "MIT"
 
   raw_list = `git ls-files`.split($/)

data/lib/fibonacci_rng/spinner.rb

@@ -18,7 +18,8 @@ class FibonacciRng
     @buffer[-1] = @buffer[1]
 
     (0...@depth).each do |idx|
-      @buffer[idx] = (@buffer[idx+1] + (@buffer[idx+2] >> 1)) & CHOP
+      tmp = @buffer[idx+2]
+      @buffer[idx] = (@buffer[idx+1] + ((tmp >> 1)|(tmp.odd? ? TOP : 0))) & CHOP
     end
   end
 

data/lib/fibonacci_rng/version.rb

@@ -2,5 +2,5 @@
 
 #The class of Fibonacci inspired random number generators.
 class FibonacciRng
-  VERSION = "0.4.3"
+  VERSION = "1.0.0"
 end

data/lib/fibonacci_rng.rb

@@ -10,6 +10,7 @@ require_relative "fibonacci_rng/version"
 class FibonacciRng
 
   CHOP   = 0x1FFFFFFF
+  TOP    = 0x10000000
   BYTE   = 0xFF
   WORD   = 0xFFFF
   BASE   = (CHOP+1).to_f

data/tests/fibinacci_rng_tests.rb

@@ -152,9 +152,9 @@ class FibonacciRngTester < Minitest::Test
   def test_building_strings
     rng = FibonacciRng.new(0)
 
-    assert_equal('8{4y5+-N+c', rng.string(10))
-    assert_equal('1149049996', rng.string(10, '0123456789'))
-    assert_equal('tfes   oAy', rng.string(10, 'Always look on the bright side of life.'))
+    assert_equal("c}l'(q@g\\z", rng.string(10))
+    assert_equal('2727573312', rng.string(10, '0123456789'))
+    assert_equal('khto lk si', rng.string(10, 'Always look on the bright side of life.'))
   end
 
 end

data/tests/hasher_tests.rb

@@ -14,10 +14,10 @@ class FibonacciHasherTester < Minitest::Test
   def test_that_it_can_be_read
     fib = FibonacciRng.new('salt')
 
-    val = 6419946790796257801349293118951652810485853780437507149800008378866623
+    val = 6283409396933018229308310224792996722092866776518016470611172637516158
     assert_equal(val, fib.hash_value)
 
-    str = 'le247zggdghf5vpcjbw2hrjf9eu8ql01wvl1fhv14bykf'
+    str = 'kxoj5k4rx6mqx1bmskx2133lrr21h8l2fs0zd1ver0ozi'
     assert_equal(str, fib.hash_string)
   end
 
@@ -26,13 +26,13 @@ class FibonacciHasherTester < Minitest::Test
 
     fib << "The quick brown fox jumps over the lazy dog."
 
-    str = 'j5jqhk7ntrze02icv38gj28efa2qrctr6mi5ejbr2p4nj'
+    str = 'hoeh45h3fqlrgnynud0rg3v8q62cadr9gmxx9lomzo3hi'
     assert_equal(str, fib.hash_string)
 
     fib << nil
 
     refute_equal(str, fib.hash_string)
-    str = '1g5sgt443g4jcn3bfpiee1fkqoklo0i1ctkjro2vevpp0'
+    str = '9anamtuoyhhb7v6s7y70m31mfsl2r2rbp4vki0vb9rnag'
     assert_equal(str, fib.hash_string)
   end
 

data/tools/scatter_plot.rb

@@ -1,9 +1,9 @@
 # coding: utf-8
 
-#A Chi Squared tester
+#A Scatter Plot tester
 class ScatterPlot
 
-  #Run a chi squared test on the random number generator.
+  #Run a scatter plot test on the random number generator.
   def run(gen, max, count)
     puts "Starting test"
     bins = Array.new(max * 2, 0)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fibonacci_rng
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Peter Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-26 00:00:00.000000000 Z
+date: 2016-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest_visible
@@ -94,8 +94,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 4.0.1
-description: A Fibonacci inspired pseudo random number generator. Suitable for light
-  duties.
+description: A Fibonacci inspired pseudo random number generator. [Updated] The algorithm
+  is changed to use bit rotate instead of bit shift.
 email:
 - peter.c.camilleri@gmail.com
 executables: []
@@ -146,6 +146,6 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: A Fibonacci inspired pseudo random number generator.
+summary: "[Updated] A Fibonacci inspired pseudo random number generator."
 test_files: []
 has_rdoc: