dyce provides two core primitives for enumeration1.
1
>>>fromdyceimportH,P
H objects represent histograms for modeling discrete outcomes.
They encode finite discrete probability distributions as integer counts without any denominator.
P objects represent pools (ordered sequences) of histograms.
If all you need is to aggregate outcomes (sums) from rolling a bunch of dice (or perform calculations on aggregate outcomes), H objects are probably sufficient.
If you need to select certain histograms from a group prior to computing aggregate outcomes (e.g., taking the highest and lowest of each possible roll of n dice), that’s where P objects come in.
As a wise person whose name has been lost to history once said: “Language is imperfect. If at all possible, shut up and point.”
So with that illuminating (or perhaps impenetrable) introduction out of the way, let’s dive into some examples!
Basic examples
A six-sided die can be modeled as:
12
>>>H(6)H(6)
H(n) is shorthand for explicitly enumerating outcomes \([{ {1} .. {n} }]\), each with a frequency of 1.
12
>>>H(6)==H({1:1,2:1,3:1,4:1,5:1,6:1})True
Tuples with repeating outcomes are accumulated.
A six-sided “2, 3, 3, 4, 4, 5” die can be modeled as:
12
>>>H((2,3,3,4,4,5))H({2:1,3:2,4:2,5:1})
A fudge die can be modeled as:
12
>>>H((-1,0,1))H({-1:1,0:1,1:1})
Python’s matrix multiplication operator (@) is used to express the number of a particular die (roughly equivalent to the “d” operator in common notations). The outcomes of rolling two six-sided dice (2d6) are:
Where n is an integer, P(n,...) is shorthand for P(H(n),...).
Python’s matrix multiplication operator (@) can also be used with pools.
The above can be expressed more succinctly.
12
>>>2@P(6)P(6,6)
Pools (in this case, Sicherman dice) can be compared to histograms.
Histograms should be sufficient for most calculations.
However, pools are useful for “taking” (selecting) only some of each roll’s outcomes.
This is done by providing one or more index arguments to the P.h method or the P.rolls_with_counts method.
Indexes can be integers, slices, or a mix thereof.
Outcome indexes are ordered from least to greatest with negative values counting from the right, as one would expect (i.e., [0], [1], …, [-2], [-1]).
Summing the least two faces when rolling three six-sided dice would be:
1234
>>>3@P(6)P(6,6,6)>>>(3@P(6)).h(0,1)# see warning below about parenthesesH({2:16,3:27,4:34,5:36,6:34,7:27,8:19,9:12,10:7,11:3,12:1})
Mind your parentheses
Parentheses are needed in the above example because @ has a lower precedence than . and […].
123456
>>>2@P(6).h(1)# equivalent to 2@(P(6).h(1))Traceback(mostrecentcalllast):...IndexError:tupleindexoutofrange>>>(2@P(6)).h(1)H({1:1,2:3,3:5,4:7,5:9,6:11})
Taking the least, middle, or greatest face when rolling three six-sided dice would be:
>>>d10=H(10)-1;d10# a common “d10” with faces [0 .. 9]H({0:1,1:1,2:1,3:1,4:1,5:1,6:1,7:1,8:1,9:1})>>>h=P(4,6,8,d10,12,20).h(0,-1)>>>print(h.format(scaled=True))avg|13.48std|4.40var|19.391|0.00%|2|0.01%|3|0.06%|4|0.30%|#5|0.92%|#####6|2.03%|###########7|3.76%|####################8|5.57%|##############################9|7.78%|###########################################10|8.99%|##################################################11|8.47%|###############################################12|8.64%|################################################13|8.66%|################################################14|6.64%|####################################15|5.62%|###############################16|5.16%|############################17|5.00%|###########################18|5.00%|###########################19|5.00%|###########################20|5.00%|###########################21|4.50%|#########################22|2.01%|###########23|0.73%|####24|0.18%|
Both histograms and pools support various comparison operations as well as substitution.
The odds of observing all even faces when rolling \(n\) six-sided dice, for \(n\) in \([1..6]\) is:
The odds of scoring at least one nine or higher on any single die when rolling \(n\) “exploding” six-sided dice, for \(n\) in \([1..10]\) is:
1 2 3 4 5 6 7 8 91011121314151617
>>># By the time we're rolling a third die, we're guaranteed a nine or higher, so we only need to look that far>>>exploding_d6=H(6).explode(max_depth=2)>>>forninrange(10,0,-1):...d6e_ge_9=exploding_d6.ge(9)...number_of_nines_or_higher_in_nd6e=n@d6e_ge_9...at_least_one_9=number_of_nines_or_higher_in_nd6e.ge(1)...print(f"{n: >2}d6-exploding: {at_least_one_9[1]/sum(at_least_one_9.counts()): >6.2%}")10d6-exploding:69.21%9d6-exploding:65.36%8d6-exploding:61.03%7d6-exploding:56.15%6d6-exploding:50.67%5d6-exploding:44.51%4d6-exploding:37.57%3d6-exploding:29.77%2d6-exploding:20.99%1d6-exploding:11.11%
Dependent probabilities
Where we can identify independent terms and reduce the dependent term to a calculation solely involving independent terms, dependent probabilities can often be compactly expressed via H.substitute,H.foreach, or P.foreach.
First, we express independent terms as histograms or pools.
Second, we express the dependent term as a callback function.
Finally, we can pass the dependent callback function to H.substitute, H.foreach, or P.foreach, along with the independent terms (as arguments in the cases of the latter two).
H.substitute is well suited to situations with a single independent term that can be expressed as a histogram.
Say we want to roll a d6 and compare whether the result is strictly greater than its distance from some constant.
Instead of a constant, let’s use another die as a second independent term.
We’ll roll a d4 and a d6 and compare whether the d6 is strictly greater than the absolute difference between dice.
For multiple independent terms that can be expressed as histograms, the H.foreach class method is often easiest.
1 2 3 4 5 6 7 8 910111213
>>>d4=H(4)# first independent term>>>d6=H(6)# second independent term>>>defoutcome_vs_difference_dependent_term(d4_outcome,d6_outcome):...returnd6_outcome>abs(d4_outcome-d6_outcome)# dependent term>>>h=H.foreach(outcome_vs_difference_dependent_term,d4_outcome=d4,d6_outcome=d6)>>>print(h.format())avg|0.83std|0.37var|0.140|16.67%|########1|83.33%|#########################################
In the alternative, one could nest substitution functions, where the innermost holds the dependent term, and the outer functions each establish the scope of their respective independent outcomes.
However, this isn’t very readable, and is often less efficient than using H.foreach class method.
Where the dependent term requires inspection of rolls from one or more pools as independent terms, P.foreach class method is useful.
Let’s say we have two pools.
A roll from the first pool wins if it shows no duplicates but a roll from the second does.
A roll from the second pool wins if it shows no duplicates but a roll from the first does.
Otherwise, it’s a tie (i.e., if neither or both rolls show duplicates).
Let’s compare how three six-sided dice fair against two four-sided dice.
1 2 3 4 5 6 7 8 9101112131415161718192021
>>>fromenumimportIntEnum>>>classDupeVs(IntEnum):...SECOND_WINS=-1# where second_roll shows no duplicates, but first_roll does...TIE=0# where both rolls show no duplicates or rolls pools have duplicates...FIRST_WINS=1# where first_roll shows no duplicates, but second_roll does>>>defcompare_fours(first_roll,second_roll):...returnDupeVs((len(set(first_roll))==len(first_roll))-(len(set(second_roll))==len(second_roll)))>>>h=P.foreach(compare_fours,first_roll=P(6,6,6),second_roll=P(4,4));hH({<DupeVs.SECOND_WINS:-1>:12,<DupeVs.TIE:0>:19,<DupeVs.FIRST_WINS:1>:5})>>>print(h.format())avg|-0.19std|0.66var|0.43-1|33.33%|################0|52.78%|##########################1|13.89%|######
Visualization
H objects provide a distribution method and a distribution_xy method to ease integration with plotting packages like matplotlib.
In addition, anydyce provides additional visualization and interactivity conveniences.
(Many of the figures in these docs leverage anydyce in their construction.)
# ======================================================================================# Copyright and other protections apply. Please see the accompanying LICENSE file for# rights and restrictions governing use of this software. All rights not expressly# waived or licensed are reserved. If that file is missing or appears to be modified# from its original, then please contact the author before viewing or using this# software in any capacity.# ======================================================================================from__future__importannotationsfromanydyce.vizimportplot_barfromdyceimportHdefdo_it(style:str)->None:importmatplotlib.pyplotax=matplotlib.pyplot.axes()text_color="white"ifstyle=="dark"else"black"ax.tick_params(axis="x",colors=text_color)ax.tick_params(axis="y",colors=text_color)plot_bar(ax,[("",3@H(6))])ax.set_title("Distribution for 3d6",color=text_color)
Time to get meta-evil on those outcomes!
Thanks to numerary, dyce offers best-effort support for arbitrary number-like outcomes, including primitives from symbolic expression packages such as SymPy.
Be aware that, depending on implementation, performance can suffer quite a bit when using symbolic primitives.
For histograms and pools, dyce remains opinionated about ordering.
For non-critical contexts where relative values are indeterminate, dyce will attempt a “natural” ordering based on the string representation of each outcome.
This is to accommodate symbolic expressions whose relative values are often unknowable.
SymPy does not even attempt simple relative comparisons between symbolic expressions, even where they are unambiguously resolvable.
Instead, it relies on the caller to invoke its proprietary solver APIs.
dyce, of course, is happily ignorant of all that keenness.
(As it should be.)
In practice, that means that certain operations won’t work with symbolic expressions where correctness depends on ordering outcomes according to relative value (e.g., dice selection from pools).
Anywhere you see a Binder logo , you can click on it to immediately start tinkering with a temporal instance of that example using anydyce.
Just be aware that Binder will eventually delete any changes, so make sure to download any notebooks you want to preserve.
dyce also provides additional primitives (R objects and their kin) which are useful for producing weighted randomized rolls without the overhead of enumeration.
These are covered seperately. ↩