capricious 0.1.0 → 0.2.1

data/CHANGES

@@ -1,9 +1,22 @@
-version 0.1.0
+version 0.2.1
+
+* 0.2.0 sneaked out the door with a stray debugging printf; this is a paper-bag release.
+
+version 0.2.0 (6cebdd8c2574be71b9f9575542903960b22aa568)
+
+* Improved documentation.
+* Added Erlang distribution.
+* Added exponential distribution.
+* Added #expected_mean and #expected_variance methods to all distribution simulators.
+* Added biased uniform distribution (i.e. uniform distributions with ranges other than 0..1).
+* Substantial speed improvements to MWC generator.
+
+version 0.1.0 (369ba2f9eb0b921b24efa5b75aa34478d0a443af)
 
 * added multiply-with-carry based PRNG (algorithm due to George Marsaglia)
 * added Poisson distribution
 
-version 0.0.2 
+version 0.0.2 (8d28e1f4065ba8cc249722f2b4b4add091cb9dfb)
 
 * initial release
 * linear-feedback shift register based PRNG

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.1

data/lib/capricious.rb

@@ -20,4 +20,7 @@ require 'capricious/lfsr'
 require 'capricious/mwc5'
 require 'capricious/sample_sink'
 require 'capricious/uniform'
+require 'capricious/biased_uniform'
 require 'capricious/poisson'
+require 'capricious/exponential'
+require 'capricious/erlang'

data/lib/capricious/biased_uniform.rb

@@ -0,0 +1,35 @@
+# capricious/biased_uniform.rb:  biased uniform-distribution PRNG, with specifiable max and min and selectable source-randomness policy
+#
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'capricious/uniform'
+
+module Capricious
+  # Models a uniform distribution, parameterized on minimum and maximum values.
+  class BiasedUniform < Uniform
+    def initialize(min=Uniform::UNIFORM_MIN, max=Uniform::UNIFORM_MAX, seed=nil, policy=MWC5, keep_stats=false)
+      @min = min
+      @max = max
+      prng_initialize(seed, policy, keep_stats)
+    end
+    
+    private
+    def next_value
+      (@prng.next_f * (max - min)) + min
+    end
+  end
+end

data/lib/capricious/erlang.rb

@@ -0,0 +1,48 @@
+# capricious/exponential.rb:  Erlang distribution PRNG, with selectable source-randomness policy
+#
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'capricious/generic_prng'
+require 'capricious/exponential'
+
+module Capricious
+  # Models the Erlang distribution, parameterized on the lambda value of the
+  # underlying exponential distribution and a shape parameter.
+  class Erlang
+    include PRNG
+    
+    attr_reader :expected_mean, :expected_variance
+    
+    # Initializes a new Erlang distribution.  =l= is the lambda parameter and
+    # =shape= is the shape parameter; =seed=, =policy=, and =keep_stats= are
+    # as in =PRNG=.
+    def initialize(l, shape, seed=nil, policy=MWC5, keep_stats=false)
+      @shape = shape
+      @expected_mean = shape / l.to_f
+      @expected_variance = shape / (l * l).to_f
+      @expo = Exponential.new(l, seed, policy, keep_stats)
+      prng_initialize(seed, policy, keep_stats)
+    end
+    
+    private
+    def next_value
+      sum = 0.0
+      @shape.times { sum += @expo.next }
+      sum
+    end
+  end
+end

data/lib/capricious/exponential.rb

@@ -0,0 +1,46 @@
+# capricious/exponential.rb:  Exponential distribution PRNG, with selectable source-randomness policy
+#
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'capricious/generic_prng'
+
+module Capricious
+  # Exponential-distribution PRNG
+  class Exponential
+    include PRNG
+    
+    attr_reader :expected_mean, :expected_variance
+    
+    # Initializes a new distribution.  =l= is the lambda parameter; =seed=,
+    # =policy=, and =keep_stats= are as in =PRNG=.
+    def initialize(l, seed=nil, policy=MWC5, keep_stats=false)
+      @expected_mean = 1 / l.to_f
+      @expected_variance = 1 / (l * l).to_f 
+      prng_initialize(seed, policy, keep_stats)
+    end
+    
+    private
+    def next_value
+      u = @prng.next_f
+      while u == 0.0 || u == 1.0
+        u = @prng.next_f
+      end
+
+      -expected_mean * Math.log(u)
+    end
+  end
+end

data/lib/capricious/generic_prng.rb

