view release on metacpan or  search on metacpan

lib/Games/Dice/Probability.pm  view on Meta::CPAN

    ($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";
    }

=head1 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.

=head1 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.

=head1 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/

=head1 AUTHOR

Jason A. Dour, E<lt>jad@cpan.orgE<gt>

=head1 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.

=cut