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            # Iterative rather than recursive so that large counts don't hit
 730            # the recursion limit: count down to the largest sum already
 731            # computed, then add one roll at a time, caching each sum.
 732            pending = []
 733            k = rolls - 1
 734            while k not in self._sum_cache and k > 1:
 735                pending.append(k)
 736                k -= 1
 737            result = self._sum_all(k)
 738            for k in reversed(pending):
 739                result = result + self
 740                self._sum_cache[k] = result
 741            result = result + self
 742
 743        self._sum_cache[rolls] = result
 744        return result
 745
 746    def __matmul__(self: 'Die[int]', other) -> 'Die':
 747        """Roll the left `Die`, then roll the right `Die` that many times and sum the outcomes.
 748        
 749        The sum is computed one at a time, with each additional item on the 
 750        right, similar to `functools.reduce()`.
 751        """
 752        if isinstance(other, icepool.AgainExpression):
 753            return NotImplemented
 754        other = implicit_convert_to_die(other)
 755
 756        data: MutableMapping[int, Any] = defaultdict(int)
 757
 758        max_abs_die_count = max(abs(self.min_outcome()),
 759                                abs(self.max_outcome()))
 760        for die_count, die_count_quantity in self.items():
 761            factor = other.denominator()**(max_abs_die_count - abs(die_count))
 762            subresult = other._sum_all(die_count)
 763            for outcome, subresult_quantity in subresult.items():
 764                data[
 765                    outcome] += subresult_quantity * die_count_quantity * factor
 766
 767        return icepool.Die(data)
 768
 769    def __rmatmul__(self, other: 'int | Die[int]') -> 'Die':
 770        """Roll the left `Die`, then roll the right `Die` that many times and sum the outcomes.
 771        
 772        The sum is computed one at a time, with each additional item on the 
 773        right, similar to `functools.reduce()`.
 774        """
 775        if isinstance(other, icepool.AgainExpression):
 776            return NotImplemented
 777        other = implicit_convert_to_die(other)
 778        return other.__matmul__(self)
 779
 780    def sequence(self, rolls: int) -> 'icepool.Die[tuple[T_co, ...]]':
 781        """Possible sequences produced by rolling this die a number of times.
 782        
 783        This is extremely expensive computationally. If possible, use `reduce()`
 784        instead; if you don't care about order, `Die.pool()` is better.
 785        """
 786        return icepool.cartesian_product(*(self for _ in range(rolls)),
 787                                         outcome_type=tuple)  # type: ignore
 788
 789    def pool(self, rolls: int | Sequence[int] = 1, /) -> 'icepool.Pool[T_co]':
 790        """Creates a `Pool` from this `Die`.
 791
 792        You might subscript the pool immediately afterwards, e.g.
 793        `d6.pool(5)[-1, ..., 1]` takes the difference between the highest and
 794        lowest of 5d6.
 795
 796        Args:
 797            rolls: The number of copies of this `Die` to put in the pool.
 798                Or, a sequence of one `int` per die acting as
 799                `keep_tuple`. Note that `...` cannot be used in the
 800                argument to this method, as the argument determines the size of
 801                the pool.
 802        """
 803        if isinstance(rolls, int):
 804            return icepool.Pool({self: rolls})
 805        else:
 806            pool_size = len(rolls)
 807            # Haven't dealt with narrowing return type.
 808            return icepool.Pool({self: pool_size})[rolls]  # type: ignore
 809
 810    @overload
 811    def keep(self, rolls: Sequence[int], /) -> 'Die':
 812        """Selects elements after drawing and sorting and sums them.
 813
 814        Args:
 815            rolls: A sequence of `int` specifying how many times to count each
 816                element in ascending order.
 817        """
 818
 819    @overload
 820    def keep(self, rolls: int,
 821             index: slice | Sequence[int | EllipsisType] | int, /):
 822        """Selects elements after drawing and sorting and sums them.
 823
 824        Args:
 825            rolls: The number of dice to roll.
 826            index: One of the following:
 827            * An `int`. This will count only the roll at the specified index.
 828                In this case, the result is a `Die` rather than a generator.
 829            * A `slice`. The selected dice are counted once each.
 830            * A sequence of one `int` for each `Die`.
 831                Each roll is counted that many times, which could be multiple or
 832                negative times.
 833
 834                Up to one `...` (`Ellipsis`) may be used.
 835                `...` will be replaced with a number of zero
 836                counts depending on the `rolls`.
 837                This number may be "negative" if more `int`s are provided than
 838                `rolls`. Specifically:
 839
 840                * If `index` is shorter than `rolls`, `...`
 841                    acts as enough zero counts to make up the difference.
 842                    E.g. `(1, ..., 1)` on five dice would act as
 843                    `(1, 0, 0, 0, 1)`.
 844                * If `index` has length equal to `rolls`, `...` has no effect.
 845                    E.g. `(1, ..., 1)` on two dice would act as `(1, 1)`.
 846                * If `index` is longer than `rolls` and `...` is on one side,
 847                    elements will be dropped from `index` on the side with `...`.
 848                    E.g. `(..., 1, 2, 3)` on two dice would act as `(2, 3)`.
 849                * If `index` is longer than `rolls` and `...`
 850                    is in the middle, the counts will be as the sum of two
 851                    one-sided `...`.
 852                    E.g. `(-1, ..., 1)` acts like `(-1, ...)` plus `(..., 1)`.
 853                    If `rolls` was 1 this would have the -1 and 1 cancel each other out.
 854        """
 855
 856    def keep(self,
 857             rolls: int | Sequence[int],
 858             index: slice | Sequence[int | EllipsisType] | int | None = None,
 859             /) -> 'Die':
 860        """Selects elements after drawing and sorting and sums them.
 861
 862        Args:
 863            rolls: The number of dice to roll.
 864            index: One of the following:
 865            * An `int`. This will count only the roll at the specified index.
 866            In this case, the result is a `Die` rather than a generator.
 867            * A `slice`. The selected dice are counted once each.
 868            * A sequence of `int`s with length equal to `rolls`.
 869                Each roll is counted that many times, which could be multiple or
 870                negative times.
 871
 872                Up to one `...` (`Ellipsis`) may be used. If no `...` is used,
 873                the `rolls` argument may be omitted.
 874
 875                `...` will be replaced with a number of zero counts in order
 876                to make up any missing elements compared to `rolls`.
 877                This number may be "negative" if more `int`s are provided than
 878                `rolls`. Specifically:
 879
 880                * If `index` is shorter than `rolls`, `...`
 881                    acts as enough zero counts to make up the difference.
 882                    E.g. `(1, ..., 1)` on five dice would act as
 883                    `(1, 0, 0, 0, 1)`.
 884                * If `index` has length equal to `rolls`, `...` has no effect.
 885                    E.g. `(1, ..., 1)` on two dice would act as `(1, 1)`.
 886                * If `index` is longer than `rolls` and `...` is on one side,
 887                    elements will be dropped from `index` on the side with `...`.
 888                    E.g. `(..., 1, 2, 3)` on two dice would act as `(2, 3)`.
 889                * If `index` is longer than `rolls` and `...`
 890                    is in the middle, the counts will be as the sum of two
 891                    one-sided `...`.
 892                    E.g. `(-1, ..., 1)` acts like `(-1, ...)` plus `(..., 1)`.
 893                    If `rolls` was 1 this would have the -1 and 1 cancel each other out.
 894        """
 895        if isinstance(rolls, int):
 896            if index is None:
 897                raise ValueError(
 898                    'If the number of rolls is an integer, an index argument must be provided.'
 899                )
 900            if isinstance(index, int):
 901                return self.pool(rolls).keep(index)
 902            else:
 903                return self.pool(rolls).keep(index).sum()  # type: ignore
 904        else:
 905            if index is not None:
 906                raise ValueError('Only one index sequence can be given.')
 907            return self.pool(len(rolls)).keep(rolls).sum()  # type: ignore
 908
 909    def lowest(self,
 910               rolls: int,
 911               /,
 912               keep: int | None = None,
 913               drop: int | None = None) -> 'Die':
 914        """Roll several of this `Die` and return the lowest result, or the sum of some of the lowest.
 915
 916        The outcomes should support addition and multiplication if `keep != 1`.
 917
 918        Args:
 919            rolls: The number of dice to roll. All dice will have the same
 920                outcomes as `self`.
 921            keep, drop: These arguments work together:
 922                * If neither are provided, the single lowest die will be taken.
 923                * If only `keep` is provided, the `keep` lowest dice will be summed.
 924                * If only `drop` is provided, the `drop` lowest dice will be dropped
 925                    and the rest will be summed.
 926                * If both are provided, `drop` lowest dice will be dropped, then
 927                    the next `keep` lowest dice will be summed.
 928
 929        Returns:
 930            A `Die` representing the probability distribution of the sum.
 931        """
 932        index = lowest_slice(keep, drop)
 933        canonical = canonical_slice(index, rolls)
 934        if canonical.start == 0 and canonical.stop == 1:
 935            return self._lowest_single(rolls)
 936        # Expression evaluators are difficult to type.
 937        return self.pool(rolls)[index].sum()  # type: ignore
 938
 939    def _lowest_single(self, rolls: int, /) -> 'Die':
 940        """Roll this die several times and keep the lowest."""
 941        if rolls == 0:
 942            return self.zero().simplify()
 943        return icepool.from_cumulative(
 944            self.outcomes(), [x**rolls for x in self.quantities('>=')],
 945            reverse=True)
 946
 947    def highest(self,
 948                rolls: int,
 949                /,
 950                keep: int | None = None,
 951                drop: int | None = None) -> 'Die[T_co]':
 952        """Roll several of this `Die` and return the highest result, or the sum of some of the highest.
 953
 954        The outcomes should support addition and multiplication if `keep != 1`.
 955
 956        Args:
 957            rolls: The number of dice to roll.
 958            keep, drop: These arguments work together:
 959                * If neither are provided, the single highest die will be taken.
 960                * If only `keep` is provided, the `keep` highest dice will be summed.
 961                * If only `drop` is provided, the `drop` highest dice will be dropped
 962                    and the rest will be summed.
 963                * If both are provided, `drop` highest dice will be dropped, then
 964                    the next `keep` highest dice will be summed.
 965
 966        Returns:
 967            A `Die` representing the probability distribution of the sum.
 968        """
 969        index = highest_slice(keep, drop)
 970        canonical = canonical_slice(index, rolls)
 971        if canonical.start == rolls - 1 and canonical.stop == rolls:
 972            return self._highest_single(rolls)
 973        # Expression evaluators are difficult to type.
 974        return self.pool(rolls)[index].sum()  # type: ignore
 975
 976    def _highest_single(self, rolls: int, /) -> 'Die[T_co]':
 977        """Roll this die several times and keep the highest."""
 978        if rolls == 0:
 979            return self.zero().simplify()
 980        return icepool.from_cumulative(
 981            self.outcomes(), [x**rolls for x in self.quantities('<=')])
 982
 983    def middle(
 984            self,
 985            rolls: int,
 986            /,
 987            keep: int = 1,
 988            *,
 989            tie: Literal['error', 'high', 'low'] = 'error') -> 'icepool.Die':
 990        """Roll several of this `Die` and sum the sorted results in the middle.
 991
 992        The outcomes should support addition and multiplication if `keep != 1`.
 993
 994        Args:
 995            rolls: The number of dice to roll.
 996            keep: The number of outcomes to sum. If this is greater than the
 997                current keep_size, all are kept.
 998            tie: What to do if `keep` is odd but the current keep_size
 999                is even, or vice versa.
1000                * 'error' (default): Raises `IndexError`.
1001                * 'high': The higher outcome is taken.
1002                * 'low': The lower outcome is taken.
1003        """
1004        # Expression evaluators are difficult to type.
1005        return self.pool(rolls).middle(keep, tie=tie).sum()  # type: ignore
1006
1007    def map_to_pool(
1008            self,
1009            repl:
1010        'Callable[..., Sequence[icepool.Die[U] | U] | Mapping[icepool.Die[U], int] | Mapping[U, int] | icepool.RerollType] | None' = None,
1011            /,
1012            *extra_args: 'Outcome | icepool.Die | icepool.MultisetExpression',
1013            star: bool | None = None,
1014            **kwargs) -> 'icepool.MultisetExpression[U]':
1015        """EXPERIMENTAL: Maps outcomes of this `Die` to `Pools`, creating a `MultisetGenerator`.
1016
1017        As `icepool.map_to_pool(repl, self, ...)`.
1018
1019        If no argument is provided, the outcomes will be used to construct a
1020        mixture of pools directly, similar to the inverse of `pool.expand()`.
1021        Note that this is not particularly efficient since it does not make much
1022        use of dynamic programming.
1023        """
1024        if repl is None:
1025            repl = lambda x: x
1026        return icepool.map_to_pool(repl,
1027                                   self,
1028                                   *extra_args,
1029                                   star=star,
1030                                   **kwargs)
1031
1032    def explode_to_pool(self,
1033                        rolls: int = 1,
1034                        outcomes: Collection[T_co] | Callable[..., bool]
1035                        | None = None,
1036                        /,
1037                        *,
1038                        star: bool | None = None,
1039                        depth: int = 9) -> 'icepool.MultisetExpression[T_co]':
1040        """EXPERIMENTAL: Causes outcomes to be rolled again, keeping that outcome as an individual die in a pool.
1041        
1042        Args:
1043            rolls: The number of initial dice.
1044            outcomes: Which outcomes to explode. Options:
1045                * A single outcome to explode.
1046                * An collection of outcomes to explode.
1047                * A callable that takes an outcome and returns `True` if it
1048                    should be exploded.
1049                * If not supplied, the max outcome will explode.
1050            star: Whether outcomes should be unpacked into separate arguments
1051                before sending them to a callable `which`.
1052                If not provided, this will be guessed based on the function
1053                signature.
1054            depth: The maximum depth of explosions for an individual dice.
1055
1056        Returns:
1057            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1058            that this is not technically a `Pool`, though it supports most of 
1059            the same operations.
1060        """
1061        if depth == 0:
1062            return self.pool(rolls)
1063        if outcomes is None:
1064            explode_set = {self.max_outcome()}
1065        else:
1066            explode_set = self._select_outcomes(outcomes, star)
1067        if not explode_set:
1068            return self.pool(rolls)
1069        explode: 'Die[T_co]'
1070        not_explode: 'Die[T_co]'
1071        explode, not_explode = self.split(explode_set)
1072
1073        single_data: 'MutableMapping[icepool.Vector[int], int]' = defaultdict(
1074            int)
1075        for i in range(depth + 1):
1076            weight = explode.denominator()**i * self.denominator()**(
1077                depth - i) * not_explode.denominator()
1078            single_data[icepool.Vector((i, 1))] += weight
1079        single_data[icepool.Vector(
1080            (depth + 1, 0))] += explode.denominator()**(depth + 1)
1081
1082        single_count_die: 'Die[icepool.Vector[int]]' = Die(single_data)
1083        count_die = rolls @ single_count_die
1084
1085        return count_die.map_to_pool(
1086            lambda x, nx: [explode] * x + [not_explode] * nx)
1087
1088    def reroll_to_pool(
1089        self,
1090        rolls: int,
1091        outcomes: Callable[..., bool] | Collection[T_co] | None = None,
1092        /,
1093        *,
1094        max_rerolls: int | Literal['inf'],
1095        star: bool | None = None,
1096        depth: int | Literal['inf'] = 1,
1097        mode: Literal['random', 'low', 'high', 'drop'] = 'random'
1098    ) -> 'icepool.MultisetExpression[T_co]':
1099        """EXPERIMENTAL: Applies a limited number of rerolls shared across a pool.
1100
1101        Each die can only be rerolled once (effectively `depth=1`), and no more
1102        than `max_rerolls` dice may be rerolled.
1103        
1104        Args:
1105            rolls: How many dice in the pool.
1106            outcomes: Selects which outcomes are eligible to be rerolled.
1107                Options:
1108                * A collection of outcomes to reroll.
1109                * A callable that takes an outcome and returns `True` if it
1110                    could be rerolled.
1111                * If not provided, the single minimum outcome will be rerolled.
1112            max_rerolls: The maximum total number of rerolls.
1113                If `max_rerolls == 'inf'`, then this is the same as 
1114                `self.reroll(which, star=star, depth=depth).pool(rolls)`.
1115            depth: EXTRA EXPERIMENTAL: The maximum depth of rerolls.
1116            star: Whether outcomes should be unpacked into separate arguments
1117                before sending them to a callable `which`.
1118                If not provided, this will be guessed based on the function
1119                signature.
1120            mode: How dice are selected for rerolling if there are more eligible
1121                dice than `max_rerolls`. Options:
1122                * `'random'` (default): Eligible dice will be chosen uniformly
1123                    at random.
1124                * `'low'`: The lowest eligible dice will be rerolled.
1125                * `'high'`: The highest eligible dice will be rerolled.
1126                * `'drop'`: All dice that ended up on an outcome selected by 
1127                    `which` will be dropped. This includes both dice that rolled
1128                    into `which` initially and were not rerolled, and dice that
1129                    were rerolled but rolled into `which` again. This can be
1130                    considerably more efficient than the other modes.
1131
1132        Returns:
1133            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1134            that this is not technically a `Pool`, though it supports most of 
1135            the same operations.
1136        """
1137        if max_rerolls == 'inf':
1138            return self.reroll(outcomes, star=star, depth=depth).pool(rolls)
1139
1140        if outcomes is None:
1141            rerollable_set = {self.min_outcome()}
1142        else:
1143            rerollable_set = self._select_outcomes(outcomes, star)
1144            if not rerollable_set:
1145                return self.pool(rolls)
1146
1147        rerollable_die: 'Die[T_co]'
1148        not_rerollable_die: 'Die[T_co]'
1149        rerollable_die, not_rerollable_die = self.split(rerollable_set)
1150        single_is_rerollable = icepool.coin(rerollable_die.denominator(),
1151                                            self.denominator())
1152
1153        if depth == 'inf':
1154            depth = max_rerolls
1155
1156        def step(rerollable, rerolls_left):
1157            """Advances one step of rerolling if there are enough rerolls left to cover all rerollable dice.
1158            
1159            Returns:
1160                The number of dice showing rerollable outcomes and the number of remaining rerolls.
1161            """
1162            if rerollable == 0:
1163                return 0, 0
1164            if rerolls_left < rerollable:
1165                return rerollable, rerolls_left
1166
1167            return icepool.tupleize(rerollable @ single_is_rerollable,
1168                                    rerolls_left - rerollable)
1169
1170        initial_state = icepool.tupleize(rolls @ single_is_rerollable,
1171                                         max_rerolls)
1172        mid_pool_composition: Die[tuple[int, int]]
1173        mid_pool_composition = icepool.map(step,
1174                                           initial_state,
1175                                           star=True,
1176                                           repeat=depth - 1)
1177
1178        def final_step(rerollable, rerolls_left):
1179            """Performs the final reroll, which might not have enough rerolls to cover all rerollable dice.
1180            
1181            Returns: The number of dice that had a rerollable outcome,
1182                the number of dice that were rerolled due to max_rerolls,
1183                the number of rerolled dice that landed on a rerollable outcome
1184                again.
1185            """
1186            rerolled = min(rerollable, rerolls_left)
1187
1188            return icepool.tupleize(rerollable, rerolled,
1189                                    rerolled @ single_is_rerollable)
1190
1191        pool_composition: Die[tuple[int, int, int]] = mid_pool_composition.map(
1192            final_step, star=True)
1193
1194        denominator = self.denominator()**(rolls + max_rerolls)
1195        pool_composition = pool_composition.multiply_to_denominator(
1196            denominator)
1197
1198        def make_pool(rerollable, rerolled, rerolled_to_rerollable):
1199            rerolls_ran_out = rerollable - rerolled
1200            not_rerollable = rolls - rerolls_ran_out - rerolled_to_rerollable
1201            common = rerollable_die.pool(
1202                rerolled_to_rerollable) + not_rerollable_die.pool(
1203                    not_rerollable)
1204            match mode:
1205                case 'random':
1206                    return common + rerollable_die.pool(rerolls_ran_out)
1207                case 'low':
1208                    return common + rerollable_die.pool(rerollable).highest(
1209                        rerolls_ran_out)
1210                case 'high':
1211                    return common + rerollable_die.pool(rerollable).lowest(
1212                        rerolls_ran_out)
1213                case 'drop':
1214                    return not_rerollable_die.pool(not_rerollable)
1215                case _:
1216                    raise ValueError(
1217                        f"Invalid reroll_priority '{mode}'. Allowed values are 'random', 'low', 'high', 'drop'."
1218                    )
1219
1220        return pool_composition.map_to_pool(make_pool, star=True)
1221
1222    # Unary operators.
1223
1224    def __neg__(self) -> 'Die[T_co]':
1225        return self.unary_operator(operator.neg)
1226
1227    def __pos__(self) -> 'Die[T_co]':
1228        return self.unary_operator(operator.pos)
1229
1230    def __invert__(self) -> 'Die[T_co]':
1231        return self.unary_operator(operator.invert)
1232
1233    def abs(self) -> 'Die[T_co]':
1234        return self.unary_operator(operator.abs)
1235
1236    __abs__ = abs
1237
1238    def round(self, ndigits: int | None = None) -> 'Die':
1239        return self.unary_operator(round, ndigits)
1240
1241    __round__ = round
1242
1243    def stochastic_round(self,
1244                         *,
1245                         max_denominator: int | None = None) -> 'Die[int]':
1246        """Randomly rounds outcomes up or down to the nearest integer according to the two distances.
1247        
1248        Specificially, rounds `x` up with probability `x - floor(x)` and down
1249        otherwise.
1250
1251        Args:
1252            max_denominator: If provided, each rounding will be performed
1253                using `fractions.Fraction.limit_denominator(max_denominator)`.
1254                Otherwise, the rounding will be performed without
1255                `limit_denominator`.
1256        """
1257        return self.map(lambda x: icepool.stochastic_round(
1258            x, max_denominator=max_denominator))
1259
1260    def trunc(self) -> 'Die':
1261        return self.unary_operator(math.trunc)
1262
1263    __trunc__ = trunc
1264
1265    def floor(self) -> 'Die':
1266        return self.unary_operator(math.floor)
1267
1268    __floor__ = floor
1269
1270    def ceil(self) -> 'Die':
1271        return self.unary_operator(math.ceil)
1272
1273    __ceil__ = ceil
1274
1275    # Binary operators.
1276
1277    def __add__(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.add)
1282
1283    def __radd__(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.add)
1288
1289    def __sub__(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.sub)
1294
1295    def __rsub__(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.sub)
1300
1301    def __mul__(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.mul)
1306
1307    def __rmul__(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.mul)
1312
1313    def __truediv__(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.truediv)
1318
1319    def __rtruediv__(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.truediv)
1324
1325    def __floordiv__(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.floordiv)
1330
1331    def __rfloordiv__(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.floordiv)
1336
1337    def __pow__(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.pow)
1342
1343    def __rpow__(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.pow)
1348
1349    def __mod__(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.mod)
1354
1355    def __rmod__(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.mod)
1360
1361    def __lshift__(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.lshift)
1366
1367    def __rlshift__(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.lshift)
1372
1373    def __rshift__(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.rshift)
1378
1379    def __rrshift__(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.rshift)
1384
1385    def __and__(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.and_)
1390
1391    def __rand__(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.and_)
1396
1397    def __or__(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.or_)
1402
1403    def __ror__(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.or_)
1408
1409    def __xor__(self, other) -> 'Die':
1410        if isinstance(other, icepool.AgainExpression):
1411            return NotImplemented
1412        other = implicit_convert_to_die(other)
1413        return self.binary_operator(other, operator.xor)
1414
1415    def __rxor__(self, other) -> 'Die':
1416        if isinstance(other, icepool.AgainExpression):
1417            return NotImplemented
1418        other = implicit_convert_to_die(other)
1419        return other.binary_operator(self, operator.xor)
1420
1421    # Comparators.
1422
1423    def __lt__(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.lt)
1428
1429    def __le__(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.le)
1434
1435    def __ge__(self, other) -> 'Die[bool]':
1436        if isinstance(other, icepool.AgainExpression):
1437            return NotImplemented
1438        other = implicit_convert_to_die(other)
1439        return self.binary_operator(other, operator.ge)
1440
1441    def __gt__(self, other) -> 'Die[bool]':
1442        if isinstance(other, icepool.AgainExpression):
1443            return NotImplemented
1444        other = implicit_convert_to_die(other)
1445        return self.binary_operator(other, operator.gt)
1446
1447    # Equality operators. These produce a `DieWithTruth`.
1448
1449    # The result has a truth value, but is not a bool.
1450    def __eq__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1451        if isinstance(other, icepool.AgainExpression):
1452            return NotImplemented
1453        other_die: Die = implicit_convert_to_die(other)
1454
1455        def data_callback() -> Counts[bool]:
1456            return self.binary_operator(other_die, operator.eq)._data
1457
1458        def truth_value_callback() -> bool:
1459            return self.equals(other)
1460
1461        return icepool.DieWithTruth(data_callback, truth_value_callback)
1462
1463    # The result has a truth value, but is not a bool.
1464    def __ne__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1465        if isinstance(other, icepool.AgainExpression):
1466            return NotImplemented
1467        other_die: Die = implicit_convert_to_die(other)
1468
1469        def data_callback() -> Counts[bool]:
1470            return self.binary_operator(other_die, operator.ne)._data
1471
1472        def truth_value_callback() -> bool:
1473            return not self.equals(other)
1474
1475        return icepool.DieWithTruth(data_callback, truth_value_callback)
1476
1477    def cmp(self, other) -> 'Die[int]':
1478        """A `Die` with outcomes 1, -1, and 0.
1479
1480        The quantities are equal to the positive outcome of `self > other`,
1481        `self < other`, and the remainder respectively.
1482        """
1483        other = implicit_convert_to_die(other)
1484
1485        data = {}
1486
1487        lt = self < other
1488        if True in lt:
1489            data[-1] = lt[True]
1490        eq = self == other
1491        if True in eq:
1492            data[0] = eq[True]
1493        gt = self > other
1494        if True in gt:
1495            data[1] = gt[True]
1496
1497        return Die(data)
1498
1499    @staticmethod
1500    def _sign(x) -> int:
1501        z = Die._zero(x)
1502        if x > z:
1503            return 1
1504        elif x < z:
1505            return -1
1506        else:
1507            return 0
1508
1509    def sign(self) -> 'Die[int]':
1510        """Outcomes become 1 if greater than `zero()`, -1 if less than `zero()`, and 0 otherwise.
1511
1512        Note that for `float`s, +0.0, -0.0, and nan all become 0.
1513        """
1514        return self.unary_operator(Die._sign)
1515
1516    # Equality and hashing.
1517
1518    def __bool__(self) -> bool:
1519        raise TypeError(
1520            'A `Die` only has a truth value if it is the result of == or !=.\n'
1521            'This could result from trying to use a die in an if-statement,\n'
1522            'in which case you should use `die.if_else()` instead.\n'
1523            'Or it could result from trying to use a `Die` inside a tuple or vector outcome,\n'
1524            'in which case you should use `tupleize()` or `vectorize().')
1525
1526    @cached_property
1527    def hash_key(self) -> tuple:
1528        """A tuple that uniquely (as `equals()`) identifies this die.
1529
1530        Apart from being hashable and totally orderable, this is not guaranteed
1531        to be in any particular format or have any other properties.
1532        """
1533        return Die, tuple(self.items())
1534
1535    __hash__ = MaybeHashKeyed.__hash__
1536
1537    def equals(self, other, *, simplify: bool = False) -> bool:
1538        """`True` iff both dice have the same outcomes and quantities.
1539
1540        This is `False` if `other` is not a `Die`, even if it would convert
1541        to an equal `Die`.
1542
1543        Truth value does NOT matter.
1544
1545        If one `Die` has a zero-quantity outcome and the other `Die` does not
1546        contain that outcome, they are treated as unequal by this function.
1547
1548        The `==` and `!=` operators have a dual purpose; they return a `Die`
1549        with a truth value determined by this method.
1550        Only dice returned by these methods have a truth value. The data of
1551        these dice is lazily evaluated since the caller may only be interested
1552        in the `Die` value or the truth value.
1553
1554        Args:
1555            simplify: If `True`, the dice will be simplified before comparing.
1556                Otherwise, e.g. a 2:2 coin is not `equals()` to a 1:1 coin.
1557        """
1558        if self is other:
1559            return True
1560
1561        if not isinstance(other, Die):
1562            return False
1563
1564        if simplify:
1565            return self.simplify().hash_key == other.simplify().hash_key
1566        else:
1567            return self.hash_key == other.hash_key
1568
1569    # Strings.
1570
1571    def __repr__(self) -> str:
1572        items_string = ', '.join(f'{repr(outcome)}: {weight}'
1573                                 for outcome, weight in self.items())
1574        return type(self).__qualname__ + '({' + items_string + '})'