icepool

18@cache
19def d(sides: int, /) -> 'icepool.Die[int]':
20    """A standard die, uniformly distributed from `1` to `sides` inclusive.
21
22    Don't confuse this with `icepool.Die()`:
23
24    * `icepool.Die([6])`: A `Die` that always rolls the integer 6.
25    * `icepool.d(6)`: A d6.
26
27    You can also import individual standard dice from the `icepool` module, e.g.
28    `from icepool import d6`.
29    """
30    if not isinstance(sides, int):
31        raise TypeError('sides must be an int.')
32    elif sides < 1:
33        raise ValueError('sides must be at least 1.')
34    return icepool.Die(range(1, sides + 1))

37@cache
38def z(sides: int, /) -> 'icepool.Die[int]':
39    """A die uniformly distributed from `0` to `sides - 1` inclusive.
40    
41    Equal to d(sides) - 1.
42    """
43    if not isinstance(sides, int):
44        raise TypeError('sides must be an int.')
45    elif sides < 1:
46        raise ValueError('sides must be at least 1.')
47    return icepool.Die(range(0, sides))

 73def coin(n: int | float | Fraction,
 74         d: int = 1,
 75         /,
 76         *,
 77         max_denominator: int | None = None) -> 'icepool.Die[bool]':
 78    """A `Die` that rolls `True` with probability `n / d`, and `False` otherwise.
 79
 80    If `n <= 0` or `n >= d` the result will have only one outcome.
 81
 82    Args:
 83        n: An int numerator, or a non-integer probability.
 84        d: An int denominator. Should not be provided if the first argument is
 85            not an int.
 86    """
 87    if not isinstance(n, int):
 88        if d != 1:
 89            raise ValueError(
 90                'If a non-int numerator is provided, a denominator must not be provided.'
 91            )
 92        fraction = Fraction(n)
 93        if max_denominator is not None:
 94            fraction = fraction.limit_denominator(max_denominator)
 95        n = fraction.numerator
 96        d = fraction.denominator
 97    data = {}
 98    if n < d:
 99        data[False] = min(d - n, d)
100    if n > 0:
101        data[True] = min(n, d)
102
103    return icepool.Die(data)

106def stochastic_round(x,
107                     /,
108                     *,
109                     max_denominator: int | None = None) -> 'icepool.Die[int]':
110    """Randomly rounds a value up or down to the nearest integer according to the two distances.
111        
112    Specificially, rounds `x` up with probability `x - floor(x)` and down
113    otherwise, producing a `Die` with up to two outcomes.
114
115    Args:
116        max_denominator: If provided, each rounding will be performed
117            using `fractions.Fraction.limit_denominator(max_denominator)`.
118            Otherwise, the rounding will be performed without
119            `limit_denominator`.
120    """
121    integer_part = math.floor(x)
122    fractional_part = x - integer_part
123    return integer_part + coin(fractional_part,
124                               max_denominator=max_denominator)

127def one_hot(sides: int, /) -> 'icepool.Die[tuple[bool, ...]]':
128    """A `Die` with `Vector` outcomes with one element set to `True` uniformly at random and the rest `False`.
129
130    This is an easy (if somewhat expensive) way of representing how many dice
131    in a pool rolled each number. For example, the outcomes of `10 @ one_hot(6)`
132    are the `(ones, twos, threes, fours, fives, sixes)` rolled in 10d6.
133    """
134    data = []
135    for i in range(sides):
136        outcome = [False] * sides
137        outcome[i] = True
138        data.append(icepool.Vector(outcome))
139    return icepool.Die(data)

