random_variates 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43a85c7f9cd47a418101215d490e1089ab8b5867f860c6200359c2d1f08079a2
-  data.tar.gz: 6bb665672cbbfcd7b281739acc3e78437ad8a2632e21208559d9a5b4dc380645
+  metadata.gz: 6ae5af59fb1609e227a42bc3fe9b93f1cb0d561513526044de0f74bc95fe9040
+  data.tar.gz: 5a18534afb749cf8b0d829b64f1f67daec0809ee0669073872dcf477a24f4d99
 SHA512:
-  metadata.gz: 5741f020d080a4e2a2e2dec67e3654eeb6e8cd5ea4725881ccb94f7b2b1b9efbfc38548bcadae625f2b68e36d868209259fc485c6d30007eed11b2154bb65df8
-  data.tar.gz: f5f8821ecf11b76639c8e1c63391dbbfc5f490617da946a49d157dee1c9f749a6d41755a5ae1abcc4b4000743c8db358654e0ff7e7840b7af2740c7afd7fa1b3
+  metadata.gz: a22d4223b928d7013deeb938fa497b231821d28939a75521b1e30f0bea1e20e95e8bb730c0a0dc8a2a0513b9174821abe36174a068dcc1cd81fafad941620af4
+  data.tar.gz: b4651ab9d4a17cb250a35a819658f92b6212c39f6cac9670ea3d069ab98e2335ea5b345e9ff138c7d642741a33441d0d29faa6c5eb41c545b65845bbf0257222

data/LICENSE.md

@@ -1,7 +1,7 @@
 
 The MIT License (MIT)
 
-Copyright (c) 2020 Paul J. Sanchez
+Copyright (c) 2023 Paul J. Sanchez
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,4 +1,4 @@
-### DESCRIPTION
+#### DESCRIPTION
 
 This gem implements random variate generation for several
 common statistical distributions.  Each distribution is implemented
@@ -7,19 +7,33 @@ instances of the class using the constructor to specify the
 parameterization.  All constructors use named parameters for clarity,
 so the order of parameters does not matter. All random variate classes
 provide an optional argument `rng`, with which the user can specify a
-U(0,1) generator as an `Enumerator` to use as the core source of randomness.
-If `rng` is not specified, it is based on Ruby's `Kernel#rand`.
+pseudo-random number generator that has a `rand` method that provides
+U(0,1) values to use as the core source of randomness.
+If `rng` is not specified, it defaults to an instance of
+class `Xoroshiro::Random`.
 
 Once a random variate class has been instantiated, values can either be
-generated on demand using the `next` method or by using the instance as
-a generator in any iterable context.  Since these are "infinite" generators, enumerative Ruby methods such as `.first` or `.take` will require a `.each` first to yield an iterator for lazy access.  Example: `my_exp = RV::Exponential.new(rate: 3); my_exp.each.take(50)` will yield an array of fifty exponentially distributed values having rate 3.
+generated on demand using the `next` method (preferred for speed) or by
+creating an `Enumerator` for use in any iterable context. For example,
+the following will create an array of fifty exponentially distributed
+values having rate 3.
+
+    my_exp = RV::Exponential.new(rate: 3)
+    my_exp.each.take(50)
 
 ---
 
-### RELEASE NOTES
+#### RELEASE NOTES
+
+**v0.5**
+
+Prior releases focused on statistical correctness and adding distributions. This
+release is about speed improvements. Substantial speedups have been accomplished by:
 
