NAME

Games::Dice::Probability - Perl extension for calculating dice probabilities and distributions.

SYNOPSIS

    use Games::Dice::Probability;

    $diceobj = Games::Dice::Probability->new("3d6");

    ($minval, $maxval) = $diceobj->bounds();
    $minval = $diceobj->min();
    $maxval = $diceobj->max();
    $tvcombs = $diceobj->combinations($targetvalue);
    $totalcombs = $diceobj->combinations();
    $prob = $diceobj->probability();
    $tvprob = $diceobj->probability($targetvalue);
    $dist = $diceobj->distribution();

    # table of value - combinations / total combinations
    foreach $value ($minval..$maxval) {
        print $value . " - " . $$dist{$value} . " / " . $$prob{$value} . "\n";
    }

DESCRIPTION

Games::Dice::Probability calculates probabilities and distributions for complex dice expressions. The expression provided when creating a new object is parsed, and each node's combinations distribution is computed and then combined appropriately to create the combinations distribution for the full expression.

Dice expressions are in the form of nDs or MIDs, where n is the number of dice and s is the number of faces on each die. D is the simple-sum dice method, the one most commonly used, where n dice of s faces each are rolled and a sum is taken of the outcomes. MID is the middle-value dice method, where three dice are rolled, and the value in the middle is taken as the result.

For example, a single six-sided die is notated as:

    1d6

Two such dice would be:

    2d6

Middle dice would be:

    mid6

or:

    mid20

And so on. Complex dice expressions can include modifiers (addition, subtraction, multiplication, division), and order of precedence brackets, such as:

    (2d6+4) + 2d6

or:

    (3d6/2) * 2d4

or:

    mid20 + (mid6+1)

When the object is created, the full distribution is calculated using as many shortcuts and optimizations as possible. These include reducing logic based on certain values of n, only calculating half of any standard distribution, and using an identity to create the other "mirrored" half of the distribution. Also, large-number math is reduced by using formulae that reduce the calculations to much smaller numbers, including the very efficient binomial coefficient method in Math::Symbolic::AuxFunctions. Lastly, each node's distribution calculation and multi-node combined distribution calculation can be Memoized, negating nearly all compute cycles for future identical calculations. All of these combined create a very sleek and fast method of calculating dice distributions.

Memoization for calculations can be disabled at the time you declare use of this module by passing an argument:

    use Games::Dice::Probability q/ nomemoize /;

The argument is recognized by 'no' or 'un' prefixed to 'memo' or 'memoize.' Memoization is strongly encouraged when using this module for multiple calculations or long-term scripts; the savings in compute cycles are vast.

Future support for BigInt is being considered, to allow for even larger values in the complex dice expressions.

EXPORT

None. This is intentional. In fact, there is a faux import() call used to optionally turn Memoize off, so exporting anything will not be successful.

SEE ALSO

Requires Math::Symbolic::AuxFunctions for the use of binomial_coeff().

Requires Parse::RecDescent to parse dice expressions.

Optionally uses Debug::ShowStuff to descend and display hashes in the object.

Optionally uses Memoize to speed up calculations of identical nodes in a dice expression tree. Use of memoization, though automatic, can be disabled when using this module.

Up to date information on this module can be obtained from its webpage:

    http://oddgeek.info/code/gdp/

AUTHOR

Jason A. Dour, <jad@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Jason A. Dour

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

cpanm Games::Dice::Probability

perl -MCPAN -e shell
install Games::Dice::Probability