@@ -1,8 +1,8 @@
 # capricious/generic_prng.rb:  generic PRNG mixin with selectable source-randomness
 #
-# Copyright (c) 2010 Red Hat, Inc.
-#
-# Author:  William Benton <willb@redhat.com>
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,8 +21,19 @@ require 'capricious/mwc5'
 require 'capricious/sample_sink'
 
 module Capricious
+  # Base mixin for distribution simulators.  Manages an underlying PRNG and
+  # optional statistics.  Mixing =PRNG= in to a simulator class will define
+  # =next= and =reset= methods as well as =@aggregate= and =@seed= attributes
+  # and a =@prng= instance variable.  Simulator classes must define a
+  # =next_value= method that returns a value in the given distribution and
+  # should define =expected_mean= and =expected_variance= methods or
+  # attributes.
   module PRNG
     
+    # Takes a seed, a policy, and whether or not to keep statistics in the
+    # =aggregate= attribute of the distribution object.  If a simulator class
+    # overrides =initialize=, it must call =prng_initialize= from within its
+    # =initialize= method.    
     def initialize(seed=nil, policy=MWC5, keep_stats=false)
       prng_initialize(seed, policy, keep_stats)
     end
@@ -33,12 +44,14 @@ module Capricious
       @aggregate = SampleSink.new if keep_stats
     end
     
+    # Returns the next value from this simulator.
     def next
       val = next_value
       @aggregate << val if @aggregate
       val
     end
 
+    # Resets the state of the underlying value.
     def reset(seed=nil)
       @prng.reset(seed)
       @aggregate = SampleSink.new if @aggregate

data/lib/capricious/lfsr.rb

@@ -1,8 +1,8 @@
 # capricious/lfsr.rb:  linear-feedback shift register class
 #
-# Copyright (c) 2010 Red Hat, Inc.
-#
-# Author:  William Benton <willb@redhat.com>
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -66,7 +66,6 @@ module Capricious
   module SixtyFourBitShifter
     MASK = 0xffffffffffffffff
     SIZE = 64
-#    BITS = [64,63,61,60]
     BITS = [64,4,3,1]
     BITSELECT = BITS.map {|bit| "@reg[#{SIZE-bit}]"}.join("^")
     

data/lib/capricious/mwc5.rb

@@ -1,8 +1,9 @@
 # capricious/mwc5.rb:  32-bit multiply-with-carry PRNG
 #
-# Copyright (c) 2010 Red Hat, Inc.
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
 #
-# Author:  William Benton <willb@redhat.com>
 # Algorithm due to George Marsaglia:  http://groups.google.com/group/comp.lang.c/msg/e3c4ea1169e463ae
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -20,6 +21,7 @@
 require 'capricious/lfsr'
 
 module Capricious
+  # Multiply-with-carry pseudorandom number generator.  Algorithm due to George Marsaglia.
   class MWC5
     attr_reader :seed, :seeds
     def MWC5.new_with_seed(seed)
@@ -59,12 +61,9 @@ module Capricious
     def shift_ks
       # XXX:  this is ugly, but it has to be to avoid coercing things into bignums
       t=(@x^(@x>>7)) & 0xffffffff
-      @x=@y
-      @y=@z
-      @z=@w
-      @w=@v
-      @v=(@v^(@v<<6))^(t^(t<<13)) & 0xffffffff
-      yy = ((@y & 0x7fffffff << 1) + 1) & 0xffffffff
+      @x,@y,@z,@w = @y,@z,@w,@v
+      @v=(@v^((@v&0x3ffffff)<<6))^(t^((t&0x1ffff)<<13)) & 0xffffffff
+      yy = (((@y & 0x7fffffff) << 1) + 1) & 0xffffffff
       (yy * @v) & 0xffffffff;
     end
   end

data/lib/capricious/poisson.rb

@@ -1,8 +1,8 @@
 # capricious/poisson.rb:  Poisson-distribution PRNG, with selectable source-randomness policy
 #
-# Copyright (c) 2010 Red Hat, Inc.
-#
-# Author:  William Benton <willb@redhat.com>
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,16 +19,27 @@
 require 'capricious/generic_prng'
 
 module Capricious
+  # Models a Poisson distribution
   class Poisson
     include PRNG
     
-    attr_reader :z
+    attr_reader :z, :expected_mean
     
