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)

70class Outcome(Hashable, Protocol[T_contra]):
71    """Protocol to attempt to verify that outcome types are hashable and sortable.
72
73    Far from foolproof, e.g. it cannot enforce total ordering.
74    """
75
76    def __lt__(self, other: T_contra) -> bool:
77        ...

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