NAME

Games::Dice::Loaded - Simulate rolling loaded dice

SYNOPSIS

  use Games::Dice::Loaded;

  my $die = Games::Dice::Loaded->new(1/6, 1/6, 1/2, 1/12, 1/12);
  my $result = $die->roll();

  my $fair_d4 = Games::Dice::Loaded->new(1, 1, 1, 1);
  $result = $fair_d4->roll();

DESCRIPTION

Games::Dice::Loaded allows you to simulate rolling arbitrarily-weighted dice with arbitrary numbers of faces - or, more formally, to sample any discrete probability distribution which may take only finitely many values. It does this using Vose's elegant alias method, which is described in Keith Schwarz's article Darts, Dice, and Coins: Sampling from a Discrete Distribution.

METHODS

new()

Constructor. Takes as arguments the probabilities of rolling each "face". If the weights given do not sum to 1, they are scaled so that they do. This method constructs the alias table, in O(num_faces) time.

roll()

Roll the die. Takes no arguments, returns a number in the range 1 .. num_faces. Takes O(1) time.

sample()

Synonym for roll().

num_faces()

The number of faces on the die. More formally, the size of the discrete random variable's domain. Read-only.

AUTHOR

Miles Gould, <mgould@cpan.org>

CONTRIBUTING

Please fork the GitHub repository.

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Miles Gould

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

Perl modules for rolling dice: Games::Dice, Games::Dice::Advanced, Bot::BasicBot::Pluggable::Module::Dice, random.

A Perl module for calculating probability distributions for dice rolls: Games::Dice::Probability.

Descriptions of the alias method:

Michael Vose, A Linear Algorithm For Generating Random Numbers with a Given Distribution

Keith Schwarz, Darts, Dice, and Coins: Sampling from a Discrete Distribution

Data structure for loaded dice? on StackOverflow

Wikipedia article