+    # Initializes a new distribution.  =l= is the lambda parameter (which is
+    # also the expected mean and variance); =seed=, =policy=, and =keep_stats=
+    # are as in =PRNG=.  Note that the linear-feedback shift register policy
+    # will not provide acceptable results with this and other non-uniform
+    # distributions due to extremely high lag-k autocorrelation for small k.
     def initialize(l, seed=nil, policy=MWC5, keep_stats=false)
       @z = Math.exp(-l)
+      @expected_mean = l
       prng_initialize(seed, policy, keep_stats)
     end
     
+    def expected_variance
+      @expected_mean
+    end
+    
     private
     # Algorithm 369, CACM, January 1970
     def next_value

data/lib/capricious/sample_sink.rb

@@ -1,8 +1,8 @@
 # capricious/sample_sink.rb:  sample aggregator
 #
-# Copyright (c) 2010 Red Hat, Inc.
-#
-# Author:  William Benton <willb@redhat.com>
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,6 +17,8 @@
 # limitations under the License.
 
 module Capricious
+  
+  # Records aggregate data about a stream of samples in constant space.
   class SampleSink
     
     attr_reader :min, :max, :count, :mean, :variance
@@ -30,17 +32,22 @@ module Capricious
       @sum_x2 = 0.0
     end
     
+    # Adds a sample and updates =min=, =max= and =count= as well as =mean=,
+    # and =variance= estimates.
     def put(sample)
       update_stats(sample)
       update_estimates(sample)
       nil
     end
     
+    # Adds a sample and updates =min=, =max= and =count= as well as =mean=,
+    # and =variance= estimates.
     def <<(sample)
       self.put(sample)
       self
     end
     
+    # Returns the square root of the variance for all witnessed samples.
     def stddev
       Math::sqrt(@variance)
     end

data/lib/capricious/uniform.rb

@@ -1,8 +1,8 @@
 # capricious/uniform.rb:  uniform-distribution PRNG, with selectable source-randomness policy
 #
-# Copyright (c) 2010 Red Hat, Inc.
-#
-# Author:  William Benton <willb@redhat.com>
+# Copyright:: Copyright (c) 2010 Red Hat, Inc.
+# Author::  William Benton <willb@redhat.com>
+# License:: http://www.apache.org/licenses/LICENSE-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,10 +19,32 @@
 require 'capricious/generic_prng'
 
 module Capricious
+  
+  # Creates pseudorandom numbers in the range [0,1) that satisfy a uniform distribution.
   class Uniform
     include PRNG
+    UNIFORM_MIN = 0.0
+    UNIFORM_MAX = 1.0
+    
+    # Returns the expected mean for this distribution:  =(min + max) / 2=.
+    def expected_mean
+      (min + max) / 2
+    end
+    
+    # Returns the expected variance for this distribution:  =(max - min) ** 2 / 12=.
+    def expected_variance
+      ((max - min) ** 2) / 12
+    end
     
     private
+    def min
+      @min || UNIFORM_MIN
+    end
+    
+    def max
+      @max || UNIFORM_MAX
+    end
+    
     def next_value
       @prng.next_f
     end

data/spec/biased_uniform_spec.rb

@@ -0,0 +1,35 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+module Capricious
+  SAMPLE_COUNT = 60000
+
+  describe BiasedUniform do
+    MIN = 13.37
+    MAX = 14.53
+    
+    def generate_samples(policy=MWC5, count=SAMPLE_COUNT)
+      @uniform = Capricious::BiasedUniform.new(MIN, MAX, nil, policy, true)
+      count.times {@uniform.next}
+    end
+    
+    [LFSR,MWC5].each do |policy|
+      it "should, given policy #{policy.name}, generate numbers in the range (#{MIN},#{MAX}]" do
+        generate_samples(policy)
+        @uniform.aggregate.max.should <= MAX
+        @uniform.aggregate.min.should > MIN
+      end
+
+      it "should, given policy #{policy.name}, generate uniformly-distributed numbers in the range (#{MIN},#{MAX}], as judged by mean and variance estimates" do
+        generate_samples(policy)
+        @uniform.aggregate.mean.should be_close(@uniform.expected_mean, 0.01)
+        @uniform.aggregate.stddev.should be_close(Math.sqrt(@uniform.expected_variance), 0.01)
+      end
+    
+      it "should, given policy #{policy.name}, generate the same sequence given the same seed" do
+        @uniform = BiasedUniform.new(MIN, MAX, nil, policy, false)
+        @uniform2 = BiasedUniform.new(MIN, MAX, nil, policy, false)
+        (SAMPLE_COUNT/40).times { @uniform2.next.should == @uniform.next }
+      end
+    end
+  end
+end

