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)

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

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