44class Outcome(Hashable, Protocol[T_contra]):
45    """Protocol to attempt to verify that outcome types are hashable and sortable.
46
47    Far from foolproof, e.g. it cannot enforce total ordering.
48    """
49
50    def __lt__(self, other: T_contra) -> bool:
51        ...

  44class Die(Population[T_co], MaybeHashKeyed):
  45    """Sampling with replacement. Quantities represent weights.
  46
  47    Dice are immutable. Methods do not modify the `Die` in-place;
  48    rather they return a `Die` representing the result.
  49
  50    It's also possible to have "empty" dice with no outcomes at all,
  51    though these have little use other than being sentinel values.
  52    """
  53
  54    _data: Counts[T_co]
  55
  56    @property
  57    def _new_type(self) -> type:
  58        return Die
  59
  60    def __new__(
  61        cls,
  62        outcomes: Sequence | Mapping[Any, int],
  63        times: Sequence[int] | int = 1,
  64        *,
  65        again_count: int | None = None,
  66        again_depth: int | None = None,
  67        again_end: 'T_co | Die[T_co] | icepool.RerollType | None' = None
  68    ) -> 'Die[T_co]':
  69        """Constructor for a `Die`.
  70
  71        Don't confuse this with `d()`:
  72
  73        * `Die([6])`: A `Die` that always rolls the `int` 6.
  74        * `d(6)`: A d6.
  75
  76        Also, don't confuse this with `Pool()`:
  77
  78        * `Die([1, 2, 3, 4, 5, 6])`: A d6.
  79        * `Pool([1, 2, 3, 4, 5, 6])`: A `Pool` of six dice that always rolls one
  80            of each number.
  81
  82        Here are some different ways of constructing a d6:
  83
  84        * Just import it: `from icepool import d6`
  85        * Use the `d()` function: `icepool.d(6)`
  86        * Use a d6 that you already have: `Die(d6)` or `Die([d6])`
  87        * Mix a d3 and a d3+3: `Die([d3, d3+3])`
  88        * Use a dict: `Die({1:1, 2:1, 3:1, 4:1, 5:1, 6:1})`
  89        * Give the faces as a sequence: `Die([1, 2, 3, 4, 5, 6])`
  90
  91        All quantities must be non-negative. Outcomes with zero quantity will be
  92        omitted.
  93
  94        Several methods and functions foward **kwargs to this constructor.
  95        However, these only affect the construction of the returned or yielded
  96        dice. Any other implicit conversions of arguments or operands to dice
  97        will be done with the default keyword arguments.
  98
  99        EXPERIMENTAL: Use `icepool.Again` to roll the dice again, usually with
 100        some modification. See the `Again` documentation for details.
 101
 102        Denominator: For a flat set of outcomes, the denominator is just the
 103        sum of the corresponding quantities. If the outcomes themselves have
 104        secondary denominators, then the overall denominator will be minimized
 105        while preserving the relative weighting of the primary outcomes.
 106
 107        Args:
 108            outcomes: The faces of the `Die`. This can be one of the following:
 109                * A `Sequence` of outcomes. Duplicates will contribute
 110                    quantity for each appearance.
 111                * A `Mapping` from outcomes to quantities.
 112
 113                Individual outcomes can each be one of the following:
 114
 115                * An outcome, which must be hashable and totally orderable.
 116                    * For convenience, `tuple`s containing `Population`s will be
 117                        `tupleize`d into a `Population` of `tuple`s.
 118                        This does not apply to subclasses of `tuple`s such as `namedtuple`
 119                        or other classes such as `Vector`.
 120                * A `Die`, which will be flattened into the result.
 121                    The quantity assigned to a `Die` is shared among its
 122                    outcomes. The total denominator will be scaled up if
 123                    necessary.
 124                * `icepool.Reroll`, which will drop itself from consideration.
 125                * EXPERIMENTAL: `icepool.Again`. See the documentation for
 126                    `Again` for details.
 127            times: Multiplies the quantity of each element of `outcomes`.
 128                `times` can either be a sequence of the same length as
 129                `outcomes` or a single `int` to apply to all elements of
 130                `outcomes`.
 131            again_count, again_depth, again_end: These affect how `Again`
 132                expressions are handled. See the `Again` documentation for
 133                details.
 134        Raises:
 135            ValueError: `None` is not a valid outcome for a `Die`.
 136        """
 137        outcomes, times = icepool.creation_args.itemize(outcomes, times)
 138
 139        # Check for Again.
 140        if icepool.population.again.contains_again(outcomes):
 141            if again_count is not None:
 142                if again_depth is not None:
 143                    raise ValueError(
 144                        'At most one of again_count and again_depth may be used.'
 145                    )
 146                return icepool.population.again.evaluate_agains_using_count(
 147                    outcomes, times, again_count, again_end)
 148            else:
 149                if again_depth is None:
 150                    again_depth = 1
 151                return icepool.population.again.evaluate_agains_using_depth(
 152                    outcomes, times, again_depth, again_end)
 153
 154        # Agains have been replaced by this point.
 155        outcomes = cast(Sequence[T_co | Die[T_co] | icepool.RerollType],
 156                        outcomes)
 157
 158        if len(outcomes) == 1 and times[0] == 1 and isinstance(
 159                outcomes[0], Die):
 160            return outcomes[0]
 161
 162        counts: Counts[T_co] = icepool.creation_args.expand_args_for_die(
 163            outcomes, times)
 164
 165        return Die._new_raw(counts)
 166
 167    @classmethod
 168    def _new_raw(cls, data: Counts[T_co]) -> 'Die[T_co]':
 169        """Creates a new `Die` using already-processed arguments.
 170
 171        Args:
 172            data: At this point, this is a Counts.
 173        """
 174        self = super(Population, cls).__new__(cls)
 175        self._data = data
 176        return self
 177
 178    # Defined separately from the superclass to help typing.
 179    def unary_operator(self: 'icepool.Die[T_co]', op: Callable[..., U], *args,
 180                       **kwargs) -> 'icepool.Die[U]':
 181        """Performs the unary operation on the outcomes.
 182
 183        This is used for the standard unary operators
 184        `-, +, abs, ~, round, trunc, floor, ceil`
 185        as well as the additional methods
 186        `zero, bool`.
 187
 188        This is NOT used for the `[]` operator; when used directly, this is
 189        interpreted as a `Mapping` operation and returns the count corresponding
 190        to a given outcome. See `marginals()` for applying the `[]` operator to
 191        outcomes.
 192
 193        Returns:
 194            A `Die` representing the result.
 195
 196        Raises:
 197            ValueError: If tuples are of mismatched length.
 198        """
 199        return self._unary_operator(op, *args, **kwargs)
 200
 201    def binary_operator(self, other: 'Die', op: Callable[..., U], *args,
 202                        **kwargs) -> 'Die[U]':
 203        """Performs the operation on pairs of outcomes.
 204
 205        By the time this is called, the other operand has already been
 206        converted to a `Die`.
 207
 208        This is used for the standard binary operators
 209        `+, -, *, /, //, %, **, <<, >>, &, |, ^`
 210        and the standard binary comparators
 211        `<, <=, >=, >, ==, !=, cmp`.
 212
 213        `==` and `!=` additionally set the truth value of the `Die` according to
 214        whether the dice themselves are the same or not.
 215
 216        The `@` operator does NOT use this method directly.
 217        It rolls the left `Die`, which must have integer outcomes,
 218        then rolls the right `Die` that many times and sums the outcomes.
 219
 220        Returns:
 221            A `Die` representing the result.
 222
 223        Raises:
 224            ValueError: If tuples are of mismatched length within one of the
 225                dice or between the dice.
 226        """
 227        data: MutableMapping[Any, int] = defaultdict(int)
 228        for (outcome_self,
 229             quantity_self), (outcome_other,
 230                              quantity_other) in itertools.product(
 231                                  self.items(), other.items()):
 232            new_outcome = op(outcome_self, outcome_other, *args, **kwargs)
 233            data[new_outcome] += quantity_self * quantity_other
 234        return self._new_type(data)
 235
 236    # Basic access.
 237
 238    def keys(self) -> CountsKeysView[T_co]:
 239        return self._data.keys()
 240
 241    def values(self) -> CountsValuesView:
 242        return self._data.values()
 243
 244    def items(self) -> CountsItemsView[T_co]:
 245        return self._data.items()
 246
 247    def __getitem__(self, outcome, /) -> int:
 248        return self._data[outcome]
 249
 250    def __iter__(self) -> Iterator[T_co]:
 251        return iter(self.keys())
 252
 253    def __len__(self) -> int:
 254        """The number of outcomes. """
 255        return len(self._data)
 256
 257    def __contains__(self, outcome) -> bool:
 258        return outcome in self._data
 259
 260    # Quantity management.
 261
 262    def simplify(self) -> 'Die[T_co]':
 263        """Divides all quantities by their greatest common denominator. """
 264        return icepool.Die(self._data.simplify())
 265
 266    # Rerolls and other outcome management.
 267
 268    def reroll(self,
 269               outcomes: Callable[..., bool] | Collection[T_co] | None = None,
 270               /,
 271               *,
 272               star: bool | None = None,
 273               depth: int | Literal['inf']) -> 'Die[T_co]':
 274        """Rerolls the given outcomes.
 275
 276        Args:
 277            outcomes: Selects which outcomes to reroll. Options:
 278                * A collection of outcomes to reroll.
 279                * A callable that takes an outcome and returns `True` if it
 280                    should be rerolled.
 281                * If not provided, the min outcome will be rerolled.
 282            star: Whether outcomes should be unpacked into separate arguments
 283                before sending them to a callable `which`.
 284                If not provided, this will be guessed based on the function
 285                signature.
 286            depth: The maximum number of times to reroll.
 287                If `None`, rerolls an unlimited number of times.
 288
 289        Returns:
 290            A `Die` representing the reroll.
 291            If the reroll would never terminate, the result has no outcomes.
 292        """
 293
 294        if outcomes is None:
 295            outcome_set = {self.min_outcome()}
 296        else:
 297            outcome_set = self._select_outcomes(outcomes, star)
 298
 299        if depth == 'inf':
 300            data = {
 301                outcome: quantity
 302                for outcome, quantity in self.items()
 303                if outcome not in outcome_set
 304            }
 305        elif depth < 0:
 306            raise ValueError('reroll depth cannot be negative.')
 307        else:
 308            total_reroll_quantity = sum(quantity
 309                                        for outcome, quantity in self.items()
 310                                        if outcome in outcome_set)
 311            total_stop_quantity = self.denominator() - total_reroll_quantity
 312            rerollable_factor = total_reroll_quantity**depth
 313            stop_factor = (self.denominator()**(depth + 1) - rerollable_factor
 314                           * total_reroll_quantity) // total_stop_quantity
 315            data = {
 316                outcome: (rerollable_factor *
 317                          quantity if outcome in outcome_set else stop_factor *
 318                          quantity)
 319                for outcome, quantity in self.items()
 320            }
 321        return icepool.Die(data)
 322
 323    def filter(self,
 324               outcomes: Callable[..., bool] | Collection[T_co],
 325               /,
 326               *,
 327               star: bool | None = None,
 328               depth: int | Literal['inf']) -> 'Die[T_co]':
 329        """Rerolls until getting one of the given outcomes.
 330
 331        Essentially the complement of `reroll()`.
 332
 333        Args:
 334            outcomes: Selects which outcomes to reroll until. Options:
 335                * A callable that takes an outcome and returns `True` if it
 336                    should be accepted.
 337                * A collection of outcomes to reroll until.
 338            star: Whether outcomes should be unpacked into separate arguments
 339                before sending them to a callable `which`.
 340                If not provided, this will be guessed based on the function
 341                signature.
 342            depth: The maximum number of times to reroll.
 343                If `None`, rerolls an unlimited number of times.
 344
 345        Returns:
 346            A `Die` representing the reroll.
 347            If the reroll would never terminate, the result has no outcomes.
 348        """
 349
 350        if callable(outcomes):
 351            if star is None:
 352                star = infer_star(outcomes)
 353            if star:
 354
 355                not_outcomes = {
 356                    outcome
 357                    for outcome in self.outcomes()
 358                    if not outcomes(*outcome)  # type: ignore
 359                }
 360            else:
 361                not_outcomes = {
 362                    outcome
 363                    for outcome in self.outcomes() if not outcomes(outcome)
 364                }
 365        else:
 366            not_outcomes = {
 367                not_outcome
 368                for not_outcome in self.outcomes()
 369                if not_outcome not in outcomes
 370            }
 371        return self.reroll(not_outcomes, depth=depth)
 372
 373    def truncate(self, min_outcome=None, max_outcome=None) -> 'Die[T_co]':
 374        """Truncates the outcomes of this `Die` to the given range.
 375
 376        The endpoints are included in the result if applicable.
 377        If one of the arguments is not provided, that side will not be truncated.
 378
 379        This effectively rerolls outcomes outside the given range.
 380        If instead you want to replace those outcomes with the nearest endpoint,
 381        use `clip()`.
 382
 383        Not to be confused with `trunc(die)`, which performs integer truncation
 384        on each outcome.
 385        """
 386        if min_outcome is not None:
 387            start = bisect.bisect_left(self.outcomes(), min_outcome)
 388        else:
 389            start = None
 390        if max_outcome is not None:
 391            stop = bisect.bisect_right(self.outcomes(), max_outcome)
 392        else:
 393            stop = None
 394        data = {k: v for k, v in self.items()[start:stop]}
 395        return icepool.Die(data)
 396
 397    def clip(self, min_outcome=None, max_outcome=None) -> 'Die[T_co]':
 398        """Clips the outcomes of this `Die` to the given values.
 399
 400        The endpoints are included in the result if applicable.
 401        If one of the arguments is not provided, that side will not be clipped.
 402
 403        This is not the same as rerolling outcomes beyond this range;
 404        the outcome is simply adjusted to fit within the range.
 405        This will typically cause some quantity to bunch up at the endpoint(s).
 406        If you want to reroll outcomes beyond this range, use `truncate()`.
 407        """
 408        data: MutableMapping[Any, int] = defaultdict(int)
 409        for outcome, quantity in self.items():
 410            if min_outcome is not None and outcome <= min_outcome:
 411                data[min_outcome] += quantity
 412            elif max_outcome is not None and outcome >= max_outcome:
 413                data[max_outcome] += quantity
 414            else:
 415                data[outcome] += quantity
 416        return icepool.Die(data)
 417
 418    @cached_property
 419    def _popped_min(self) -> tuple['Die[T_co]', int]:
 420        die = Die._new_raw(self._data.remove_min())
 421        return die, self.quantities()[0]
 422
 423    def _pop_min(self) -> tuple['Die[T_co]', int]:
 424        """A `Die` with the min outcome removed, and the quantity of the removed outcome.
 425
 426        Raises:
 427            IndexError: If this `Die` has no outcome to pop.
 428        """
 429        return self._popped_min
 430
 431    @cached_property
 432    def _popped_max(self) -> tuple['Die[T_co]', int]:
 433        die = Die._new_raw(self._data.remove_max())
 434        return die, self.quantities()[-1]
 435
 436    def _pop_max(self) -> tuple['Die[T_co]', int]:
 437        """A `Die` with the max outcome removed, and the quantity of the removed outcome.
 438
 439        Raises:
 440            IndexError: If this `Die` has no outcome to pop.
 441        """
 442        return self._popped_max
 443
 444    # Processes.
 445    @overload
 446    def map(
 447            self,
 448            repl:
 449        'Callable[..., U | Die[U] | icepool.RerollType | icepool.AgainExpression] | Mapping[T_co, U | Die[U] | icepool.RerollType | icepool.AgainExpression]',
 450            /,
 451            *extra_args,
 452            star: bool | None = None,
 453            repeat: None = None,
 454            again_count: int | None = None,
 455            again_depth: int | None = None,
 456            again_end: 'U | Die[U] | icepool.RerollType | None' = None,
 457            **kwargs) -> 'Die[U]':
 458        ...
 459
 460    @overload
 461    def map(
 462            self,
 463            repl:
 464        'Callable[..., T_co | Die[T_co] | icepool.RerollType | icepool.AgainExpression] | Mapping[T_co, T_co | Die[T_co] | icepool.RerollType | icepool.AgainExpression]',
 465            /,
 466            *extra_args,
 467            star: bool | None = None,
 468            repeat: int | Literal['inf'],
 469            **kwargs) -> 'Die[T_co]':
 470        ...
 471
 472    def map(
 473            self,
 474            repl:
 475        'Callable[..., U | Die[U] | icepool.RerollType | icepool.AgainExpression] | Mapping[T_co, U | Die[U] | icepool.RerollType | icepool.AgainExpression]',
 476            /,
 477            *extra_args,
 478            star: bool | None = None,
 479            repeat: int | Literal['inf'] | None = None,
 480            again_count: int | None = None,
 481            again_depth: int | None = None,
 482            again_end: 'U | Die[U] | icepool.RerollType | None' = None,
 483            **kwargs) -> 'Die[U]':
 484        """Maps outcomes of the `Die` to other outcomes.
 485
 486        This is also useful for representing processes.
 487
 488        As `icepool.map(repl, self, ...)`.
 489        """
 490        return icepool.map(
 491            repl,
 492            self,
 493            *extra_args,
 494            star=star,
 495            repeat=repeat,  # type:ignore
 496            again_count=again_count,
 497            again_depth=again_depth,
 498            again_end=again_end,
 499            **kwargs)  # type:ignore
 500
 501    def map_and_time(
 502            self,
 503            repl:
 504        'Callable[..., T_co | Die[T_co] | icepool.RerollType] | Mapping[T_co, T_co | Die[T_co] | icepool.RerollType]',
 505            /,
 506            *extra_args,
 507            star: bool | None = None,
 508            repeat: int,
 509            **kwargs) -> 'Die[tuple[T_co, int]]':
 510        """Repeatedly map outcomes of the state to other outcomes, while also
 511        counting timesteps.
 512
 513        This is useful for representing processes.
 514
 515        As `map_and_time(repl, self, ...)`.
 516        """
 517        return icepool.map_and_time(repl,
 518                                    self,
 519                                    *extra_args,
 520                                    star=star,
 521                                    repeat=repeat,
 522                                    **kwargs)
 523
 524    def mean_time_to_absorb(
 525            self,
 526            repl:
 527        'Callable[..., T_co | icepool.Die[T_co] | icepool.RerollType] | Mapping[Any, T_co | icepool.Die[T_co] | icepool.RerollType]',
 528            /,
 529            *extra_args,
 530            star: bool | None = None,
 531            **kwargs) -> Fraction:
 532        """EXPERIMENTAL: The mean time for the process to reach an absorbing state.
 533        
 534        As `mean_time_to_absorb(repl, self, ...)`.
 535        """
 536        return icepool.mean_time_to_absorb(repl,
 537                                           self,
 538                                           *extra_args,
 539                                           star=star,
 540                                           **kwargs)
 541
 542    def time_to_sum(self: 'Die[int]',
 543                    target: int,
 544                    /,
 545                    max_time: int | None = None,
 546                    dnf: 'int|icepool.RerollType|None' = None) -> 'Die[int]':
 547        """The number of rolls until the cumulative sum is greater or equal to the target.
 548        
 549        Args:
 550            target: The number to stop at once reached.
 551            max_time: The maximum number of rolls to run.
 552                If the sum is not reached, the outcome is determined by `dnf`.
 553            dnf: What time to assign in cases where the target was not reached
 554                in `max_time`. If not provided, this is set to `max_time`.
 555                `dnf=icepool.Reroll` will remove this case from the result,
 556                effectively rerolling it.
 557        """
 558        if target <= 0:
 559            return Die([0])
 560
 561        if max_time is None:
 562            if self.min_outcome() <= 0:
 563                raise ValueError(
 564                    'max_time must be provided if not all outcomes are positive.'
 565                )
 566            max_time = (target + self.min_outcome() - 1) // self.min_outcome()
 567
 568        if dnf is None:
 569            dnf = max_time
 570
 571        def step(total, roll):
 572            return min(total + roll, target)
 573
 574        result: 'Die[tuple[int, int]]' = Die([0]).map_and_time(step,
 575                                                               self,
 576                                                               repeat=max_time)
 577
 578        def get_time(total, time):
 579            if total < target:
 580                return dnf
 581            else:
 582                return time
 583
 584        return result.map(get_time)
 585
 586    @cached_property
 587    def _mean_time_to_sum_cache(self) -> list[Fraction]:
 588        return [Fraction(0)]
 589
 590    def mean_time_to_sum(self: 'Die[int]', target: int, /) -> Fraction:
 591        """The mean number of rolls until the cumulative sum is greater or equal to the target.
 592
 593        Args:
 594            target: The target sum.
 595
 596        Raises:
 597            ValueError: If `self` has negative outcomes.
 598            ZeroDivisionError: If `self.mean() == 0`.
 599        """
 600        target = max(target, 0)
 601
 602        if target < len(self._mean_time_to_sum_cache):
 603            return self._mean_time_to_sum_cache[target]
 604
 605        if self.min_outcome() < 0:
 606            raise ValueError(
 607                'mean_time_to_sum does not handle negative outcomes.')
 608        time_per_effect = Fraction(self.denominator(),
 609                                   self.denominator() - self.quantity(0))
 610
 611        for i in range(len(self._mean_time_to_sum_cache), target + 1):
 612            result = time_per_effect + self.reroll([
 613                0
 614            ], depth='inf').map(lambda x: self.mean_time_to_sum(i - x)).mean()
 615            self._mean_time_to_sum_cache.append(result)
 616
 617        return result
 618
 619    def explode(self,
 620                outcomes: Collection[T_co] | Callable[..., bool] | None = None,
 621                /,
 622                *,
 623                star: bool | None = None,
 624                depth: int = 9,
 625                end=None) -> 'Die[T_co]':
 626        """Causes outcomes to be rolled again and added to the total.
 627
 628        Args:
 629            outcomes: Which outcomes to explode. Options:
 630                * An collection of outcomes to explode.
 631                * A callable that takes an outcome and returns `True` if it
 632                    should be exploded.
 633                * If not supplied, the max outcome will explode.
 634            star: Whether outcomes should be unpacked into separate arguments
 635                before sending them to a callable `which`.
 636                If not provided, this will be guessed based on the function
 637                signature.
 638            depth: The maximum number of additional dice to roll, not counting
 639                the initial roll.
 640                If not supplied, a default value will be used.
 641            end: Once `depth` is reached, further explosions will be treated
 642                as this value. By default, a zero value will be used.
 643                `icepool.Reroll` will make one extra final roll, rerolling until
 644                a non-exploding outcome is reached.
 645        """
 646
 647        if outcomes is None:
 648            outcome_set = {self.max_outcome()}
 649        else:
 650            outcome_set = self._select_outcomes(outcomes, star)
 651
 652        if depth < 0:
 653            raise ValueError('depth cannot be negative.')
 654        elif depth == 0:
 655            return self
 656
 657        def map_final(outcome):
 658            if outcome in outcome_set:
 659                return outcome + icepool.Again
 660            else:
 661                return outcome
 662
 663        return self.map(map_final, again_depth=depth, again_end=end)
 664
 665    def if_else(
 666        self,
 667        outcome_if_true: U | 'Die[U]',
 668        outcome_if_false: U | 'Die[U]',
 669        *,
 670        again_count: int | None = None,
 671        again_depth: int | None = None,
 672        again_end: 'U | Die[U] | icepool.RerollType | None' = None
 673    ) -> 'Die[U]':
 674        """Ternary conditional operator.
 675
 676        This replaces truthy outcomes with the first argument and falsy outcomes
 677        with the second argument.
 678
 679        Args:
 680            again_count, again_depth, again_end: Forwarded to the final die constructor.
 681        """
 682        return self.map(lambda x: bool(x)).map(
 683            {
 684                True: outcome_if_true,
 685                False: outcome_if_false
 686            },
 687            again_count=again_count,
 688            again_depth=again_depth,
 689            again_end=again_end)
 690
 691    def is_in(self, outcomes: Container[T_co], /) -> 'Die[bool]':
 692        """A die that returns True iff the roll of the die is contained in the target."""
 693        return self.map(lambda x: x in outcomes)
 694
 695    def count(self, rolls: int, outcomes: Container[T_co], /) -> 'Die[int]':
 696        """Roll this dice a number of times and count how many are in the target."""
 697        return rolls @ self.is_in(outcomes)
 698
 699    # Pools and sums.
 700
 701    @cached_property
 702    def _sum_cache(self) -> MutableMapping[int, 'Die']:
 703        return {}
 704
 705    def _sum_all(self, rolls: int, /) -> 'Die':
 706        """Roll this `Die` `rolls` times and sum the results.
 707
 708        The sum is computed one at a time, with each additional item on the 
 709        right, similar to `functools.reduce()`.
 710
 711        If `rolls` is negative, roll the `Die` `abs(rolls)` times and negate
 712        the result.
 713
 714        If you instead want to replace tuple (or other sequence) outcomes with
 715        their sum, use `die.map(sum)`.
 716        """
 717        if rolls in self._sum_cache:
 718            return self._sum_cache[rolls]
 719
 720        if rolls < 0:
 721            result = -self._sum_all(-rolls)
 722        elif rolls == 0:
 723            result = self.zero().simplify()
 724        elif rolls == 1:
 725            result = self
 726        else:
 727            # In addition to working similar to reduce(), this seems to perform
 728            # better than binary split.
 729            result = self._sum_all(rolls - 1) + self
 730
 731        self._sum_cache[rolls] = result
 732        return result
 733
 734    def __matmul__(self: 'Die[int]', other) -> 'Die':
 735        """Roll the left `Die`, then roll the right `Die` that many times and sum the outcomes.
 736        
 737        The sum is computed one at a time, with each additional item on the 
 738        right, similar to `functools.reduce()`.
 739        """
 740        if isinstance(other, icepool.AgainExpression):
 741            return NotImplemented
 742        other = implicit_convert_to_die(other)
 743
 744        data: MutableMapping[int, Any] = defaultdict(int)
 745
 746        max_abs_die_count = max(abs(self.min_outcome()),
 747                                abs(self.max_outcome()))
 748        for die_count, die_count_quantity in self.items():
 749            factor = other.denominator()**(max_abs_die_count - abs(die_count))
 750            subresult = other._sum_all(die_count)
 751            for outcome, subresult_quantity in subresult.items():
 752                data[
 753                    outcome] += subresult_quantity * die_count_quantity * factor
 754
 755        return icepool.Die(data)
 756
 757    def __rmatmul__(self, other: 'int | Die[int]') -> 'Die':
 758        """Roll the left `Die`, then roll the right `Die` that many times and sum the outcomes.
 759        
 760        The sum is computed one at a time, with each additional item on the 
 761        right, similar to `functools.reduce()`.
 762        """
 763        if isinstance(other, icepool.AgainExpression):
 764            return NotImplemented
 765        other = implicit_convert_to_die(other)
 766        return other.__matmul__(self)
 767
 768    def sequence(self, rolls: int) -> 'icepool.Die[tuple[T_co, ...]]':
 769        """Possible sequences produced by rolling this die a number of times.
 770        
 771        This is extremely expensive computationally. If possible, use `reduce()`
 772        instead; if you don't care about order, `Die.pool()` is better.
 773        """
 774        return icepool.cartesian_product(*(self for _ in range(rolls)),
 775                                         outcome_type=tuple)  # type: ignore
 776
 777    def pool(self, rolls: int | Sequence[int] = 1, /) -> 'icepool.Pool[T_co]':
 778        """Creates a `Pool` from this `Die`.
 779
 780        You might subscript the pool immediately afterwards, e.g.
 781        `d6.pool(5)[-1, ..., 1]` takes the difference between the highest and
 782        lowest of 5d6.
 783
 784        Args:
 785            rolls: The number of copies of this `Die` to put in the pool.
 786                Or, a sequence of one `int` per die acting as
 787                `keep_tuple`. Note that `...` cannot be used in the
 788                argument to this method, as the argument determines the size of
 789                the pool.
 790        """
 791        if isinstance(rolls, int):
 792            return icepool.Pool({self: rolls})
 793        else:
 794            pool_size = len(rolls)
 795            # Haven't dealt with narrowing return type.
 796            return icepool.Pool({self: pool_size})[rolls]  # type: ignore
 797
 798    @overload
 799    def keep(self, rolls: Sequence[int], /) -> 'Die':
 800        """Selects elements after drawing and sorting and sums them.
 801
 802        Args:
 803            rolls: A sequence of `int` specifying how many times to count each
 804                element in ascending order.
 805        """
 806
 807    @overload
 808    def keep(self, rolls: int,
 809             index: slice | Sequence[int | EllipsisType] | int, /):
 810        """Selects elements after drawing and sorting and sums them.
 811
 812        Args:
 813            rolls: The number of dice to roll.
 814            index: One of the following:
 815            * An `int`. This will count only the roll at the specified index.
 816                In this case, the result is a `Die` rather than a generator.
 817            * A `slice`. The selected dice are counted once each.
 818            * A sequence of one `int` for each `Die`.
 819                Each roll is counted that many times, which could be multiple or
 820                negative times.
 821
 822                Up to one `...` (`Ellipsis`) may be used.
 823                `...` will be replaced with a number of zero
 824                counts depending on the `rolls`.
 825                This number may be "negative" if more `int`s are provided than
 826                `rolls`. Specifically:
 827
 828                * If `index` is shorter than `rolls`, `...`
 829                    acts as enough zero counts to make up the difference.
 830                    E.g. `(1, ..., 1)` on five dice would act as
 831                    `(1, 0, 0, 0, 1)`.
 832                * If `index` has length equal to `rolls`, `...` has no effect.
 833                    E.g. `(1, ..., 1)` on two dice would act as `(1, 1)`.
 834                * If `index` is longer than `rolls` and `...` is on one side,
 835                    elements will be dropped from `index` on the side with `...`.
 836                    E.g. `(..., 1, 2, 3)` on two dice would act as `(2, 3)`.
 837                * If `index` is longer than `rolls` and `...`
 838                    is in the middle, the counts will be as the sum of two
 839                    one-sided `...`.
 840                    E.g. `(-1, ..., 1)` acts like `(-1, ...)` plus `(..., 1)`.
 841                    If `rolls` was 1 this would have the -1 and 1 cancel each other out.
 842        """
 843
 844    def keep(self,
 845             rolls: int | Sequence[int],
 846             index: slice | Sequence[int | EllipsisType] | int | None = None,
 847             /) -> 'Die':
 848        """Selects elements after drawing and sorting and sums them.
 849
 850        Args:
 851            rolls: The number of dice to roll.
 852            index: One of the following:
 853            * An `int`. This will count only the roll at the specified index.
 854            In this case, the result is a `Die` rather than a generator.
 855            * A `slice`. The selected dice are counted once each.
 856            * A sequence of `int`s with length equal to `rolls`.
 857                Each roll is counted that many times, which could be multiple or
 858                negative times.
 859
 860                Up to one `...` (`Ellipsis`) may be used. If no `...` is used,
 861                the `rolls` argument may be omitted.
 862
 863                `...` will be replaced with a number of zero counts in order
 864                to make up any missing elements compared to `rolls`.
 865                This number may be "negative" if more `int`s are provided than
 866                `rolls`. Specifically:
 867
 868                * If `index` is shorter than `rolls`, `...`
 869                    acts as enough zero counts to make up the difference.
 870                    E.g. `(1, ..., 1)` on five dice would act as
 871                    `(1, 0, 0, 0, 1)`.
 872                * If `index` has length equal to `rolls`, `...` has no effect.
 873                    E.g. `(1, ..., 1)` on two dice would act as `(1, 1)`.
 874                * If `index` is longer than `rolls` and `...` is on one side,
 875                    elements will be dropped from `index` on the side with `...`.
 876                    E.g. `(..., 1, 2, 3)` on two dice would act as `(2, 3)`.
 877                * If `index` is longer than `rolls` and `...`
 878                    is in the middle, the counts will be as the sum of two
 879                    one-sided `...`.
 880                    E.g. `(-1, ..., 1)` acts like `(-1, ...)` plus `(..., 1)`.
 881                    If `rolls` was 1 this would have the -1 and 1 cancel each other out.
 882        """
 883        if isinstance(rolls, int):
 884            if index is None:
 885                raise ValueError(
 886                    'If the number of rolls is an integer, an index argument must be provided.'
 887                )
 888            if isinstance(index, int):
 889                return self.pool(rolls).keep(index)
 890            else:
 891                return self.pool(rolls).keep(index).sum()  # type: ignore
 892        else:
 893            if index is not None:
 894                raise ValueError('Only one index sequence can be given.')
 895            return self.pool(len(rolls)).keep(rolls).sum()  # type: ignore
 896
 897    def lowest(self,
 898               rolls: int,
 899               /,
 900               keep: int | None = None,
 901               drop: int | None = None) -> 'Die':
 902        """Roll several of this `Die` and return the lowest result, or the sum of some of the lowest.
 903
 904        The outcomes should support addition and multiplication if `keep != 1`.
 905
 906        Args:
 907            rolls: The number of dice to roll. All dice will have the same
 908                outcomes as `self`.
 909            keep, drop: These arguments work together:
 910                * If neither are provided, the single lowest die will be taken.
 911                * If only `keep` is provided, the `keep` lowest dice will be summed.
 912                * If only `drop` is provided, the `drop` lowest dice will be dropped
 913                    and the rest will be summed.
 914                * If both are provided, `drop` lowest dice will be dropped, then
 915                    the next `keep` lowest dice will be summed.
 916
 917        Returns:
 918            A `Die` representing the probability distribution of the sum.
 919        """
 920        index = lowest_slice(keep, drop)
 921        canonical = canonical_slice(index, rolls)
 922        if canonical.start == 0 and canonical.stop == 1:
 923            return self._lowest_single(rolls)
 924        # Expression evaluators are difficult to type.
 925        return self.pool(rolls)[index].sum()  # type: ignore
 926
 927    def _lowest_single(self, rolls: int, /) -> 'Die':
 928        """Roll this die several times and keep the lowest."""
 929        if rolls == 0:
 930            return self.zero().simplify()
 931        return icepool.from_cumulative(
 932            self.outcomes(), [x**rolls for x in self.quantities('>=')],
 933            reverse=True)
 934
 935    def highest(self,
 936                rolls: int,
 937                /,
 938                keep: int | None = None,
 939                drop: int | None = None) -> 'Die[T_co]':
 940        """Roll several of this `Die` and return the highest result, or the sum of some of the highest.
 941
 942        The outcomes should support addition and multiplication if `keep != 1`.
 943
 944        Args:
 945            rolls: The number of dice to roll.
 946            keep, drop: These arguments work together:
 947                * If neither are provided, the single highest die will be taken.
 948                * If only `keep` is provided, the `keep` highest dice will be summed.
 949                * If only `drop` is provided, the `drop` highest dice will be dropped
 950                    and the rest will be summed.
 951                * If both are provided, `drop` highest dice will be dropped, then
 952                    the next `keep` highest dice will be summed.
 953
 954        Returns:
 955            A `Die` representing the probability distribution of the sum.
 956        """
 957        index = highest_slice(keep, drop)
 958        canonical = canonical_slice(index, rolls)
 959        if canonical.start == rolls - 1 and canonical.stop == rolls:
 960            return self._highest_single(rolls)
 961        # Expression evaluators are difficult to type.
 962        return self.pool(rolls)[index].sum()  # type: ignore
 963
 964    def _highest_single(self, rolls: int, /) -> 'Die[T_co]':
 965        """Roll this die several times and keep the highest."""
 966        if rolls == 0:
 967            return self.zero().simplify()
 968        return icepool.from_cumulative(
 969            self.outcomes(), [x**rolls for x in self.quantities('<=')])
 970
 971    def middle(
 972            self,
 973            rolls: int,
 974            /,
 975            keep: int = 1,
 976            *,
 977            tie: Literal['error', 'high', 'low'] = 'error') -> 'icepool.Die':
 978        """Roll several of this `Die` and sum the sorted results in the middle.
 979
 980        The outcomes should support addition and multiplication if `keep != 1`.
 981
 982        Args:
 983            rolls: The number of dice to roll.
 984            keep: The number of outcomes to sum. If this is greater than the
 985                current keep_size, all are kept.
 986            tie: What to do if `keep` is odd but the current keep_size
 987                is even, or vice versa.
 988                * 'error' (default): Raises `IndexError`.
 989                * 'high': The higher outcome is taken.
 990                * 'low': The lower outcome is taken.
 991        """
 992        # Expression evaluators are difficult to type.
 993        return self.pool(rolls).middle(keep, tie=tie).sum()  # type: ignore
 994
 995    def map_to_pool(
 996            self,
 997            repl:
 998        'Callable[..., Sequence[icepool.Die[U] | U] | Mapping[icepool.Die[U], int] | Mapping[U, int] | icepool.RerollType] | None' = None,
 999            /,
1000            *extra_args: 'Outcome | icepool.Die | icepool.MultisetExpression',
1001            star: bool | None = None,
1002            **kwargs) -> 'icepool.MultisetExpression[U]':
1003        """EXPERIMENTAL: Maps outcomes of this `Die` to `Pools`, creating a `MultisetGenerator`.
1004
1005        As `icepool.map_to_pool(repl, self, ...)`.
1006
1007        If no argument is provided, the outcomes will be used to construct a
1008        mixture of pools directly, similar to the inverse of `pool.expand()`.
1009        Note that this is not particularly efficient since it does not make much
1010        use of dynamic programming.
1011        """
1012        if repl is None:
1013            repl = lambda x: x
1014        return icepool.map_to_pool(repl,
1015                                   self,
1016                                   *extra_args,
1017                                   star=star,
1018                                   **kwargs)
1019
1020    def explode_to_pool(self,
1021                        rolls: int = 1,
1022                        outcomes: Collection[T_co] | Callable[..., bool]
1023                        | None = None,
1024                        /,
1025                        *,
1026                        star: bool | None = None,
1027                        depth: int = 9) -> 'icepool.MultisetExpression[T_co]':
1028        """EXPERIMENTAL: Causes outcomes to be rolled again, keeping that outcome as an individual die in a pool.
1029        
1030        Args:
1031            rolls: The number of initial dice.
1032            outcomes: Which outcomes to explode. Options:
1033                * A single outcome to explode.
1034                * An collection of outcomes to explode.
1035                * A callable that takes an outcome and returns `True` if it
1036                    should be exploded.
1037                * If not supplied, the max outcome will explode.
1038            star: Whether outcomes should be unpacked into separate arguments
1039                before sending them to a callable `which`.
1040                If not provided, this will be guessed based on the function
1041                signature.
1042            depth: The maximum depth of explosions for an individual dice.
1043
1044        Returns:
1045            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1046            that this is not technically a `Pool`, though it supports most of 
1047            the same operations.
1048        """
1049        if depth == 0:
1050            return self.pool(rolls)
1051        if outcomes is None:
1052            explode_set = {self.max_outcome()}
1053        else:
1054            explode_set = self._select_outcomes(outcomes, star)
1055        if not explode_set:
1056            return self.pool(rolls)
1057        explode: 'Die[T_co]'
1058        not_explode: 'Die[T_co]'
1059        explode, not_explode = self.split(explode_set)
1060
1061        single_data: 'MutableMapping[icepool.Vector[int], int]' = defaultdict(
1062            int)
1063        for i in range(depth + 1):
1064            weight = explode.denominator()**i * self.denominator()**(
1065                depth - i) * not_explode.denominator()
1066            single_data[icepool.Vector((i, 1))] += weight
1067        single_data[icepool.Vector(
1068            (depth + 1, 0))] += explode.denominator()**(depth + 1)
1069
1070        single_count_die: 'Die[icepool.Vector[int]]' = Die(single_data)
1071        count_die = rolls @ single_count_die
1072
1073        return count_die.map_to_pool(
1074            lambda x, nx: [explode] * x + [not_explode] * nx)
1075
1076    def reroll_to_pool(
1077        self,
1078        rolls: int,
1079        outcomes: Callable[..., bool] | Collection[T_co] | None = None,
1080        /,
1081        *,
1082        max_rerolls: int | Literal['inf'],
1083        star: bool | None = None,
1084        depth: int | Literal['inf'] = 1,
1085        mode: Literal['random', 'low', 'high', 'drop'] = 'random'
1086    ) -> 'icepool.MultisetExpression[T_co]':
1087        """EXPERIMENTAL: Applies a limited number of rerolls shared across a pool.
1088
1089        Each die can only be rerolled once (effectively `depth=1`), and no more
1090        than `max_rerolls` dice may be rerolled.
1091        
1092        Args:
1093            rolls: How many dice in the pool.
1094            outcomes: Selects which outcomes are eligible to be rerolled.
1095                Options:
1096                * A collection of outcomes to reroll.
1097                * A callable that takes an outcome and returns `True` if it
1098                    could be rerolled.
1099                * If not provided, the single minimum outcome will be rerolled.
1100            max_rerolls: The maximum total number of rerolls.
1101                If `max_rerolls == 'inf'`, then this is the same as 
1102                `self.reroll(which, star=star, depth=depth).pool(rolls)`.
1103            depth: EXTRA EXPERIMENTAL: The maximum depth of rerolls.
1104            star: Whether outcomes should be unpacked into separate arguments
1105                before sending them to a callable `which`.
1106                If not provided, this will be guessed based on the function
1107                signature.
1108            mode: How dice are selected for rerolling if there are more eligible
1109                dice than `max_rerolls`. Options:
1110                * `'random'` (default): Eligible dice will be chosen uniformly
1111                    at random.
1112                * `'low'`: The lowest eligible dice will be rerolled.
1113                * `'high'`: The highest eligible dice will be rerolled.
1114                * `'drop'`: All dice that ended up on an outcome selected by 
1115                    `which` will be dropped. This includes both dice that rolled
1116                    into `which` initially and were not rerolled, and dice that
1117                    were rerolled but rolled into `which` again. This can be
1118                    considerably more efficient than the other modes.
1119
1120        Returns:
1121            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1122            that this is not technically a `Pool`, though it supports most of 
1123            the same operations.
1124        """
1125        if max_rerolls == 'inf':
1126            return self.reroll(outcomes, star=star, depth=depth).pool(rolls)
1127
1128        if outcomes is None:
1129            rerollable_set = {self.min_outcome()}
1130        else:
1131            rerollable_set = self._select_outcomes(outcomes, star)
1132            if not rerollable_set:
1133                return self.pool(rolls)
1134
1135        rerollable_die: 'Die[T_co]'
1136        not_rerollable_die: 'Die[T_co]'
1137        rerollable_die, not_rerollable_die = self.split(rerollable_set)
1138        single_is_rerollable = icepool.coin(rerollable_die.denominator(),
1139                                            self.denominator())
1140
1141        if depth == 'inf':
1142            depth = max_rerolls
1143
1144        def step(rerollable, rerolls_left):
1145            """Advances one step of rerolling if there are enough rerolls left to cover all rerollable dice.
1146            
1147            Returns:
1148                The number of dice showing rerollable outcomes and the number of remaining rerolls.
1149            """
1150            if rerollable == 0:
1151                return 0, 0
1152            if rerolls_left < rerollable:
1153                return rerollable, rerolls_left
1154
1155            return icepool.tupleize(rerollable @ single_is_rerollable,
1156                                    rerolls_left - rerollable)
1157
1158        initial_state = icepool.tupleize(rolls @ single_is_rerollable,
1159                                         max_rerolls)
1160        mid_pool_composition: Die[tuple[int, int]]
1161        mid_pool_composition = icepool.map(step,
1162                                           initial_state,
1163                                           star=True,
1164                                           repeat=depth - 1)
1165
1166        def final_step(rerollable, rerolls_left):
1167            """Performs the final reroll, which might not have enough rerolls to cover all rerollable dice.
1168            
1169            Returns: The number of dice that had a rerollable outcome,
1170                the number of dice that were rerolled due to max_rerolls,
1171                the number of rerolled dice that landed on a rerollable outcome
1172                again.
1173            """
1174            rerolled = min(rerollable, rerolls_left)
1175
1176            return icepool.tupleize(rerollable, rerolled,
1177                                    rerolled @ single_is_rerollable)
1178
1179        pool_composition: Die[tuple[int, int, int]] = mid_pool_composition.map(
1180            final_step, star=True)
1181
1182        denominator = self.denominator()**(rolls + max_rerolls)
1183        pool_composition = pool_composition.multiply_to_denominator(
1184            denominator)
1185
1186        def make_pool(rerollable, rerolled, rerolled_to_rerollable):
1187            rerolls_ran_out = rerollable - rerolled
1188            not_rerollable = rolls - rerolls_ran_out - rerolled_to_rerollable
1189            common = rerollable_die.pool(
1190                rerolled_to_rerollable) + not_rerollable_die.pool(
1191                    not_rerollable)
1192            match mode:
1193                case 'random':
1194                    return common + rerollable_die.pool(rerolls_ran_out)
1195                case 'low':
1196                    return common + rerollable_die.pool(rerollable).highest(
1197                        rerolls_ran_out)
1198                case 'high':
1199                    return common + rerollable_die.pool(rerollable).lowest(
1200                        rerolls_ran_out)
1201                case 'drop':
1202                    return not_rerollable_die.pool(not_rerollable)
1203                case _:
1204                    raise ValueError(
1205                        f"Invalid reroll_priority '{mode}'. Allowed values are 'random', 'low', 'high', 'drop'."
1206                    )
1207
1208        return pool_composition.map_to_pool(make_pool, star=True)
1209
1210    # Unary operators.
1211
1212    def __neg__(self) -> 'Die[T_co]':
1213        return self.unary_operator(operator.neg)
1214
1215    def __pos__(self) -> 'Die[T_co]':
1216        return self.unary_operator(operator.pos)
1217
1218    def __invert__(self) -> 'Die[T_co]':
1219        return self.unary_operator(operator.invert)
1220
1221    def abs(self) -> 'Die[T_co]':
1222        return self.unary_operator(operator.abs)
1223
1224    __abs__ = abs
1225
1226    def round(self, ndigits: int | None = None) -> 'Die':
1227        return self.unary_operator(round, ndigits)
1228
1229    __round__ = round
1230
1231    def stochastic_round(self,
1232                         *,
1233                         max_denominator: int | None = None) -> 'Die[int]':
1234        """Randomly rounds outcomes up or down to the nearest integer according to the two distances.
1235        
1236        Specificially, rounds `x` up with probability `x - floor(x)` and down
1237        otherwise.
1238
1239        Args:
1240            max_denominator: If provided, each rounding will be performed
1241                using `fractions.Fraction.limit_denominator(max_denominator)`.
1242                Otherwise, the rounding will be performed without
1243                `limit_denominator`.
1244        """
1245        return self.map(lambda x: icepool.stochastic_round(
1246            x, max_denominator=max_denominator))
1247
1248    def trunc(self) -> 'Die':
1249        return self.unary_operator(math.trunc)
1250
1251    __trunc__ = trunc
1252
1253    def floor(self) -> 'Die':
1254        return self.unary_operator(math.floor)
1255
1256    __floor__ = floor
1257
1258    def ceil(self) -> 'Die':
1259        return self.unary_operator(math.ceil)
1260
1261    __ceil__ = ceil
1262
1263    # Binary operators.
1264
1265    def __add__(self, other) -> 'Die':
1266        if isinstance(other, icepool.AgainExpression):
1267            return NotImplemented
1268        other = implicit_convert_to_die(other)
1269        return self.binary_operator(other, operator.add)
1270
1271    def __radd__(self, other) -> 'Die':
1272        if isinstance(other, icepool.AgainExpression):
1273            return NotImplemented
1274        other = implicit_convert_to_die(other)
1275        return other.binary_operator(self, operator.add)
1276
1277    def __sub__(self, other) -> 'Die':
1278        if isinstance(other, icepool.AgainExpression):
1279            return NotImplemented
1280        other = implicit_convert_to_die(other)
1281        return self.binary_operator(other, operator.sub)
1282
1283    def __rsub__(self, other) -> 'Die':
1284        if isinstance(other, icepool.AgainExpression):
1285            return NotImplemented
1286        other = implicit_convert_to_die(other)
1287        return other.binary_operator(self, operator.sub)
1288
1289    def __mul__(self, other) -> 'Die':
1290        if isinstance(other, icepool.AgainExpression):
1291            return NotImplemented
1292        other = implicit_convert_to_die(other)
1293        return self.binary_operator(other, operator.mul)
1294
1295    def __rmul__(self, other) -> 'Die':
1296        if isinstance(other, icepool.AgainExpression):
1297            return NotImplemented
1298        other = implicit_convert_to_die(other)
1299        return other.binary_operator(self, operator.mul)
1300
1301    def __truediv__(self, other) -> 'Die':
1302        if isinstance(other, icepool.AgainExpression):
1303            return NotImplemented
1304        other = implicit_convert_to_die(other)
1305        return self.binary_operator(other, operator.truediv)
1306
1307    def __rtruediv__(self, other) -> 'Die':
1308        if isinstance(other, icepool.AgainExpression):
1309            return NotImplemented
1310        other = implicit_convert_to_die(other)
1311        return other.binary_operator(self, operator.truediv)
1312
1313    def __floordiv__(self, other) -> 'Die':
1314        if isinstance(other, icepool.AgainExpression):
1315            return NotImplemented
1316        other = implicit_convert_to_die(other)
1317        return self.binary_operator(other, operator.floordiv)
1318
1319    def __rfloordiv__(self, other) -> 'Die':
1320        if isinstance(other, icepool.AgainExpression):
1321            return NotImplemented
1322        other = implicit_convert_to_die(other)
1323        return other.binary_operator(self, operator.floordiv)
1324
1325    def __pow__(self, other) -> 'Die':
1326        if isinstance(other, icepool.AgainExpression):
1327            return NotImplemented
1328        other = implicit_convert_to_die(other)
1329        return self.binary_operator(other, operator.pow)
1330
1331    def __rpow__(self, other) -> 'Die':
1332        if isinstance(other, icepool.AgainExpression):
1333            return NotImplemented
1334        other = implicit_convert_to_die(other)
1335        return other.binary_operator(self, operator.pow)
1336
1337    def __mod__(self, other) -> 'Die':
1338        if isinstance(other, icepool.AgainExpression):
1339            return NotImplemented
1340        other = implicit_convert_to_die(other)
1341        return self.binary_operator(other, operator.mod)
1342
1343    def __rmod__(self, other) -> 'Die':
1344        if isinstance(other, icepool.AgainExpression):
1345            return NotImplemented
1346        other = implicit_convert_to_die(other)
1347        return other.binary_operator(self, operator.mod)
1348
1349    def __lshift__(self, other) -> 'Die':
1350        if isinstance(other, icepool.AgainExpression):
1351            return NotImplemented
1352        other = implicit_convert_to_die(other)
1353        return self.binary_operator(other, operator.lshift)
1354
1355    def __rlshift__(self, other) -> 'Die':
1356        if isinstance(other, icepool.AgainExpression):
1357            return NotImplemented
1358        other = implicit_convert_to_die(other)
1359        return other.binary_operator(self, operator.lshift)
1360
1361    def __rshift__(self, other) -> 'Die':
1362        if isinstance(other, icepool.AgainExpression):
1363            return NotImplemented
1364        other = implicit_convert_to_die(other)
1365        return self.binary_operator(other, operator.rshift)
1366
1367    def __rrshift__(self, other) -> 'Die':
1368        if isinstance(other, icepool.AgainExpression):
1369            return NotImplemented
1370        other = implicit_convert_to_die(other)
1371        return other.binary_operator(self, operator.rshift)
1372
1373    def __and__(self, other) -> 'Die':
1374        if isinstance(other, icepool.AgainExpression):
1375            return NotImplemented
1376        other = implicit_convert_to_die(other)
1377        return self.binary_operator(other, operator.and_)
1378
1379    def __rand__(self, other) -> 'Die':
1380        if isinstance(other, icepool.AgainExpression):
1381            return NotImplemented
1382        other = implicit_convert_to_die(other)
1383        return other.binary_operator(self, operator.and_)
1384
1385    def __or__(self, other) -> 'Die':
1386        if isinstance(other, icepool.AgainExpression):
1387            return NotImplemented
1388        other = implicit_convert_to_die(other)
1389        return self.binary_operator(other, operator.or_)
1390
1391    def __ror__(self, other) -> 'Die':
1392        if isinstance(other, icepool.AgainExpression):
1393            return NotImplemented
1394        other = implicit_convert_to_die(other)
1395        return other.binary_operator(self, operator.or_)
1396
1397    def __xor__(self, other) -> 'Die':
1398        if isinstance(other, icepool.AgainExpression):
1399            return NotImplemented
1400        other = implicit_convert_to_die(other)
1401        return self.binary_operator(other, operator.xor)
1402
1403    def __rxor__(self, other) -> 'Die':
1404        if isinstance(other, icepool.AgainExpression):
1405            return NotImplemented
1406        other = implicit_convert_to_die(other)
1407        return other.binary_operator(self, operator.xor)
1408
1409    # Comparators.
1410
1411    def __lt__(self, other) -> 'Die[bool]':
1412        if isinstance(other, icepool.AgainExpression):
1413            return NotImplemented
1414        other = implicit_convert_to_die(other)
1415        return self.binary_operator(other, operator.lt)
1416
1417    def __le__(self, other) -> 'Die[bool]':
1418        if isinstance(other, icepool.AgainExpression):
1419            return NotImplemented
1420        other = implicit_convert_to_die(other)
1421        return self.binary_operator(other, operator.le)
1422
1423    def __ge__(self, other) -> 'Die[bool]':
1424        if isinstance(other, icepool.AgainExpression):
1425            return NotImplemented
1426        other = implicit_convert_to_die(other)
1427        return self.binary_operator(other, operator.ge)
1428
1429    def __gt__(self, other) -> 'Die[bool]':
1430        if isinstance(other, icepool.AgainExpression):
1431            return NotImplemented
1432        other = implicit_convert_to_die(other)
1433        return self.binary_operator(other, operator.gt)
1434
1435    # Equality operators. These produce a `DieWithTruth`.
1436
1437    # The result has a truth value, but is not a bool.
1438    def __eq__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1439        if isinstance(other, icepool.AgainExpression):
1440            return NotImplemented
1441        other_die: Die = implicit_convert_to_die(other)
1442
1443        def data_callback() -> Counts[bool]:
1444            return self.binary_operator(other_die, operator.eq)._data
1445
1446        def truth_value_callback() -> bool:
1447            return self.equals(other)
1448
1449        return icepool.DieWithTruth(data_callback, truth_value_callback)
1450
1451    # The result has a truth value, but is not a bool.
1452    def __ne__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1453        if isinstance(other, icepool.AgainExpression):
1454            return NotImplemented
1455        other_die: Die = implicit_convert_to_die(other)
1456
1457        def data_callback() -> Counts[bool]:
1458            return self.binary_operator(other_die, operator.ne)._data
1459
1460        def truth_value_callback() -> bool:
1461            return not self.equals(other)
1462
1463        return icepool.DieWithTruth(data_callback, truth_value_callback)
1464
1465    def cmp(self, other) -> 'Die[int]':
1466        """A `Die` with outcomes 1, -1, and 0.
1467
1468        The quantities are equal to the positive outcome of `self > other`,
1469        `self < other`, and the remainder respectively.
1470        """
1471        other = implicit_convert_to_die(other)
1472
1473        data = {}
1474
1475        lt = self < other
1476        if True in lt:
1477            data[-1] = lt[True]
1478        eq = self == other
1479        if True in eq:
1480            data[0] = eq[True]
1481        gt = self > other
1482        if True in gt:
1483            data[1] = gt[True]
1484
1485        return Die(data)
1486
1487    @staticmethod
1488    def _sign(x) -> int:
1489        z = Die._zero(x)
1490        if x > z:
1491            return 1
1492        elif x < z:
1493            return -1
1494        else:
1495            return 0
1496
1497    def sign(self) -> 'Die[int]':
1498        """Outcomes become 1 if greater than `zero()`, -1 if less than `zero()`, and 0 otherwise.
1499
1500        Note that for `float`s, +0.0, -0.0, and nan all become 0.
1501        """
1502        return self.unary_operator(Die._sign)
1503
1504    # Equality and hashing.
1505
1506    def __bool__(self) -> bool:
1507        raise TypeError(
1508            'A `Die` only has a truth value if it is the result of == or !=.\n'
1509            'This could result from trying to use a die in an if-statement,\n'
1510            'in which case you should use `die.if_else()` instead.\n'
1511            'Or it could result from trying to use a `Die` inside a tuple or vector outcome,\n'
1512            'in which case you should use `tupleize()` or `vectorize().')
1513
1514    @cached_property
1515    def hash_key(self) -> tuple:
1516        """A tuple that uniquely (as `equals()`) identifies this die.
1517
1518        Apart from being hashable and totally orderable, this is not guaranteed
1519        to be in any particular format or have any other properties.
1520        """
1521        return Die, tuple(self.items())
1522
1523    __hash__ = MaybeHashKeyed.__hash__
1524
1525    def equals(self, other, *, simplify: bool = False) -> bool:
1526        """`True` iff both dice have the same outcomes and quantities.
1527
1528        This is `False` if `other` is not a `Die`, even if it would convert
1529        to an equal `Die`.
1530
1531        Truth value does NOT matter.
1532
1533        If one `Die` has a zero-quantity outcome and the other `Die` does not
1534        contain that outcome, they are treated as unequal by this function.
1535
1536        The `==` and `!=` operators have a dual purpose; they return a `Die`
1537        with a truth value determined by this method.
1538        Only dice returned by these methods have a truth value. The data of
1539        these dice is lazily evaluated since the caller may only be interested
1540        in the `Die` value or the truth value.
1541
1542        Args:
1543            simplify: If `True`, the dice will be simplified before comparing.
1544                Otherwise, e.g. a 2:2 coin is not `equals()` to a 1:1 coin.
1545        """
1546        if self is other:
1547            return True
1548
1549        if not isinstance(other, Die):
1550            return False
1551
1552        if simplify:
1553            return self.simplify().hash_key == other.simplify().hash_key
1554        else:
1555            return self.hash_key == other.hash_key
1556
1557    # Strings.
1558
1559    def __repr__(self) -> str:
1560        items_string = ', '.join(f'{repr(outcome)}: {weight}'
1561                                 for outcome, weight in self.items())
1562        return type(self).__qualname__ + '({' + items_string + '})'