-**v0.4**
- - All distribution classes have been placed in a module called `RV` to try to avoid namespace conflicts.
- - The `Gaussian` class has been renamed, it is now the `Normal` class.
- - Parameters for `Gaussian` and `BoxMuller` have been renamed.  They are now `mu:` and `sigma:`.
- - `Exponential`, `Normal`, and `BoxMuller` distribution parameters can now be set to new values without having to instantiate an entirely new generator object.
+ - replacing the prior U(0,1) `Enumerator` architecture with direct calls to the PRNG;
+ - replacing `loop do` with the measurably faster `while true` in
+   acceptance/rejection based algorithms; and
+ - replacing ruby's built-in `Random` with `Xoroshiro::Random` as the default
+   PRNG. Xoshiro256** is faster than ruby's MT19937 implementation, and passes
+   all tests in the TestU01 suite. See [xoshiro / xoroshiro generators and the
+   PRNG shootout](https://prng.di.unimi.it) for more information.

data/lib/random_variates.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require 'xoroshiro'
+
 # This library implements random variate generation for several
 # common statistical distributions.  Each distribution is implemented
 # in its own class, and different parameterizations are created as
 # instances of the class using the constructor to specify the
 # parameterization.  All constructors use named parameters for clarity,
 # so the order of parameters does not matter. All RV classes provide an
-# optional argument +rng+, with which the user can specify an enumerable
-# U(0,1) generator to use as the core source of randomness.  If +rng+ is
+# optional argument +rng+, with which the user can specify a U(0,1)
+# PRNG object to use as the core source of randomness.  If +rng+ is
 # not specified, it defaults to +Kernel#rand+.
 #
 # Once a random variate class has been instantiated, values can either be
@@ -15,8 +17,8 @@
 # a generator in any iterable context.
 
 module RV
-  # Provide access to +Kernel#rand+ as an +Enumerator+.
-  U_GENERATOR = Enumerator.new { |yielder| loop { yielder << rand } }
+  # Set default PRNG.
+  U_GENERATOR = Xoroshiro::Random.new
 
   # The +RV_Generator+ module provides a common core of methods to make
   # all of the RV classes iterable.
@@ -26,7 +28,11 @@ module RV
     end
 
     def each
-      Enumerator.new { |y| loop { y << self.next } }
+      Enumerator.new do |y|
+        while true
+          y << self.next
+        end
+      end
     end
   end
 
@@ -40,18 +46,17 @@ module RV
   class Uniform
     include RV_Generator
 
-    attr_reader :min, :max, :range
+    attr_reader :min, :max
 
     def initialize(min: 0.0, max: 1.0, rng: U_GENERATOR)
-      raise 'Max must be greater than min.' if max <= min
+      raise 'Max must be greater than min.' unless max > min
       @min = min
       @max = max
-      @range = max - min
       @rng = rng
     end
 
     def next
-      @min + @range * @rng.next
+      @rng.rand(@min..@max)
     end
   end
 
@@ -110,7 +115,7 @@ module RV
     end
 
     def next
-      u = @rng.next
+      u = @rng.rand
       u < @crossover_p ?
         @min + Math.sqrt(@range * (@mode - @min) * u) :
         @max - Math.sqrt(@range * (@max - @mode) * (1.0 - u))
@@ -148,18 +153,18 @@ module RV
     end
 
     def next
-      -@mean * Math.log(@rng.next)
+      -@mean * Math.log(@rng.rand)
     end
 
     def rate=(rate)
-      raise 'Rate must be a number.' unless rate.is_a? Number
+      raise 'Rate must be a number.' unless rate.is_a? Numeric
       raise 'Rate must be positive.' if rate <= 0
       @mean = 1.0 / rate
       @rate = rate
     end
 
     def mean=(mean)
-      raise 'Mean must be a number.' unless mean.is_a? Number
+      raise 'Mean must be a number.' unless mean.is_a? Numeric
       raise 'Mean must be positive.' if mean <= 0
       @mean = mean
       @rate = 1.0 / mean
@@ -189,10 +194,10 @@ module RV
     end
 
     def next
-      loop do
-        u = @rng.next
+      while true
+        u = @rng.rand
         next if u == 0.0
-        v = BOUND * (@rng.next - 0.5)
+        v = BOUND * (@rng.rand - 0.5)
         x = v / u
         x_sqr = x * x
         u_sqr = u * u
@@ -207,12 +212,12 @@ module RV
     end
 
     def sigma=(sigma)
-      raise 'sigma must be a number.' unless sigma.is_a? Number
+      raise 'sigma must be a number.' unless sigma.is_a? Numeric
       @sigma = sigma
     end
 
     def mu=(mu)
-      raise 'mu must be a number.' unless mu.is_a? Number
+      raise 'mu must be a number.' unless mu.is_a? Numeric
       @mu = mu
     end
   end
@@ -238,13 +243,12 @@ module RV
       @sigma = sigma
       @rng = rng
       @need_new_pair = false
-      # @next_norm = 0.0
     end
 
     def next
       if @need_new_pair ^= true
-        theta = TWO_PI * @rng.next
-        d = @sigma * Math.sqrt(-2.0 * Math.log(@rng.next))
+        theta = TWO_PI * @rng.rand
+        d = @sigma * Math.sqrt(-2.0 * Math.log(@rng.rand))
         @next_norm = @mu + d * Math.sin(theta)
         @mu + d * Math.cos(theta)
       else
@@ -253,12 +257,12 @@ module RV
     end
 
     def sigma=(sigma)
-      raise 'sigma must be a number.' unless sigma.is_a? Number
+      raise 'sigma must be a number.' unless sigma.is_a? Numeric
       @sigma = sigma
     end
 
     def mu=(mu)
-      raise 'mu must be a number.' unless mu.is_a? Number
+      raise 'mu must be a number.' unless mu.is_a? Numeric
       @mu = mu
     end
   end
@@ -297,21 +301,21 @@ module RV
         z = v = 0.0
         d = alpha - 1.0 / 3.0
         c = (1.0 / 3.0) / Math.sqrt(d)
-        loop do
-          loop do
+        while true
+          while true
             z = @std_normal.next
             v = 1.0 + c * z
             break if v > 0
           end
           z2 = z * z
           v = v * v * v
-          u = @rng.next
+          u = @rng.rand
           break if u < 1.0 - 0.0331 * z2 * z2
           break if Math.log(u) < (0.5 * z2 + d * (1.0 - v + Math.log(v)))
         end
         d * v * beta
       else
-        __gen__(alpha + 1.0, beta) * (@rng.next**(1.0 / alpha))
+        __gen__(alpha + 1.0, beta) * (@rng.rand**(1.0 / alpha))
       end
     end
   end
@@ -338,7 +342,7 @@ module RV
     end
 
     def next
-      (-Math.log(@rng.next))**@power / @rate
+      (-Math.log(@rng.rand))**@power / @rate
     end
   end
 
@@ -381,9 +385,9 @@ module RV
     end
 
     def next
-      loop do
-        r1 = @rng.next
-        theta = @s * (2.0 * @rng.next - 1.0) / r1
+      while true
+        r1 = @rng.rand
+        theta = @s * (2.0 * @rng.rand - 1.0) / r1
         next if theta.abs > Math::PI
         return theta if (0.25 * @kappa * theta * theta < 1.0 - r1) ||
                         (0.5 * @kappa * (Math.cos(theta) - 1.0) >= Math.log(r1))
@@ -410,10 +414,17 @@ module RV
       @rng = rng
     end
 
+    def rate=(rate)
+      raise 'Rate must be a number.' unless rate.is_a? Numeric
+      raise 'Rate must be positive.' if rate <= 0
+      @rate = rate
+      @threshold = Math.exp(-rate)
+    end
+
     def next
       count = 0
       product = 1.0
-      count += 1 until (product *= @rng.next) < @threshold
+      count += 1 until (product *= @rng.rand) < @threshold
       count
     end
   end
@@ -432,13 +443,12 @@ module RV
     def initialize(p: 0.5, rng: U_GENERATOR)
       raise 'Require 0 < p < 1.' if p <= 0 || p >= 1
 
-      @p = p
       @log_q = Math.log(1 - p)
       @rng = rng
     end
 
     def next
-      (Math.log(1.0 - @rng.next) / @log_q).ceil
+      (Math.log(1.0 - @rng.rand) / @log_q).ceil
     end
   end
 
@@ -473,8 +483,8 @@ module RV
 
     def next
       result = sum = 0
-      loop do
-        sum += Math.log(@rng.next) / (@n - result)
+      while true
+        sum += Math.log(@rng.rand) / (@n - result)
         break if sum < @log_q
         result += 1
       end

metadata

@@ -1,16 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: random_variates
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Paul J Sanchez
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-02 00:00:00.000000000 Z
-dependencies: []
-description: Random variate generators implemented as enumerators.
+date: 2023-05-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: xoroshiro
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Random variate generators implemented with Enumerator.
 email: pjs@alum.mit.edu
 executables: []
 extensions: []
@@ -22,8 +36,11 @@ files:
 homepage: https://bitbucket.org/paul_j_sanchez/random_variates.git
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://bitbucket.org/paul_j_sanchez/random_variates.git
+  documentation_uri: https://rubydoc.info/gems/random_variates
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -31,15 +48,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.4.13
+signing_key:
 specification_version: 4
-summary: Random variate generator classes.
+summary: Random variate generator classes for popular distributions.
 test_files: []