loaded_dice 0.1.0

data/LICENSE

@@ -0,0 +1,23 @@
+
+ Copyright (c) 2012 Kaspar Schiess
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,16 @@
+SYNOPSIS
+
+  die = LoadedDie.new(1,1,2,1,1,1)
+  die.roll # => one of {0,1,2,3,4,5}, with 2 being more likely.
+
+  # And just for kicks, here's a 20 sided non loaded die: 
+  die = LoadedDie.new(*([1] * 20))
+  die.roll
+
+DESCRIPTION
+
+Roll the dice in your favor! A loaded die implementation that allows
+simulation of dice with any number of faces. Applications might include games,
+but also simulations, where events have discrete probabilities and are
+mutually exclusive.
+

data/lib/loaded_die.rb

@@ -0,0 +1,87 @@
+# A loaded die that takes a probability map as constructor argument and will
+# generate die rolls every time you call #roll. Die sides are numbered 0-n,
+# where n is the size of the probability map. 
+#
+# Example: 
+#   # A three sided die with probabilities 1/6, 2/6, 3/6
+#   die = LoadedDie.new(1,2,3)
+#   die.roll    # => one of {0, 1, 2}
+#
+# This is Voses Alias Method from an excellent description of the various
+# algorithms by Keith Schwarz. It has a setup cost of O(n), a cost for each
+# roll of O(1) and uses O(n) memory. I recommend reading "Darts, Dice and
+# Coins: Sampling from a Discrete Distribution" by Keith Schwarz.
+#
+class LoadedDie
+  # Returns the number of sides this die has. 
+  attr_reader :sides
+  # The original probability map. 
+  attr_reader :probabilities
+  attr_reader :normalized_probabilities
+  
+  # Sets up a die with the given probabilities. No need to have a probability
+  # map that sums to 1, the code will normalize the numbers and provide you
+  # with #normalized_probabilities. 
+  #
+  def initialize(*probabilities)
+    init(*probabilities)
+  end
+  def init(*probabilities) # :nodoc: 
+    @probabilities = probabilities
+    @sides = probabilities.size
+    
+    @alias = Array.new(sides)
+    @prob  = Array.new(sides)
+    
+    # The original algorithm calls for probabilities that sum to 1. 
+    sum = probabilities.inject(0) { |a,e| a + e }
+
+    # This is not needed for the algorithm, but is a nice thing to have.
+    @normalized_probabilities = 
+      probabilities.map { |e| e/Float(sum) }
+
+    # This is what we'll work with.
+    mul_probabilities = probabilities.map { |e| e*sides/Float(sum) }
+    
+    # Partition into worklists small and large
+    small, large = mul_probabilities.
+      # generate tuples <p(i), i>
+      zip((0..sides).to_a).
+      # partition into small and large
+      partition { |p,i| p < 1 }
+
+    until large.empty? || small.empty?      
+      pl, l = small.pop
+      pg, g = large.pop
+      
+      @prob[l] = pl
+      @alias[l] = g
+      
+      pg = (pg + pl) - 1
+      tuple = [pg, g]
+      (pg < 1 ? small : large).
+        push tuple
+    end
+    
+    # large will mostly not be empty at this point. Small can be non-empty due
+    # to floating point numerical instability.
+    [large, small].each do |list|
+      until list.empty? 
+        pg, g = list.pop
+        @prob[g] = 1
+      end
+    end
+  end
+  
+  # Rolls the die once and returns a number in the range 0...sides. Numbers
+  # will be distributed relative to the probabilities given in
+  # #normalized_probabilities.
+  #
+  def roll
+    # First roll a die with homogenous distribution: 
+    n = rand(sides)
+    # And now a biased coin with prob(head) == @prob[n]
+    return n if rand() < @prob[n]
+    return @alias[n]
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: loaded_dice
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Kaspar Schiess
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-26 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: kaspar.schiess@absurd.li
+executables: []
+extensions: []
+extra_rdoc_files:
+- README
+files:
+- LICENSE
+- README
+- lib/loaded_die.rb
+homepage: 
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- README
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Simulates a loaded die with n sides. Perfect for non homogenous randomisation
+  needs.
+test_files: []