data/spec/erlang_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+module Capricious
+  LAMBDA = 3
+  R = 6
+  SAMPLE_COUNT = 200
+
+  describe Erlang do
+    def generate_samples(count=SAMPLE_COUNT)
+      count.times {@erlang.next}
+    end
+    
+    before(:each) do
+      @erlang = Capricious::Erlang.new(LAMBDA, R, nil, MWC5, true)
+    end
+    
+    it "should generate distributed numbers in an Erlang distribution with lambda #{LAMBDA} and r #{R}, as judged by mean and variance estimates" do
+      generate_samples(10000)
+      
+      @erlang.aggregate.mean.should be_close(@erlang.expected_mean, 0.05)
+      @erlang.aggregate.variance.should be_close(@erlang.expected_variance, 0.15)
+    end
+    
+    it "should generate the same sequence given the same seed" do
+      @erlang2 = Erlang.new(LAMBDA, R, @erlang.seed, MWC5, true)
+      SAMPLE_COUNT.times { @erlang2.next.should == @erlang.next }
+    end
+  end
+end

data/spec/exponential_spec.rb

@@ -0,0 +1,28 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+module Capricious
+  LAMBDA = 8
+  SAMPLE_COUNT = 200
+
+  describe Exponential do
+    def generate_samples(count=SAMPLE_COUNT)
+      count.times {@expo.next}
+    end
+    
+    before(:each) do
+      @expo = Capricious::Exponential.new(LAMBDA, nil, MWC5, true)
+    end
+    
+    it "should generate distributed numbers in an exponential distribution with lambda #{LAMBDA}, as judged by mean and variance estimates" do
+      generate_samples(10000)
+      
+      @expo.aggregate.mean.should be_close(@expo.expected_mean, 0.05)
+      @expo.aggregate.variance.should be_close(@expo.expected_variance, 0.15)
+    end
+    
+    it "should generate the same sequence given the same seed" do
+      @expo2 = Exponential.new(LAMBDA, @expo.seed, MWC5, true)
+      SAMPLE_COUNT.times { @expo2.next.should == @expo.next }
+    end
+  end
+end

data/spec/uniform_spec.rb

@@ -1,8 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 module Capricious
-  EXPECTED_MEAN = 0.5
-  EXPECTED_STDDEV = 0.288675134594813
   SAMPLE_COUNT = 20000
 
   describe Uniform do
@@ -20,8 +18,8 @@ module Capricious
 
       it "should, given policy #{policy.name}, generate uniformly-distributed numbers in the range (0,1], as judged by mean and variance estimates" do
         generate_samples(policy)
-        @uniform.aggregate.mean.should be_close(EXPECTED_MEAN, 0.01)
-        @uniform.aggregate.stddev.should be_close(EXPECTED_STDDEV, 0.01)
+        @uniform.aggregate.mean.should be_close(@uniform.expected_mean, 0.01)
+        @uniform.aggregate.stddev.should be_close(Math.sqrt(@uniform.expected_variance), 0.01)
       end
     
       it "should, given policy #{policy.name}, generate the same sequence given the same seed" do

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: capricious
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Will Benton
@@ -9,19 +14,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-12 00:00:00 -06:00
+date: 2010-03-15 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
         version: 1.2.9
-    version: 
+  type: :development
+  version_requirements: *id001
 description: Pseudorandom number generator classes and support code, parameterized on a source of randomness and a probability distribution
 email: willb@redhat.com
 executables: []
@@ -40,12 +49,18 @@ files:
 - Rakefile
 - VERSION
 - lib/capricious.rb
+- lib/capricious/biased_uniform.rb
+- lib/capricious/erlang.rb
+- lib/capricious/exponential.rb
 - lib/capricious/generic_prng.rb
 - lib/capricious/lfsr.rb
 - lib/capricious/mwc5.rb
 - lib/capricious/poisson.rb
 - lib/capricious/sample_sink.rb
 - lib/capricious/uniform.rb
+- spec/biased_uniform_spec.rb
+- spec/erlang_spec.rb
+- spec/exponential_spec.rb
 - spec/poisson_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -63,22 +78,27 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Pseudorandom number generator classes and support code
 test_files: 
+- spec/biased_uniform_spec.rb
+- spec/erlang_spec.rb
+- spec/exponential_spec.rb
 - spec/poisson_spec.rb
 - spec/spec_helper.rb
 - spec/uniform_spec.rb