icepool

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

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

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

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

128def one_hot(sides: int, /) -> 'icepool.Die[tuple[bool, ...]]':
129    """A `Die` with `Vector` outcomes with one element set to `True` uniformly at random and the rest `False`.
130
131    This is an easy (if somewhat expensive) way of representing how many dice
132    in a pool rolled each number. For example, the outcomes of `10 @ one_hot(6)`
133    are the `(ones, twos, threes, fours, fives, sixes)` rolled in 10d6.
134    """
135    data = []
136    for i in range(sides):
137        outcome = [False] * sides
138        outcome[i] = True
139        data.append(icepool.Vector(outcome))
140    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) -> 'icepool.MultisetExpression[U]':
 966        """EXPERIMENTAL: Maps outcomes of this `Die` to `Pools`, creating a `MultisetGenerator`.
 967
 968        As `icepool.map_to_pool(repl, self, ...)`.
 969
 970        If no argument is provided, the outcomes will be used to construct a
 971        mixture of pools directly, similar to the inverse of `pool.expand()`.
 972        Note that this is not particularly efficient since it does not make much
 973        use of dynamic programming.
 974
 975        Args:
 976            repl: One of the following:
 977                * A callable that takes in one outcome per element of args and
 978                    produces a `Pool` (or something convertible to such).
 979                * A mapping from old outcomes to `Pool` 
 980                    (or something convertible to such).
 981                    In this case args must have exactly one element.
 982                The new outcomes may be dice rather than just single outcomes.
 983                The special value `icepool.Reroll` will reroll that old outcome.
 984            star: If `True`, the first of the args will be unpacked before 
 985                giving them to `repl`.
 986                If not provided, it will be guessed based on the signature of 
 987                `repl` and the number of arguments.
 988            denominator: If provided, the denominator of the result will be this
 989                value. Otherwise it will be the minimum to correctly weight the
 990                pools.
 991
 992        Returns:
 993            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
 994            that this is not technically a `Pool`, though it supports most of 
 995            the same operations.
 996
 997        Raises:
 998            ValueError: If `denominator` cannot be made consistent with the 
 999                resulting mixture of pools.
1000        """
1001        if repl is None:
1002            repl = lambda x: x
1003        return icepool.map_to_pool(repl, self, *extra_args, star=star)
1004
1005    def explode_to_pool(self,
1006                        rolls: int,
1007                        which: Collection[T_co] | Callable[..., bool]
1008                        | None = None,
1009                        /,
1010                        *,
1011                        star: bool | None = None,
1012                        depth: int = 9) -> 'icepool.MultisetExpression[T_co]':
1013        """EXPERIMENTAL: Causes outcomes to be rolled again, keeping that outcome as an individual die in a pool.
1014        
1015        Args:
1016            rolls: The number of initial dice.
1017            which: Which outcomes to explode. Options:
1018                * A single outcome to explode.
1019                * An collection of outcomes to explode.
1020                * A callable that takes an outcome and returns `True` if it
1021                    should be exploded.
1022                * If not supplied, the max outcome will explode.
1023            star: Whether outcomes should be unpacked into separate arguments
1024                before sending them to a callable `which`.
1025                If not provided, this will be guessed based on the function
1026                signature.
1027            depth: The maximum depth of explosions for an individual dice.
1028
1029        Returns:
1030            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1031            that this is not technically a `Pool`, though it supports most of 
1032            the same operations.
1033        """
1034        if depth == 0:
1035            return self.pool(rolls)
1036        if which is None:
1037            explode_set = {self.max_outcome()}
1038        else:
1039            explode_set = self._select_outcomes(which, star)
1040        if not explode_set:
1041            return self.pool(rolls)
1042        explode: 'Die[T_co]'
1043        not_explode: 'Die[T_co]'
1044        explode, not_explode = self.split(explode_set)
1045
1046        single_data: 'MutableMapping[icepool.Vector[int], int]' = defaultdict(
1047            int)
1048        for i in range(depth + 1):
1049            weight = explode.denominator()**i * self.denominator()**(
1050                depth - i) * not_explode.denominator()
1051            single_data[icepool.Vector((i, 1))] += weight
1052        single_data[icepool.Vector(
1053            (depth + 1, 0))] += explode.denominator()**(depth + 1)
1054
1055        single_count_die: 'Die[icepool.Vector[int]]' = Die(single_data)
1056        count_die = rolls @ single_count_die
1057
1058        return count_die.map_to_pool(
1059            lambda x, nx: [explode] * x + [not_explode] * nx)
1060
1061    def reroll_to_pool(
1062        self,
1063        rolls: int,
1064        which: Callable[..., bool] | Collection[T_co],
1065        /,
1066        max_rerolls: int,
1067        *,
1068        star: bool | None = None,
1069        mode: Literal['random', 'lowest', 'highest', 'drop'] = 'random'
1070    ) -> 'icepool.MultisetExpression[T_co]':
1071        """EXPERIMENTAL: Applies a limited number of rerolls shared across a pool.
1072
1073        Each die can only be rerolled once (effectively `depth=1`), and no more
1074        than `max_rerolls` dice may be rerolled.
1075        
1076        Args:
1077            rolls: How many dice in the pool.
1078            which: Selects which outcomes are eligible to be rerolled. Options:
1079                * A collection of outcomes to reroll.
1080                * A callable that takes an outcome and returns `True` if it
1081                    could be rerolled.
1082            max_rerolls: The maximum number of dice to reroll. 
1083                Note that each die can only be rerolled once, so if the number 
1084                of eligible dice is less than this, the excess rerolls have no
1085                effect.
1086            star: Whether outcomes should be unpacked into separate arguments
1087                before sending them to a callable `which`.
1088                If not provided, this will be guessed based on the function
1089                signature.
1090            mode: How dice are selected for rerolling if there are more eligible
1091                dice than `max_rerolls`. Options:
1092                * `'random'` (default): Eligible dice will be chosen uniformly
1093                    at random.
1094                * `'lowest'`: The lowest eligible dice will be rerolled.
1095                * `'highest'`: The highest eligible dice will be rerolled.
1096                * `'drop'`: All dice that ended up on an outcome selected by 
1097                    `which` will be dropped. This includes both dice that rolled
1098                    into `which` initially and were not rerolled, and dice that
1099                    were rerolled but rolled into `which` again. This can be
1100                    considerably more efficient than the other modes.
1101
1102        Returns:
1103            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1104            that this is not technically a `Pool`, though it supports most of 
1105            the same operations.
1106        """
1107        rerollable_set = self._select_outcomes(which, star)
1108        if not rerollable_set:
1109            return self.pool(rolls)
1110
1111        rerollable_die: 'Die[T_co]'
1112        not_rerollable_die: 'Die[T_co]'
1113        rerollable_die, not_rerollable_die = self.split(rerollable_set)
1114        single_is_rerollable = icepool.coin(rerollable_die.denominator(),
1115                                            self.denominator())
1116        rerollable = rolls @ single_is_rerollable
1117
1118        def split(initial_rerollable: int) -> Die[tuple[int, int, int]]:
1119            """Computes the composition of the pool.
1120
1121            Returns:
1122                initial_rerollable: The number of dice that initially fell into
1123                    the rerollable set.
1124                rerolled_to_rerollable: The number of dice that were rerolled,
1125                    but fell into the rerollable set again.
1126                not_rerollable: The number of dice that ended up outside the
1127                    rerollable set, including both initial and rerolled dice.
1128                not_rerolled: The number of dice that were eligible for
1129                    rerolling but were not rerolled.
1130            """
1131            initial_not_rerollable = rolls - initial_rerollable
1132            rerolled = min(initial_rerollable, max_rerolls)
1133            not_rerolled = initial_rerollable - rerolled
1134
1135            def second_split(rerolled_to_rerollable):
1136                """Splits the rerolled dice into those that fell into the rerollable and not-rerollable sets."""
1137                rerolled_to_not_rerollable = rerolled - rerolled_to_rerollable
1138                return icepool.tupleize(
1139                    initial_rerollable, rerolled_to_rerollable,
1140                    initial_not_rerollable + rerolled_to_not_rerollable,
1141                    not_rerolled)
1142
1143            return icepool.map(second_split,
1144                               rerolled @ single_is_rerollable,
1145                               star=False)
1146
1147        pool_composition = rerollable.map(split, star=False)
1148        denominator = self.denominator()**(rolls + min(rolls, max_rerolls))
1149        pool_composition = pool_composition.multiply_to_denominator(
1150            denominator)
1151
1152        def make_pool(initial_rerollable, rerolled_to_rerollable,
1153                      not_rerollable, not_rerolled):
1154            common = rerollable_die.pool(
1155                rerolled_to_rerollable) + not_rerollable_die.pool(
1156                    not_rerollable)
1157            match mode:
1158                case 'random':
1159                    return common + rerollable_die.pool(not_rerolled)
1160                case 'lowest':
1161                    return common + rerollable_die.pool(
1162                        initial_rerollable).highest(not_rerolled)
1163                case 'highest':
1164                    return common + rerollable_die.pool(
1165                        initial_rerollable).lowest(not_rerolled)
1166                case 'drop':
1167                    return not_rerollable_die.pool(not_rerollable)
1168                case _:
1169                    raise ValueError(
1170                        f"Invalid reroll_priority '{mode}'. Allowed values are 'random', 'lowest', 'highest', 'drop'."
1171                    )
1172
1173        return pool_composition.map_to_pool(make_pool, star=True)
1174
1175    # Unary operators.
1176
1177    def __neg__(self) -> 'Die[T_co]':
1178        return self.unary_operator(operator.neg)
1179
1180    def __pos__(self) -> 'Die[T_co]':
1181        return self.unary_operator(operator.pos)
1182
1183    def __invert__(self) -> 'Die[T_co]':
1184        return self.unary_operator(operator.invert)
1185
1186    def abs(self) -> 'Die[T_co]':
1187        return self.unary_operator(operator.abs)
1188
1189    __abs__ = abs
1190
1191    def round(self, ndigits: int | None = None) -> 'Die':
1192        return self.unary_operator(round, ndigits)
1193
1194    __round__ = round
1195
1196    def stochastic_round(self,
1197                         *,
1198                         max_denominator: int | None = None) -> 'Die[int]':
1199        """Randomly rounds outcomes up or down to the nearest integer according to the two distances.
1200        
1201        Specificially, rounds `x` up with probability `x - floor(x)` and down
1202        otherwise.
1203
1204        Args:
1205            max_denominator: If provided, each rounding will be performed
1206                using `fractions.Fraction.limit_denominator(max_denominator)`.
1207                Otherwise, the rounding will be performed without
1208                `limit_denominator`.
1209        """
1210        return self.map(lambda x: icepool.stochastic_round(
1211            x, max_denominator=max_denominator))
1212
1213    def trunc(self) -> 'Die':
1214        return self.unary_operator(math.trunc)
1215
1216    __trunc__ = trunc
1217
1218    def floor(self) -> 'Die':
1219        return self.unary_operator(math.floor)
1220
1221    __floor__ = floor
1222
1223    def ceil(self) -> 'Die':
1224        return self.unary_operator(math.ceil)
1225
1226    __ceil__ = ceil
1227
1228    # Binary operators.
1229
1230    def __add__(self, other) -> 'Die':
1231        if isinstance(other, icepool.AgainExpression):
1232            return NotImplemented
1233        other = implicit_convert_to_die(other)
1234        return self.binary_operator(other, operator.add)
1235
1236    def __radd__(self, other) -> 'Die':
1237        if isinstance(other, icepool.AgainExpression):
1238            return NotImplemented
1239        other = implicit_convert_to_die(other)
1240        return other.binary_operator(self, operator.add)
1241
1242    def __sub__(self, other) -> 'Die':
1243        if isinstance(other, icepool.AgainExpression):
1244            return NotImplemented
1245        other = implicit_convert_to_die(other)
1246        return self.binary_operator(other, operator.sub)
1247
1248    def __rsub__(self, other) -> 'Die':
1249        if isinstance(other, icepool.AgainExpression):
1250            return NotImplemented
1251        other = implicit_convert_to_die(other)
1252        return other.binary_operator(self, operator.sub)
1253
1254    def __mul__(self, other) -> 'Die':
1255        if isinstance(other, icepool.AgainExpression):
1256            return NotImplemented
1257        other = implicit_convert_to_die(other)
1258        return self.binary_operator(other, operator.mul)
1259
1260    def __rmul__(self, other) -> 'Die':
1261        if isinstance(other, icepool.AgainExpression):
1262            return NotImplemented
1263        other = implicit_convert_to_die(other)
1264        return other.binary_operator(self, operator.mul)
1265
1266    def __truediv__(self, other) -> 'Die':
1267        if isinstance(other, icepool.AgainExpression):
1268            return NotImplemented
1269        other = implicit_convert_to_die(other)
1270        return self.binary_operator(other, operator.truediv)
1271
1272    def __rtruediv__(self, other) -> 'Die':
1273        if isinstance(other, icepool.AgainExpression):
1274            return NotImplemented
1275        other = implicit_convert_to_die(other)
1276        return other.binary_operator(self, operator.truediv)
1277
1278    def __floordiv__(self, other) -> 'Die':
1279        if isinstance(other, icepool.AgainExpression):
1280            return NotImplemented
1281        other = implicit_convert_to_die(other)
1282        return self.binary_operator(other, operator.floordiv)
1283
1284    def __rfloordiv__(self, other) -> 'Die':
1285        if isinstance(other, icepool.AgainExpression):
1286            return NotImplemented
1287        other = implicit_convert_to_die(other)
1288        return other.binary_operator(self, operator.floordiv)
1289
1290    def __pow__(self, other) -> 'Die':
1291        if isinstance(other, icepool.AgainExpression):
1292            return NotImplemented
1293        other = implicit_convert_to_die(other)
1294        return self.binary_operator(other, operator.pow)
1295
1296    def __rpow__(self, other) -> 'Die':
1297        if isinstance(other, icepool.AgainExpression):
1298            return NotImplemented
1299        other = implicit_convert_to_die(other)
1300        return other.binary_operator(self, operator.pow)
1301
1302    def __mod__(self, other) -> 'Die':
1303        if isinstance(other, icepool.AgainExpression):
1304            return NotImplemented
1305        other = implicit_convert_to_die(other)
1306        return self.binary_operator(other, operator.mod)
1307
1308    def __rmod__(self, other) -> 'Die':
1309        if isinstance(other, icepool.AgainExpression):
1310            return NotImplemented
1311        other = implicit_convert_to_die(other)
1312        return other.binary_operator(self, operator.mod)
1313
1314    def __lshift__(self, other) -> 'Die':
1315        if isinstance(other, icepool.AgainExpression):
1316            return NotImplemented
1317        other = implicit_convert_to_die(other)
1318        return self.binary_operator(other, operator.lshift)
1319
1320    def __rlshift__(self, other) -> 'Die':
1321        if isinstance(other, icepool.AgainExpression):
1322            return NotImplemented
1323        other = implicit_convert_to_die(other)
1324        return other.binary_operator(self, operator.lshift)
1325
1326    def __rshift__(self, other) -> 'Die':
1327        if isinstance(other, icepool.AgainExpression):
1328            return NotImplemented
1329        other = implicit_convert_to_die(other)
1330        return self.binary_operator(other, operator.rshift)
1331
1332    def __rrshift__(self, other) -> 'Die':
1333        if isinstance(other, icepool.AgainExpression):
1334            return NotImplemented
1335        other = implicit_convert_to_die(other)
1336        return other.binary_operator(self, operator.rshift)
1337
1338    def __and__(self, other) -> 'Die':
1339        if isinstance(other, icepool.AgainExpression):
1340            return NotImplemented
1341        other = implicit_convert_to_die(other)
1342        return self.binary_operator(other, operator.and_)
1343
1344    def __rand__(self, other) -> 'Die':
1345        if isinstance(other, icepool.AgainExpression):
1346            return NotImplemented
1347        other = implicit_convert_to_die(other)
1348        return other.binary_operator(self, operator.and_)
1349
1350    def __or__(self, other) -> 'Die':
1351        if isinstance(other, icepool.AgainExpression):
1352            return NotImplemented
1353        other = implicit_convert_to_die(other)
1354        return self.binary_operator(other, operator.or_)
1355
1356    def __ror__(self, other) -> 'Die':
1357        if isinstance(other, icepool.AgainExpression):
1358            return NotImplemented
1359        other = implicit_convert_to_die(other)
1360        return other.binary_operator(self, operator.or_)
1361
1362    def __xor__(self, other) -> 'Die':
1363        if isinstance(other, icepool.AgainExpression):
1364            return NotImplemented
1365        other = implicit_convert_to_die(other)
1366        return self.binary_operator(other, operator.xor)
1367
1368    def __rxor__(self, other) -> 'Die':
1369        if isinstance(other, icepool.AgainExpression):
1370            return NotImplemented
1371        other = implicit_convert_to_die(other)
1372        return other.binary_operator(self, operator.xor)
1373
1374    # Comparators.
1375
1376    def __lt__(self, other) -> 'Die[bool]':
1377        if isinstance(other, icepool.AgainExpression):
1378            return NotImplemented
1379        other = implicit_convert_to_die(other)
1380        return self.binary_operator(other, operator.lt)
1381
1382    def __le__(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.le)
1387
1388    def __ge__(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.ge)
1393
1394    def __gt__(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.gt)
1399
1400    # Equality operators. These produce a `DieWithTruth`.
1401
1402    # The result has a truth value, but is not a bool.
1403    def __eq__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1404        if isinstance(other, icepool.AgainExpression):
1405            return NotImplemented
1406        other_die: Die = implicit_convert_to_die(other)
1407
1408        def data_callback() -> Counts[bool]:
1409            return self.binary_operator(other_die, operator.eq)._data
1410
1411        def truth_value_callback() -> bool:
1412            return self.equals(other)
1413
1414        return icepool.DieWithTruth(data_callback, truth_value_callback)
1415
1416    # The result has a truth value, but is not a bool.
1417    def __ne__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1418        if isinstance(other, icepool.AgainExpression):
1419            return NotImplemented
1420        other_die: Die = implicit_convert_to_die(other)
1421
1422        def data_callback() -> Counts[bool]:
1423            return self.binary_operator(other_die, operator.ne)._data
1424
1425        def truth_value_callback() -> bool:
1426            return not self.equals(other)
1427
1428        return icepool.DieWithTruth(data_callback, truth_value_callback)
1429
1430    def cmp(self, other) -> 'Die[int]':
1431        """A `Die` with outcomes 1, -1, and 0.
1432
1433        The quantities are equal to the positive outcome of `self > other`,
1434        `self < other`, and the remainder respectively.
1435        """
1436        other = implicit_convert_to_die(other)
1437
1438        data = {}
1439
1440        lt = self < other
1441        if True in lt:
1442            data[-1] = lt[True]
1443        eq = self == other
1444        if True in eq:
1445            data[0] = eq[True]
1446        gt = self > other
1447        if True in gt:
1448            data[1] = gt[True]
1449
1450        return Die(data)
1451
1452    @staticmethod
1453    def _sign(x) -> int:
1454        z = Die._zero(x)
1455        if x > z:
1456            return 1
1457        elif x < z:
1458            return -1
1459        else:
1460            return 0
1461
1462    def sign(self) -> 'Die[int]':
1463        """Outcomes become 1 if greater than `zero()`, -1 if less than `zero()`, and 0 otherwise.
1464
1465        Note that for `float`s, +0.0, -0.0, and nan all become 0.
1466        """
1467        return self.unary_operator(Die._sign)
1468
1469    # Equality and hashing.
1470
1471    def __bool__(self) -> bool:
1472        raise TypeError(
1473            'A `Die` only has a truth value if it is the result of == or !=.\n'
1474            'This could result from trying to use a die in an if-statement,\n'
1475            'in which case you should use `die.if_else()` instead.\n'
1476            'Or it could result from trying to use a `Die` inside a tuple or vector outcome,\n'
1477            'in which case you should use `tupleize()` or `vectorize().')
1478
1479    @cached_property
1480    def _hash_key(self) -> tuple:
1481        """A tuple that uniquely (as `equals()`) identifies this die.
1482
1483        Apart from being hashable and totally orderable, this is not guaranteed
1484        to be in any particular format or have any other properties.
1485        """
1486        return tuple(self.items())
1487
1488    @cached_property
1489    def _hash(self) -> int:
1490        return hash(self._hash_key)
1491
1492    def __hash__(self) -> int:
1493        return self._hash
1494
1495    def equals(self, other, *, simplify: bool = False) -> bool:
1496        """`True` iff both dice have the same outcomes and quantities.
1497
1498        This is `False` if `other` is not a `Die`, even if it would convert
1499        to an equal `Die`.
1500
1501        Truth value does NOT matter.
1502
1503        If one `Die` has a zero-quantity outcome and the other `Die` does not
1504        contain that outcome, they are treated as unequal by this function.
1505
1506        The `==` and `!=` operators have a dual purpose; they return a `Die`
1507        with a truth value determined by this method.
1508        Only dice returned by these methods have a truth value. The data of
1509        these dice is lazily evaluated since the caller may only be interested
1510        in the `Die` value or the truth value.
1511
1512        Args:
1513            simplify: If `True`, the dice will be simplified before comparing.
1514                Otherwise, e.g. a 2:2 coin is not `equals()` to a 1:1 coin.
1515        """
1516        if not isinstance(other, Die):
1517            return False
1518
1519        if simplify:
1520            return self.simplify()._hash_key == other.simplify()._hash_key
1521        else:
1522            return self._hash_key == other._hash_key
1523
1524    # Strings.
1525
1526    def __repr__(self) -> str:
1527        items_string = ', '.join(f'{repr(outcome)}: {weight}'
1528                                 for outcome, weight in self.items())
1529        return type(self).__qualname__ + '({' + items_string + '})'