icepool

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

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

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

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

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

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

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