Glossary
Outcome
A possible result represented in a calculation.
1 is one of the outcomes of rolling a six-sided die (d6).
Count
A nonnegative integer assigned to an outcome indicating its weight relative to other outcomes. A count can represent the number of ways an outcome occurs. Reducing counts to their lowest terms can change a count’s value without changing its probability or relative weight.
Histogram (dyce.H)
A dyce.H object is an immutable map of outcomes to counts.
Pool (dyce.P)
A dyce.P object is an immutable sorted sequence of H objects.
[\(m\)]d\(n\) (e.g. d6, 2d20)
d\(n\) is shorthand for a histogram modeling a fair die having \(n\) faces whose outcomes are numbered \([{ {1} .. {n} }]\).
\(m\)d\(n\) is shorthand for a either the sum of \(m\) such histograms or a pool of \(m\) such histograms, depending on the context.
The convention is to disambiguate with a variable prefix (e.g., h2d20 is a histogram, whereas p2d20 is a pool).
Probability distribution
A probability distribution (sometimes shortened to “distribution”) assigns a probability to each possible outcome in a histogram.
H.probability_items yields outcome and probability pairs, using fractions by default to represent exact probabilities.
For outcomes with positive counts, each specific outcome’s probability is its count divided by H.total.
Outcomes with zero counts have probabilities of zero.
Roll
A tuple of outcomes from a P, sorted from least to greatest.
Outcomes that cannot be compared are sorted by the natural order of their string representations.
Roll order is independent of pool order.
An outcome’s position in a roll does not identify the histogram that produced that outcome.
Outcome selection
The choice of outcomes by their positions in a sorted roll.
P.at sums selected outcomes into a histogram.
P.rolls_with_counts yields selected rolls and their counts.
This is distinct from indexing or slicing a pool, which selects histograms from that pool, not outcomes from rolls.
Sample
Outcomes selected at random based on their counts (relative weights).
H.sample returns a single outcome.
P.sample returns a roll.
Lowest terms
Histogram counts with their greatest common divisor reduced to one.
H.lowest_terms divides positive counts by their greatest common divisor, preserving probabilities exactly.
It removes outcomes with zero counts unless preserve_zero_counts=True.
Quantization
A reduction of histogram counts to fit within a specified bit width, approximating their relative weights.
This reduction is lossy and can change probabilities or reduce positive counts to zero.
See the experimental H.quantize_counts method.
Path probability
The probability of reaching a branch in (possibly recursive) expand calls.
The min_path_probability parameter sets the threshold below which a branch is discarded.
Truncation
The removal of branches from an expand calculation because their path probability is below a threshold or they exceed Python’s recursion limit.
TruncationWarning reports this removal.
The resulting probabilities describe the remaining outcomes.
Returning an empty histogram from the callback intentionally excludes a branch and does not, by itself, cause a truncation warning.
Experimental
An API whose interface may change or which may be removed in a future release. Experimental APIs are marked in the API reference.
Deprecated
An API retained for compatibility whose use is discouraged. Consult its deprecation notice for replacement and removal guidance.